1MONGOS(1) mongodb-manual MONGOS(1)
2
6 mongos - MongoDB Sharded Cluster Query Router
7
9 mongos for "MongoDB Shard," is a routing service for MongoDB shard con‐
10 figurations that processes queries from the application layer, and
11 determines the location of this data in the sharded cluster, in order
12 to complete these operations. From the perspective of the application,
13 a mongos instance behaves identically to any other MongoDB instance.
14
16 Never change the name of the mongos binary.
17
19 Core Options
20 mongos
21 --help, -h
23 Returns information on the options and use of mongos.
24 --version
26 Returns the mongos release number.
27 --config <filename>, -f <filename>
29 Specifies a configuration file for runtime configuration
30 options. The configuration file is the preferred method for run‐
31 time configuration of mongos. The options are equivalent to the
32 command-line configuration options. See http://docs.mon‐
33 godb.org/manual/reference/configuration-options for more infor‐
34 mation.
35 Ensure the configuration file uses ASCII encoding. The mongos
37 instance does not support configuration files with non-ASCII
38 encoding, including UTF-8.
39 --verbose, -v
41 Increases the amount of internal reporting returned on standard
42 output or in log files. Increase the verbosity with the -v form
43 by including the option multiple times, (e.g. -vvvvv.)
44 --quiet
46 Runs the mongos in a quiet mode that attempts to limit the
47 amount of output.
48 This option suppresses:
50 · output from database commands
52 · replication activity
54 · connection accepted events
56 · connection closed events
58 --port <port>
60 Default: 27017
61 Specifies the TCP port on which the MongoDB instance listens for
63 client connections.
64 --bind_ip <ip address>
66 Default: All interfaces.
67 Changed in version 2.6.0: The deb and rpm packages include a
69 default configuration file that sets --bind_ip to 127.0.0.1.
70 Specifies the IP address that mongos binds to in order to listen
73 for connections from applications. You may attach mongos to any
74 interface. When attaching mongos to a publicly accessible inter‐
75 face, ensure that you have implemented proper authentication and
76 firewall restrictions to protect the integrity of your database.
77 --maxConns <number>
79 Specifies the maximum number of simultaneous connections that
80 mongos will accept. This setting will have no effect if the
81 value of this setting is higher than your operating system's
82 configured maximum connection tracking threshold.
83 This setting is particularly useful for mongos if you have a
85 client that creates a number of connections but allows them to
86 timeout rather than close the connections. When you set maxIn‐
87 comingConnections, ensure the value is slightly higher than the
88 size of the connection pool or the total number of connections
89 to prevent erroneous connection spikes from propagating to the
90 members of a sharded cluster.
91 Changed in version 2.6: MongoDB removed the upward limit on the
93 maxIncomingConnections setting.
94 --syslog
97 Sends all logging output to the host's syslog system rather than
98 to standard output or to a log file. , as with --logpath.
99 The --syslog option is not supported on Windows.
101 --syslogFacility <string>
103 Default: user
104 Specifies the facility level used when logging messages to sys‐
106 log. The value you specify must be supported by your operating
107 system's implementation of syslog. To use this option, you must
108 enable the --syslog option.
109 --logpath <path>
111 Sends all diagnostic logging information to a log file instead
112 of to standard output or to the host's syslog system. MongoDB
113 creates the log file at the path you specify.
114 By default, MongoDB overwrites the log file when the process
116 restarts. To instead append to the log file, set the
117 --logappend option.
118 --logappend
120 Appends new entries to the end of the log file rather than over‐
121 writing the content of the log when the mongos instance
122 restarts.
123 --timeStampFormat <string>
125 Default: iso8601-local
126 The time format for timestamps in log messages. Specify one of
128 the following values:
129 ┌──────────────┬──────────────────────────────┐
131 │Value │ Description │
132 └──────────────┴──────────────────────────────┘
133 │ctime │ Displays timestamps as Wed │
136 │ │ Dec 31 18:17:54.811. │
137 ├──────────────┼──────────────────────────────┤
138 │iso8601-utc │ Displays timestamps in │
139 │ │ Coordinated Universal Time │
140 │ │ (UTC) in the ISO-8601 for‐ │
141 │ │ mat. For example, for New │
142 │ │ York at the start of the │
143 │ │ Epoch: │
144 │ │ 1970-01-01T00:00:00.000Z │
145 ├──────────────┼──────────────────────────────┤
146 │iso8601-local │ Displays timestamps in │
147 │ │ local time in the ISO-8601 │
148 │ │ format. For example, for │
149 │ │ New York at the start of │
150 │ │ the Epoch: │
151 │ │ 1969-12-31T19:00:00.000+0500 │
152 └──────────────┴──────────────────────────────┘
153 --pidfilepath <path>
155 Specifies a file location to hold the process ID of the mongos
156 process where mongos will write its PID. This is useful for
157 tracking the mongos process in combination with the --fork
158 option. Without a specified --pidfilepath option, the process
159 creates no PID file.
160 --keyFile <file>
162 Specifies the path to a key file that stores the shared secret
163 that MongoDB instances use to authenticate to each other in a
164 sharded cluster or replica set. --keyFile implies --auth. See
165 inter-process-auth for more information.
166 --setParameter <options>
168 Specifies one of the MongoDB parameters described in
169 http://docs.mongodb.org/manual/reference/parameters. You can
170 specify multiple setParameter fields.
171 --httpinterface
173 New in version 2.6.
174 Enables the HTTP interface. Enabling the interface can increase
177 network exposure.
178 Leave the HTTP interface disabled for production deployments. If
180 you do enable this interface, you should only allow trusted
181 clients to access this port. See security-firewalls.
182 NOTE:
184 In MongoDB Enterprise, the HTTP Console does not support Ker‐
185 beros Authentication.
186 --nounixsocket
188 Disables listening on the UNIX domain socket. The mongos process
189 always listens on the UNIX socket unless one of the following is
190 true:
191 · --nounixsocket is set
193 · bindIp is not set
195 · bindIp does not specify 127.0.0.1
197 New in version 2.6: mongos installed from official .deb and .rpm
199 packages have the bind_ip configuration set to 127.0.0.1 by
200 default.
201 --unixSocketPrefix <path>
204 Default: /tmp
205 The path for the UNIX socket. If this option has no value, the
207 mongos process creates a socket with /tmp as a prefix. MongoDB
208 creates and listens on a UNIX socket unless one of the following
209 is true:
210 · --nounixsocket is set
212 · bindIp is not set
214 · bindIp does not specify 127.0.0.1
216 --fork Enables a daemon mode that runs the mongos process in the back‐
218 ground. By default mongos does not run as a daemon: typically
219 you will run mongos as a daemon, either by using --fork or by
220 using a controlling process that handles the daemonization
221 process (e.g. as with upstart and systemd).
222 Sharded Cluster Options
224 --configdb <config1>,<config2>,<config3>
225 Specifies the configuration database for the sharded cluster.
226 You must specify either 1 or 3 configuration servers, in a comma
227 separated list. Always use 3 config servers in production envi‐
228 ronments.
229 All mongos instances must specify the exact same value for
231 --configdb
232 If your configuration databases reside in more that one data
234 center, order the hosts so that first config sever in the list
235 is the closest to the majority of your mongos instances.
236 WARNING:
238 Never remove a config server from this setting, even if the
239 config server is not available or offline.
240 --localThreshold
242 Default: 15
243 Affects the logic that mongos uses when selecting replica set
245 members to pass read operations from clients. Specify a value
246 in milliseconds. The default value of 15 corresponds to the
247 default value in all of the client drivers.
248 When mongos receives a request that permits reads to secondary
250 members, the mongos will:
251 · Find the member of the set with the lowest ping time.
253 · Construct a list of replica set members that is within a ping
255 time of 15 milliseconds of the nearest suitable member of the
256 set.
257 If you specify a value for the --localThreshold option, mongos
259 will construct the list of replica members that are within the
260 latency allowed by this value.
261 · Select a member to read from at random from this list.
263 The ping time used for a member compared by the --localThreshold
265 setting is a moving average of recent ping times, calculated at
266 most every 10 seconds. As a result, some queries may reach mem‐
267 bers above the threshold until the mongos recalculates the aver‐
268 age.
269 See the replica-set-read-preference-behavior-member-selection
271 section of the read preference documentation for more informa‐
272 tion.
273 --upgrade
275 Updates the meta data format used by the config database.
276 --chunkSize <value>
278 Default: 64
279 Determines the size in megabytes of each chunk in the sharded
281 cluster. A size of 64 megabytes is ideal in most deployments:
282 larger chunk size can lead to uneven data distribution; smaller
283 chunk size can lead to inefficient movement of chunks between
284 nodes.
285 This option affects chunk size only when you initialize the
287 cluster for the first time. If you later modify the option, the
288 new value has no effect. See the http://docs.mongodb.org/man‐
289 ual/tutorial/modify-chunk-size-in-sharded-cluster procedure if
290 you need to change the chunk size on an existing sharded clus‐
291 ter.
292 --noAutoSplit
294 Prevents mongos from automatically inserting metadata splits in
295 a sharded collection. If set on all mongos instances, this pre‐
296 vents MongoDB from creating new chunks as the data in a collec‐
297 tion grows.
298 Because any mongos in a cluster can create a split, to totally
300 disable splitting in a cluster you must set --noAutoSplit on all
301 mongos.
302 WARNING:
304 With --noAutoSplit enabled, the data in your sharded cluster
305 may become imbalanced over time. Enable with caution.
306 SSL Options
308 See
309 http://docs.mongodb.org/manual/tutorial/configure-ssl for full documen‐
310 tation of MongoDB's support.
311 --sslOnNormalPorts
313 Deprecated since version 2.6.
314 Enables SSL for mongos.
317 With --sslOnNormalPorts, a mongos requires SSL encryption for
319 all connections on the default MongoDB port, or the port speci‐
320 fied by --port. By default, --sslOnNormalPorts is disabled.
321 The default distribution of MongoDB does not contain support for
323 SSL. For more information on MongoDB and SSL, see
324 http://docs.mongodb.org/manual/tutorial/configure-ssl.
325 --sslMode <mode>
327 New in version 2.6.
328 Enables SSL or mixed SSL used for all network connections. The
331 argument to the --sslMode option can be one of the following:
332 ┌───────────┬────────────────────────────┐
337 │Value │ Description │
338 ├───────────┼────────────────────────────┤
339 │disabled │ The server does not use │
340 │ │ SSL. │
341 ├───────────┼────────────────────────────┤
342 │allowSSL │ Connections between │
343 │ │ servers do not use SSL. │
344 │ │ For incoming connections, │
345 │ │ the server accepts both │
346 │ │ SSL and non-SSL. │
347 ├───────────┼────────────────────────────┤
348 │preferSSL │ Connections between │
349 │ │ servers use SSL. For │
350 │ │ incoming connections, the │
351 │ │ server accepts both SSL │
352 │ │ and non-SSL. │
353 ├───────────┼────────────────────────────┤
354 │requireSSL │ The server uses and │
355 │ │ accepts only SSL encrypted │
356 │ │ connections. │
357 └───────────┴────────────────────────────┘
358 The default distribution of MongoDB does not contain support for
360 SSL. For more information on MongoDB and SSL, see
361 http://docs.mongodb.org/manual/tutorial/configure-ssl.
362 --sslPEMKeyFile <filename>
364 New in version 2.2.
365 Specifies the .pem file that contains both the SSL certificate
368 and key. Specify the file name of the .pem file using relative
369 or absolute paths.
370 When SSL is enabled, you must specify --sslPEMKeyFile.
372 The default distribution of MongoDB does not contain support for
374 SSL. For more information on MongoDB and SSL, see
375 http://docs.mongodb.org/manual/tutorial/configure-ssl.
376 --sslPEMKeyPassword <value>
378 New in version 2.2.
379 Specifies the password to de-crypt the certificate-key file
382 (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only
383 if the certificate-key file is encrypted. In all cases, the mon‐
384 gos will redact the password from all logging and reporting out‐
385 put.
386 Changed in version 2.6: If the private key in the PEM file is
388 encrypted and you do not specify the --sslPEMKeyPassword option,
389 the mongos will prompt for a passphrase. See ssl-certifi‐
390 cate-password.
391 The default distribution of MongoDB does not contain support for
394 SSL. For more information on MongoDB and SSL, see
395 http://docs.mongodb.org/manual/tutorial/configure-ssl.
396 --clusterAuthMode <option>
398 Default: keyFile
399 New in version 2.6.
401 The authentication mode used for cluster authentication. If you
404 use internal x.509 authentication, specify so here. This option
405 can have one of the following values:
406 ┌────────────┬────────────────────────────┐
408 │Value │ Description │
409 ├────────────┼────────────────────────────┤
410 │keyFile │ Use a keyfile for authen‐ │
411 │ │ tication. Accept only │
412 │ │ keyfiles. │
413 ├────────────┼────────────────────────────┤
414 │sendKeyFile │ For rolling upgrade pur‐ │
415 │ │ poses. Send a keyfile for │
416 │ │ authentication but can │
417 │ │ accept both keyfiles and │
418 │ │ x.509 certificates. │
419 ├────────────┼────────────────────────────┤
420 │sendX509 │ For rolling upgrade pur‐ │
421 │ │ poses. Send the x.509 cer‐ │
422 │ │ tificate for authentica‐ │
423 │ │ tion but can accept both │
424 │ │ keyfiles and x.509 cer‐ │
425 │ │ tificates. │
426 ├────────────┼────────────────────────────┤
427 │x509 │ Recommended. Send the │
428 │ │ x.509 certificate for │
429 │ │ authentication and accept │
430 │ │ only x.509 certificates. │
431 └────────────┴────────────────────────────┘
432 The default distribution of MongoDB does not contain support for
434 SSL. For more information on MongoDB and SSL, see
435 http://docs.mongodb.org/manual/tutorial/configure-ssl.
436 --sslClusterFile <filename>
438 New in version 2.6.
439 Specifies the .pem file that contains the x.509 certificate-key
442 file for membership authentication for the cluster or replica
443 set.
444 If --sslClusterFile does not specify the .pem file for internal
446 cluster authentication, the cluster uses the .pem file specified
447 in the --sslPEMKeyFile option.
448 The default distribution of MongoDB does not contain support for
450 SSL. For more information on MongoDB and SSL, see
451 http://docs.mongodb.org/manual/tutorial/configure-ssl.
452 --sslClusterPassword <value>
454 New in version 2.6.
455 Specifies the password to de-crypt the x.509 certificate-key
458 file specified with --sslClusterFile. Use the
459 --sslClusterPassword option only if the certificate-key file is
460 encrypted. In all cases, the mongos will redact the password
461 from all logging and reporting output.
462 If the x.509 key file is encrypted and you do not specify the
464 --sslClusterPassword option, the mongos will prompt for a
465 passphrase. See ssl-certificate-password.
466 The default distribution of MongoDB does not contain support for
468 SSL. For more information on MongoDB and SSL, see
469 http://docs.mongodb.org/manual/tutorial/configure-ssl.
470 --sslCAFile <filename>
472 New in version 2.4.
473 Specifies the .pem file that contains the root certificate chain
476 from the Certificate Authority. Specify the file name of the
477 .pem file using relative or absolute paths.
478 The default distribution of MongoDB does not contain support for
480 SSL. For more information on MongoDB and SSL, see
481 http://docs.mongodb.org/manual/tutorial/configure-ssl.
482 WARNING:
484 If the --sslCAFile option and its target file are not speci‐
485 fied, x.509 client and member authentication will not func‐
486 tion. mongod, and mongos in sharded systems, will not be able
487 to verify the certificates of processes connecting to it
488 against the trusted certificate authority (CA) that issued
489 them, breaking the certificate chain.
490 As of version 2.6.4, mongod will not start with x.509 authen‐
492 tication enabled if the CA file is not specified.
493 --sslCRLFile <filename>
495 New in version 2.4.
496 Specifies the .pem file that contains the Certificate Revocation
499 List. Specify the file name of the .pem file using relative or
500 absolute paths.
501 The default distribution of MongoDB does not contain support for
503 SSL. For more information on MongoDB and SSL, see
504 http://docs.mongodb.org/manual/tutorial/configure-ssl.
505 --sslWeakCertificateValidation
507 New in version 2.4.
508 Changed in version 3.0.0: --sslAllowConnectionsWithoutCertifi‐
511 cates became --sslWeakCertificateValidation. For compatibility,
512 MongoDB processes continue to accept --sslAllowConnectionsWith‐
513 outCertificates, but all users should update their configuration
514 files.
515 Disables the requirement for SSL certificate validation that
518 --sslCAFile enables. With the --sslWeakCertificateValidation
519 option, the mongos will accept connections when the client does
520 not present a certificate when establishing the connection.
521 If the client presents a certificate and the mongos has
523 --sslWeakCertificateValidation enabled, the mongos will validate
524 the certificate using the root certificate chain specified by
525 --sslCAFile and reject clients with invalid certificates.
526 Use the --sslWeakCertificateValidation option if you have a
528 mixed deployment that includes clients that do not or cannot
529 present certificates to the mongos.
530 The default distribution of MongoDB does not contain support for
532 SSL. For more information on MongoDB and SSL, see
533 http://docs.mongodb.org/manual/tutorial/configure-ssl.
534 --sslAllowInvalidCertificates
536 New in version 2.6.
537 Bypasses the validation checks for SSL certificates on other
540 servers in the cluster and allows the use of invalid certifi‐
541 cates. When using the allowInvalidCertificates setting, MongoDB
542 logs as a warning the use of the invalid certificate.
543 The default distribution of MongoDB does not contain support for
545 SSL. For more information on MongoDB and SSL, see
546 http://docs.mongodb.org/manual/tutorial/configure-ssl.
547 --sslAllowInvalidHostnames
549 New in version 3.0.
550 Disables the validation of the hostnames in SSL certificates,
553 when connecting to other mongos instances for inter-process
554 authentication. This allows mongos to connect to other mongos
555 instances if the hostnames in their certificates do not match
556 their configured hostname.
557 The default distribution of MongoDB does not contain support for
559 SSL. For more information on MongoDB and SSL, see
560 http://docs.mongodb.org/manual/tutorial/configure-ssl.
561 --sslFIPSMode
563 New in version 2.4.
564 Directs the mongos to use the FIPS mode of the installed OpenSSL
567 library. Your system must have a FIPS compliant OpenSSL library
568 to use the --sslFIPSMode option.
569 NOTE:
571 FIPS Compatible SSL is available only in MongoDB Enterprise.
572 See http://docs.mongodb.org/manual/tutorial/configure-fips
573 for more information.
574 Audit Options
576 --auditDestination
577 New in version 2.6.
578 Enables auditing. The --auditDestination option can have one of
581 the following values:
582 ┌────────┬────────────────────────────┐
584 │Value │ Description │
585 ├────────┼────────────────────────────┤
586 │syslog │ Output the audit events to │
587 │ │ syslog in JSON format. Not │
588 │ │ available on Windows. │
589 │ │ Audit messages have a sys‐ │
590 │ │ log severity level of info │
591 │ │ and a facility level of │
592 │ │ user. │
593 │ │ │
594 │ │ The syslog message limit │
595 │ │ can result in the trunca‐ │
596 │ │ tion of audit messages. │
597 │ │ The auditing system will │
598 │ │ neither detect the trunca‐ │
599 │ │ tion nor error upon its │
600 │ │ occurrence. │
601 ├────────┼────────────────────────────┤
602 │console │ Output the audit events to │
603 │ │ stdout in JSON format. │
604 └────────┴────────────────────────────┘
605 │file │ Output the audit events to │
607 │ │ the file specified in │
608 │ │ --auditPath in the format │
609 │ │ specified in │
610 │ │ --auditFormat. │
611 └────────┴────────────────────────────┘
612 NOTE:
614 Available only in MongoDB Enterprise.
615 --auditFormat
617 New in version 2.6.
618 Specifies the format of the output file for auditing if
621 --auditDestination is file. The --auditFormat option can have
622 one of the following values:
623 ┌──────┬────────────────────────────┐
625 │Value │ Description │
626 ├──────┼────────────────────────────┤
627 │JSON │ Output the audit events in │
628 │ │ JSON format to the file │
629 │ │ specified in --auditPath. │
630 ├──────┼────────────────────────────┤
631 │BSON │ Output the audit events in │
632 │ │ BSON binary format to the │
633 │ │ file specified in │
634 │ │ --auditPath. │
635 └──────┴────────────────────────────┘
636 Printing audit events to a file in JSON format degrades server
638 performance more than printing to a file in BSON format.
639 NOTE:
641 Available only in MongoDB Enterprise.
642 --auditPath
644 New in version 2.6.
645 Specifies the output file for auditing if --auditDestination has
648 value of file. The --auditPath option can take either a full
649 path name or a relative path name.
650 NOTE:
652 Available only in MongoDB Enterprise.
653 --auditFilter
655 New in version 2.6.
656 Specifies the filter to limit the types of operations the audit
659 system records. The option takes a string representation of a
660 query document of the form:
661 { <field1>: <expression1>, ... }
663 The <field> can be any field in the audit message, including
665 fields returned in the param document. The <expression> is a
666 query condition expression.
667 To specify an audit filter, enclose the filter document in sin‐
669 gle quotes to pass the document as a string.
670 To specify the audit filter in a configuration file, you must
672 use the YAML format of the configuration file.
673 NOTE:
675 Available only in MongoDB Enterprise.
676 Additional Options
678 --ipv6 Enables IPv6 support and allows the mongos to connect to the
679 MongoDB instance using an IPv6 network. All MongoDB programs and
680 processes disable IPv6 support by default.
681 --jsonp
683 Permits JSONP access via an HTTP interface. Enabling the inter‐
684 face can increase network exposure. The --jsonp option enables
685 the HTTP interface, even if the HTTP interface option is dis‐
686 abled.
687 --noscripting
689 Disables the scripting engine.
690
692 MongoDB Documentation Project
693
695 2011-2015
6963.0 January 30, 2015 MONGOS(1)