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.