NAME¶
mongos - MongoDB Shard Utility
SYNOPSIS¶
mongos for "MongoDB Shard," is a routing service for MongoDB
shard configurations that processes queries from the application layer, and
determines the location of this data in the
sharded cluster, in order
to complete these operations. From the perspective of the application, a
mongos instance behaves identically to any other MongoDB instance.
- Note
- Changed in version 2.1.
Some aggregation operations using the aggregate will cause
mongos instances to require more CPU resources than in previous
versions. This modified performance profile may dictate alternate
architecture decisions if you use the aggregation framework
extensively in a sharded environment.
- See also
-
/sharding and /core/sharded-clusters.
OPTIONS¶
- --help, -h
- Returns a basic help and usage text.
- --version
- Returns the version of the mongod daemon.
- --config <filename>, -f <filename>
- Specifies a configuration file, that you can use to specify
runtime-configurations. While the options are equivalent and accessible
via the other command line arguments, the configuration file is the
preferred method for runtime configuration of mongod. See the "
/reference/configuration-options" document for more
information about these options.
Not all configuration options for mongod make sense in the context of
mongos.
- --verbose, -v
- Increases the amount of internal reporting returned on standard output or
in the log file specified by --logpath. Use the -v form to
control the level of verbosity by including the option multiple times,
(e.g. -vvvvv.)
- --quiet
- Runs the mongos instance in a quiet mode that attempts to limit the
amount of output.
- --port <port>
- Specifies a TCP port for the mongos to listen for client
connections. By default mongos listens for connections on port
27017.
UNIX-like systems require root access to access ports with numbers lower
than 1024.
- --bind_ip <ip address>
- The IP address that the mongos process will bind to and listen for
connections. By default mongos listens for connections on the
localhost (i.e. 127.0.0.1 address.) You may attach mongos to
any interface; however, if you attach mongos to a publicly
accessible interface you must implement proper authentication or firewall
restrictions to protect the integrity of your database.
- --maxConns <number>
- Specifies the maximum number of simultaneous connections that
mongos will accept. This setting will have no effect if the value
of this setting is higher than your operating system's configured maximum
connection tracking threshold.
This is particularly useful for mongos if you have a client that
creates a number of collections but allows them to timeout rather than
close the collections. When you set maxConns, ensure the value is
slightly higher than the size of the connection pool or the total number
of connections to prevent erroneous connection spikes from propagating to
the members of a shard cluster.
- Note
- You cannot set maxConns to a value higher than 20000.
- --objcheck
- Forces the mongos to validate all requests from clients upon
receipt to ensure that invalid objects are never inserted into the
database. This option has a performance impact, and is not enabled by
default.
- --logpath <path>
- Specify a path for the log file that will hold all diagnostic logging
information.
Unless specified, mongos will output all log information to the
standard output. Additionally, unless you also specify --logappend,
the logfile will be overwritten when the process restarts.
- --logappend
- Specify to ensure that mongos appends additional logging data to
the end of the logfile rather than overwriting the content of the log when
the process restarts.
- --syslog
- New in version 2.1.0.
Sends all logging output to the host's syslog system rather than to
standard output or a log file as with --logpath.
- Warning
- You cannot use --syslog with --logpath.
- --pidfilepath <path>
- Specify a file location to hold the "PID" or process ID
of the mongos process. Useful for tracking the mongos
process in combination with the mongos --fork option.
Without a specified --pidfilepath option, mongos creates no
PID file.
- --keyFile <file>
- Specify the path to a key file to store authentication information. This
option is only useful for the connection between mongos instances
and components of the sharded cluster.
- See also
-
sharding-security
- --nounixsocket
- Disables listening on the UNIX socket. Without this option mongos
creates a UNIX socket.
- --unixSocketPrefix <path>
- Specifies a path for the UNIX socket. Unless specified, mongos
creates a socket in the /tmp path.
- --fork
- Enables a daemon mode for mongod which forces the process to
the background. This is the normal mode of operation, in production and
production-like environments, but may not be desirable for
testing.
- --configdb
<config1>,<config2><:port>,<config3>
- Set this option to specify a configuration database (i.e. config
database) for the sharded cluster. You must specify either 1
configuration server or 3 configuration servers, in a comma separated
list.
- Note
- mongos instances read from the first config server in
the list provided. All mongos instances must specify the
hosts to the --configdb setting in the same order.
If your configuration databases reside in more that one data center, order
the hosts in the --configdb argument so that the config database
that is closest to the majority of your mongos instances is first
servers in the list.
- Warning
- Never remove a config server from the --configdb parameter, even if
the config server or servers are not available, or offline.
- --test
- This option is for internal testing use only, and runs unit tests without
starting a mongos instance.
- --upgrade
- This option updates the meta data format used by the config
database.
- --chunkSize <value>
- The value of the --chunkSize determines the size of each
chunk, in megabytes, of data distributed around the
sharded cluster. The default value is 64 megabytes, which is the
ideal size for chunks in most deployments: larger chunk size can lead to
uneven data distribution, smaller chunk size often leads to inefficient
movement of chunks between nodes. However, in some circumstances it may be
necessary to set a different chunk size.
This option only sets the chunk size when initializing the cluster
for the first time. If you modify the run-time option later, the new value
will have no effect. See the "
sharding-balancing-modify-chunk-size" procedure if you need to
change the chunk size on an existing sharded cluster.
- --ipv6
- Enables IPv6 support to allow clients to connect to mongos using
IPv6 networks. MongoDB disables IPv6 support by default in mongod
and all utilities.
- --jsonp
- Permits JSONP access via an HTTP interface. Consider the security
implications of allowing this activity before enabling this option.
- --noscripting
- Disables the scripting engine.
- --nohttpinterface
- New in version 2.1.2.
Disables the HTTP interface.
- --localThreshold
- New in version 2.2.
--localThreshold affects the logic that mongos uses when
selecting replica set members to pass read operations to from
clients. Specify a value to --localThreshold in milliseconds. The
default value is 15, which corresponds to the default value in all
of the client drivers.
When mongos receives a request that permits reads to secondary
members, the mongos will:
- •
- find the member of the set with the lowest ping time.
- •
- construct a list of replica set members that is within a ping time of 15
milliseconds of the nearest suitable member of the set.
If you specify a value for --localThreshold, mongos will
construct the list of replica members that are within the latency allowed
by this value.
- •
- The mongos will select a member to read from at random from this
list.
The ping time used for a set member compared by the
--localThreshold
setting is a moving average of recent ping times, calculated, at most, every
10 seconds. As a result, some queries may reach members above the threshold
until the
mongos recalculates the average.
See the
replica-set-read-preference-behavior-member-selection section of
the
read preference documentation for more information.
- --noAutoSplit
- New in version 2.0.7.
--noAutoSplit prevents mongos from automatically inserting
metadata splits in a sharded collection. If set on all
mongos, this will prevent MongoDB from creating new chunks as the
data in a collection grows.
Because any mongos in a cluster can create a split, to totally
disable splitting in a cluster you must set --noAutoSplit on all
mongos.
- Warning
- With --noAutoSplit enabled, the data in your sharded cluster may
become imbalanced over time. Enable with caution.
SSL Options¶
- See
-
/administration/ssl for full documentation of MongoDB's
support.
- --authenticationDatabase <dbname>
- New in version 2.4.
Specifies the database that holds the user's (e.g --username)
credentials.
By default, mongos assumes that the database specified to the
--db argument holds the user's credentials, unless you specify
--authenticationDatabase.
See userSource, /reference/privilege-documents and
/reference/user-privileges for more information about delegated
authentication in MongoDB.
- --authenticationMechanism <name>
- New in version 2.4.
Specifies the authentication mechanism. By default, the authentication
mechanism is MONGODB-CR, which is the MongoDB challenge/response
authentication mechanism. In the MongoDB Subscriber Edition, mongos
also includes support for GSSAPI to handle Kerberos authentication.
See /tutorial/control-access-to-mongodb-with-kerberos-authentication
for more information about Kerberos authentication.
AUTHOR¶
MongoDB Documentation Project
COPYRIGHT¶
2011-2013, 10gen, Inc.