mongos
On this page
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.
Considerations
Never change the name of the mongos
binary.
Options
Core Options
-
--config
<filename>
,
-f
<filename>
-
Specifies a configuration file for runtime configuration options. The configuration file is the preferred method for runtime configuration of mongos. The options are equivalent to the command-line configuration options. See Configuration File Options for more information.
Ensure the configuration file uses ASCII encoding. The mongos instance does not support configuration files with non-ASCII encoding, including UTF-8.
-
--verbose
,
-v
-
Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the
-v
form by including the option multiple times, (e.g.-vvvvv
.)
-
--quiet
-
Runs mongos in a quiet mode that attempts to limit the amount of output.
This option suppresses:
- output from database commands
- replication activity
- connection accepted events
- connection closed events
-
--port
<port>
-
Default: 27017
The TCP port on which the
mongos
instance listens for client connections.
-
--bind_ip
<ip address>
-
Default: localhost
Note
Starting in MongoDB 3.6, mongos bind to localhost (
127.0.0.1
) by default. See Default Bind to Localhost.The IP addresses and/or full Unix domain socket paths on which mongos should listen for client connections. You may attach mongos to any interface. To bind to multiple addresses, enter a list of comma-separated values.
Example
localhost,/tmp/mongod.sock
You can specify both IPv4 and IPv6 addresses, or hostnames that resolve to an IPv4 or IPv6 address.
Example
localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513
Note
If specifying an IPv6 address or a hostname that resolves to an IPv6 address to
--bind_ip
, you must start mongos with--ipv6
to enable IPv6 support. Specifying an IPv6 address to--bind_ip
does not enable IPv6 support.If specifying a link-local IPv6 address (
fe80::/10
), you must append the zone index to that address (i.e.fe80::<address>%<adapter-name>
).Example
localhost,fe80::a00:27ff:fee0:1fcf%enp0s3
Tip
To avoid downtime, give each config server a logical DNS name (unrelated to the server’s physical or virtual hostname). Without logical DNS names, moving or renaming a config server requires shutting down every
mongod
andmongos
instance in the sharded cluster.Warning
Before binding to a non-localhost (e.g. publicly accessible) IP address, ensure you have secured your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.
To bind to all IPv4 addresses, enter
0.0.0.0
.To bind to all IPv4 and IPv6 addresses, enter
0.0.0.0,::
or alternatively, use thenet.bindIpAll
setting.Note
--bind_ip
and--bind_ip_all
are mutually exclusive. Specifying both options causes mongos to throw an error and terminate.
-
--bind_ip_all
-
New in version 3.6.
If specified, the mongos instance binds to all IPv4 addresses (i.e.
0.0.0.0
). If mongos starts with--ipv6
,--bind_ip_all
also binds to all IPv6 addresses (i.e.::
).mongos only supports IPv6 if started with
--ipv6
. Specifying--bind_ip_all
alone does not enable IPv6 support.Warning
Before binding to a non-localhost (e.g. publicly accessible) IP address, ensure you have secured your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.
Alternatively, you can set the
--bind_ip
option to0.0.0.0,::
to bind to all IP addresses.Note
--bind_ip
and--bind_ip_all
are mutually exclusive. That is, you can specify one or the other, but not both.
-
--maxConns
<number>
-
The maximum number of simultaneous connections that mongos will accept. This setting has no effect if it is higher than your operating system’s configured maximum connection tracking threshold.
Do not assign too low of a value to this option, or you will encounter errors during normal application operation.
This is particularly useful for a
mongos
if you have a client that creates multiple connections and allows them to timeout rather than closing them.In this case, set
maxIncomingConnections
to a value slightly higher than the maximum number of connections that the client creates, or the maximum size of the connection pool.This setting prevents the
mongos
from causing connection spikes on the individual shards. Spikes like these may disrupt the operation and memory allocation of the sharded cluster.Note
Changed in version 2.6: MongoDB removed the upward limit on the
maxIncomingConnections
setting.
-
--syslog
-
Sends all logging output to the host’s syslog system rather than to standard output or to a log file. , as with
--logpath
.The
--syslog
option is not supported on Windows.Warning
The
syslog
daemon generates timestamps when it logs a message, not when MongoDB issues the message. This can lead to misleading timestamps for log entries, especially when the system is under heavy load. We recommend using the--logpath
option for production systems to ensure accurate timestamps.
-
--syslogFacility
<string>
-
Default: user
Specifies the facility level used when logging messages to syslog. The value you specify must be supported by your operating system’s implementation of syslog. To use this option, you must enable the
--syslog
option.
-
--logpath
<path>
-
Sends all diagnostic logging information to a log file instead of to standard output or to the host’s syslog system. MongoDB creates the log file at the path you specify.
By default, MongoDB will move any existing log file rather than overwrite it. To instead append to the log file, set the
--logappend
option.
-
--logappend
-
Appends new entries to the end of the existing log file when the mongos instance restarts. Without this option,
mongod
will back up the existing log and create a new file.
-
--redactClientLogData
-
New in version 3.4: Available in MongoDB Enterprise only.
A mongos running with
--redactClientLogData
redacts any message accompanying a given log event before logging. This prevents the mongos from writing potentially sensitive data stored on the database to the diagnostic log. Metadata such as error or operation codes, line numbers, and source file names are still visible in the logs.Use
--redactClientLogData
in conjunction with Encryption at Rest and TLS/SSL (Transport Encryption) to assist compliance with regulatory requirements.For example, a MongoDB deployment might store Personally Identifiable Information (PII) in one or more collections. The mongos logs events such as those related to CRUD operations, sharding metadata, etc. It is possible that the mongos may expose PII as a part of these logging operations. A mongos running with
--redactClientLogData
removes any message accompanying these events before being output to the log, effectively removing the PII.Diagnostics on a mongos running with
--redactClientLogData
may be more difficult due to the lack of data related to a log event. See the process logging manual page for an example of the effect of--redactClientLogData
on log output.On a running mongos, use
setParameter
with theredactClientLogData
parameter to configure this setting.
-
--timeStampFormat
<string>
-
Default: iso8601-local
The time format for timestamps in log messages. Specify one of the following values:
Value Description ctime
Displays timestamps as Wed Dec 31 18:17:54.811
.iso8601-utc
Displays timestamps in Coordinated Universal Time (UTC) in the ISO-8601 format. For example, for New York at the start of the Epoch: 1970-01-01T00:00:00.000Z
iso8601-local
Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: 1969-12-31T19:00:00.000-0500
-
--pidfilepath
<path>
-
Specifies a file location to store the process ID (PID) of the mongos process. The user running the
mongod
ormongos
process must be able to write to this path. If the--pidfilepath
option is not specified, the process does not create a PID file. This option is generally only useful in combination with the--fork
option.Linux
On Linux, PID file management is generally the responsibility of your distro’s init system: usually a service file in the
/etc/init.d
directory, or a systemd unit file registered withsystemctl
. Only use the--pidfilepath
option if you are not using one of these init systems. For more information, please see the respective Installation Guide for your operating system.