mongos

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

--help , -h

Returns information on the options and use of mongos.

--version

Returns the mongos release number.

--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 and mongos 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 the net.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 to 0.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 the redactClientLogData 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 or mongos 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 with systemctl. 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.