401 lines
12 KiB
Groff
401 lines
12 KiB
Groff
.TH "MONGOS" "1" "March 14, 2013" "2.2.3" "mongodb-manual"
|
|
.SH NAME
|
|
mongos \- MongoDB Shard Utility
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.\" Man page generated from reStructuredText.
|
|
.
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fI\%mongos\fP 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
|
|
\fIsharded cluster\fP, in order to complete these operations.
|
|
From the perspective of the application, a
|
|
\fI\%mongos\fP instance behaves identically to any other MongoDB
|
|
instance.
|
|
.IP Note
|
|
Changed in version 2.1.
|
|
.sp
|
|
Some aggregation operations using the \fBaggregate\fP will
|
|
cause \fI\%mongos\fP instances to require more CPU resources
|
|
than in previous versions. This modified performance profile may
|
|
dictate alternate architecture decisions if you use the
|
|
\fIaggregation framework\fP extensively in a sharded environment.
|
|
.RE
|
|
.IP "See also"
|
|
.sp
|
|
\fB/sharding\fP and \fB/core/sharded\-clusters\fP.
|
|
.RE
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B mongos
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-help, \-h
|
|
Returns a basic help and usage text.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-version
|
|
Returns the version of the \fBmongod\fP daemon.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-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 "\fB/reference/configuration\-options\fP" document
|
|
for more information about these options.
|
|
.sp
|
|
Not all configuration options for \fBmongod\fP make sense in
|
|
the context of \fI\%mongos\fP.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-verbose, \-v
|
|
Increases the amount of internal reporting returned on standard
|
|
output or in the log file specified by \fI\%--logpath\fP. Use the
|
|
\fB\-v\fP form to control the level of verbosity by including the
|
|
option multiple times, (e.g. \fB\-vvvvv\fP.)
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-quiet
|
|
Runs the \fI\%mongos\fP instance in a quiet mode that attempts to limit
|
|
the amount of output.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-port <port>
|
|
Specifies a TCP port for the \fI\%mongos\fP to listen for client
|
|
connections. By default \fI\%mongos\fP listens for connections on
|
|
port 27017.
|
|
.sp
|
|
UNIX\-like systems require root access to access ports with numbers
|
|
lower than 1024.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-bind_ip <ip address>
|
|
The IP address that the \fI\%mongos\fP process will bind to and
|
|
listen for connections. By default \fI\%mongos\fP listens for
|
|
connections on the localhost (i.e. \fB127.0.0.1\fP address.) You may
|
|
attach \fI\%mongos\fP to any interface; however, if you attach
|
|
\fI\%mongos\fP to a publicly accessible interface you must
|
|
implement proper authentication or firewall restrictions to protect
|
|
the integrity of your database.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-maxConns <number>
|
|
Specifies the maximum number of simultaneous connections that
|
|
\fI\%mongos\fP will accept. This setting will have no effect if
|
|
the value of this setting is higher than your operating system\(aqs
|
|
configured maximum connection tracking threshold.
|
|
.sp
|
|
This is particularly useful for \fI\%mongos\fP if you have a
|
|
client that creates a number of collections but allows them to
|
|
timeout rather than close the collections. When you set
|
|
\fBmaxConns\fP, 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 \fIshard\fP cluster.
|
|
.IP Note
|
|
You cannot set \fBmaxConns\fP to a value higher
|
|
than \fI20000\fP.
|
|
.RE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-objcheck
|
|
Forces the \fI\%mongos\fP 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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-logpath <path>
|
|
Specify a path for the log file that will hold all diagnostic
|
|
logging information.
|
|
.sp
|
|
Unless specified, \fI\%mongos\fP will output all log information
|
|
to the standard output. Additionally, unless you also specify
|
|
\fI\%--logappend\fP, the logfile will be overwritten when the
|
|
process restarts.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-logappend
|
|
Specify to ensure that \fI\%mongos\fP appends additional logging
|
|
data to the end of the logfile rather than overwriting the content
|
|
of the log when the process restarts.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-syslog
|
|
New in version 2.1.0.
|
|
.sp
|
|
Sends all logging output to the host\(aqs \fIsyslog\fP system rather
|
|
than to standard output or a log file as with \fI\%--logpath\fP.
|
|
.IP Warning
|
|
You cannot use \fI\%--syslog\fP with \fI\%--logpath\fP.
|
|
.RE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-pidfilepath <path>
|
|
Specify a file location to hold the "\fIPID\fP" or process ID of the
|
|
\fI\%mongos\fP process. Useful for tracking the \fI\%mongos\fP process in
|
|
combination with the \fI\%mongos --fork\fP option.
|
|
.sp
|
|
Without a specified \fI\%--pidfilepath\fP option,
|
|
\fI\%mongos\fP creates no PID file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-keyFile <file>
|
|
Specify the path to a key file to store authentication
|
|
information. This option is only useful for the connection between
|
|
\fI\%mongos\fP instances and components of the \fIsharded cluster\fP.
|
|
.IP "See also"
|
|
.sp
|
|
\fIsharding\-security\fP
|
|
.RE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-nounixsocket
|
|
Disables listening on the UNIX socket. Without this option
|
|
\fI\%mongos\fP creates a UNIX socket.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-unixSocketPrefix <path>
|
|
Specifies a path for the UNIX socket. Unless specified,
|
|
\fI\%mongos\fP creates a socket in the \fB/tmp\fP path.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-fork
|
|
Enables a \fIdaemon\fP mode for \fBmongod\fP which forces the
|
|
process to the background. This is the normal mode of operation, in
|
|
production and production\-like environments, but may \fInot\fP be
|
|
desirable for testing.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-configdb <config1>,<config2><:port>,<config3>
|
|
Set this option to specify a configuration database
|
|
(i.e. \fIconfig database\fP) for the \fIsharded cluster\fP. You must
|
|
specify either 1 configuration server or 3 configuration servers,
|
|
in a comma separated list.
|
|
.IP Note
|
|
\fI\%mongos\fP instances read from the first \fIconfig
|
|
server\fP in the list provided. All
|
|
\fI\%mongos\fP instances \fBmust\fP specify the hosts to the
|
|
\fI\%--configdb\fP setting in the same order.
|
|
.sp
|
|
If your configuration databases reside in more that one data
|
|
center, order the hosts in the \fI\%--configdb\fP argument so
|
|
that the config database that is closest to the majority of your
|
|
\fI\%mongos\fP instances is first servers in the list.
|
|
.RE
|
|
.IP Warning
|
|
Never remove a config server from the \fI\%--configdb\fP parameter, even if
|
|
the config server or servers are not available, or offline.
|
|
.RE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-test
|
|
This option is for internal testing use only, and runs unit tests
|
|
without starting a \fI\%mongos\fP instance.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-upgrade
|
|
This option updates the meta data format used by the
|
|
\fIconfig database\fP.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-chunkSize <value>
|
|
The value of the \fI\%--chunkSize\fP determines the size of each
|
|
\fIchunk\fP, \fIin megabytes\fP, of data distributed around the
|
|
\fIsharded cluster\fP. 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.
|
|
.sp
|
|
This option \fIonly\fP 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
|
|
"\fIsharding\-balancing\-modify\-chunk\-size\fP" procedure if you
|
|
need to change the chunk size on an existing sharded cluster.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ipv6
|
|
Enables IPv6 support to allow clients to connect to \fI\%mongos\fP
|
|
using IPv6 networks. MongoDB disables IPv6 support by default in
|
|
\fBmongod\fP and all utilities.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-jsonp
|
|
Permits \fIJSONP\fP access via an HTTP interface. Consider the
|
|
security implications of allowing this activity before enabling
|
|
this option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-noscripting
|
|
Disables the scripting engine.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-nohttpinterface
|
|
New in version 2.1.2.
|
|
.sp
|
|
Disables the HTTP interface.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-localThreshold
|
|
New in version 2.2.
|
|
.sp
|
|
\fI\%--localThreshold\fP affects the logic that \fI\%mongos\fP
|
|
uses when selecting \fIreplica set\fP members to pass read
|
|
operations to from clients. Specify a value to
|
|
\fI\%--localThreshold\fP in milliseconds. The default value is
|
|
\fB15\fP, which corresponds to the default value in all of the client
|
|
\fBdrivers\fP.
|
|
.sp
|
|
When \fI\%mongos\fP receives a request that permits reads to
|
|
\fIsecondary\fP members, the \fI\%mongos\fP will:
|
|
.INDENT 7.0
|
|
.INDENT 3.5
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
find the member of the set with the lowest ping time.
|
|
.IP \(bu 2
|
|
construct a list of replica set members that is within a ping
|
|
time of 15 milliseconds of the nearest suitable member of the
|
|
set.
|
|
.sp
|
|
If you specify a value for \fI\%--localThreshold\fP,
|
|
\fI\%mongos\fP will construct the list of replica members
|
|
that are within the latency allowed by this value.
|
|
.IP \(bu 2
|
|
The \fI\%mongos\fP will select a member to read from at
|
|
random from this list.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The ping time used for a set member compared by the
|
|
\fI\%--localThreshold\fP 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 \fI\%mongos\fP
|
|
recalculates the average.
|
|
.sp
|
|
See the \fIreplica\-set\-read\-preference\-behavior\-member\-selection\fP
|
|
section of the \fIread preference\fP
|
|
documentation for more information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-noAutoSplit
|
|
New in version 2.0.7.
|
|
.sp
|
|
\fI\%--noAutoSplit\fP prevents \fI\%mongos\fP from
|
|
automatically inserting metadata splits in a \fIsharded
|
|
collection\fP. If set on all \fI\%mongos\fP, this will prevent
|
|
MongoDB from creating new chunks as the data in a collection
|
|
grows.
|
|
.sp
|
|
Because any \fI\%mongos\fP in a cluster can create a split,
|
|
to totally disable splitting in a cluster you must
|
|
set \fI\%--noAutoSplit\fP on all \fI\%mongos\fP.
|
|
.IP Warning
|
|
With \fI\%--noAutoSplit\fP enabled, the data in your sharded
|
|
cluster may become imbalanced over time. Enable with caution.
|
|
.RE
|
|
.UNINDENT
|
|
.SS SSL Options
|
|
.IP "See"
|
|
.sp
|
|
\fB/administration/ssl\fP for full documentation of
|
|
MongoDB\(aqs support.
|
|
.RE
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationDatabase <dbname>
|
|
New in version 2.4.
|
|
.sp
|
|
Specifies the database that holds the user\(aqs (e.g
|
|
\fI\-\-username\fP) credentials.
|
|
.sp
|
|
By default, \fI\%mongos\fP assumes that the database specified to the
|
|
\fI\-\-db\fP argument holds the user\(aqs credentials, unless you
|
|
specify \fI\%--authenticationDatabase\fP.
|
|
.sp
|
|
See \fBuserSource\fP,
|
|
\fB/reference/privilege\-documents\fP and
|
|
\fB/reference/user\-privileges\fP for more information about
|
|
delegated authentication in MongoDB.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationMechanism <name>
|
|
New in version 2.4.
|
|
.sp
|
|
Specifies the authentication mechanism. By default, the
|
|
authentication mechanism is \fBMONGODB\-CR\fP, which is the MongoDB
|
|
challenge/response authentication mechanism. In the MongoDB Subscriber Edition,
|
|
\fI\%mongos\fP also includes support for \fBGSSAPI\fP to handle
|
|
Kerberos authentication.
|
|
.sp
|
|
See \fB/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication\fP
|
|
for more information about Kerberos authentication.
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
MongoDB Documentation Project
|
|
.SH COPYRIGHT
|
|
2011-2013, 10gen, Inc.
|
|
.\" Generated by docutils manpage writer.
|
|
.
|