diff options
author | Kelsey T Schubert <kelsey.schubert@mongodb.com> | 2019-10-29 19:45:47 +0000 |
---|---|---|
committer | evergreen <evergreen@mongodb.com> | 2019-10-29 19:45:47 +0000 |
commit | 46d533cb48d05929b64f83a7771131a75a43ee5c (patch) | |
tree | 470794ed39429dcfc5f3bb1eafffc71496e6fd58 /debian | |
parent | d6098dae6d561026e865c9fe6f1e9ed77ca63d15 (diff) | |
download | mongo-46d533cb48d05929b64f83a7771131a75a43ee5c.tar.gz |
SERVER-42846 Update manpages
Diffstat (limited to 'debian')
-rw-r--r-- | debian/bsondump.1 | 6 | ||||
-rw-r--r-- | debian/mongo.1 | 38 | ||||
-rw-r--r-- | debian/mongod.1 | 192 | ||||
-rw-r--r-- | debian/mongodb-parameters.5 | 1235 | ||||
-rw-r--r-- | debian/mongodump.1 | 74 | ||||
-rw-r--r-- | debian/mongoexport.1 | 100 | ||||
-rw-r--r-- | debian/mongofiles.1 | 34 | ||||
-rw-r--r-- | debian/mongoimport.1 | 1552 | ||||
-rw-r--r-- | debian/mongoldap.1 | 748 | ||||
-rw-r--r-- | debian/mongoreplay.1 | 1298 | ||||
-rw-r--r-- | debian/mongorestore.1 | 35 | ||||
-rw-r--r-- | debian/mongos.1 | 28 | ||||
-rw-r--r-- | debian/mongostat.1 | 2 | ||||
-rw-r--r-- | debian/mongotop.1 | 2 |
14 files changed, 4586 insertions, 758 deletions
diff --git a/debian/bsondump.1 b/debian/bsondump.1 index 46b2d0dd02d..93b536585f0 100644 --- a/debian/bsondump.1 +++ b/debian/bsondump.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "BSONDUMP" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "BSONDUMP" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME bsondump \- MongoDB BSON Utility . @@ -62,6 +62,10 @@ Run \fI\%bsondump\fP from the system command line, not the \fBmongo\fP shell. BSON files, not a tool for data ingestion or other application use. .UNINDENT .UNINDENT +.sp +Starting in version 4.2, \fI\%bsondump\fP uses Extended +JSON v2.0 (Canonical mode) +to format its data. .SH OPTIONS .sp Changed in version 3.0.0: \fI\%bsondump\fP removed the \fB\-\-filter\fP, \fB\-\-dbpath\fP and the diff --git a/debian/mongo.1 b/debian/mongo.1 index e06ce6b7020..a38d4270deb 100644 --- a/debian/mongo.1 +++ b/debian/mongo.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGO" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGO" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongo \- MongoDB Shell . @@ -59,11 +59,20 @@ The \fI\%mongo\fP shell is part of the \fI\%MongoDB distributions\fP\&. \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +Starting in MongoDB 4.2, the \fI\%mongo\fP shell displays a +warning message when connected to non\-genuine MongoDB instances as +these instances may behave differently from the official MongoDB +instances; e.g. missing or incomplete features, different feature +behaviors, etc. +.IP \(bu 2 Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see 4.0\-disable\-tls\&. .UNINDENT .UNINDENT +.UNINDENT .SH SYNTAX .INDENT 0.0 .IP \(bu 2 @@ -587,6 +596,15 @@ default name of \fBmongodb\fP\&. This option is available only in MongoDB Enterprise. .UNINDENT .SS TLS Options +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 +encryption on systems where TLS 1.1+ is available. For +more details, see 4.0\-disable\-tls\&. +.UNINDENT +.UNINDENT .INDENT 0.0 .INDENT 3.5 .SS See @@ -883,6 +901,15 @@ counterparts instead. The SSL protocol is deprecated and MongoDB supports TLS 1.0 and later. .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 +encryption on systems where TLS 1.1+ is available. For +more details, see 4.0\-disable\-tls\&. +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B \-\-ssl @@ -1650,6 +1677,13 @@ mongo script\-file.js \-u <user> \-p .fi .UNINDENT .UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBisInteractive()\fP +.UNINDENT +.UNINDENT .SS Use \fI\%\-\-eval\fP to Print Query Results as JSON .sp To print return a query as JSON, from the system prompt using @@ -1678,6 +1712,8 @@ the additional JavaScript required to generate this output. /reference/method .IP \(bu 2 /mongo +.IP \(bu 2 +\fBisInteractive()\fP .UNINDENT .UNINDENT .UNINDENT diff --git a/debian/mongod.1 b/debian/mongod.1 index 5da79eb7515..5892f4e2196 100644 --- a/debian/mongod.1 +++ b/debian/mongod.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOD" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOD" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongod \- MongoDB Server . @@ -387,6 +387,45 @@ is, you can specify one or the other, but not both. .UNINDENT .INDENT 0.0 .TP +.B \-\-clusterIpSourceWhitelist <string> +New in version 3.6. + +.sp +A list of IP addresses/CIDR (\fI\%Classless Inter\-Domain Routing\fP) ranges against which the +\fI\%mongod\fP validates authentication requests from other members of +the replica set and, if part of a sharded cluster, the \fBmongos\fP +instances. The \fI\%mongod\fP verifies that the originating IP is +either explicitly in the list or belongs to a CIDR range in the list. If the +IP address is not present, the server does not authenticate the +\fI\%mongod\fP or \fBmongos\fP\&. +.sp +\fI\%\-\-clusterIpSourceWhitelist\fP has no effect on a \fI\%mongod\fP started without +authentication\&. +.sp +\fI\%\-\-clusterIpSourceWhitelist\fP accepts multiple comma\-separated IPv4/6 addresses or Classless +Inter\-Domain Routing (\fI\%CIDR\fP) ranges: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-clusterIpSourceWhitelist 192.0.2.0/24,127.0.0.1,::1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +Ensure \fI\%\-\-clusterIpSourceWhitelist\fP includes the IP address \fIor\fP CIDR ranges that include the +IP address of each replica set member or \fBmongos\fP in the +deployment to ensure healthy communication between cluster components. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B \-\-ipv6 Enables IPv6 support. \fBmongod\fP disables IPv6 support by default. .sp @@ -978,12 +1017,26 @@ _ New in version 4.2. .sp -Outputs the resolved YAML configuration document for the \fBmongod\fP -to \fBstdout\fP and halts the \fBmongod\fP instance. For configuration -options using externally\-sourced\-values, \fI\%\-\-outputConfig\fP returns the -resolved value for those options. This may include any configured -passwords or secrets previously obfuscated through the external -source. +Outputs the \fBmongod\fP instance\(aqs configuration options, formatted +in YAML, to \fBstdout\fP and exits the \fBmongod\fP instance. For +configuration options that uses externally\-sourced\-values, +\fI\%\-\-outputConfig\fP returns the resolved value for those options. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This may include any configured passwords or secrets previously +obfuscated through the external source. +.UNINDENT +.UNINDENT +.sp +For usage examples, see: +.INDENT 7.0 +.IP \(bu 2 +expansion\-directive\-output +.IP \(bu 2 +/tutorial/convert\-command\-line\-options\-to\-yaml +.UNINDENT .UNINDENT .SS Free Monitoring .sp @@ -1504,8 +1557,35 @@ A relative LDAP query URL formatted conforming to \fI\%RFC4515\fP and \fI\%RFC45 the LDAP groups to which the authenticated user belongs to. The query is relative to the host or hosts specified in \fI\%\-\-ldapServers\fP\&. .sp -Use the \fB{USER}\fP placeholder in the URL to substitute the authenticated -username, or the transformed username if a \fI\%username mapping\fP is specified. +In the URL, you can use the following substituion tokens: +.TS +center; +|l|l|. +_ +T{ +Substitution Token +T} T{ +Description +T} +_ +T{ +\fB{USER}\fP +T} T{ +Substitutes the authenticated username, or the +\fBtransformed\fP +username if a \fI\%username mapping\fP is specified. +T} +_ +T{ +\fB{PROVIDED_USER}\fP +T} T{ +Substitutes the supplied username, i.e. before either +authentication or \fBLDAP transformation\fP\&. +.sp +New in version 4.2. +T} +_ +.TE .sp When constructing the query URL, ensure that the order of LDAP parameters respects RFC4516: @@ -1688,47 +1768,6 @@ in\-memory storage engine\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-nssize <value> -\fIDefault\fP: 16 -.sp -Specifies the default size for namespace files, which are files that end -in \fB\&.ns\fP\&. Each collection and index counts as a namespace. -.sp -Use this setting to control size for newly created namespace files. This -option has no impact on existing files. The maximum size for a namespace -file is 2047 megabytes. The default value of 16 megabytes provides for -approximately 24,000 namespaces. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-quota -Enables a maximum limit for the number data files each database can -have. When running with the \fI\%\-\-quota\fP option, MongoDB has a maximum of 8 -data files per database. Adjust the quota with -\fI\%\-\-quotaFiles\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-quotaFiles <number> -\fIDefault\fP: 8 -.sp -Modifies the limit on the number of data files per database. \fI\%\-\-quotaFiles\fP -option requires that you set \fI\%\-\-quota\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-smallfiles -Sets MongoDB to use a smaller default file size. The \fI\%\-\-smallfiles\fP option -reduces the initial size for data files and limits the maximum size to -512 megabytes. \fI\%\-\-smallfiles\fP also reduces the size of each journal -file from 1 gigabyte to 128 megabytes. Use \fI\%\-\-smallfiles\fP if you have a large -number of databases that each holds a small quantity of data. -.sp -The \fI\%\-\-smallfiles\fP option can lead the \fBmongod\fP instance to create a large -number of files, which can affect performance for larger databases. -.UNINDENT -.INDENT 0.0 -.TP .B \-\-syncdelay <value> \fIDefault\fP: 60 .sp @@ -1864,15 +1903,6 @@ WiredTiger storage engine. .UNINDENT .INDENT 0.0 .TP -.B \-\-journalOptions <arguments> -Provides functionality for testing. Not for general use, and will affect data -file integrity in the case of abnormal system shutdown. -.sp -Not available for \fI\%mongod\fP instances that use the -in\-memory storage engine\&. -.UNINDENT -.INDENT 0.0 -.TP .B \-\-journalCommitInterval <value> \fIDefault\fP: 100 or 30 .sp @@ -1898,10 +1928,8 @@ in\-memory storage engine\&. Defines the maximum size of the internal cache that WiredTiger will use for all data. The memory consumed by an index build (see \fBmaxIndexBuildMemoryUsageMegabytes\fP) is separate from the -WiredTiger cache memory. -.sp -Starting in MongoDB 3.4, \fI\%\-\-wiredTigerCacheSizeGB\fP values can range from 0.25 GB to -10000 GB and can be a float. +WiredTiger cache memory. Starting in MongoDB 3.4, the values can range +from 0.25 GB to 10000 GB and can be a float. .sp Starting in MongoDB 3.4, the default WiredTiger internal cache size is the larger of either: @@ -1918,6 +1946,18 @@ Conversely, a system with a total of 1.25 GB of RAM will allocate 256 MB to the WiredTiger cache because that is more than half of the total RAM minus one gigabyte (\fB0.5 * (1.25 GB \- 1 GB) = 128 MB < 256 MB\fP). .sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +In some instances, such as when running in a container, the database +can have memory constraints that are lower than the total system +memory. In such instances, this memory limit, rather than the total +system memory, is used as the maximum RAM available. +.sp +To see the memory limit, see \fBhostInfo.system.memLimitMB\fP\&. +.UNINDENT +.UNINDENT +.sp Avoid increasing the WiredTiger internal cache size above its default value. .sp @@ -1950,9 +1990,10 @@ instances. .sp If you run \fI\%mongod\fP in a container (e.g. \fBlxc\fP, \fBcgroups\fP, Docker, etc.) that does \fInot\fP have access to all of the -RAM available in a system, you must set \fI\%\-\-wiredTigerCacheSizeGB\fP to a value less -than the amount of RAM available in the container. The exact amount -depends on the other processes running in the container. +RAM available in a system, you must set \fI\%\-\-wiredTigerCacheSizeGB\fP to a value +less than the amount of RAM available in the container. The exact +amount depends on the other processes running in the container. See +\fBmemLimitMB\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -3949,6 +3990,25 @@ need to, but can, also specify the \fI\%\-\-kmipServerCAFile\fP\&. .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B \-\-eseDatabaseKeyRollover +New in version 4.2. + +.sp +Roll over the encrypted storage engine database keys configured with +\fBAES256\-GCM\fP cipher. +.sp +When \fI\%mongod\fP instance is started with this option, the +instance rotates the keys and exits. +.INDENT 7.0 +.INDENT 3.5 +.IP "Enterprise Feature" +.sp +Available in MongoDB Enterprise only. +.UNINDENT +.UNINDENT +.UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT diff --git a/debian/mongodb-parameters.5 b/debian/mongodb-parameters.5 index 729c7e1191d..52264008606 100644 --- a/debian/mongodb-parameters.5 +++ b/debian/mongodb-parameters.5 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGODB-PARAMETERS" "5" "Jun 21, 2018" "4.0" "mongodb-manual" +.TH "MONGODB-PARAMETERS" "5" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongodb-parameters \- MongoDB setParameter Options . @@ -278,13 +278,35 @@ Defaults to 30 seconds. New in version 3.6. .sp +Changed in version 4.0: With the use of native TLS/SSL libraries, the parameter +\fI\%opensslCipherConfig\fP is supported for Linux/BSD and +no longer supported in Windows and macOS. See MongoDB 4.0 +TLS/SSL\&. + +.sp Specify the cipher string for OpenSSL when using TLS/SSL encryption. For a list of cipher strings, see -\fI\%https://wiki.openssl.org/index.php/Manual:Ciphers(1)#CIPHER_STRINGS\fP +\fI\%https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER\-STRINGS\fP .sp You can only set \fI\%opensslCipherConfig\fP during start\-up, and cannot change this setting using the \fBsetParameter\fP database command. +.sp +For version 4.2 and greater, the use of \fBTLS\fP options is preferred +over \fBSSL\fP options. The TLS options have the same functionality as +the \fBSSL\fP options. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter opensslCipherConfig=HIGH:!EXPORT:!aNULL@STRENGTH \-\-tlsMode requireTLS \-\-tlsCertificateKeyFile Certs/server.pem +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For versions 4.0 and earlier: .INDENT 7.0 .INDENT 3.5 .sp @@ -317,7 +339,7 @@ instance to use for proxy authentication. .B saslHostName Available for both \fBmongod\fP and \fBmongos\fP\&. .sp -\fI\%saslHostName\fP overrides MongoDB’s default hostname +\fI\%saslHostName\fP overrides MongoDB\(aqs default hostname detection for the purpose of configuring SASL and Kerberos authentication. .sp @@ -507,6 +529,152 @@ db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } ) .fi .UNINDENT .UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +\fI\%tlsMode\fP +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B tlsMode +New in version 4.2. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +Set to either: +.INDENT 7.0 +.IP \(bu 2 +\fBpreferTLS\fP +.IP \(bu 2 +\fBrequireTLS\fP +.UNINDENT +.sp +The \fI\%tlsMode\fP parameter is useful during rolling +upgrade to TLS/SSL to minimize +downtime. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +\fI\%sslMode\fP +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B tlsWithholdClientCertificate +\fIDefault\fP: false +.sp +New in version 4.2. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +A TLS certificate is set for a \fBmongod\fP or +\fBmongos\fP either by the +\fB\-\-tlsClusterFile\fP option or by the +\fB\-\-tlsCertificateKeyFile\fP option when +\fB\-\-tlsClusterFile\fP is not set. If the TLS +certificate is set, by default, the instance sends the certificate when +initiating intra\-cluster communications with other +\fBmongod\fP or \fBmongos\fP instances in +the deployment. Set \fBtlsWithholdClientCertificate\fP to \fB1\fP or \fBtrue\fP to +direct the instance to withhold sending its TLS certificate during these +communications. Use this option with +\fB\-\-tlsAllowConnectionsWithoutCertificates\fP +(to allow inbound connections without certificates) on all members of the +deployment. \fBtlsWithholdClientCertificate\fP is mutually exclusive with +\fB\-\-clusterAuthMode x509\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B tlsX509ClusterAuthDNOverride +New in version 4.2. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +An alternative Distinguished Name (DN) that the instance can also +use to identify members of the deployment. +.sp +For a MongoDB deployment that uses x.509 certificates for +\fBclusterAuthMode\fP, deployment members identify +each other using x.509 certificates ( +\fBnet.tls.clusterFile\fP, if specified, and +\fBnet.tls.certificateKeyFile\fP) during intra\-cluster +communications. For members of the same deployment, the \fBDN\fP from +their certificates must have the same Organization attributes +(\fBO\fP\(aqs), the Organizational Unit attributes (\fBOU\fP\(aqs), and the +Domain Components (\fBDC\fP\(aqs). +.sp +If \fI\%tlsX509ClusterAuthDNOverride\fP is set for a member, +the member can also use the override value when comparing the \fBDN\fP +components (\fBO\fP\(aqs, \fBOU\fP\(aqs, and \fBDC\fP\(aqs) of the presented +certificates. That is the member checks the presented certificates +against its +\fBnet.tls.clusterFile\fP/\fBnet.tls.certificateKeyFile\fP\&. +If the DN does not match, the member checks the presented +certifcate against the \fI\%tlsX509ClusterAuthDNOverride\fP +value. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If set, you must set this parameter on all members of the +deployment. +.UNINDENT +.UNINDENT +.sp +You can use this parameter for a rolling update of certificates to +new certificates that contain a new \fBDN\fP value. See +/tutorial/rotate\-x509\-membership\-certificates\&. +.sp +For more information about membership certificate requirements, see +x509\-member\-certificate\-requirements for details. +.UNINDENT +.INDENT 0.0 +.TP +.B sslWithholdClientCertificate +\fIDefault\fP: false +.sp +Deprecated since version 4.2: Use \fI\%tlsWithholdClientCertificate\fP instead. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +A TLS certificate is set for a \fBmongod\fP or +\fBmongos\fP either by the +\fB\-\-tlsClusterFile\fP option or by the +\fB\-\-tlsCertificateKeyFile\fP option when +\fB\-\-tlsClusterFile\fP is not set. If the TLS +certificate is set, by default, the instance sends the certificate when +initiating intra\-cluster communications with other +\fBmongod\fP or \fBmongos\fP instances in +the deployment. Set \fBsslWithholdClientCertificate\fP to \fB1\fP or \fBtrue\fP to +direct the instance to withhold sending its TLS certificate during these +communications. Use this option with +\fB\-\-tlsAllowConnectionsWithoutCertificates\fP +(to allow inbound connections without certificates) on all members of the +deployment. \fBsslWithholdClientCertificate\fP is mutually exclusive with +\fB\-\-clusterAuthMode x509\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -556,6 +724,21 @@ MongoDB server still consume server resources, and this may adversely impact benign login attempts if the server is denying access to many other clients simultaneously. .UNINDENT +.INDENT 0.0 +.TP +.B allowRolesFromX509Certificates +\fIDefault\fP: true +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +\fIAvailable starting in MongoDB 4.0.11 (and 3.6.14 and 3.4.22)\fP +.sp +A boolean flag that allows or disallows the retrieval of +authorization roles from client x.509 certificates. +.sp +You can only set \fI\%allowRolesFromX509Certificates\fP during +startup in the config file or on the command line. +.UNINDENT .SS General Parameters .INDENT 0.0 .TP @@ -689,7 +872,7 @@ pools. See \fI\%ShardingTaskExecutorPoolMaxSize\fP\&. .UNINDENT .sp \fBOnly\fP adjust this setting if your driver does \fInot\fP pool -connections and you’re using authentication in the +connections and you\(aqre using authentication in the context of a sharded cluster. .sp You can only set \fI\%connPoolMaxConnsPerHost\fP during startup @@ -812,31 +995,57 @@ db.adminCommand( { setParameter: 1, cursorTimeoutMillis: 300000 } ) .fi .UNINDENT .UNINDENT +.sp +Setting \fI\%cursorTimeoutMillis\fP to less than or equal +to \fB0\fP results in all cursors being immediately eligible for timeout. +Generally, the timeout value should be greater than the average amount of +time for a query to return results. Use tools like the \fBcursor.explain()\fP +cursor modifier to analyze the average query time and select an appropriate +timeout period. .UNINDENT .INDENT 0.0 .TP .B failIndexKeyTooLong -New in version 2.6. - -.sp Available for \fBmongod\fP only. .sp -In MongoDB 2.6, if you attempt to insert or update a document so -that the value of an indexed field is longer than the -\fBIndex Key Length Limit\fP, the operation -will fail and return an error to the client. In previous versions -of MongoDB, these operations would successfully insert or modify a -document but the index or indexes would not include references to -the document. +.INDENT 7.0 +Changed in version 4.2: .IP \(bu 2 +MongoDB removes the \fBIndex Key Limit\fP for +featureCompatibilityVersion (fCV) set to +\fB"4.2"\fP or greater. +.IP \(bu 2 +In concert with the removal of the limit, +\fBfailIndexTooLong\fP only applies for MongoDB 2.6 +through MongoDB versions with featureCompatibilityVersion (fCV) set to \fB"4.0"\fP or earlier. +.UNINDENT + +.sp +For MongoDB 2.6 through MongoDB versions with +\fBfeatureCompatibilityVersion\fP (fCV) set to \fB"4.0"\fP or earlier, +\fBIndex Key Length Limit\fP applies. If you +attempt to insert or update a document whose index field exceeds +the \fBIndex Key Length Limit\fP, the operation +will fail and return an error to the client. .sp To avoid this issue, consider using hashed indexes or indexing a computed value. If you have an existing data set and want to disable this behavior so you can upgrade and then gradually resolve these indexing issues, you can use \fI\%failIndexKeyTooLong\fP to disable this behavior. .sp -\fI\%failIndexKeyTooLong\fP defaults to \fBtrue\fP\&. When -\fBfalse\fP, a 2.6 \fBmongod\fP instance will provide the 2.4 -behavior. +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +Setting \fI\%failIndexKeyTooLong\fP to \fBfalse\fP is +a temporary workaround, not a permanent solution to the +problem of oversized index keys. With +\fI\%failIndexKeyTooLong\fP set to \fBfalse\fP, queries can +return incomplete results if they use indexes that skip over +documents whose indexed fields exceed the +\fBIndex Key Length Limit\fP\&. +.UNINDENT +.UNINDENT +.sp +\fI\%failIndexKeyTooLong\fP defaults to \fBtrue\fP\&. .sp Issue the following command to disable the index key length validation: @@ -866,25 +1075,6 @@ mongod \-\-setParameter failIndexKeyTooLong=false .UNINDENT .INDENT 0.0 .TP -.B newCollectionsUsePowerOf2Sizes -Deprecated since version 3.0.0: MongoDB deprecates the -\fI\%newCollectionsUsePowerOf2Sizes\fP parameter such that -you cannot set the \fI\%newCollectionsUsePowerOf2Sizes\fP to -\fBfalse\fP and \fI\%newCollectionsUsePowerOf2Sizes\fP set to -\fBtrue\fP is a no\-op. To disable the power of 2 allocation for a collection, use the -\fBcollMod\fP command with the \fBnoPadding\fP flag -or the \fBdb.createCollection()\fP method with the -\fBnoPadding\fP option. - -.sp -\fIDefault\fP: \fBtrue\fP\&. -.sp -Available for \fBmongod\fP only. -.sp -Available for the MMAPv1 storage engine only. -.UNINDENT -.INDENT 0.0 -.TP .B notablescan Available for \fBmongod\fP only. .sp @@ -915,7 +1105,7 @@ the /tutorial/evaluate\-operation\-performance and sections and using the \fI\%logLevel\fP parameter, /reference/program/mongostat and profiling\&. .sp -Don’t run production \fBmongod\fP instances with +Don\(aqt run production \fBmongod\fP instances with \fI\%notablescan\fP because preventing collection scans can potentially affect queries in all databases, including administrative queries. .UNINDENT @@ -958,7 +1148,7 @@ mongod \-\-setParameter ttlMonitorEnabled=false .INDENT 0.0 .TP .B disableJavaScriptJIT -Changed in version 4.0: The JavaScript engine’s JIT compiler is now disabled by default. +Changed in version 4.0: The JavaScript engine\(aqs JIT compiler is now disabled by default. .sp Available for \fBmongod\fP only. @@ -979,10 +1169,14 @@ db.adminCommand( { setParameter: 1, disableJavaScriptJIT: false } ) .UNINDENT .UNINDENT .sp -Be aware that \fBgroup\fP and \fB$where\fP will reuse existing -JavaScript interpreter contexts, so changes to -\fI\%disableJavaScriptJIT\fP may not take effect immediately for these -operations. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fB$where\fP will reuse existing JavaScript interpreter +contexts, so changes to \fI\%disableJavaScriptJIT\fP may not +take effect immediately for these operations. +.UNINDENT +.UNINDENT .sp Alternately, you may enable the JIT at startup time by starting the \fBmongod\fP instance with the following option: @@ -1005,11 +1199,18 @@ New in version 3.4. .sp \fIDefault\fP: 500 .sp -Limits the amount of memory that simultaneous foreground index +Limits the amount of memory that simultaneous index builds on one collection may consume for the duration of the -builds. +builds. The specified amount of memory is shared between all +indexes built using a single +\fBcreateIndexes\fP command or its shell helper +\fBdb.collection.createIndexes()\fP\&. .sp -Foreground index builds may be initiated either by a user command +The memory consumed by an index build is separate from the +WiredTiger cache memory (see +\fBcacheSizeGB\fP). +.sp +Index builds may be initiated either by a user command such as Create Index or by an administrative process such as an initial sync\&. @@ -1018,7 +1219,7 @@ Both are subject to the limit set by .sp An initial sync operation populates only one collection at a time and has no risk of exceeding the memory -limit. However, it is possible for a user to start foreground index +limit. However, it is possible for a user to start index builds on multiple collections in multiple databases simultaneously and potentially consume an amount of memory greater than the limit set in \fI\%maxIndexBuildMemoryUsageMegabytes\fP\&. @@ -1032,13 +1233,52 @@ procedure as described on /tutorial/build\-indexes\-on\-replica\-sets\&. .UNINDENT .UNINDENT +.sp +Changed in version 4.2. + +.INDENT 7.0 +.IP \(bu 2 +For feature compatibility version (fcv) \fB"4.2"\fP, +the index build memory limit applies to all index builds. +.IP \(bu 2 +For feature compatibility version (fcv) \fB"4.0"\fP, +the index build memory limit only applies to foreground +index builds. +.UNINDENT .UNINDENT .INDENT 0.0 .TP -.B watchdogPeriodSeconds -New in version 3.6. +.B reportOpWriteConcernCountersInServerStatus +New in version 4.0.6. .sp +\fIDefault\fP: false +.sp +A boolean flag that determines whether the +\fBdb.serverStatus()\fP method and \fBserverStatus\fP +command return \fBopWriteConcernCounters\fP information. [1] +.sp +You can only set +\fI\%reportOpWriteConcernCountersInServerStatus\fP during +startup in the config file or on the command line. For example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter reportOpWriteConcernCountersInServerStatus=true +.ft P +.fi +.UNINDENT +.UNINDENT +.IP [1] 5 +Enabling \fI\%reportOpWriteConcernCountersInServerStatus\fP +can have a negative performance impact; specificaly, when running +\fIwithout\fP TLS. +.UNINDENT +.INDENT 0.0 +.TP +.B watchdogPeriodSeconds Available for \fBmongod\fP only. .sp \fIType\fP: integer @@ -1048,30 +1288,62 @@ Available for \fBmongod\fP only. \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in MongoDB Enterprise. Not available on macOS. +.INDENT 0.0 +.IP \(bu 2 +Starting in MongoDB 4.2, the Storage Node Watchdog is available in both the Community and +MongoDB Enterprise editions. +.IP \(bu 2 +In earlier versions (3.2.16+, 3.4.7+, 3.6.0+, 4.0.0+), the +Storage Node Watchdog is only +available in MongoDB Enterprise edition. .UNINDENT .UNINDENT +.UNINDENT +.sp +Determines how frequent the Storage Node Watchdog checks the status of the monitored +filesystems: +.INDENT 7.0 +.IP \(bu 2 +The \fB\-\-dbpath\fP directory +.IP \(bu 2 +The \fBjournal\fP directory inside the \fB\-\-dbpath\fP directory if +\fBjournaling\fP is enabled +.IP \(bu 2 +The directory of \fB\-\-logpath\fP file +.IP \(bu 2 +The directory of \fB\-\-auditPath\fP file +.UNINDENT .sp -Determines how often the -Storage Node Watchdog checks the status of -the monitored filesystems. +Valid values for \fBwatchdobgPeriodSeconds\fP are: +.INDENT 7.0 +.IP \(bu 2 +\fB\-1\fP (the default), to disable/pause Storage Node Watchdog, or +.IP \(bu 2 +An integer greater than or equal to 60. +.UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -If a filesystem on a monitored directory becomes unresponsive, it can -take a maximum of nearly \fItwice\fP the value of -\fI\%watchdogPeriodSeconds\fP to terminate the \fBmongod\fP\&. +.INDENT 0.0 +.IP \(bu 2 +If a filesystem on a monitored directory becomes unresponsive, +it can take a maximum of nearly \fItwice\fP the value of +\fI\%watchdogPeriodSeconds\fP to terminate the +\fBmongod\fP\&. +.IP \(bu 2 +If any of its monitored directory is a symlink to other +volumes, the Storage Node Watchdog does not monitor the symlink +target. For example, if the \fBmongod\fP uses +\fBstorage.directoryPerDB: true\fP (or \fB\-\-directoryperdb\fP) and symlinks a database directory to +another volume, the Storage Node Watchdog does not follow the +symlink to monitor the target. +.UNINDENT .UNINDENT .UNINDENT .sp -Valid values are \-1, meaning the -Storage Node Watchdog is disabled, or an -integer greater than or equal to 60. -.sp -By default the Storage Node Watchdog is -disabled. To enable it, \fI\%watchdogPeriodSeconds\fP must be set at -startup time. +To enable Storage Node Watchdog, +\fI\%watchdogPeriodSeconds\fP must be set during startup. .INDENT 7.0 .INDENT 3.5 .sp @@ -1083,15 +1355,16 @@ mongod \-\-setParameter watchdogPeriodSeconds=60 .UNINDENT .UNINDENT .sp -You can only enable the Storage Node Watchdog -at startup. +You can only enable the Storage Node Watchdog at startup. However, once enabled, you can +pause the Storage Node Watchdog or +change the \fI\%watchdogPeriodSeconds\fP during runtime. .sp -However, once enabled, you can pause the Storage Node Watchdog or change the \fI\%watchdogPeriodSeconds\fP -during runtime. -.sp -To pause the Storage Node Watchdog during -runtime, set \fI\%watchdogPeriodSeconds\fP to \-1. +Once enabled, .INDENT 7.0 +.IP \(bu 2 +To pause the Storage Node Watchdog +during runtime, set \fI\%watchdogPeriodSeconds\fP to \-1. +.INDENT 2.0 .INDENT 3.5 .sp .nf @@ -1101,10 +1374,11 @@ db.adminCommand( { setParameter: 1, watchdogPeriodSeconds: \-1 } ) .fi .UNINDENT .UNINDENT -.sp +.IP \(bu 2 To resume or change the period during runtime, set -\fI\%watchdogPeriodSeconds\fP to a number greater than or equal to 60. -.INDENT 7.0 +\fI\%watchdogPeriodSeconds\fP to a number greater than or +equal to 60. +.INDENT 2.0 .INDENT 3.5 .sp .nf @@ -1114,6 +1388,7 @@ db.adminCommand( { setParameter: 1, watchdogPeriodSeconds: 120 } ) .fi .UNINDENT .UNINDENT +.UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 @@ -1131,10 +1406,12 @@ startup time. Available for both \fBmongod\fP and \fBmongos\fP\&. .sp Specify an integer between \fB0\fP and \fB5\fP signifying the verbosity -of the logging, where \fB5\fP is the most verbose. +of the logging, where \fB5\fP is the +most verbose. [2] .sp -Consider the following example which sets the -\fI\%logLevel\fP to \fB2\fP: +The default \fI\%logLevel\fP is \fB0\fP (Informational). +.sp +The following example sets the \fI\%logLevel\fP to \fB2\fP: .INDENT 7.0 .INDENT 3.5 .sp @@ -1146,14 +1423,22 @@ db.adminCommand( { setParameter: 1, logLevel: 2 } ) .UNINDENT .UNINDENT .sp -The default \fI\%logLevel\fP is \fB0\fP\&. -.sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 -\fBverbosity\fP\&. +.INDENT 0.0 +.IP \(bu 2 +\fI\%logComponentVerbosity\fP +.IP \(bu 2 +\fBverbosity\fP +.UNINDENT .UNINDENT .UNINDENT +.IP [2] 5 +Starting in version 4.2, MongoDB includes the Debug verbosity level +(1\-5) in the log messages\&. For example, +if the verbosity level is 2, MongoDB logs \fBD2\fP\&. In previous +versions, MongoDB log messages only specified \fBD\fP for Debug level. .UNINDENT .INDENT 0.0 .TP @@ -1165,19 +1450,19 @@ Available for both \fBmongod\fP and \fBmongos\fP\&. .sp Sets the verbosity levels of various components for log messages\&. The verbosity level determines the amount of Informational and Debug -messages MongoDB outputs. +messages MongoDB outputs. [3] .sp The verbosity level can range from \fB0\fP to \fB5\fP: .INDENT 7.0 .IP \(bu 2 -\fB0\fP is the MongoDB’s default log verbosity level, to include +\fB0\fP is the MongoDB\(aqs default log verbosity level, to include Informational messages. .IP \(bu 2 \fB1\fP to \fB5\fP increases the verbosity level to include Debug messages. .UNINDENT .sp -For a component, you can also specify \fB\-1\fP to inherit the parent’s +For a component, you can also specify \fB\-1\fP to inherit the parent\(aqs verbosity level. .sp To specify the verbosity level, use a document similar to the @@ -1237,6 +1522,8 @@ The components correspond to the following settings: .IP \(bu 2 \fBcontrol\fP .IP \(bu 2 +\fBftdc\fP +.IP \(bu 2 \fBgeo\fP .IP \(bu 2 \fBindex\fP @@ -1247,6 +1534,14 @@ The components correspond to the following settings: .IP \(bu 2 \fBreplication\fP .IP \(bu 2 +\fBreplication.election\fP +.IP \(bu 2 +\fBreplication.heartbeats\fP +.IP \(bu 2 +\fBreplication.initialSync\fP +.IP \(bu 2 +\fBreplication.rollback\fP +.IP \(bu 2 \fBrecovery\fP .IP \(bu 2 \fBsharding\fP @@ -1255,6 +1550,8 @@ The components correspond to the following settings: .IP \(bu 2 \fBstorage.journal\fP .IP \(bu 2 +\fBtransaction\fP +.IP \(bu 2 \fBwrite\fP .UNINDENT .sp @@ -1316,6 +1613,11 @@ mongod \-\-setParameter "logComponentVerbosity={command: 3}" The \fBmongo\fP shell also provides the \fBdb.setLogLevel()\fP to set the log level for a single component. For various ways to set the log verbosity level, see log\-messages\-configure\-verbosity\&. +.IP [3] 5 +Starting in version 4.2, MongoDB includes the Debug verbosity level +(1\-5) in the log messages\&. For example, +if the verbosity level is 2, MongoDB logs \fBD2\fP\&. In previous +versions, MongoDB log messages only specified \fBD\fP for Debug level. .UNINDENT .INDENT 0.0 .TP @@ -1423,6 +1725,39 @@ db.adminCommand( { setParameter: 1, traceExceptions: true } ) .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B suppressNoTLSPeerCertificateWarning +New in version 4.0.1. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +\fIType\fP: boolean +.sp +\fIDefault\fP: false +.sp +By default, a \fBmongod\fP or \fBmongos\fP with +TLS/SSL enabled and +\fBnet.ssl.allowConnectionsWithoutCertificates\fP : \fBtrue\fP +lets clients connect without providing a certificate for +validation while logging an warning. Set +\fBsuppressNoTLSPeerCertificateWarning\fP to \fB1\fP or \fBtrue\fP to +suppress those warnings. +.sp +The following operation sets \fBsuppressNoTLSPeerCertificateWarning\fP +to \fBtrue\fP: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, suppressNoTLSPeerCertificateWarning: true} ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS Diagnostic Parameters .sp To facilitate analysis of the MongoDB server behavior by MongoDB @@ -1430,13 +1765,13 @@ engineers, MongoDB logs server statistics to diagnostic files at periodic intervals. .sp For \fBmongod\fP, the diagnostic data files are stored in the -\fBdiagnostic.data\fP directory under the \fBmongod\fP instance’s +\fBdiagnostic.data\fP directory under the \fBmongod\fP instance\(aqs \fB\-\-dbpath\fP or \fBstorage.dbPath\fP\&. .sp For \fBmongos\fP, the diagnostic data files, by default, are -stored in a directory under the \fBmongos\fP instance’s +stored in a directory under the \fBmongos\fP instance\(aqs \fB\-\-logpath\fP or \fBsystemLog.path\fP directory. The diagnostic -data directory is computed by truncating the logpath’s file +data directory is computed by truncating the logpath\(aqs file extension(s) and concatenating \fBdiagnostic.data\fP to the remaining name. .sp @@ -1464,7 +1799,7 @@ for specific diagnostic purposes. New in version 3.2. .sp -Changed in version 3.6: Available for both \fBmongod\fP and \fBmongos\fP\&. +Changed in version 3.4.14: Available for both \fBmongod\fP and \fBmongos\fP\&. .sp \fIType\fP: boolean @@ -1489,7 +1824,7 @@ mongod \-\-setParameter diagnosticDataCollectionEnabled=false .INDENT 0.0 .TP .B diagnosticDataCollectionDirectoryPath -New in version 3.6. +New in version 3.4.14. .sp \fIType\fP: String @@ -1501,7 +1836,7 @@ Specify the directory for the diagnostic directory for \fBmongos\fP creates the directory. .sp If unspecified, the diagnostic data directory is computed by -truncating the \fBmongos\fP instance’s \fB\-\-logpath\fP or +truncating the \fBmongos\fP instance\(aqs \fB\-\-logpath\fP or \fBsystemLog.path\fP file extension(s) and concatenating \fBdiagnostic.data\fP\&. .sp @@ -1528,7 +1863,7 @@ New in version 3.2. Changed in version 3.4: Increased default size to 200 megabytes. .sp -Changed in version 3.6: Available for both \fBmongod\fP and \fBmongos\fP\&. +Changed in version 3.4.14: Available for both \fBmongod\fP and \fBmongos\fP\&. .sp \fIType\fP: integer @@ -1565,7 +1900,7 @@ be greater than maximum diagnostic file size New in version 3.2. .sp -Changed in version 3.6: Available for both \fBmongod\fP and \fBmongos\fP\&. +Changed in version 3.4.14: Available for both \fBmongod\fP and \fBmongos\fP\&. .sp \fIType\fP: integer @@ -1598,7 +1933,7 @@ The minimum value for New in version 3.2. .sp -Changed in version 3.6: Available for both \fBmongod\fP and \fBmongos\fP\&. +Changed in version 3.4.14: Available for both \fBmongod\fP and \fBmongos\fP\&. .sp \fIType\fP: integer @@ -1628,31 +1963,36 @@ milliseconds. .SS Logical Session Parameters .INDENT 0.0 .TP -.B logicalSessionRefreshMinutes -New in version 3.6. - +.B logicalSessionRefreshMillis +.INDENT 7.0 +.INDENT 3.5 +.IP "Availability" +.sp +New in version 4.0.4 (and version 3.6.9). +.UNINDENT +.UNINDENT .sp Available for both \fBmongod\fP and \fBmongos\fP\&. .sp \fIType\fP: integer .sp -\fIDefault\fP: 5 +\fIDefault\fP: 300000 (i.e. 5 minutes) .sp -The interval (in minutes) at which the cache refreshes its logical +The interval (in milliseconds) at which the cache refreshes its logical session records against the main session store. .sp -You can only set \fI\%logicalSessionRefreshMinutes\fP at +You can only set \fI\%logicalSessionRefreshMillis\fP at startup and cannot change this setting with the \fBsetParameter\fP command. .sp -For example, to set the \fI\%logicalSessionRefreshMinutes\fP +For example, to set the \fI\%logicalSessionRefreshMillis\fP for a \fBmongod\fP instance to 10 minutes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -mongod \-\-setParameter logicalSessionRefreshMinutes=10 +mongod \-\-setParameter logicalSessionRefreshMillis=600000 .ft P .fi .UNINDENT @@ -1748,6 +2088,35 @@ mongod \-\-setParameter maxAcceptableLogicalClockDriftSecs=900 .UNINDENT .INDENT 0.0 .TP +.B maxSessions +New in version 4.0.1. + +.sp +Available for both \fBmongod\fP and \fBmongos\fP\&. +.sp +\fIType\fP: integer +.sp +\fIDefault\fP: 1000000 +.sp +The maximum number of sessions that can be cached. +.sp +You can only set \fI\%maxSessions\fP during start\-up. +.sp +For example, to set the \fI\%maxSessions\fP +for a \fBmongod\fP instance to 1000: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter maxSessions=1000 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B TransactionRecordMinimumLifetimeMinutes New in version 3.6. @@ -1786,75 +2155,71 @@ mongod \-\-setParameter TransactionRecordMinimumLifetimeMinutes=20 .UNINDENT .UNINDENT .UNINDENT +.SS Replication Parameters .INDENT 0.0 .TP -.B maxTransactionLockRequestTimeoutMillis -New in version 4.0. +.B enableFlowControl +New in version 4.2. .sp -Available for \fBmongod\fP only. +\fIType\fP: boolean .sp -\fIType\fP: integer +\fIDefault\fP: true .sp -\fIDefault\fP: 5 +Enables or disables the mechanism that controls the rate at which the +primary applies its writes with the goal of keeping the secondary members\(aq +\fBmajority committed\fP lag under a +configurable maximum value. .sp -The amount of time in milliseconds that multi\-document -transactions should wait to aquire locks -required by the operations in the transaction. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For flow control to engage, the replica set/sharded cluster must +have: featureCompatibilityVersion (FCV) of +\fB4.2\fP and read concern \fBmajority enabled\fP\&. That is, enabled flow +control has no effect if FCV is not \fB4.2\fP or if read concern +majority is disabled. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B flowControlTargetLagSeconds +New in version 4.2. + .sp -If the transaction cannot aquire the locks after waiting -\fI\%maxTransactionLockRequestTimeoutMillis\fP, the transaction -aborts. +\fIType\fP: integer .sp -By default, multi\-document transactions -wait \fB5\fP milliseconds. That is, if the transaction cannot acquire -the locks within \fB5\fP milliseconds, the transaction aborts. If an -operation provides a greater timeout in a lock request, -\fI\%maxTransactionLockRequestTimeoutMillis\fP overrides the -operation\-specific timeout. +\fIDefault\fP: 10 .sp -You can set \fI\%maxTransactionLockRequestTimeoutMillis\fP to: -.INDENT 7.0 -.IP \(bu 2 -\fB0\fP such that if the transaction cannot acquire the required -locks immediately, the transaction aborts. -.IP \(bu 2 -A number greater than \fB0\fP to wait the specified time to acquire -the required locks. This can help obviate transaction aborts on -momentary concurrent lock acquisitions, like fast\-running metadata -operations. However, this could possibly delay the abort of -deadlocked transaction operations. -.IP \(bu 2 -\fB\-1\fP to use the operation specific timeout. -.UNINDENT +The target maximum \fBmajority committed\fP lag when running +with flow control. When flow control is enabled, the mechanism +attempts to keep the \fBmajority committed\fP lag under +the specified seconds. The parameter has no effect if flow control +is disabled. .sp -The following sets the -\fI\%maxTransactionLockRequestTimeoutMillis\fP to \fB20\fP -milliseconds: -.INDENT 7.0 -.INDENT 3.5 +The specified value must be greater than 0. .sp -.nf -.ft C -db.adminCommand( { setParameter: 1, maxTransactionLockRequestTimeoutMillis: 20 } ) -.ft P -.fi -.UNINDENT +In general, the default settings should suffice; however, if +modifying from the default value, decreasing, rather than +increasing, the value may prove to be more useful. .UNINDENT +.INDENT 0.0 +.TP +.B flowControlWarnThresholdSeconds +New in version 4.2. + .sp -You can also set this parameter during start\-up: -.INDENT 7.0 -.INDENT 3.5 +\fIType\fP: integer .sp -.nf -.ft C -mongod \-\-setParameter maxTransactionLockRequestTimeoutMillis=20 -.ft P -.fi -.UNINDENT -.UNINDENT +\fIDefault\fP: 10 +.sp +The amount of time to wait to log a warning once the flow control +mechanism detects the majority commit point has not moved. +.sp +The specified value must be greater than or equal to 0, with 0 to +disable warnings. .UNINDENT -.SS Replication Parameters .INDENT 0.0 .TP .B oplogInitialFindMaxSeconds @@ -1873,31 +2238,6 @@ data synchronization\&. .UNINDENT .INDENT 0.0 .TP -.B replIndexPrefetch -Available for \fBmongod\fP only. -.sp -Use \fI\%replIndexPrefetch\fP in conjunction with -\fBreplSetName\fP when configuring a replica -set. The default value is \fBall\fP and available -options are: -.INDENT 7.0 -.IP \(bu 2 -\fBnone\fP -.IP \(bu 2 -\fBall\fP -.IP \(bu 2 -\fB_id_only\fP -.UNINDENT -.sp -By default secondary members of a replica set will -load all indexes related to an operation into memory before -applying operations from the oplog. You can modify this behavior so -that the secondaries will only load the \fB_id\fP index. Specify -\fB_id_only\fP or \fBnone\fP to prevent the \fBmongod\fP from -loading \fIany\fP index into memory. -.UNINDENT -.INDENT 0.0 -.TP .B replWriterThreadCount New in version 3.2. @@ -1916,23 +2256,33 @@ setting with the \fBsetParameter\fP command. .INDENT 0.0 .TP .B rollbackTimeLimitSecs -New in version 4.0. +Changed in version 4.2. .sp \fIType\fP: 64\-bit integer .sp -\fIDefault\fP: 1800 +\fIDefault\fP: 86400 (1 day) .sp -Maximum age of data that will be rolled back in the event of a -replication operations failure. If the time between the end of the -rolled back instance oplog and the common point (the last point where -the source node and the rolled back node had the same data) exceeds -this value, the rollback will fail. Note that negative values for +Maximum age of data that can be rolled back. Negative values for this parameter are not valid. .sp -To set an effectively unlimited rollback period, set the value to +Starting in MongoDB 4.2, if the time between the end of the +to\-be\-rolledback instance\(aqs oplog and the first operation after the +common point (the last point where the source node and the +to\-be\-rolledback node had the same data) exceeds this value, the +rollback will fail. +.sp +In MongoDB 4.0, if the time between the end of the to\-be\-rolledback +instance\(aqs oplog and the common point (the last point where the +source node and the to\-be\-rolledback node had the same data) exceeds +this value, the rollback will fail. +.sp +To effectively have an unlimited rollback period, set the value to \fB2147483647\fP which is the maximum value allowed and equivalent to roughly 68 years. +.sp +New in version 4.0. + .UNINDENT .INDENT 0.0 .TP @@ -1954,7 +2304,7 @@ time, the secondary makes a no\-op write to advance the last applied time. .sp The following example sets the -\fI\%waitForSecondaryBeforeNoopWriteMS\fP to 20 seconds: +\fI\%waitForSecondaryBeforeNoopWriteMS\fP to 20 milliseconds: .INDENT 7.0 .INDENT 3.5 .sp @@ -2025,36 +2375,86 @@ db.adminCommand( { setParameter: 1, createRollbackDataFiles: false } ) .sp For more information, see rollback\-data\-files\&. .UNINDENT -.SS Sharding Parameters .INDENT 0.0 .TP -.B AsyncRequestsSenderUseBaton -Type: boolean +.B enableElectionHandoff +New in version 4.0.2. + .sp -Default: true +\fIType\fP: boolean .sp -A flag that enables performance optimization on Linux for -scatter/gather operations on \fBmongos\fP when using a -single \fI\%Task Executor connection pool\fP\&. +\fIDefault\fP: true .sp -\fBSEE ALSO:\fP +A flag that can reduce the downtime after the primary steps down +from either the \fBrs.stepDown()\fP method or the +\fBreplSetStepDown\fP command. Specifically, if true, when a +primary steps down after \fBrs.stepDown()\fP (or the +\fBreplSetStepDown\fP command without the \fBforce: true\fP), +it nominates an eligible secondary to call an election immediately. +If false, after the step down, secondaries can wait up to +\fBsettings.electionTimeoutMillis\fP before calling an election. +.sp +An eligible secondary must be caught up with the stepped down +primary and have \fBpriority\fP greater than 0. If +multiple secondary members meet this criteria, the stepped down +primary selects the eligible secondary with the highest +\fBpriority\fP\&. If the more than one eligible +secondary members have the same \fBpriority\fP, the +stepped down primary selects the secondary with the lowest +\fB_id\fP\&. The stepped down primary does not wait +for the effects of the handoff. +.sp +The parameter has no impact if the primary steps down for reasons +other than \fBrs.stepDown()\fP (or the +\fBreplSetStepDown\fP command without the \fBforce: true\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B replBatchLimitBytes +\fIDefault\fP: 104857600 (100MB) +.sp +Sets the maximum oplog application batch size in bytes. +.sp +Values can range from 16777216 (16MB) to 104857600 (100MB) inclusive. +.sp +The following example sets \fI\%replBatchLimitBytes\fP +to 64 MB so that the rollback files are not created: .INDENT 7.0 .INDENT 3.5 -\fI\%taskExecutorPoolSize\fP +.sp +.nf +.ft C +mongod \-\-setParameter replBatchLimitBytes=67108864 +.ft P +.fi .UNINDENT .UNINDENT .sp -New in version 4.0. +During runtime, you can also set the parameter with the +\fBsetParameter\fP command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, replBatchLimitBytes: 64 * 1024 * 1024 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 4.0.10. .UNINDENT -.INDENT 0.0 -.TP -.B recoverShardingState -Available for \fBmongod\fP only. +.SS Sharding Parameters .sp -Specify a boolean to check or ignore sharding state recovery -information. Default is \fBtrue\fP to check the sharding state -recovery information. +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Starting in version 4.2, MongoDB removes the parameter +\fBAsyncRequestsSenderUseBaton\fP and always enables the performance +enhancement controlled by the parameter. +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -2122,7 +2522,7 @@ this setting using the \fBsetParameter\fP database command. .sp If set, \fI\%ShardingTaskExecutorPoolHostTimeoutMS\fP should be greater than the sum of -:parameter\(gaShardingTaskExecutorPoolRefreshRequirementMS\(ga and +\fI\%ShardingTaskExecutorPoolRefreshRequirementMS\fP and \fI\%ShardingTaskExecutorPoolRefreshTimeoutMS\fP\&. Otherwise, \fBmongos\fP adjusts the value of \fI\%ShardingTaskExecutorPoolHostTimeoutMS\fP to be greater than the @@ -2238,7 +2638,7 @@ pool can open to any given \fBmongod\fP instance. first time a connection to a new host is requested from the pool. While the pool is idle, the pool maintains this number of connections until \fI\%ShardingTaskExecutorPoolHostTimeoutMS\fP -milliseconds pass without the any application using that pool. +milliseconds pass without any application using that pool. .sp You can only set this parameter during start\-up and cannot change this setting using the \fBsetParameter\fP database command. @@ -2328,6 +2728,103 @@ mongos \-\-setParameter ShardingTaskExecutorPoolRefreshTimeoutMS=30000 .UNINDENT .INDENT 0.0 .TP +.B ShardingTaskExecutorPoolReplicaSetMatching +New in version 4.2. + +.sp +Type: string +.sp +Default: "matchPrimaryNode" +.sp +Available for \fBmongos\fP only. +.sp +The policy that determines the minimum size limit of the +\fBmongos\fP instance\(aqs connection pools to the sharded +cluster\(aqs replica set secondaries. +.sp +Available values are: +.TS +center; +|l|l|. +_ +T{ +Matching Policy +T} T{ +Description +T} +_ +T{ +\fB"matchPrimaryNode"\fP (Default) +T} T{ +For each replica set in the sharded cluster (i.e. shard +replica set and config servers), the minimum size limit of +the \fBmongos\fP instance\(aqs connection pool to each +secondary of that replica set is equal to the size of its +connection pool to the primary. +.sp +In case of primary stepdown, \fBmatchPrimaryNode\fP ensures +that any secondary that becomes the primary can handle the +current level of primary reads and writes. +T} +_ +T{ +\fB"matchBusiestNode"\fP +T} T{ +For each replica set in the sharded cluster (i.e. shard +replica set and config servers), the minimum size limit of +the \fBmongos\fP instance\(aqs connection pool to each +member of that replica set is equal to the largest among +the active connections counts to the primary and each +secondary members. +.sp +With \fB"matchBusiestNode"\fP, \fBmongos\fP maintains +enough connections to each secondary to handle the current +level of primary and secondary reads and writes. The number +of connections to maintain in the pool decreases as the +number of active connections decreases. +T} +_ +T{ +\fB"disabled"\fP +T} T{ +For each replica set in the sharded cluster (i.e. shard +replica set and config servers), the minimum number of +connections in the \fBmongos\fP instance\(aqs +connection pool to each secondary is equal to the +\fI\%ShardingTaskExecutorPoolMinSize\fP\&. +T} +_ +.TE +.sp +The following example sets the +\fI\%ShardingTaskExecutorPoolReplicaSetMatching\fP to +\fB"matchBusiestNode"\fP during startup: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter ShardingTaskExecutorPoolReplicaSetMatching="matchBusiestNode" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +During runtime, you can also set the parameter with the +\fBsetParameter\fP command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, ShardingTaskExecutorPoolReplicaSetMatching: "matchBusiestNode" } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B taskExecutorPoolSize Changed in version 4.0. @@ -2354,9 +2851,18 @@ Executor connection pools is 64. .UNINDENT .sp Starting in MongoDB 4.0, the default value of -\fI\%taskExecutorPoolSize\fP is \fB1\fP\&. For the previous -behavior, set \fI\%taskExecutorPoolSize\fP to 0 and, on Linux, -set \fI\%AsyncRequestsSenderUseBaton\fP to \fBfalse\fP\&. +\fI\%taskExecutorPoolSize\fP is \fB1\fP: +.INDENT 7.0 +.IP \(bu 2 +In MongoDB 4.0 deployment, you can set +\fI\%taskExecutorPoolSize\fP to \fB0\fP and, on Linux, set +\fI\%AsyncRequestsSenderUseBaton\fP to +\fBfalse\fP for the previous behavior. +.IP \(bu 2 +In MongoDB 4.2+ deployment, MongoDB removes the +\fBAsyncRequestsSenderUseBaton\fP parameter and always enables the +performance enhancement controlled by the parameter. +.UNINDENT .sp You can only set this parameter during start\-up and cannot change this setting using the \fBsetParameter\fP database command. @@ -2385,6 +2891,95 @@ mongos \-\-setParameter taskExecutorPoolSize=6 .UNINDENT .INDENT 0.0 .TP +.B migrateCloneInsertionBatchDelayMS +New in version 4.0.5: The parameter is also available starting in 3.4.18 and 3.6.10 + +.sp +Available for \fBmongod\fP only. +.sp +Type: Non\-negative integer +.sp +Default: 0 +.sp +Time in milliseconds to wait between batches of insertions during +cloning step of the migration process. This wait is in addition to +the \fBsecondaryThrottle\fP\&. +.sp +The default value of \fB0\fP indicates no additional wait. +.sp +The following sets the \fI\%migrateCloneInsertionBatchDelayMS\fP to 200 +milliseconds: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter migrateCloneInsertionBatchDelayMS=200 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The parameter may also be set using the \fBsetParameter\fP +command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, migrateCloneInsertionBatchDelayMS: 200 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B migrateCloneInsertionBatchSize +New in version 4.0.5: The parameter is also available starting in 3.4.18 and 3.6.10 + +.sp +Available for \fBmongod\fP only. +.sp +Type: Non\-negative integer +.sp +Default: 0 +.sp +The maximum number of documents to insert in a single batch during +the cloning step of the migration process. +.sp +The default value of \fB0\fP indicates no maximum number of documents +per batch. However, in practice, this results in batches that +contain up to 16 MB of documents. +.sp +The following sets the \fI\%migrateCloneInsertionBatchSize\fP to 100 +documents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter migrateCloneInsertionBatchSize=100 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The parameter may also be set using the \fBsetParameter\fP +command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, migrateCloneInsertionBatchSize: 100 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B orphanCleanupDelaySecs New in version 3.6. @@ -2443,6 +3038,146 @@ db.adminCommand( { setParameter: 1, orphanCleanupDelaySecs: 1200 } ) .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B rangeDeleterBatchDelayMS +New in version 4.0.1: The parameter is also available starting in 3.4.17 and 3.6.7. + +.sp +Available for \fBmongod\fP only. +.sp +Type: Non\-negative integer +.sp +Default: 20 +.sp +The amount of time in milliseconds to wait before the next batch of +deletion during the cleanup stage of chunk migration (or the \fBcleanupOrphaned\fP +command). +.sp +In MongoDB 3.4, consider whether _secondaryThrottle is set before modifying the +\fI\%rangeDeleterBatchDelayMS\fP\&. In MongoDB 3.4, the +_secondaryThrottle replication delay occurs after each document deletion +instead of after the batch deletion. +.sp +In MongoDB 3.6+, the _secondaryThrottle replication delay occurs after each batch deletion. +.sp +The following sets the \fI\%rangeDeleterBatchDelayMS\fP to 200 +milliseconds: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter rangeDeleterBatchDelayMS=200 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The parameter may also be set using the \fBsetParameter\fP +command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, rangeDeleterBatchDelayMS: 200 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B rangeDeleterBatchSize +New in version 4.0.5: The parameter is also available starting in 3.4.19 and 3.6.10 + +.sp +Available for \fBmongod\fP only. +.sp +Type: Non\-negative integer +.sp +Default: 0 +.sp +The maximum number of documents in each batch to delete during the +cleanup stage of chunk migration +(or the \fBcleanupOrphaned\fP command). +.sp +The default value of \fB0\fP indicates that the system chooses an +appropriate value, generally 128 documents. +.sp +The following sets the \fI\%rangeDeleterBatchSize\fP to 100 +documents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter rangeDeleterBatchSize=100 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The parameter may also be set using the \fBsetParameter\fP +command: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, rangeDeleterBatchSize: 100 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B skipShardingConfigurationChecks +New in version 3.6.3. + +.sp +Available for \fBmongod\fP only. +.sp +Type: boolean +.sp +Default: false +.sp +When \fBtrue\fP, allows for starting a shard member or config server +member as a standalone for maintenance operations. This parameter is +mutually exclusive with the \fB\-\-configsvr\fP or \fB\-\-shardsvr\fP options. +.sp +You can only set this parameter during start\-up and cannot change +this setting using the \fBsetParameter\fP database command. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter skipShardingConfigurationChecks=true +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +Once maintenance has completed, remove the +\fI\%skipShardingConfigurationChecks\fP parameter when +restarting the \fBmongod\fP\&. +.UNINDENT +.UNINDENT +.sp +The parameter is also available for MongoDB versions: +.INDENT 7.0 +.IP \(bu 2 +MongoDB 3.2.19+ +.IP \(bu 2 +MongoDB 3.4.11+ +.UNINDENT +.UNINDENT .SS Storage Parameters .INDENT 0.0 .TP @@ -2514,7 +3249,7 @@ New in version 3.6. .sp If \fI\%honorSystemUmask\fP is set to \fBtrue\fP, new files created by MongoDB have permissions in accordance with the -user’s \fBumask\fP settings. +user\(aqs \fBumask\fP settings. .sp If \fI\%honorSystemUmask\fP is set to \fBfalse\fP, new files created by MongoDB have permissions set to \fB600\fP, which gives @@ -2654,7 +3389,8 @@ New in version 2.6.5. \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in \fI\%MongoDB Enterprise\fP\&. +Available only in \fI\%MongoDB Enterprise\fP +and \fI\%MongoDB Atlas\fP\&. .UNINDENT .UNINDENT .sp @@ -2698,6 +3434,8 @@ more than logging only the authorization failures. New in version 4.0. .sp +Available for \fBmongod\fP only. +.sp \fIDefault\fP: 60 .sp Specifies the lifetime of multi\-document transactions\&. Transactions that exceeds this limit are @@ -2706,8 +3444,14 @@ process. The cleanup process runs every \fI\%transactionLifetimeLimitSeconds\fP/2 seconds or at least once per every 60 seconds. .sp +The cleanup process helps relieve storage cache pressure. +.sp The minimum value for transactionLifetimeLimitSeconds is \fB1\fP second. +.sp +The following sets the +\fI\%transactionLifetimeLimitSeconds\fP to \fB30\fP +seconds: .INDENT 7.0 .INDENT 3.5 .sp @@ -2731,10 +3475,81 @@ mongod \-\-setParameter "transactionLifetimeLimitSeconds=30" .fi .UNINDENT .UNINDENT +.sp +To set the parameter for a sharded cluster, the parameter must be +modified for all shard replica set members. +.UNINDENT +.INDENT 0.0 +.TP +.B maxTransactionLockRequestTimeoutMillis +New in version 4.0. + +.sp +Available for \fBmongod\fP only. +.sp +\fIType\fP: integer +.sp +\fIDefault\fP: 5 +.sp +The maximum amount of time in milliseconds that multi\-document +transactions should wait to acquire locks +required by the operations in the transaction. +.sp +If the transaction cannot acquire the locks after waiting +\fI\%maxTransactionLockRequestTimeoutMillis\fP, the transaction +aborts. +.sp +By default, multi\-document transactions +wait \fB5\fP milliseconds. That is, if the transaction cannot acquire +the locks within \fB5\fP milliseconds, the transaction aborts. If an +operation provides a greater timeout in a lock request, +\fI\%maxTransactionLockRequestTimeoutMillis\fP overrides the +operation\-specific timeout. +.sp +You can set \fI\%maxTransactionLockRequestTimeoutMillis\fP to: +.INDENT 7.0 +.IP \(bu 2 +\fB0\fP such that if the transaction cannot acquire the required +locks immediately, the transaction aborts. +.IP \(bu 2 +A number greater than \fB0\fP to wait the specified time to acquire +the required locks. This can help obviate transaction aborts on +momentary concurrent lock acquisitions, like fast\-running metadata +operations. However, this could possibly delay the abort of +deadlocked transaction operations. +.IP \(bu 2 +\fB\-1\fP to use the operation specific timeout. +.UNINDENT +.sp +The following sets the +\fI\%maxTransactionLockRequestTimeoutMillis\fP to \fB20\fP +milliseconds: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +db.adminCommand( { setParameter: 1, maxTransactionLockRequestTimeoutMillis: 20 } ) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can also set this parameter during start\-up: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongod \-\-setParameter maxTransactionLockRequestTimeoutMillis=20 +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2008-2018 +2008-2019 .\" Generated by docutils manpage writer. . diff --git a/debian/mongodump.1 b/debian/mongodump.1 index 317550be310..2463ce09767 100644 --- a/debian/mongodump.1 +++ b/debian/mongodump.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGODUMP" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGODUMP" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongodump \- MongoDB Data Dump Utility . @@ -35,6 +35,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .IP \(bu 2 \fI\%Synopsis\fP .IP \(bu 2 +\fI\%Usage in Backup Strategy\fP +.IP \(bu 2 \fI\%Syntax\fP .IP \(bu 2 \fI\%Behavior\fP @@ -58,13 +60,14 @@ of mongodump\&. \fI\%mongodump\fP is a utility for creating a binary export of the contents of a database. \fI\%mongodump\fP can export data from either \fBmongod\fP or \fBmongos\fP instances. +.SH USAGE IN BACKUP STRATEGY +.SS Standalones/Replica Sets .sp -\fI\%mongodump\fP can be a part of a backup strategy with \fBmongorestore\fP for partial -backups based on a query, syncing from production to staging or -development environments, or changing the storage engine of a -standalone. However, the use of \fI\%mongodump\fP and -\fBmongorestore\fP as a backup strategy can be problematic for -sharded clusters and replica sets. +For standalone or a replica set, \fI\%mongodump\fP can be a part +of a backup strategy with +\fBmongorestore\fP for partial backups based on a query, +syncing from production to staging or development environments, or +changing the storage engine of a standalone. .sp For an overview of \fI\%mongodump\fP in conjunction with \fBmongorestore\fP part of a backup and recovery strategy, see: @@ -72,10 +75,25 @@ For an overview of \fI\%mongodump\fP in conjunction with .IP \(bu 2 /tutorial/backup\-and\-restore\-tools .IP \(bu 2 -/tutorial/backup\-sharded\-cluster\-with\-database\-dumps -.IP \(bu 2 /core/backups .UNINDENT +.SS Sharded Cluster +.sp +Starting in MongoDB 4.2, \fI\%mongodump\fP and +\fBmongorestore\fP \fBcannot\fP be part of a backup +strategy for sharded clusters. These manual tools do not maintain +the atomicity guarantees of transactions across shards. +.sp +To maintain the atomicity guarantees of transactions across shards, +use the coordinated backup and restore services provided by: +.INDENT 0.0 +.IP \(bu 2 +\fI\%MongoDB Atlas\fP, +.IP \(bu 2 +\fI\%MongoDB Cloud Manager\fP, or +.IP \(bu 2 +\fI\%MongoDB Ops Manager\fP\&. +.UNINDENT .SH SYNTAX .sp Run \fI\%mongodump\fP from the system command line, not the \fBmongo\fP shell. @@ -370,6 +388,23 @@ read\-only views\&. By default, create a binary export of the documents included in the view. To capture the documents in a view use \fI\%\-\-viewsAsCollections\fP\&. +.SS Metadata Format +.sp +Starting in version 4.2, \fI\%mongodump\fP uses Extended +JSON v2.0 (Canonical) format +for the metadata files. To parse these files for restore, use +\fBmongorestore\fP version 4.2+ that supports Extended +JSON v2.0 (Canonical or Relaxed mode) format. +.INDENT 0.0 +.INDENT 3.5 +.SS Tip +.sp +If general, use corresponding versions of \fI\%mongodump\fP +and \fBmongorestore\fP\&. That is, to restore data files +created with a specific version of \fI\%mongodump\fP, use the +corresponding version of \fBmongorestore\fP\&. +.UNINDENT +.UNINDENT .SS Overwrite Files .sp \fI\%mongodump\fP overwrites output files if they exist in the @@ -932,11 +967,28 @@ to the dump files. .INDENT 0.0 .TP .B \-\-query <json>, \-q <json> -Provides a JSON document as a query that optionally limits the -documents included in the output of \fI\%mongodump\fP\&. +Provides a JSON document as a query that optionally limits +the documents included in the output of \fI\%mongodump\fP\&. To +use the \fB\-\-query\fP option, you must also specify the +\fI\%\-\-collection\fP option. .sp You must enclose the query document in single quotes (\fB\(aq{ ... }\(aq\fP) to ensure that it does not interact with your shell environment. +.sp +Starting in MongoDB 4.2, the query \fBmust\fP be in +Extended JSON v2 format (either relaxed or canonical/strict +mode), including enclosing the +field names and operators in quotes. For example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongodump \-d test \-c records \-q \(aq{ "a": { "$gte": 3 }, "date": { "$lt": { "$date": "2016\-01\-01T00:00:00.000Z" } } }\(aq +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP diff --git a/debian/mongoexport.1 b/debian/mongoexport.1 index cbab4dc4ffb..94ed4651bc8 100644 --- a/debian/mongoexport.1 +++ b/debian/mongoexport.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOEXPORT" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOEXPORT" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongoexport \- MongoDB Export Utility . @@ -387,13 +387,20 @@ kind of functionality. .UNINDENT .UNINDENT .sp -To preserve type information, \fI\%mongoexport\fP and \fBmongoimport\fP -uses the strict mode representation -for certain types. +Starting in version 4.2, \fI\%mongoexport\fP: +.INDENT 0.0 +.IP \(bu 2 +Outputs data in Extended JSON v2.0 (Relaxed mode) by default. +.IP \(bu 2 +Outputs Extended JSON v2.0 (Canonical mode) if used with +\fI\%\-\-jsonFormat\fP\&. +.UNINDENT +.sp +Earlier versions used Extended JSON v1.0 (Canonical mode)\&. .sp For example, the following insert operation in the \fBmongo\fP -shell uses the shell mode representation for the BSON types -\fBdata_date\fP and \fBdata_numberlong\fP: +shell uses the various shell helpers for the +BSON types Date and 64\-bit integer: .INDENT 0.0 .INDENT 3.5 .sp @@ -406,7 +413,7 @@ db.traffic.insert( { _id: 1, volume: NumberLong(\(aq2980000\(aq), date: new Date .UNINDENT .UNINDENT .sp -The argument to \fBdata_numberlong\fP must be quoted to avoid potential +The argument to 64\-bit integer must be quoted to avoid potential loss of accuracy. .sp Use \fI\%mongoexport\fP to export the data: @@ -421,20 +428,57 @@ mongoexport \-\-db test \-\-collection traffic \-\-out traffic.json .UNINDENT .UNINDENT .sp -The exported data is in strict mode representation to preserve type information: +In version 4.2+, the exported data is in Extended JSON v2.0 +(Relaxed mode)\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{"_id":1.0,"volume":2980000,"date":{"$date":"2019\-08\-05T16:18:29.559Z"}} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To output in Extended JSON v2.0 (Canonical +mode), include the +\fI\%\-\-jsonFormat=canonical\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoexport \-\-db test \-\-collection traffic \-\-jsonFormat=canonical \-\-out traffic.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The exported data is in Extended JSON v2.0 (Canonical +mode): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -{ "_id" : 1, "volume" : { "$numberLong" : "2980000" }, "date" : { "$date" : "2014\-03\-13T13:47:42.483\-0400" } } +{"_id":{"$numberDouble":"1.0"},"volume":{"$numberLong":"2980000"},"date":{"$date":{"$numberLong":"1565363188675"}}} .ft P .fi .UNINDENT .UNINDENT .sp -See /reference/mongodb\-extended\-json for a complete list of -these types and the representations used. +In version 4.0 and earlier, the exported data is in Extended JSON v1.0 (Strict mode) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{"_id":1.0,"volume":{"$numberLong":"2980000"},"date":{"$date":"2019\-08\-05T16:18:29.559Z"}} +.ft P +.fi +.UNINDENT +.UNINDENT .SS FIPS .sp Starting in version 4.2, MongoDB removes the \fB\-\-sslFIPSMode\fP @@ -1017,12 +1061,16 @@ See \fI\%Use a File to Specify the Fields to Export in CSV Format\fP for sample .TP .B \-\-query <JSON>, \-q <JSON> Provides a query as a JSON document (enclosed in quotes) to -return matching documents in the export. Specify JSON in strict -format\&. +return matching documents in the export. .sp You must enclose the query document in single quotes (\fB\(aq{ ... }\(aq\fP) to ensure that it does not interact with your shell environment. .sp +Starting in MongoDB 4.2, the query \fBmust\fP be in +Extended JSON v2 format (either relaxed or canonical/strict +mode), including enclosing the +field names and operators in quotes: +.sp For example, given a collection named \fBrecords\fP in the database \fBtest\fP with the following documents: .INDENT 7.0 @@ -1041,17 +1089,18 @@ For example, given a collection named \fBrecords\fP in the database .UNINDENT .UNINDENT .sp -The following \fI\%mongoexport\fP uses the \fI\%\-q\fP option to -export only the documents with the field \fBa\fP greater than or equal to -(\fB$gte\fP) to \fB3\fP and the field \fBdate\fP less than -\fBISODate("2016\-01\-01T00:00:00Z")\fP (using the strict format -for dates { "$date": "YYYY\-MM\-DDTHH:mm:ss.mmm<offset>"}): +The following \fI\%mongoexport\fP uses the \fI\%\-q\fP option +to export only the documents with the field \fBa\fP greater than or +equal to (\fB$gte\fP) to \fB3\fP and the field \fBdate\fP less than +\fBISODate("2016\-01\-01T00:00:00Z")\fP (using the extended JSON v2 +format (relaxed mode) for dates { "$date": +"YYYY\-MM\-DDTHH:mm:ss.mmm<offset>"}): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -mongoexport \-d test \-c records \-q \(aq{ a: { $gte: 3 }, date: { $lt: { "$date": "2016\-01\-01T00:00:00.000Z" } } }\(aq \-\-out exportdir/myRecords.json +mongoexport \-d test \-c records \-q \(aq{ "a": { "$gte": 3 }, "date": { "$lt": { "$date": "2016\-01\-01T00:00:00.000Z" } } }\(aq \-\-out exportdir/myRecords.json .ft P .fi .UNINDENT @@ -1097,6 +1146,17 @@ name, the \fI\%mongoexport\fP writes data to standard output .UNINDENT .INDENT 0.0 .TP +.B \-\-jsonFormat <canonical|relaxed> +\fIDefault\fP: relaxed +.sp +Modifies the output to use either canonical or relaxed mode of the +/reference/mongodb\-extended\-json format. +.sp +For differences between canonical and relaxed modes, see +/reference/mongodb\-extended\-json\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-jsonArray Modifies the output of \fI\%mongoexport\fP to write the entire contents of the export as a single JSON array. By @@ -1463,7 +1523,7 @@ database using the "\fI\%\-\-db\fP" option. For instance, this command returns all documents in the \fBsales\fP database\(aqs \fBcontacts\fP collection that contain a field named \fBdept\fP equal to \fB"ABC"\fP and the field \fBdate\fP greater than or equal to -ISODate("2018\-01\-01") (using the strict format for dates +ISODate("2018\-01\-01") (using the canonical format for dates { "$date": "YYYY\-MM\-DDTHH:mm:ss.mmm<offset>"} ) .INDENT 0.0 .INDENT 3.5 diff --git a/debian/mongofiles.1 b/debian/mongofiles.1 index 742fd9d7af5..49475149358 100644 --- a/debian/mongofiles.1 +++ b/debian/mongofiles.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOFILES" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOFILES" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongofiles \- MongoDB GridFS Utility . @@ -767,14 +767,25 @@ different location for the file on the local file system, use the .UNINDENT .INDENT 0.0 .TP -.B get_id "<ObjectId>" +.B get_id "<_id>" New in version 3.2.0. .sp -Copy the specified file from GridFS storage to the local file system. +Copy the file, specified by its \fB<_id>\fP, from GridFS storage to the +local file system. .sp -Here \fB<ObjectId>\fP refers to the extended JSON \fB_id\fP of the -object in GridFS. \fI\%mongofiles\fP writes the file to the local +Here \fB<_id>\fP refers to the extended JSON \fB_id\fP of the +object in GridFS: +.INDENT 7.0 +.IP \(bu 2 +Starting in MongoDB 4.2, \fBget_id\fP can accept either ObjectId +values or non\-ObjectId values for \fB<_id>\fP\&. +.IP \(bu 2 +In MongoDB 4.0 and earlier, \fBget_id\fP only +accepts \fB<ObjectId>\fP values. +.UNINDENT +.sp +\fI\%mongofiles\fP writes the file to the local file system using the file\(aqs \fBfilename\fP in GridFS. To choose a different location for the file on the local file system, use the \fI\%\-\-local\fP option. @@ -786,12 +797,19 @@ Delete the specified file from GridFS storage. .UNINDENT .INDENT 0.0 .TP -.B delete_id "<ObjectId>" +.B delete_id "<_id>" New in version 3.2.0. .sp -Delete the specified file from GridFS storage. Specify the file using -its \fB_id\fP\&. +Delete the file, specified by its \fB<_id>\fP, from GridFS storage: +.INDENT 7.0 +.IP \(bu 2 +Starting in MongoDB 4.2, \fBdelete_id\fP can accept +either ObjectId values or non\-ObjectId values for \fB<_id>\fP\&. +.IP \(bu 2 +In MongoDB 4.0 and earlier, \fBdelete_id\fP only +accepts \fB<ObjectId>\fP values. +.UNINDENT .UNINDENT .SH EXAMPLES .sp diff --git a/debian/mongoimport.1 b/debian/mongoimport.1 index c494b85d758..f72ce2ce4df 100644 --- a/debian/mongoimport.1 +++ b/debian/mongoimport.1 @@ -1,8 +1,8 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOIMPORT" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOIMPORT" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME -mongoimport \- MongoDB LDAP Configuration Testing Utility +mongoimport \- MongoDB Import Utility . .nr rst2man-indent-level 0 . @@ -35,683 +35,1375 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .IP \(bu 2 \fI\%Synopsis\fP .IP \(bu 2 -\fI\%Usage\fP +\fI\%Behavior\fP +.IP \(bu 2 +\fI\%Required Access\fP .IP \(bu 2 \fI\%Options\fP +.IP \(bu 2 +\fI\%Examples\fP .UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "macOS Sierra and Go 1.6 Incompatibility" .sp -New in version 3.4: MongoDB Enterprise - +Users running on macOS Sierra require the 3.2.10 or newer version +of mongoimport\&. +.UNINDENT +.UNINDENT .SH SYNOPSIS .sp -Starting in version 3.4, MongoDB Enterprise provides -\fI\%mongoldap\fP for testing MongoDB\(aqs LDAP configuration -options against a running LDAP server or set -of servers. -.sp -To validate the LDAP options in the configuration file, set the -\fI\%mongoldap\fP \fI\%\-\-config\fP option to the configuration file\(aqs -path. -.sp -To test the LDAP configuration options, you must specify a \fI\%\-\-user\fP -and \fB\-\-password\fP\&. \fI\%mongoldap\fP simulates authentication to a -MongoDB server running with the provided configuration options and credentials. +The \fI\%mongoimport\fP tool imports content from an +Extended JSON, CSV, or TSV export +created by \fBmongoexport\fP, or potentially, another third\-party export +tool. .sp -\fI\%mongoldap\fP returns a report that includes the success or failure of -any step in the LDAP authentication or authorization procedure. Error messages -include information on specific errors encountered and potential advice for -resolving the error. +See the mongoexport document for more information regarding +\fBmongoexport\fP, which provides the inverse "exporting" +capability. .sp -When configuring options related to LDAP authorization, \fI\%mongoldap\fP executes an LDAP query -constructed using the provided configuration options and username, and returns -a list of roles on the \fBadmin\fP database which the user is authorized for. +Run \fI\%mongoimport\fP from the system command line, not the \fBmongo\fP shell. +.SH BEHAVIOR .sp -You can use this information when configuring LDAP authorization roles for user access control. For example, use -\fI\%mongoldap\fP to ensure your configuration allows privileged users to -gain the necessary roles to perform their expected tasks. Similarly, use -\fI\%mongoldap\fP to ensure your configuration disallows non\-privileged -users from gaining roles for accessing the MongoDB server, or performing -unauthorized actions. +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Avoid using \fI\%mongoimport\fP and \fBmongoexport\fP for +full instance production backups. They do not reliably preserve all rich +BSON data types, because JSON can only represent a subset +of the types supported by BSON. Use \fBmongodump\fP +and \fBmongorestore\fP as described in /core/backups for this +kind of functionality. +.UNINDENT +.UNINDENT +.SS JSON Format .sp -When configuring options related to LDAP authentication, use \fI\%mongoldap\fP to ensure that the authentication -operation works as expected. +Starting in MongoDB 4.2, \fI\%mongoimport\fP expects import data +to be in Extended JSON v2.0 (either Relaxed or Canonical mode) +by default. To recognize data that is in Extended JSON v1.0 format, see +\fI\%\-\-legacy\fP\&. .sp -Run \fI\%mongoldap\fP from the system command line, not the \fBmongo\fP shell. +In earlier versions, \fI\%mongoimport\fP expects data in +/reference/mongodb\-extended\-json\-v1 format. +.INDENT 0.0 +.INDENT 3.5 +.SS Tip .sp -This document provides a complete overview of all command line options for -\fI\%mongoldap\fP\&. -.SH USAGE +In general, the versions of \fBmongoexport\fP and +\fI\%mongoimport\fP should match. That is, to import data +created from \fBmongoexport\fP, you should use the +corresponding version of \fI\%mongoimport\fP\&. +.UNINDENT +.UNINDENT +.SS Encoding +.sp +\fI\%mongoimport\fP only supports data files that are UTF\-8 encoded. +Using other encodings will produce errors. +.SS FIPS +.sp +Starting in version 4.2, MongoDB removes the \fB\-\-sslFIPSMode\fP +option for mongoimport\&. mongoimport +will use FIPS compliant connections to +\fBmongod\fP/\fBmongos\fP if the +\fBmongod\fP/\fBmongos\fP instances are +configured to use FIPS mode\&. +.SS Write Concern +.sp +Starting in version 4.2, if you specify write concern in both the +\fI\%\-\-writeConcern\fP option and the +\fI\%\-\-uri connection string\fP option, the +\fI\%\-\-writeConcern\fP value overrides +the write concern specified in the URI string. +.sp +In earlier versions, the two options are incompatible. +.SH REQUIRED ACCESS +.sp +In order to connect to a \fBmongod\fP that enforces authorization +with the \fB\-\-auth\fP option, you must use the +\fB\-\-username\fP and \fB\-\-password\fP options. The connecting user must +possess, at a minimum, the \fBreadWrite\fP role on the database +into which they are importing data. +.SH OPTIONS .sp -\fBNOTE:\fP +Changed in version 3.0.0: \fI\%mongoimport\fP removed the \fB\-\-dbpath\fP as well as related +\fB\-\-directoryperdb\fP and \fB\-\-journal\fP options. To use +\fI\%mongoimport\fP, you must run \fI\%mongoimport\fP against a running +\fBmongod\fP or \fBmongos\fP instance as appropriate. + .INDENT 0.0 -.INDENT 3.5 -A full description of LDAP or Active Directory is beyond the scope of -this documentation. +.TP +.B mongoimport .UNINDENT +.INDENT 0.0 +.TP +.B \-\-help +Returns information on the options and use of \fBmongoimport\fP\&. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-verbose, \-v +Increases the amount of internal reporting returned on standard output +or in log files. Increase the verbosity with the \fB\-v\fP form by +including the option multiple times, (e.g. \fB\-vvvvv\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quiet +Runs \fBmongoimport\fP in a quiet mode that attempts to limit the amount +of output. .sp -Consider the following sample configuration file, designed to support -LDAP authentication and authorization via Active Directory: +This option suppresses: +.INDENT 7.0 +.IP \(bu 2 +output from database commands +.IP \(bu 2 +replication activity +.IP \(bu 2 +connection accepted events +.IP \(bu 2 +connection closed events +.UNINDENT +.UNINDENT .INDENT 0.0 +.TP +.B \-\-version +Returns the \fBmongoimport\fP release number. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-uri <connectionString> +New in version 3.4.6. + +.sp +Specify a resolvable URI +connection string (enclose in quotes) to connect to the MongoDB deployment. +.INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -security: - authorization: "enabled" - ldap: - servers: "activedirectory.example.net" - bind: - queryUser: "mongodbadmin@dba.example.com" - queryPassword: "secret123" - userToDNMapping: - \(aq[ - { - match : "(.+)", - ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" - } - ]\(aq - authz: - queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" -setParameter: - authenticationMechanisms: "PLAIN" +\-\-uri "mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]" .ft P .fi .UNINDENT .UNINDENT .sp -You can use \fI\%mongoldap\fP to validate the configuration file, which -returns a report of the procedure. You must specify a username and password -for \fI\%mongoldap\fP\&. +For information on the components of the connection string, see +the Connection String URI Format documentation. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For TLS/SSL options, use the command\-line options instead of the +URI options for TLS/SSL (Available starting in +4.2)\&. +.UNINDENT +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +The following command\-line options cannot be used in conjunction +with \fI\%\-\-uri\fP option: +.INDENT 0.0 +.IP \(bu 2 +\fI\%\-\-host\fP +.IP \(bu 2 +\fI\%\-\-port\fP +.IP \(bu 2 +\fI\%\-\-db\fP +.IP \(bu 2 +\fI\%\-\-username\fP +.IP \(bu 2 +\fI\%\-\-password\fP (if the +URI connection string also includes the password) +.IP \(bu 2 +\fI\%\-\-authenticationDatabase\fP +.IP \(bu 2 +\fI\%\-\-authenticationMechanism\fP +.UNINDENT +.sp +Instead, specify these options as part of your \fI\%\-\-uri\fP +connection string. +.UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 +.TP +.B \-\-host <hostname><:port>, \-h <hostname><:port> +\fIDefault\fP: localhost:27017 +.sp +Specifies a resolvable hostname for the \fBmongod\fP to which to +connect. By default, the \fBmongoimport\fP attempts to connect to a MongoDB +instance running on the localhost on port number \fB27017\fP\&. +.sp +To connect to a replica set, specify the +\fBreplSetName\fP and a seed list of set members, as in +the following: +.INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -mongoldap \-\-config <path\-to\-config> \-\-user "bob@dba.example.com" \-\-password "secret123" +\-\-host <replSetName>/<hostname1><:port>,<hostname2><:port>,<...> .ft P .fi .UNINDENT .UNINDENT .sp -If the provided credentials are valid, and the LDAP options in the -configuration files are valid, the output might be as follows: -.INDENT 0.0 +When specifying the replica set list format, \fBmongoimport\fP always connects to +the primary\&. +.sp +You can also connect to any single member of the replica set by specifying +the host and port of only that member: +.INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -Checking that an LDAP server has been specified... -[OK] LDAP server found - -Connecting to LDAP server... -[OK] Connected to LDAP server - -Parsing MongoDB to LDAP DN mappings.. -[OK] MongoDB to LDAP DN mappings appear to be valid - -Attempting to authenticate against the LDAP server... -[OK] Successful authentication performed - -Checking if LDAP authorization has been enabled by configuration... -[OK] LDAP authorization enabled - -Parsing LDAP query template.. -[OK] LDAP query configuration template appears valid - -Executing query against LDAP server... -[OK] Successfully acquired the following roles: -\&... +\-\-host <hostname1><:port> .ft P .fi .UNINDENT .UNINDENT -.SH OPTIONS +.sp +Changed in version 3.0.0: If you use IPv6 and use the \fB<address>:<port>\fP format, you must +enclose the portion of an address and port combination in +brackets (e.g. \fB[<address>]\fP). + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +You cannot specify both \fI\%\-\-host\fP and \fI\%\-\-uri\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP -.B \-\-config <filename>, \-f <filename> -Specifies a configuration file for runtime configuration options. -The options are equivalent to the command\-line -configuration options. See /reference/configuration\-options for -more information. +.B \-\-port <port> +\fIDefault\fP: 27017 .sp -\fBmongoldap\fP uses any configuration options related to security\-ldap -or security\-ldap\-external for testing LDAP authentication or -authorization. +Specifies the TCP port on which the MongoDB instance listens for +client connections. .sp -Requires specifying \fI\%\-\-user\fP\&. May accept \fI\%\-\-password\fP for -testing LDAP authentication. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +You cannot specify both \fI\%\-\-port\fP and \fI\%\-\-uri\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ipv6 +\fIRemoved in version 3.0.\fP .sp -Ensure the configuration file uses ASCII encoding. The \fBmongoldap\fP -instance does not support configuration files with non\-ASCII encoding, -including UTF\-8. +Enables IPv6 support and allows \fBmongoimport\fP to connect to the +MongoDB instance using an IPv6 network. Prior to MongoDB 3.0, you +had to specify \fI\%\-\-ipv6\fP to use IPv6. In MongoDB 3.0 and later, IPv6 +is always enabled. .UNINDENT .INDENT 0.0 .TP -.B \-\-user <string> -Username for \fBmongoldap\fP to use when attempting LDAP authentication or -authorization. +.B \-\-ssl +New in version 2.6. + +.sp +Enables connection to a \fBmongod\fP or \fBmongos\fP that has +TLS/SSL support enabled. +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-password <string> -Password of the \fB\-\-user\fP for \fBmongoldap\fP to use when attempting LDAP -authentication. Not required for LDAP authorization. +.B \-\-sslCAFile <filename> +New in version 2.6. + +.sp +Specifies the \fB\&.pem\fP file that contains the root certificate chain +from the Certificate Authority. Specify the file name of the +\fB\&.pem\fP file using relative or absolute paths. +.sp +Starting in version 3.4, if \fB\-\-tlsCAFile\fP/\fBnet.tls.CAFile\fP (or +their aliases \fB\-\-sslCAFile\fP/\fBnet.ssl.CAFile\fP) is not specified +and you are not using x.509 authentication, the system\-wide CA +certificate store will be used when connecting to an TLS/SSL\-enabled +server. +.sp +To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP or +\fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, +\fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using +\fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +\fBVersion 3.2 and earlier:\fP For TLS/SSL connections (\fB\-\-ssl\fP) to +\fBmongod\fP and \fBmongos\fP, if the \fBmongoimport\fP runs without the +\fI\%\-\-sslCAFile\fP, \fBmongoimport\fP will not attempt +to validate the server certificates. This creates a vulnerability +to expired \fBmongod\fP and \fBmongos\fP certificates as +well as to foreign processes posing as valid \fBmongod\fP or +\fBmongos\fP instances. Ensure that you \fIalways\fP specify the +CA file to validate the server certificates in cases where +intrusion is a possibility. +.UNINDENT +.UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapServers <host1>:<port>,<host2>:<port>,...,<hostN>:<port> -New in version 3.4: Available in MongoDB Enterprise only. +.B \-\-sslPEMKeyFile <filename> +New in version 2.6. .sp -The LDAP server against which the \fBmongoldap\fP executes LDAP operations -against to authenticate users or determine what actions a user is authorized -to perform on a given database. If the LDAP server specified has any -replicated instances, you may specify the host and port of each replicated -server in a comma\-delimited list. +Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate +and key. Specify the file name of the \fB\&.pem\fP file using relative +or absolute paths. .sp -If your LDAP infrastrucure partitions the LDAP directory over multiple LDAP -servers, specify \fIone\fP LDAP server any of its replicated instances to -\fI\%\-\-ldapServers\fP\&. MongoDB supports following LDAP referrals as defined in \fI\%RFC 4511 -4.1.10\fP\&. Do not use \fI\%\-\-ldapServers\fP -for listing every LDAP server in your infrastructure. +This option is required when using the \fI\%\-\-ssl\fP option to connect +to a \fBmongod\fP or \fBmongos\fP that has +\fBCAFile\fP enabled \fIwithout\fP +\fBallowConnectionsWithoutCertificates\fP\&. .sp -This setting can be configured on a running \fBmongoldap\fP using -\fBsetParameter\fP\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslPEMKeyPassword <value> +New in version 2.6. + .sp -If unset, \fBmongoldap\fP cannot use LDAP authentication or authorization\&. +Specifies the password to de\-crypt the certificate\-key file (i.e. +\fI\%\-\-sslPEMKeyFile\fP). Use the \fI\%\-\-sslPEMKeyPassword\fP option only if the +certificate\-key file is encrypted. In all cases, the \fBmongoimport\fP will +redact the password from all logging and reporting output. +.sp +If the private key in the PEM file is encrypted and you do not specify +the \fI\%\-\-sslPEMKeyPassword\fP option, the \fBmongoimport\fP will prompt for a passphrase. See +ssl\-certificate\-password\&. +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapQueryUser <string> -New in version 3.4: Available in MongoDB Enterprise only. +.B \-\-sslCRLFile <filename> +New in version 2.6. .sp -The identity with which \fBmongoldap\fP binds as, when connecting to or -performing queries on an LDAP server. +Specifies the \fB\&.pem\fP file that contains the Certificate Revocation +List. Specify the file name of the \fB\&.pem\fP file using relative or +absolute paths. .sp -Only required if any of the following are true: -.INDENT 7.0 -.IP \(bu 2 -Using LDAP authorization\&. -.IP \(bu 2 -Using an LDAP query for \fI\%username transformation\fP\&. -.IP \(bu 2 -The LDAP server disallows anonymous binds +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslAllowInvalidCertificates +New in version 2.6. + .sp -You must use \fI\%\-\-ldapQueryUser\fP with \fI\%\-\-ldapQueryPassword\fP\&. +Bypasses the validation checks for server certificates and allows +the use of invalid certificates. When using the +\fBallowInvalidCertificates\fP setting, MongoDB logs as a +warning the use of the invalid certificate. .sp -If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. +Starting in MongoDB 4.0, if you specify +\fB\-\-sslAllowInvalidCertificates\fP or +\fBnet.ssl.allowInvalidCertificates: true\fP (or in MongoDB 4.2, the +alias \fB\-\-tlsAllowInvalidateCertificates\fP or +\fBnet.tls.allowInvalidCertificates: true\fP) when using x.509 +authentication, an invalid certificate is only sufficient to +establish a TLS/SSL connection but is \fIinsufficient\fP for +authentication. .sp -This setting can be configured on a running \fBmongoldap\fP using -\fBsetParameter\fP\&. +# We created a separate blurb for tls in the ssl\-clients page. .sp -\fBNOTE:\fP +\fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 -Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP -instead of \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify -both \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. +Although available, avoid using the +\fB\-\-sslAllowInvalidCertificates\fP option if possible. If the use of +\fB\-\-sslAllowInvalidCertificates\fP is necessary, only use the option +on systems where intrusion is not possible. +.sp +If the \fBmongo\fP shell (and other +mongodb\-tools\-support\-ssl) runs with the +\fB\-\-sslAllowInvalidCertificates\fP option, the +\fBmongo\fP shell (and other +mongodb\-tools\-support\-ssl) will not attempt to validate +the server certificates. This creates a vulnerability to expired +\fBmongod\fP and \fBmongos\fP certificates as +well as to foreign processes posing as valid +\fBmongod\fP or \fBmongos\fP instances. If you +only need to disable the validation of the hostname in the +TLS/SSL certificates, see \fB\-\-sslAllowInvalidHostnames\fP\&. .UNINDENT .UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapQueryPassword <string> -New in version 3.4: Available in MongoDB Enterprise only. -.sp -The password used to bind to an LDAP server when using -\fI\%\-\-ldapQueryUser\fP\&. You must use \fI\%\-\-ldapQueryPassword\fP with -\fI\%\-\-ldapQueryUser\fP\&. +.B \-\-sslAllowInvalidHostnames +New in version 3.0. .sp -If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. +Disables the validation of the hostnames in TLS/SSL certificates. Allows +\fBmongoimport\fP to connect to MongoDB instances even if the hostname in their +certificates do not match the specified hostname. .sp -This setting can be configured on a running \fBmongoldap\fP using -\fBsetParameter\fP\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-username <username>, \-u <username> +Specifies a username with which to authenticate to a MongoDB database +that uses authentication. Use in conjunction with the \fI\%\-\-password\fP and +\fI\%\-\-authenticationDatabase\fP options. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP -instead of \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify -both \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. +You cannot specify both \fI\%\-\-username\fP and \fI\%\-\-uri\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapBindWithOSDefaults <bool> -\fIDefault\fP: False -.sp -New in version 3.4: Available in MongoDB Enterprise for the Windows platform only. +.B \-\-password <password>, \-p <password> +Specifies a password with which to authenticate to a MongoDB database +that uses authentication. Use in conjunction with the \fI\%\-\-username\fP and +\fI\%\-\-authenticationDatabase\fP options. +.sp +Changed in version 3.0.2: To prompt the user +for the password, pass the \fI\%\-\-username\fP option without +\fI\%\-\-password\fP or specify an empty string as the \fI\%\-\-password\fP value, +as in \fB\-\-password ""\fP . .sp -Allows \fBmongoldap\fP to authenticate, or bind, using your Windows login -credentials when connecting to the LDAP server. -.sp -Only required if: +\fBNOTE:\fP .INDENT 7.0 -.IP \(bu 2 -Using LDAP authorization\&. -.IP \(bu 2 -Using an LDAP query for \fI\%username transformation\fP\&. -.IP \(bu 2 -The LDAP server disallows anonymous binds +.INDENT 3.5 +You cannot specify both \fI\%\-\-password\fP and \fI\%\-\-uri\fP\&. +.UNINDENT .UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-authenticationDatabase <dbname> +Specifies the authentication database where the specified \fI\%\-\-username\fP has been created. +See user\-authentication\-database\&. .sp -Use \fI\%\-\-ldapBindWithOSDefaults\fP to replace \fI\%\-\-ldapQueryUser\fP and -\fI\%\-\-ldapQueryPassword\fP\&. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +You cannot specify both \fI\%\-\-authenticationDatabase\fP and \fI\%\-\-uri\fP\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapBindMethod <string> -\fIDefault\fP: simple +.B \-\-authenticationMechanism <name> +\fIDefault\fP: SCRAM\-SHA\-1 .sp -New in version 3.4: Available in MongoDB Enterprise only. +Specifies the authentication mechanism the \fBmongoimport\fP instance uses to +authenticate to the \fBmongod\fP or \fBmongos\fP\&. +.sp +Changed in version 4.0: MongoDB removes support for the deprecated MongoDB +Challenge\-Response (\fBMONGODB\-CR\fP) authentication mechanism. +.sp +MongoDB adds support for SCRAM mechanism using the SHA\-256 hash +function (\fBSCRAM\-SHA\-256\fP). +.TS +center; +|l|l|. +_ +T{ +Value +T} T{ +Description +T} +_ +T{ +SCRAM\-SHA\-1 +T} T{ +\fI\%RFC 5802\fP standard +Salted Challenge Response Authentication Mechanism using the SHA\-1 +hash function. +T} +_ +T{ +SCRAM\-SHA\-256 +T} T{ +\fI\%RFC 7677\fP standard +Salted Challenge Response Authentication Mechanism using the SHA\-256 +hash function. .sp -The method \fBmongoldap\fP uses to authenticate to an LDAP server. -Use with \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP to -connect to the LDAP server. +Requires featureCompatibilityVersion set to \fB4.0\fP\&. .sp -\fI\%\-\-ldapBindMethod\fP supports the following values: +New in version 4.0. +T} +_ +T{ +MONGODB\-X509 +T} T{ +MongoDB TLS/SSL certificate authentication. +T} +_ +T{ +GSSAPI (Kerberos) +T} T{ +External authentication using Kerberos. This mechanism is +available only in \fI\%MongoDB Enterprise\fP\&. +T} +_ +T{ +PLAIN (LDAP SASL) +T} T{ +External authentication using LDAP. You can also use \fBPLAIN\fP +for authenticating in\-database users. \fBPLAIN\fP transmits +passwords in plain text. This mechanism is available only in +\fI\%MongoDB Enterprise\fP\&. +T} +_ +.TE +.sp +\fBNOTE:\fP .INDENT 7.0 -.IP \(bu 2 -\fBsimple\fP \- \fBmongoldap\fP uses simple authentication. -.IP \(bu 2 -\fBsasl\fP \- \fBmongoldap\fP uses SASL protocol for authentication +.INDENT 3.5 +You cannot specify both \fI\%\-\-authenticationMechanism\fP and \fI\%\-\-uri\fP\&. +.UNINDENT .UNINDENT -.sp -If you specify \fBsasl\fP, you can configure the available SASL mechanisms -using \fI\%\-\-ldapBindSASLMechanisms\fP\&. \fBmongoldap\fP defaults to -using \fBDIGEST\-MD5\fP mechanism. .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapBindSASLMechanisms <string> -\fIDefault\fP: DIGEST\-MD5 -.sp -New in version 3.4: Available in MongoDB Enterprise only. +.B \-\-gssapiServiceName +New in version 2.6. .sp -A comma\-separated list of SASL mechanisms \fBmongoldap\fP can -use when authenticating to the LDAP server. The \fBmongoldap\fP and the -LDAP server must agree on at least one mechanism. The \fBmongoldap\fP -dynamically loads any SASL mechanism libraries installed on the host -machine at runtime. -.sp -Install and configure the appropriate libraries for the selected -SASL mechanism(s) on both the \fBmongoldap\fP host and the remote -LDAP server host. Your operating system may include certain SASL -libraries by default. Defer to the documentation associated with each -SASL mechanism for guidance on installation and configuration. -.sp -If using the \fBGSSAPI\fP SASL mechanism for use with -security\-kerberos, verify the following for the -\fBmongoldap\fP host machine: -.INDENT 7.0 -.TP -.B \fBLinux\fP -.INDENT 7.0 -.IP \(bu 2 -The \fBKRB5_CLIENT_KTNAME\fP environment -variable resolves to the name of the client keytab\-files -for the host machine. For more on Kerberos environment -variables, please defer to the -\fI\%Kerberos documentation\fP\&. -.IP \(bu 2 -The client keytab includes a -kerberos\-user\-principal for the \fBmongoldap\fP to use when -connecting to the LDAP server and execute LDAP queries. +Specify the name of the service using GSSAPI/Kerberos\&. Only required if the service does not use the +default name of \fBmongodb\fP\&. +.sp +This option is available only in MongoDB Enterprise. .UNINDENT +.INDENT 0.0 .TP -.B \fBWindows\fP -If connecting to an Active Directory server, the Windows -Kerberos configuration automatically generates a -\fI\%Ticket\-Granting\-Ticket\fP -when the user logs onto the system. Set \fI\%\-\-ldapBindWithOSDefaults\fP to -\fBtrue\fP to allow \fBmongoldap\fP to use the generated credentials when -connecting to the Active Directory server and execute queries. -.UNINDENT +.B \-\-gssapiHostName +New in version 2.6. + +.sp +Specify the hostname of a service using GSSAPI/Kerberos\&. \fIOnly\fP required if the hostname of a machine does +not match the hostname resolved by DNS. .sp -Set \fI\%\-\-ldapBindMethod\fP to \fBsasl\fP to use this option. +This option is available only in MongoDB Enterprise. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-db <database>, \-d <database> +Specifies the name of the database on which to run the \fBmongoimport\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -For a complete list of SASL mechanisms see the -\fI\%IANA listing\fP\&. -Defer to the documentation for your LDAP or Active Directory -service for identifying the SASL mechanisms compatible with the -service. -.sp -MongoDB is not a source of SASL mechanism libraries, nor -is the MongoDB documentation a definitive source for -installing or configuring any given SASL mechanism. For -documentation and support, defer to the SASL mechanism -library vendor or owner. +You cannot specify both \fI\%\-\-db\fP and \fI\%\-\-uri\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-collection <collection>, \-c <collection> +Specifies the collection to import. .sp -For more information on SASL, defer to the following resources: +New in version 2.6: If you do not specify \fI\%\-\-collection\fP, +\fI\%mongoimport\fP takes the collection name from the input +filename. MongoDB omits the extension of the file from the +collection name, if the input file has an extension. + +.UNINDENT .INDENT 0.0 -.IP \(bu 2 -For Linux, please see the \fI\%Cyrus SASL documentation\fP\&. -.IP \(bu 2 -For Windows, please see the \fI\%Windows SASL documentation\fP\&. +.TP +.B \-\-fields <field1[,field2]>, \-f <field1[,field2]> +Specify a comma separated list of field names when importing csv +or tsv files that do not have field names in the first (i.e. +header) line of the file. +.sp +If you attempt to include \fI\%\-\-fields\fP when importing JSON data, +\fBmongoimport\fP will return an error. \fI\%\-\-fields\fP is only for csv +or tsv imports. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-fieldFile <filename> +As an alternative to \fI\%\-\-fields\fP, the \fI\%\-\-fieldFile\fP +option allows you to specify a file that holds a list of field names if +your csv or tsv file does not include field names in the +first line of the file (i.e. header). Place one field per line. +.sp +If you attempt to include \fI\%\-\-fieldFile\fP when importing JSON data, +\fBmongoimport\fP will return an error. \fI\%\-\-fieldFile\fP is only for csv +or tsv imports. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-ignoreBlanks +Ignores empty fields in csv and tsv exports. If not +specified, \fI\%mongoimport\fP creates fields without values in +imported documents. +.sp +If you attempt to include \fI\%\-\-ignoreBlanks\fP when importing JSON data, +\fBmongoimport\fP will return an error. \fI\%\-\-ignoreBlanks\fP is only for csv +or tsv imports. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-type <json|csv|tsv> +Specifies the file type to import. The default format is JSON, +but it\(aqs possible to import csv and tsv files. +.sp +The \fBcsv\fP parser accepts that data that complies with RFC +\fI\%RFC 4180\fP\&. As a result, backslashes are \fInot\fP a valid escape +character. If you use double\-quotes to enclose fields in the CSV +data, you must escape internal double\-quote marks by prepending +another double\-quote. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-file <filename> +Specifies the location and name of a file containing the data to import. +If you do not specify a file, \fI\%mongoimport\fP reads data from +standard input (e.g. "stdin"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-drop +Modifies the import process so that the target instance drops +the collection before importing the data from the input. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-headerline +If using \fI\%\-\-type csv\fP or \fI\%\-\-type +tsv\fP, uses the first line as field names. +Otherwise, \fI\%mongoimport\fP will import the first line as a +distinct document. +.sp +If you attempt to include \fI\%\-\-headerline\fP when importing JSON data, +\fBmongoimport\fP will return an error. \fI\%\-\-headerline\fP is only for csv +or tsv imports. .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapTransportSecurity <string> -\fIDefault\fP: tls +.B \-\-mode insert|upsert|merge +\fIDefault\fP: insert .sp -New in version 3.4: Available in MongoDB Enterprise only. +New in version 3.4. .sp -By default, \fBmongoldap\fP creates a TLS/SSL secured connection to the LDAP -server. +Specifies how the import process should handle existing documents +in the database that match documents in the import file. .sp -For Linux deployments, you must configure the appropriate TLS Options in -\fB/etc/openldap/ldap.conf\fP file. Your operating system\(aqs package manager -creates this file as part of the MongoDB Enterprise installation, via the -\fBlibldap\fP dependency. See the documentation for \fBTLS Options\fP in the -\fI\%ldap.conf OpenLDAP documentation\fP -for more complete instructions. +By default, \fBmongoimport\fP uses the \fB_id\fP field to match documents in +the collection with documents in the import file. +To specify the fields against which to match existing +documents for the \fBupsert\fP and \fBmerge\fP modes, +use \fI\%\-\-upsertFields\fP\&. +.TS +center; +|l|l|. +_ +T{ +Value +T} T{ +Description +T} +_ +T{ +\fBinsert\fP +T} T{ +Insert the documents in the import file. \fBmongoimport\fP will log +an error if you attempt to import a document that contains a +duplicate value for a field with a unique index, such as \fB_id\fP\&. +T} +_ +T{ +\fBupsert\fP +T} T{ +Replace existing documents in the database with matching +documents from the +import file. \fBmongoimport\fP will insert all other +documents. \fI\%Replace Matching Documents during Import\fP describes how to +use \fI\%\-\-mode\fP \fBupsert\fP\&. +T} +_ +T{ +\fBmerge\fP +T} T{ +Merge existing documents that match a document in the import file with +the new document. \fBmongoimport\fP will insert all other documents. +\fI\%Merge Matching Documents during Import\fP describes how to use \fI\%\-\-mode\fP +\fBmerge\fP\&. +T} +_ +.TE +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-upsertFields <field1[,field2]> +Specifies a list of fields for the query portion of the +upsert\&. +Use this option if the \fB_id\fP fields in the +existing documents don\(aqt match the field in the document, but +another field or field combination can uniquely identify +documents as a basis for performing upsert operations. +.sp +Changed in version 3.4: Modifies the import process to update existing objects in the +database if they match based on the specified fields, while +inserting all other objects. You do not need to use \fI\%\-\-mode +upsert\fP with \fI\%\-\-upsertFields\fP\&. +.sp +If you do not specify a field, \fI\%\-\-upsertFields\fP will upsert on the basis of +the \fB_id\fP field. + .sp -For Windows deployment, you must add the LDAP server CA certificates to the -Windows certificate management tool. The exact name and functionality of the -tool may vary depending on operating system version. Please see the -documentation for your version of Windows for more information on -certificate management. +To ensure adequate performance, indexes should exist for this +field or fields. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-stopOnError +Forces \fBmongoimport\fP to halt the insert operation at the +first error rather than continuing the operation despite errors. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-jsonArray +Accepts the import of data expressed with multiple MongoDB documents +within a single JSON array. Limited to +imports of 16 MB or smaller. .sp -Set \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP to disable TLS/SSL between \fBmongoldap\fP and the LDAP -server. +Use \fI\%\-\-jsonArray\fP in conjunction with \fBmongoexport \-\-jsonArray\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-legacy +Indicates that the import data is in Extended JSON v1 format instead of the default +Extended JSON v2 format\&. +.INDENT 7.0 +.INDENT 3.5 +.SH TIP .sp -\fBWARNING:\fP +In general, the versions of \fBmongoexport\fP and +\fI\%mongoimport\fP should match. That is, to import +data created from \fBmongoexport\fP, you should use +the corresponding version of \fI\%mongoimport\fP\&. +.UNINDENT +.UNINDENT +.sp +For example, if the import data is in v1 format: .INDENT 7.0 .INDENT 3.5 -Setting \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP transmits plaintext information and possibly -credentials between \fBmongoldap\fP and the LDAP server. +.sp +.nf +.ft C +{"_id":1.0,"myregfield":{"$regex":"foo","$options":"i"}} +.ft P +.fi +.UNINDENT .UNINDENT +.sp +Import without the \fI\%\-\-legacy\fP option results in +the following document in the collection: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "_id" : 1, "myregfield" : { "$regex" : "foo", "$options" : "i" } } +.ft P +.fi .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-\-ldapTimeoutMS <long> -\fIDefault\fP: 10000 .sp -New in version 3.4: Available in MongoDB Enterprise only. - +Import with the \fI\%\-\-legacy\fP results in +the following document in the collection: +.INDENT 7.0 +.INDENT 3.5 .sp -The amount of time in milliseconds \fBmongoldap\fP should wait for an LDAP server -to respond to a request. +.nf +.ft C +{ "_id" : 1, "myregfield" : { "$regularExpression" : { "pattern" : "foo", "options" : "i" } } } +.ft P +.fi +.UNINDENT +.UNINDENT .sp -Increasing the value of \fI\%\-\-ldapTimeoutMS\fP may prevent connection failure between the -MongoDB server and the LDAP server, if the source of the failure is a -connection timeout. Decreasing the value of \fI\%\-\-ldapTimeoutMS\fP reduces the time -MongoDB waits for a response from the LDAP server. +New in version 4.2. + +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-maintainInsertionOrder +\fIDefault\fP: False .sp -This setting can be configured on a running \fBmongoldap\fP using -\fBsetParameter\fP\&. +If specified, \fBmongoimport\fP inserts the documents in the order of +their appearance in the input source, otherwise \fBmongoimport\fP may +perform the insertions in an arbitrary order. .UNINDENT .INDENT 0.0 .TP -.B \-\-ldapUserToDNMapping <string> -New in version 3.4: Available in MongoDB Enterprise only. +.B \-\-numInsertionWorkers int +\fIDefault\fP: 1 +.sp +New in version 3.0.0. .sp -Maps the username provided to \fBmongoldap\fP for authentication to a LDAP -Distinguished Name (DN). You may need to use \fI\%\-\-ldapUserToDNMapping\fP to transform a -username into an LDAP DN in the following scenarios: -.INDENT 7.0 -.IP \(bu 2 -Performing LDAP authentication with simple LDAP binding, where users -authenticate to MongoDB with usernames that are not full LDAP DNs. -.IP \(bu 2 -Using an \fBLDAP authorization query template\fP that requires a DN. -.IP \(bu 2 -Transforming the usernames of clients authenticating to Mongo DB using -different authentication mechanisms (e.g. x.509, kerberos) to a full LDAP -DN for authorization. +Specifies the number of insertion workers to run concurrently. +.sp +For large imports, increasing the number of insertion workers +may increase the speed of the import. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-writeConcern <document> +\fIDefault\fP: majority .sp -\fI\%\-\-ldapUserToDNMapping\fP expects a quote\-enclosed JSON\-string representing an ordered array -of documents. Each document contains a regular expression \fBmatch\fP and -either a \fBsubstitution\fP or \fBldapQuery\fP template used for transforming the -incoming username. +Specifies the write concern for each write operation that \fBmongoimport\fP +performs. .sp -Each document in the array has the following form: +Specify the write concern as a document with w options: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -{ - match: "<regex>" - substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>" -} +\-\-writeConcern "{w:\(aqmajority\(aq}" .ft P .fi .UNINDENT .UNINDENT +.sp +If the write concern is also included in the \fI\%\-\-uri +connection string\fP, the command\-line +\fI\%\-\-writeConcern\fP overrides the write concern specified in +the URI string. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-bypassDocumentValidation +Enables \fBmongoimport\fP to bypass document validation +during the operation. This lets you insert documents that do not +meet the validation requirements. +.sp +New in version 3.2.1. + +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-columnsHaveTypes +New in version 3.4. + +.sp +Instructs \fBmongoimport\fP that the +field list specified in \fI\%\-\-fields\fP, \fI\%\-\-fieldFile\fP, +or \fI\%\-\-headerline\fP specifies the types of each field. +.sp +Field names must be in the form of \fB<colName>.<type>(<arg>)\fP\&. You +must backslash\-escape the following characters if you wish to include +them in an argument: \fB(\fP, \fB)\fP, and \fB\e\fP\&. .TS center; |l|l|l|. _ T{ -Field +\fBtype\fP T} T{ -Description +Supported Arguments T} T{ -Example +Example Header Field T} _ T{ -\fBmatch\fP +\fBauto()\fP T} T{ -An ECMAScript\-formatted regular expression (regex) to match against a -provided username. Each parenthesis\-enclosed section represents a -regex capture group used by \fBsubstitution\fP or \fBldapQuery\fP\&. +None. T} T{ -\fB"(.+)ENGINEERING"\fP -\fB"(.+)DBA"\fP +\fBmisc.auto()\fP T} _ T{ -\fBsubstitution\fP +\fBbinary(<arg>)\fP +T} T{ +.INDENT 7.0 +.IP \(bu 2 +\fBbase32\fP (\fI\%RFC4648\fP encoding schema) +.IP \(bu 2 +\fBbase64\fP (\fI\%RFC4648\fP encoding schema) +.IP \(bu 2 +\fBhex\fP +.UNINDENT T} T{ -An LDAP distinguished name (DN) formatting template that converts the -authentication name matched by the \fBmatch\fP regex into a LDAP DN. -Each curly bracket\-enclosed numeric value is replaced by the -corresponding \fI\%regex capture group\fP extracted -from the authentication username via the \fBmatch\fP regex. +\fBuser thumbnail.binary(base64)\fP +T} +_ +T{ +\fBboolean()\fP +T} T{ +None. +T} T{ +\fBverified.boolean()\fP +T} +_ +T{ +\fBdate(<arg>)\fP +T} T{ +Alias for \fBdate_go(<arg>)\fP\&. \fI\%Go Language time.Parse format\fP\&. +T} T{ +\fBcreated.date(2006\-01\-02 15:04:05)\fP +T} +_ +T{ +\fBdate_go(<arg>)\fP +T} T{ +\fI\%Go Language time.Parse format\fP +T} T{ +\fBcreated.date_go(2006\-01\-02 15:04:05)\fP +T} +_ +T{ +\fBdate_ms(<arg>)\fP +T} T{ +\fI\%Microsoft SQL Server FORMAT format\fP +T} T{ +\fBcreated.date_ms(yyyy\-MM\-dd H:mm:ss)\fP +T} +_ +T{ +\fBdate_oracle(<arg>)\fP +T} T{ +\fI\%Oracle Database TO_DATE format\fP\&. +T} T{ +\fBcreated.date_oracle(YYYY\-MM\-DD HH24:MI:SS)\fP +T} +_ +T{ +\fBdecimal()\fP +T} T{ +None +T} T{ +\fBprice.decimal()\fP +T} +_ +T{ +\fBdouble()\fP +T} T{ +None. +T} T{ +\fBrevenue.double()\fP +T} +_ +T{ +\fBint32()\fP +T} T{ +None. +T} T{ +\fBfollowerCount.int32()\fP +T} +_ +T{ +\fBint64()\fP +T} T{ +None. +T} T{ +\fBbigNumber.int64()\fP +T} +_ +T{ +\fBstring()\fP +T} T{ +None. +T} T{ +\fBzipcode.string()\fP +T} +_ +.TE .sp -The result of the substitution must be an \fI\%RFC4514\fP escaped string. +See \fI\%Import CSV with Specified Field Types\fP for sample usage. +.sp +If you attempt to include \fI\%\-\-columnsHaveTypes\fP when importing JSON data, +\fBmongoimport\fP will return an error. \fI\%\-\-columnsHaveTypes\fP is only for csv +or tsv imports. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-parseGrace <grace> +\fIDefault\fP: stop +.sp +New in version 3.4. + +.sp +Specifies how \fBmongoimport\fP handles type coercion failures when importing +CSV or TSV files with \fI\%\-\-columnsHaveTypes\fP\&. +.sp +\fI\%\-\-parseGrace\fP has no effect when importing JSON documents. +.TS +center; +|l|l|. +_ +T{ +Value T} T{ -\fB"cn={0},ou=engineering, -dc=example,dc=com"\fP +Description T} _ T{ -\fBldapQuery\fP -T} T{ -A LDAP query formatting template that inserts the authentication -name matched by the \fBmatch\fP regex into an LDAP query URI encoded -respecting RFC4515 and RFC4516. Each curly bracket\-enclosed numeric -value is replaced by the corresponding \fI\%regex capture group\fP extracted -from the authentication username via the \fBmatch\fP expression. -\fBmongoldap\fP executes the query against the LDAP server to retrieve -the LDAP DN for the authenticated user. \fBmongoldap\fP requires -exactly one returned result for the transformation to be -successful, or \fBmongoldap\fP skips this transformation. -T} T{ -\fB"ou=engineering,dc=example, -dc=com??one?(user={0})"\fP +\fBautoCast\fP +T} T{ +Assigns a type based on the value of the field. +For example, if a field is defined as a \fBdouble\fP and the +value for that field was \fB"foo"\fP, \fBmongoimport\fP would make +that field value a string type. +T} +_ +T{ +\fBskipField\fP +T} T{ +For the row being imported, \fBmongoimport\fP does not include the +field whose type does not match the expected type. +T} +_ +T{ +\fBskipRow\fP +T} T{ +\fBmongoimport\fP does not import rows containing a value whose +type does not match the expected type. +T} +_ +T{ +\fBstop\fP +T} T{ +\fBmongoimport\fP returns an error that ends the import. T} _ .TE +.UNINDENT +.SH EXAMPLES +.SS Simple Import .sp -\fBNOTE:\fP -.INDENT 7.0 +\fI\%mongoimport\fP restores a database from a backup taken with +\fBmongoexport\fP\&. Most of the arguments to \fBmongoexport\fP also +exist for \fI\%mongoimport\fP\&. +.sp +In the following example, \fI\%mongoimport\fP imports +the JSON data from the \fBcontacts.json\fP file into the collection +\fBcontacts\fP in the \fBusers\fP database. +.INDENT 0.0 .INDENT 3.5 -An explanation of \fI\%RFC4514\fP, -\fI\%RFC4515\fP, -\fI\%RFC4516\fP, or LDAP queries is out -of scope for the MongoDB Documentation. Please review the RFC directly or -use your preferred LDAP resource. +.sp +.nf +.ft C +mongoimport \-\-db users \-\-collection contacts \-\-file contacts.json +.ft P +.fi .UNINDENT .UNINDENT +.SS Replace Matching Documents during Import .sp -For each document in the array, you must use either \fBsubstitution\fP or -\fBldapQuery\fP\&. You \fIcannot\fP specify both in the same document. +Changed in version 3.4: In MongoDB 3.4, \fI\%\-\-mode upsert\fP replaces the +deprecated \fB\-\-upsert\fP option. + .sp -When performing authentication or authorization, \fBmongoldap\fP steps through -each document in the array in the given order, checking the authentication -username against the \fBmatch\fP filter. If a match is found, -\fBmongoldap\fP applies the transformation and uses the output for -authenticating the user. \fBmongoldap\fP does not check the remaining documents -in the array. +With \fI\%\-\-mode\fP \fBupsert\fP, \fI\%mongoimport\fP replaces +existing documents in the database that match a document in the +import file with the document from the import file. +Documents that do not match an existing document in the database are +inserted as usual. By default \fI\%mongoimport\fP matches documents +based on the \fB_id\fP field. Use \fI\%\-\-upsertFields\fP to specify +the fields to match against. .sp -If the given document does not match the provided authentication name, or -the transformation described by the document fails, \fBmongoldap\fP continues -through the list of documents to find additional matches. If no matches are -found in any document, \fBmongoldap\fP returns an error. -.INDENT 7.0 +Consider the following document in the \fBpeople\fP collection in the +\fBexample\fP database: +.INDENT 0.0 .INDENT 3.5 -.SH EXAMPLE .sp -The following shows two transformation documents. The first -document matches against any string ending in \fB@ENGINEERING\fP, placing -anything preceeding the suffix into a regex capture group. The -second document matches against any string ending in \fB@DBA\fP, placing -anything preceeding the suffix into a regex capture group. +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "name" : "Crystal Duncan", + "region" : "United States", + "email" : "crystal@example.com" +} +.ft P +.fi +.UNINDENT +.UNINDENT .sp -\fBIMPORTANT:\fP +The following document exists in a \fBpeople\-20160927.json\fP JSON file. +The \fB_id\fP field of the JSON object matches the \fB_id\fP field of the +document in the \fBpeople\fP collection. .INDENT 0.0 .INDENT 3.5 -You must pass the array to \fI\%\-\-ldapUserToDNMapping\fP as a string. +.sp +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "username" : "crystal", + "likes" : [ "running", "pandas", "software development" ] +} +.ft P +.fi .UNINDENT .UNINDENT +.sp +To import the \fBpeople\-20160927.json\fP file and replace documents in +the database that match the documents in the import file, specify \fI\%\-\-mode\fP +\fBupsert\fP, as in the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -"[ - { - match: "(.+)@ENGINEERING.EXAMPLE.COM", - substitution: "cn={0},ou=engineering,dc=example,dc=com" - }, - { - match: "(.+)@DBA.EXAMPLE.COM", - ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})" - - } - -]" +mongoimport \-c people \-d example \-\-mode upsert \-\-file people\-20160927.json .ft P .fi .UNINDENT .UNINDENT .sp -A user with username \fBalice@ENGINEERING.EXAMPLE.COM\fP matches the first -document. The regex capture group \fB{0}\fP corresponds to the string -\fBalice\fP\&. The resulting output is the DN -\fB"cn=alice,ou=engineering,dc=example,dc=com"\fP\&. +The document in the \fBpeople\fP collection would then contain only +the fields from the imported document, as in the following: +.INDENT 0.0 +.INDENT 3.5 .sp -A user with username \fBbob@DBA.EXAMPLE.COM\fP matches the second document. -The regex capture group \fB{0}\fP corresponds to the string \fBbob\fP\&. The -resulting output is the LDAP query -\fB"ou=dba,dc=example,dc=com??one?(user=bob)"\fP\&. \fBmongoldap\fP executes this -query against the LDAP server, returning the result -\fB"cn=bob,ou=dba,dc=example,dc=com"\fP\&. +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "username" : "crystal", + "likes" : [ "running", "pandas", "software development" ] +} +.ft P +.fi .UNINDENT .UNINDENT +.SS Merge Matching Documents during Import .sp -If \fI\%\-\-ldapUserToDNMapping\fP is unset, \fBmongoldap\fP applies no transformations to the username -when attempting to authenticate or authorize a user against the LDAP server. +New in version 3.4. + .sp -This setting can be configured on a running \fBmongoldap\fP using the -\fBsetParameter\fP database command. -.UNINDENT +With \fI\%\-\-mode\fP \fBmerge\fP, \fI\%mongoimport\fP enables you to +merge fields from a new record with an existing document in the +database. Documents that do not match an existing document in the +database are inserted as usual. By default \fI\%mongoimport\fP +matches documents based on the \fB_id\fP field. Use +\fI\%\-\-upsertFields\fP to specify the fields to match against. +.sp +The \fBpeople\fP collection in the \fBexample\fP database contains the +following document: .INDENT 0.0 -.TP -.B \-\-ldapAuthzQueryTemplate <string> -New in version 3.4: Available in MongoDB Enterprise only. - +.INDENT 3.5 +.sp +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "name" : "Crystal Duncan", + "region" : "United States", + "email" : "crystal@example.com" +} +.ft P +.fi +.UNINDENT +.UNINDENT .sp -A relative LDAP query URL formatted conforming to \fI\%RFC4515\fP and \fI\%RFC4516\fP that \fBmongoldap\fP executes to obtain -the LDAP groups to which the authenticated user belongs to. The query is -relative to the host or hosts specified in \fI\%\-\-ldapServers\fP\&. +The following document exists in a \fBpeople\-20160927.json\fP JSON file. +The \fB_id\fP field of the JSON object matches the \fB_id\fP field of the +document in the \fBpeople\fP collection. +.INDENT 0.0 +.INDENT 3.5 .sp -Use the \fB{USER}\fP placeholder in the URL to substitute the authenticated -username, or the transformed username if a \fI\%username mapping\fP is specified. +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "username" : "crystal", + "email": "crystal.duncan@example.com", + "likes" : [ "running", "pandas", "software development" ] +} +.ft P +.fi +.UNINDENT +.UNINDENT .sp -When constructing the query URL, ensure that the order of LDAP parameters -respects RFC4516: -.INDENT 7.0 +To import the \fBpeople\-20160927.json\fP file and merge documents from +the import file with matching documents in the database, specify +\fI\%\-\-mode\fP \fBmerge\fP, as in the following: +.INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -[ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] +mongoimport \-c people \-d example \-\-mode merge \-\-file people\-20160927.json .ft P .fi .UNINDENT .UNINDENT .sp -If your query includes an attribute, \fBmongoldap\fP assumes that the query -retrieves a the DNs which this entity is member of. +The import operation combines the fields from the JSON file with the +original document in the database, +matching the documents based on the \fB_id\fP field. +During the import process, \fI\%mongoimport\fP adds the new \fBusername\fP and +\fBlikes\fP fields to the document and updates the \fBemail\fP field with +the value from the imported document, as in the following: +.INDENT 0.0 +.INDENT 3.5 .sp -If your query does not include an attribute, \fBmongoldap\fP assumes -the query retrieves all entities which the user is member of. +.nf +.ft C +{ + "_id" : ObjectId("580100f4da893943d393e909"), + "name" : "Crystal Duncan", + "region" : "United States", + "email" : "crystal.duncan@example.com", + "username" : "crystal", + "likes" : [ + "running", + "pandas", + "software development" + ] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Import \fBJSON\fP to Remote Host Running with Authentication .sp -For each LDAP DN returned by the query, \fBmongoldap\fP assigns the authorized -user a corresponding role on the \fBadmin\fP database. If a role on the on the -\fBadmin\fP database exactly matches the DN, \fBmongoldap\fP grants the user the -roles and privileges assigned to that role. See the -\fBdb.createRole()\fP method for more information on creating roles. -.INDENT 7.0 +In the following example, \fI\%mongoimport\fP imports data from the +file \fB/opt/backups/mdb1\-examplenet.json\fP into the \fBcontacts\fP collection +within the database \fBmarketing\fP on a remote MongoDB +database with authentication enabled. +.sp +\fI\%mongoimport\fP connects to the \fBmongod\fP instance running on +the host \fBmongodb1.example.net\fP over port \fB37017\fP\&. It authenticates with the +username \fBuser\fP and the password \fBpass\fP\&. +.INDENT 0.0 .INDENT 3.5 -.SH EXAMPLE .sp -This LDAP query returns any groups listed in the LDAP user object\(aqs -\fBmemberOf\fP attribute. +.nf +.ft C +mongoimport \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password "pass" \-\-collection contacts \-\-db marketing \-\-file /opt/backups/mdb1\-examplenet.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBCSV\fP Import +.SS General CSV Import +.sp +In the following example, \fI\%mongoimport\fP imports the csv +formatted data in the \fB/opt/backups/contacts.csv\fP file into the +collection \fBcontacts\fP in the \fBusers\fP database on the MongoDB +instance running on the localhost port numbered +\fB27017\fP\&. +.sp +Specifying \fI\%\-\-headerline\fP instructs +\fI\%mongoimport\fP to determine the name of the fields using the first +line in the CSV file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -"{USER}?memberOf?base" +mongoimport \-\-db users \-\-collection contacts \-\-type csv \-\-headerline \-\-file /opt/backups/contacts.csv .ft P .fi .UNINDENT .UNINDENT .sp -Your LDAP configuration may not include the \fBmemberOf\fP attribute as part -of the user schema, may possess a different attribute for reporting group -membership, or may not track group membership through attributes. -Configure your query with respect to your own unique LDAP configuration. +\fI\%mongoimport\fP uses the input file name, without the +extension, as the collection name if \fB\-c\fP or \fB\-\-collection\fP is +unspecified. The following example is therefore equivalent: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoimport \-\-db users \-\-type csv \-\-headerline \-\-file /opt/backups/contacts.csv +.ft P +.fi .UNINDENT .UNINDENT +.SS Import CSV with Specified Field Types .sp -If unset, \fBmongoldap\fP cannot authorize users using LDAP. +New in version 3.4. + .sp -This setting can be configured on a running \fBmongoldap\fP using the -\fBsetParameter\fP database command. +MongoDB 3.4 added support for specifying field types. Specify field +names and types in the form \fB<colName>.<type>(<arg>)\fP using +\fI\%\-\-fields\fP, \fI\%\-\-fieldFile\fP, or \fI\%\-\-headerline\fP\&. .sp -\fBNOTE:\fP -.INDENT 7.0 +Consider the following CSV data: +.INDENT 0.0 .INDENT 3.5 -An explanation of \fI\%RFC4515\fP, -\fI\%RFC4516\fP or LDAP queries is out -of scope for the MongoDB Documentation. Please review the RFC directly or -use your preferred LDAP resource. +.sp +.nf +.ft C +Katherine Gray, 1996\-02\-03, F, 1235, TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXggZWEgY29tbW9kbyBjb25zZXF1YXQuIER1aXMgYXV0ZSBpcnVyZSBkb2xvciBpbiByZXByZWhlbmRlcml0IGluIHZvbHVwdGF0ZSB2ZWxpdCBlc3NlIGNpbGx1bSBkb2xvcmUgZXUgZnVnaWF0IG51bGxhIHBhcmlhdHVyLiBFeGNlcHRldXIgc2ludCBvY2NhZWNhdCBjdXBpZGF0YXQgbm9uIHByb2lkZW50LCBzdW50IGluIGN1bHBhIHF1aSBvZmZpY2lhIGRlc2VydW50IG1vbGxpdCBhbmltIGlkIGVzdCBsYWJvcnVtLg== +Albert Gilbert, 1992\-04\-24, T, 13, Q3VwY2FrZSBpcHN1bSBkb2xvciBzaXQgYW1ldCB0b290c2llIHJvbGwgYm9uYm9uIHRvZmZlZS4gQ2FuZHkgY2FuZXMgcGllIGNyb2lzc2FudCBjaG9jb2xhdGUgYmFyIGxvbGxpcG9wIGJlYXIgY2xhdyBtYWNhcm9vbi4gU3dlZXQgcm9sbCBjdXBjYWtlIGNoZWVzZWNha2Ugc291ZmZsw6kgYnJvd25pZSBpY2UgY3JlYW0uIEp1anViZXMgY2FrZSBjdXBjYWtlIG1hY2Fyb29uIGRhbmlzaCBqZWxseS1vIHNvdWZmbMOpLiBDYWtlIGFwcGxlIHBpZSBnaW5nZXJicmVhZCBjaG9jb2xhdGUgc3VnYXIgcGx1bS4gU3dlZXQgY2hvY29sYXRlIGNha2UgY2hvY29sYXRlIGNha2UganVqdWJlcyB0aXJhbWlzdSBvYXQgY2FrZS4gU3dlZXQgc291ZmZsw6kgY2hvY29sYXRlLiBMaXF1b3JpY2UgY290dG9uIGNhbmR5IGNob2NvbGF0ZSBtYXJzaG1hbGxvdy4gSmVsbHkgY29va2llIGNha2UgamVsbHkgYm +.ft P +.fi .UNINDENT .UNINDENT +.sp +The \fI\%\-\-fields\fP option specifies which +field type \fI\%mongoimport\fP will use when importing the data +into MongoDB. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoimport \-\-db users \-\-collection contacts \-\-type csv \-\-columnsHaveTypes \-\-fields "name.string(),birthdate.date(2006\-01\-02),contacted.boolean(),followerCount.int32(),user thumbnail.binary(base64)" \-\-file /example/file.csv +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Ignore Blank Fields +.sp +Use the \fI\%\-\-ignoreBlanks\fP option +to ignore blank fields. For CSV and TSV imports, this +option provides the desired functionality in most cases because it avoids +inserting fields with null values into your collection. +.sp +The following example imports the data from \fBdata.csv\fP, skipping +any blank fields: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoimport \-\-db users \-\-collection contacts \-\-type csv \-\-file /example/data.csv \-\-ignoreBlanks +.ft P +.fi +.UNINDENT .UNINDENT .SH AUTHOR MongoDB Documentation Project diff --git a/debian/mongoldap.1 b/debian/mongoldap.1 new file mode 100644 index 00000000000..e3e606d4bf9 --- /dev/null +++ b/debian/mongoldap.1 @@ -0,0 +1,748 @@ +.\" Man page generated from reStructuredText. +. +.TH "MONGOLDAP" "1" "Aug 16, 2019" "4.2" "mongodb-manual" +.SH NAME +mongoldap \- MongoDB LDAP Configuration Testing 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 +.. +.SS On this page +.INDENT 0.0 +.IP \(bu 2 +\fI\%Synopsis\fP +.IP \(bu 2 +\fI\%Usage\fP +.IP \(bu 2 +\fI\%Options\fP +.UNINDENT +.sp +New in version 3.4: MongoDB Enterprise + +.SH SYNOPSIS +.sp +Starting in version 3.4, MongoDB Enterprise provides +\fI\%mongoldap\fP for testing MongoDB\(aqs LDAP configuration +options against a running LDAP server or set +of servers. +.sp +To validate the LDAP options in the configuration file, set the +\fI\%mongoldap\fP \fI\%\-\-config\fP option to the configuration file\(aqs +path. +.sp +To test the LDAP configuration options, you must specify a \fI\%\-\-user\fP +and \fB\-\-password\fP\&. \fI\%mongoldap\fP simulates authentication to a +MongoDB server running with the provided configuration options and credentials. +.sp +\fI\%mongoldap\fP returns a report that includes the success or failure of +any step in the LDAP authentication or authorization procedure. Error messages +include information on specific errors encountered and potential advice for +resolving the error. +.sp +When configuring options related to LDAP authorization, \fI\%mongoldap\fP executes an LDAP query +constructed using the provided configuration options and username, and returns +a list of roles on the \fBadmin\fP database which the user is authorized for. +.sp +You can use this information when configuring LDAP authorization roles for user access control. For example, use +\fI\%mongoldap\fP to ensure your configuration allows privileged users to +gain the necessary roles to perform their expected tasks. Similarly, use +\fI\%mongoldap\fP to ensure your configuration disallows non\-privileged +users from gaining roles for accessing the MongoDB server, or performing +unauthorized actions. +.sp +When configuring options related to LDAP authentication, use \fI\%mongoldap\fP to ensure that the authentication +operation works as expected. +.sp +Run \fI\%mongoldap\fP from the system command line, not the \fBmongo\fP shell. +.sp +This document provides a complete overview of all command line options for +\fI\%mongoldap\fP\&. +.SH USAGE +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A full description of LDAP or Active Directory is beyond the scope of +this documentation. +.UNINDENT +.UNINDENT +.sp +Consider the following sample configuration file, designed to support +LDAP authentication and authorization via Active Directory: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +security: + authorization: "enabled" + ldap: + servers: "activedirectory.example.net" + bind: + queryUser: "mongodbadmin@dba.example.com" + queryPassword: "secret123" + userToDNMapping: + \(aq[ + { + match : "(.+)", + ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" + } + ]\(aq + authz: + queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" +setParameter: + authenticationMechanisms: "PLAIN" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can use \fI\%mongoldap\fP to validate the configuration file, which +returns a report of the procedure. You must specify a username and password +for \fI\%mongoldap\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoldap \-\-config <path\-to\-config> \-\-user "bob@dba.example.com" \-\-password "secret123" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If the provided credentials are valid, and the LDAP options in the +configuration files are valid, the output might be as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Checking that an LDAP server has been specified... +[OK] LDAP server found + +Connecting to LDAP server... +[OK] Connected to LDAP server + +Parsing MongoDB to LDAP DN mappings.. +[OK] MongoDB to LDAP DN mappings appear to be valid + +Attempting to authenticate against the LDAP server... +[OK] Successful authentication performed + +Checking if LDAP authorization has been enabled by configuration... +[OK] LDAP authorization enabled + +Parsing LDAP query template.. +[OK] LDAP query configuration template appears valid + +Executing query against LDAP server... +[OK] Successfully acquired the following roles: +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-\-config <filename>, \-f <filename> +Specifies a configuration file for runtime configuration options. +The options are equivalent to the command\-line +configuration options. See /reference/configuration\-options for +more information. +.sp +\fBmongoldap\fP uses any configuration options related to security\-ldap +or security\-ldap\-external for testing LDAP authentication or +authorization. +.sp +Requires specifying \fI\%\-\-user\fP\&. May accept \fI\%\-\-password\fP for +testing LDAP authentication. +.sp +Ensure the configuration file uses ASCII encoding. The \fBmongoldap\fP +instance does not support configuration files with non\-ASCII encoding, +including UTF\-8. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-user <string> +Username for \fBmongoldap\fP to use when attempting LDAP authentication or +authorization. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-password <string> +Password of the \fB\-\-user\fP for \fBmongoldap\fP to use when attempting LDAP +authentication. Not required for LDAP authorization. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapServers <host1>:<port>,<host2>:<port>,...,<hostN>:<port> +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +The LDAP server against which the \fBmongoldap\fP executes LDAP operations +against to authenticate users or determine what actions a user is authorized +to perform on a given database. If the LDAP server specified has any +replicated instances, you may specify the host and port of each replicated +server in a comma\-delimited list. +.sp +If your LDAP infrastrucure partitions the LDAP directory over multiple LDAP +servers, specify \fIone\fP LDAP server any of its replicated instances to +\fI\%\-\-ldapServers\fP\&. MongoDB supports following LDAP referrals as defined in \fI\%RFC 4511 +4.1.10\fP\&. Do not use \fI\%\-\-ldapServers\fP +for listing every LDAP server in your infrastructure. +.sp +This setting can be configured on a running \fBmongoldap\fP using +\fBsetParameter\fP\&. +.sp +If unset, \fBmongoldap\fP cannot use LDAP authentication or authorization\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapQueryUser <string> +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +The identity with which \fBmongoldap\fP binds as, when connecting to or +performing queries on an LDAP server. +.sp +Only required if any of the following are true: +.INDENT 7.0 +.IP \(bu 2 +Using LDAP authorization\&. +.IP \(bu 2 +Using an LDAP query for \fI\%username transformation\fP\&. +.IP \(bu 2 +The LDAP server disallows anonymous binds +.UNINDENT +.sp +You must use \fI\%\-\-ldapQueryUser\fP with \fI\%\-\-ldapQueryPassword\fP\&. +.sp +If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. +.sp +This setting can be configured on a running \fBmongoldap\fP using +\fBsetParameter\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP +instead of \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify +both \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapQueryPassword <string> +New in version 3.4: Available in MongoDB Enterprise only. +.sp +The password used to bind to an LDAP server when using +\fI\%\-\-ldapQueryUser\fP\&. You must use \fI\%\-\-ldapQueryPassword\fP with +\fI\%\-\-ldapQueryUser\fP\&. + +.sp +If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. +.sp +This setting can be configured on a running \fBmongoldap\fP using +\fBsetParameter\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP +instead of \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify +both \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapBindWithOSDefaults <bool> +\fIDefault\fP: False +.sp +New in version 3.4: Available in MongoDB Enterprise for the Windows platform only. + +.sp +Allows \fBmongoldap\fP to authenticate, or bind, using your Windows login +credentials when connecting to the LDAP server. +.sp +Only required if: +.INDENT 7.0 +.IP \(bu 2 +Using LDAP authorization\&. +.IP \(bu 2 +Using an LDAP query for \fI\%username transformation\fP\&. +.IP \(bu 2 +The LDAP server disallows anonymous binds +.UNINDENT +.sp +Use \fI\%\-\-ldapBindWithOSDefaults\fP to replace \fI\%\-\-ldapQueryUser\fP and +\fI\%\-\-ldapQueryPassword\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapBindMethod <string> +\fIDefault\fP: simple +.sp +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +The method \fBmongoldap\fP uses to authenticate to an LDAP server. +Use with \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP to +connect to the LDAP server. +.sp +\fI\%\-\-ldapBindMethod\fP supports the following values: +.INDENT 7.0 +.IP \(bu 2 +\fBsimple\fP \- \fBmongoldap\fP uses simple authentication. +.IP \(bu 2 +\fBsasl\fP \- \fBmongoldap\fP uses SASL protocol for authentication +.UNINDENT +.sp +If you specify \fBsasl\fP, you can configure the available SASL mechanisms +using \fI\%\-\-ldapBindSASLMechanisms\fP\&. \fBmongoldap\fP defaults to +using \fBDIGEST\-MD5\fP mechanism. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapBindSASLMechanisms <string> +\fIDefault\fP: DIGEST\-MD5 +.sp +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +A comma\-separated list of SASL mechanisms \fBmongoldap\fP can +use when authenticating to the LDAP server. The \fBmongoldap\fP and the +LDAP server must agree on at least one mechanism. The \fBmongoldap\fP +dynamically loads any SASL mechanism libraries installed on the host +machine at runtime. +.sp +Install and configure the appropriate libraries for the selected +SASL mechanism(s) on both the \fBmongoldap\fP host and the remote +LDAP server host. Your operating system may include certain SASL +libraries by default. Defer to the documentation associated with each +SASL mechanism for guidance on installation and configuration. +.sp +If using the \fBGSSAPI\fP SASL mechanism for use with +security\-kerberos, verify the following for the +\fBmongoldap\fP host machine: +.INDENT 7.0 +.TP +.B \fBLinux\fP +.INDENT 7.0 +.IP \(bu 2 +The \fBKRB5_CLIENT_KTNAME\fP environment +variable resolves to the name of the client keytab\-files +for the host machine. For more on Kerberos environment +variables, please defer to the +\fI\%Kerberos documentation\fP\&. +.IP \(bu 2 +The client keytab includes a +kerberos\-user\-principal for the \fBmongoldap\fP to use when +connecting to the LDAP server and execute LDAP queries. +.UNINDENT +.TP +.B \fBWindows\fP +If connecting to an Active Directory server, the Windows +Kerberos configuration automatically generates a +\fI\%Ticket\-Granting\-Ticket\fP +when the user logs onto the system. Set \fI\%\-\-ldapBindWithOSDefaults\fP to +\fBtrue\fP to allow \fBmongoldap\fP to use the generated credentials when +connecting to the Active Directory server and execute queries. +.UNINDENT +.sp +Set \fI\%\-\-ldapBindMethod\fP to \fBsasl\fP to use this option. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For a complete list of SASL mechanisms see the +\fI\%IANA listing\fP\&. +Defer to the documentation for your LDAP or Active Directory +service for identifying the SASL mechanisms compatible with the +service. +.sp +MongoDB is not a source of SASL mechanism libraries, nor +is the MongoDB documentation a definitive source for +installing or configuring any given SASL mechanism. For +documentation and support, defer to the SASL mechanism +library vendor or owner. +.sp +For more information on SASL, defer to the following resources: +.INDENT 0.0 +.IP \(bu 2 +For Linux, please see the \fI\%Cyrus SASL documentation\fP\&. +.IP \(bu 2 +For Windows, please see the \fI\%Windows SASL documentation\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapTransportSecurity <string> +\fIDefault\fP: tls +.sp +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +By default, \fBmongoldap\fP creates a TLS/SSL secured connection to the LDAP +server. +.sp +For Linux deployments, you must configure the appropriate TLS Options in +\fB/etc/openldap/ldap.conf\fP file. Your operating system\(aqs package manager +creates this file as part of the MongoDB Enterprise installation, via the +\fBlibldap\fP dependency. See the documentation for \fBTLS Options\fP in the +\fI\%ldap.conf OpenLDAP documentation\fP +for more complete instructions. +.sp +For Windows deployment, you must add the LDAP server CA certificates to the +Windows certificate management tool. The exact name and functionality of the +tool may vary depending on operating system version. Please see the +documentation for your version of Windows for more information on +certificate management. +.sp +Set \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP to disable TLS/SSL between \fBmongoldap\fP and the LDAP +server. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Setting \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP transmits plaintext information and possibly +credentials between \fBmongoldap\fP and the LDAP server. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapTimeoutMS <long> +\fIDefault\fP: 10000 +.sp +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +The amount of time in milliseconds \fBmongoldap\fP should wait for an LDAP server +to respond to a request. +.sp +Increasing the value of \fI\%\-\-ldapTimeoutMS\fP may prevent connection failure between the +MongoDB server and the LDAP server, if the source of the failure is a +connection timeout. Decreasing the value of \fI\%\-\-ldapTimeoutMS\fP reduces the time +MongoDB waits for a response from the LDAP server. +.sp +This setting can be configured on a running \fBmongoldap\fP using +\fBsetParameter\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapUserToDNMapping <string> +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +Maps the username provided to \fBmongoldap\fP for authentication to a LDAP +Distinguished Name (DN). You may need to use \fI\%\-\-ldapUserToDNMapping\fP to transform a +username into an LDAP DN in the following scenarios: +.INDENT 7.0 +.IP \(bu 2 +Performing LDAP authentication with simple LDAP binding, where users +authenticate to MongoDB with usernames that are not full LDAP DNs. +.IP \(bu 2 +Using an \fBLDAP authorization query template\fP that requires a DN. +.IP \(bu 2 +Transforming the usernames of clients authenticating to Mongo DB using +different authentication mechanisms (e.g. x.509, kerberos) to a full LDAP +DN for authorization. +.UNINDENT +.sp +\fI\%\-\-ldapUserToDNMapping\fP expects a quote\-enclosed JSON\-string representing an ordered array +of documents. Each document contains a regular expression \fBmatch\fP and +either a \fBsubstitution\fP or \fBldapQuery\fP template used for transforming the +incoming username. +.sp +Each document in the array has the following form: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + match: "<regex>" + substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>" +} +.ft P +.fi +.UNINDENT +.UNINDENT +.TS +center; +|l|l|l|. +_ +T{ +Field +T} T{ +Description +T} T{ +Example +T} +_ +T{ +\fBmatch\fP +T} T{ +An ECMAScript\-formatted regular expression (regex) to match against a +provided username. Each parenthesis\-enclosed section represents a +regex capture group used by \fBsubstitution\fP or \fBldapQuery\fP\&. +T} T{ +\fB"(.+)ENGINEERING"\fP +\fB"(.+)DBA"\fP +T} +_ +T{ +\fBsubstitution\fP +T} T{ +An LDAP distinguished name (DN) formatting template that converts the +authentication name matched by the \fBmatch\fP regex into a LDAP DN. +Each curly bracket\-enclosed numeric value is replaced by the +corresponding \fI\%regex capture group\fP extracted +from the authentication username via the \fBmatch\fP regex. +.sp +The result of the substitution must be an \fI\%RFC4514\fP escaped string. +T} T{ +\fB"cn={0},ou=engineering, +dc=example,dc=com"\fP +T} +_ +T{ +\fBldapQuery\fP +T} T{ +A LDAP query formatting template that inserts the authentication +name matched by the \fBmatch\fP regex into an LDAP query URI encoded +respecting RFC4515 and RFC4516. Each curly bracket\-enclosed numeric +value is replaced by the corresponding \fI\%regex capture group\fP extracted +from the authentication username via the \fBmatch\fP expression. +\fBmongoldap\fP executes the query against the LDAP server to retrieve +the LDAP DN for the authenticated user. \fBmongoldap\fP requires +exactly one returned result for the transformation to be +successful, or \fBmongoldap\fP skips this transformation. +T} T{ +\fB"ou=engineering,dc=example, +dc=com??one?(user={0})"\fP +T} +_ +.TE +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +An explanation of \fI\%RFC4514\fP, +\fI\%RFC4515\fP, +\fI\%RFC4516\fP, or LDAP queries is out +of scope for the MongoDB Documentation. Please review the RFC directly or +use your preferred LDAP resource. +.UNINDENT +.UNINDENT +.sp +For each document in the array, you must use either \fBsubstitution\fP or +\fBldapQuery\fP\&. You \fIcannot\fP specify both in the same document. +.sp +When performing authentication or authorization, \fBmongoldap\fP steps through +each document in the array in the given order, checking the authentication +username against the \fBmatch\fP filter. If a match is found, +\fBmongoldap\fP applies the transformation and uses the output for +authenticating the user. \fBmongoldap\fP does not check the remaining documents +in the array. +.sp +If the given document does not match the provided authentication name, or +the transformation described by the document fails, \fBmongoldap\fP continues +through the list of documents to find additional matches. If no matches are +found in any document, \fBmongoldap\fP returns an error. +.INDENT 7.0 +.INDENT 3.5 +.SH EXAMPLE +.sp +The following shows two transformation documents. The first +document matches against any string ending in \fB@ENGINEERING\fP, placing +anything preceeding the suffix into a regex capture group. The +second document matches against any string ending in \fB@DBA\fP, placing +anything preceeding the suffix into a regex capture group. +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +You must pass the array to \fI\%\-\-ldapUserToDNMapping\fP as a string. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +"[ + { + match: "(.+)@ENGINEERING.EXAMPLE.COM", + substitution: "cn={0},ou=engineering,dc=example,dc=com" + }, + { + match: "(.+)@DBA.EXAMPLE.COM", + ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})" + + } + +]" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A user with username \fBalice@ENGINEERING.EXAMPLE.COM\fP matches the first +document. The regex capture group \fB{0}\fP corresponds to the string +\fBalice\fP\&. The resulting output is the DN +\fB"cn=alice,ou=engineering,dc=example,dc=com"\fP\&. +.sp +A user with username \fBbob@DBA.EXAMPLE.COM\fP matches the second document. +The regex capture group \fB{0}\fP corresponds to the string \fBbob\fP\&. The +resulting output is the LDAP query +\fB"ou=dba,dc=example,dc=com??one?(user=bob)"\fP\&. \fBmongoldap\fP executes this +query against the LDAP server, returning the result +\fB"cn=bob,ou=dba,dc=example,dc=com"\fP\&. +.UNINDENT +.UNINDENT +.sp +If \fI\%\-\-ldapUserToDNMapping\fP is unset, \fBmongoldap\fP applies no transformations to the username +when attempting to authenticate or authorize a user against the LDAP server. +.sp +This setting can be configured on a running \fBmongoldap\fP using the +\fBsetParameter\fP database command. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ldapAuthzQueryTemplate <string> +New in version 3.4: Available in MongoDB Enterprise only. + +.sp +A relative LDAP query URL formatted conforming to \fI\%RFC4515\fP and \fI\%RFC4516\fP that \fBmongoldap\fP executes to obtain +the LDAP groups to which the authenticated user belongs to. The query is +relative to the host or hosts specified in \fI\%\-\-ldapServers\fP\&. +.sp +In the URL, you can use the following substituion tokens: +.TS +center; +|l|l|. +_ +T{ +Substitution Token +T} T{ +Description +T} +_ +T{ +\fB{USER}\fP +T} T{ +Substitutes the authenticated username, or the +\fBtransformed\fP +username if a \fI\%username mapping\fP is specified. +T} +_ +T{ +\fB{PROVIDED_USER}\fP +T} T{ +Substitutes the supplied username, i.e. before either +authentication or \fBLDAP transformation\fP\&. +.sp +New in version 4.2. +T} +_ +.TE +.sp +When constructing the query URL, ensure that the order of LDAP parameters +respects RFC4516: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +[ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If your query includes an attribute, \fBmongoldap\fP assumes that the query +retrieves a the DNs which this entity is member of. +.sp +If your query does not include an attribute, \fBmongoldap\fP assumes +the query retrieves all entities which the user is member of. +.sp +For each LDAP DN returned by the query, \fBmongoldap\fP assigns the authorized +user a corresponding role on the \fBadmin\fP database. If a role on the on the +\fBadmin\fP database exactly matches the DN, \fBmongoldap\fP grants the user the +roles and privileges assigned to that role. See the +\fBdb.createRole()\fP method for more information on creating roles. +.INDENT 7.0 +.INDENT 3.5 +.SH EXAMPLE +.sp +This LDAP query returns any groups listed in the LDAP user object\(aqs +\fBmemberOf\fP attribute. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +"{USER}?memberOf?base" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Your LDAP configuration may not include the \fBmemberOf\fP attribute as part +of the user schema, may possess a different attribute for reporting group +membership, or may not track group membership through attributes. +Configure your query with respect to your own unique LDAP configuration. +.UNINDENT +.UNINDENT +.sp +If unset, \fBmongoldap\fP cannot authorize users using LDAP. +.sp +This setting can be configured on a running \fBmongoldap\fP using the +\fBsetParameter\fP database command. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +An explanation of \fI\%RFC4515\fP, +\fI\%RFC4516\fP or LDAP queries is out +of scope for the MongoDB Documentation. Please review the RFC directly or +use your preferred LDAP resource. +.UNINDENT +.UNINDENT +.UNINDENT +.SH AUTHOR +MongoDB Documentation Project +.SH COPYRIGHT +2008-2019 +.\" Generated by docutils manpage writer. +. diff --git a/debian/mongoreplay.1 b/debian/mongoreplay.1 new file mode 100644 index 00000000000..00f4cc388e8 --- /dev/null +++ b/debian/mongoreplay.1 @@ -0,0 +1,1298 @@ +.\" Man page generated from reStructuredText. +. +.TH "MONGOREPLAY" "1" "Aug 16, 2019" "4.2" "mongodb-manual" +.SH NAME +mongoreplay \- MongoDB Traffic Capture and Replay Tool +. +.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 +.. +.SS On this page +.INDENT 0.0 +.IP \(bu 2 +\fI\%Synopsis\fP +.IP \(bu 2 +\fI\%Required Access\fP +.IP \(bu 2 +\fI\%Options\fP +.IP \(bu 2 +\fI\%Commands\fP +.IP \(bu 2 +\fI\%mongoreplay Report Format\fP +.IP \(bu 2 +\fI\%Examples\fP +.UNINDENT +.SH SYNOPSIS +.sp +New in version 3.4. + +.INDENT 0.0 +.INDENT 3.5 +.IP "Availability" +.sp +Available for Linux and macOS. +.UNINDENT +.UNINDENT +.sp +\fI\%mongoreplay\fP is a traffic capture and replay tool for MongoDB +that you can use to inspect and record commands sent to a MongoDB +instance, and then replay those commands back onto another host at a +later time. +.sp +\fI\%mongoreplay\fP can help you preview how your MongoDB deployment +will perform a production workload under a different environment, +such as with a different storage engine, on different hardware, or +with a different operating system configuration. +\fI\%mongoreplay\fP can also help reproduce and investigate an issue by +recording and replaying the operations that trigger the issue. +Finally, \fI\%mongoreplay\fP serves as a more flexible version of +the legacy \fBmongosniff\fP tool to help you investigate database activity. +.sp +Run \fI\%mongoreplay\fP from the system command line, not the \fBmongo\fP shell. +.SH REQUIRED ACCESS +.sp +\fI\%mongoreplay\fP requires access to the network interface that +the \fI\%record\fP or \fI\%monitor\fP commands will +listen on. You may need to run \fI\%mongoreplay\fP with root privileges +to access the network device. +.sp +\fI\%mongoreplay\fP will not work with MongoDB instances using an SSL connection. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Only use root privileges when connecting to trusted sources. +.UNINDENT +.UNINDENT +.sp +If you are using \fI\%play\fP to connect to a MongoDB deployment +that enforces access control, you must +connect as a user with the required privileges to execute the +recorded operations. Include the user\(aqs credentials in the +\fI\%\-\-host\fP MongoDB connection string. +.SH OPTIONS +.INDENT 0.0 +.TP +.B mongoreplay +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-verbosity, \-v +Increases the amount of internal reporting returned on standard output +or in log files. Increase the verbosity with the \fB\-v\fP form by +including the option multiple times, (e.g. \fB\-vvvvv\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-debug, \-d +Increases the amount of detail about \fBmongoreplay\fP operations +and errors recorded +in log files. Increase the debugging detail with the \fB\-d\fP form by +including the option multiple times, (e.g. \fB\-ddd\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-silent, \-s +When set, \fBmongoreplay\fP does not produce any log output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-help +Returns information on the options and use of \fBmongoreplay\fP\&. +.UNINDENT +.SH COMMANDS +.sp +\fI\%mongoreplay\fP includes the following \fIcommands\fP to record, +play back, and monitor MongoDB network traffic. +.SS \fBmongoreplay record\fP +.sp +\fI\%record\fP produces a playback file based on +network traffic. \fI\%record\fP supports collecting network +traffic directly or can +accept a \fI\%pcap file\fP +to produce the playback file. +The playback file contains a list of all requests sent to the +\fBmongod\fP instance during the recording as well as all +responses transmitted to the client during the recording. The playback +file also records metadata for each request, such as the connection +identifier and timestamp. +.sp +The following prototype uses \fI\%mongoreplay\fP to record data +on the loopback network interface and creates a playback file +located at \fB~/recordings/playback\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay record \-i eth0 \-e "port 27017" \-p ~/recordings/playback +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Similarly, the following prototype uses \fI\%mongoreplay\fP +to produce a playback file from an existing pcap file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay record \-f traffic.pcap \-p ~/recordings/playback +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBrecord\fP supports the following options: +.INDENT 0.0 +.TP +.B mongoreplay record +.UNINDENT +.INDENT 0.0 +.TP +.B record +.UNINDENT +.INDENT 0.0 +.TP +.B \-f <path> +Specifies the path to a pcap file that \fI\%record\fP should read to +produce a playback file. +.sp +Use \fB\-f\fP as an alternative to capturing network traffic using +\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include +both options, \fBmongoreplay record\fP produces an error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b <number> +Size of heap used to merge separate streams together. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-expr <filter expression>, \-e <filter expression> +An expression in \fI\%Berkeley Packet Filter (BPF) syntax\fP to apply to incoming traffic to +record. Required if you are capturing traffic from a network interface using +\fI\%\-i\fP\&. +.sp +For example, to capture traffic from a MongoDB instance running on +port 27017, you would specify \fB\-e \(aqport 27017\(aq\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i <interface> +Specifies the network interface that \fI\%record\fP should listen on to +capture network traffic. +.sp +Use with \fI\%\-e\fP\&. +.sp +Use \fB\-i\fP as an alternative to reading an existing pcap file with +\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include +both options, \fBmongoreplay record\fP produces an error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-gzip <boolean> +If specified, \fI\%record\fP compresses the playback file with gzip. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-playback\-file <path>, \-p <path> +Specifies the path to which to write the playback file. +.sp +The produced playback file is a BSON file. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.SS See +.sp +\fI\%Use record\fP for examples of using +\fI\%mongoreplay\fP with the \fBrecord\fP command. +.UNINDENT +.UNINDENT +.SS \fBmongoreplay play\fP +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Starting in MongoDB 4.0, \fI\%mongoreplay play\fP supports a new +\fBMONGOREPLAY_HOST\fP environment variable that specifies the +MongoDB connection string. The new environment +vairable can be used instead of the command\-line \fI\%\-\-host\fP option. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B play +\fI\%play\fP replays a playback file created with +\fI\%record\fP against a \fBmongod\fP instance. +.UNINDENT +.sp +For example, the following uses \fI\%mongoreplay play\fP to replay the +\fB~/recordings/playback\fP playback file to the \fBmongod\fP instance running on +\fB192.168.0.4:27018\fP: +.INDENT 0.0 +.IP \(bu 2 +Using the \fI\%\-\-host\fP option: +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay play \-p ~/recordings/playback \-\-report ~/reports/replay_stats.json \-\-host mongodb://192.168.0.4:27018 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP \(bu 2 +Using the \fBMONGOREPLAY_HOST\fP environment variable (Available starting in MongoDB 4.0): +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +export MONGOREPLAY_HOST="mongodb://192.168.0.4:27018" +mongoreplay play \-p ~/recordings/playback \-\-report ~/reports/replay_stats.json +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS \fBplay\fP Options +.sp +\fBplay\fP supports the following options: +.INDENT 0.0 +.TP +.B mongoreplay play +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-collect <json|format|none> +\fIDefault\fP: format +.sp +Specifies the output format for the collected statistics. +.INDENT 7.0 +.IP \(bu 2 +\fBjson\fP: outputs stat information as json +.IP \(bu 2 +\fBformat\fP: uses the formatting specified in the \fB\-\-format\fP option +to produce the output file. +.IP \(bu 2 +\fBnone\fP: does not provide any output +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-report <path> +Specifies the path to which to write an execution report. +Use \fI\%\-\-collect\fP to specify the output format for the report. +.sp +If you do not specify \fB\-\-report\fP, \fI\%play\fP writes to STDOUT. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-truncate +If specified, disables truncation of large reply payload data in the +\fI\%play\fP log output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-format +\fIDefault\fP: \fB%F{blue}%t%f %F{cyan}(Connection: %o:%i)%f %F{yellow}%l%f +%F{red}%T %c%f %F{white}%n%f +%F{green}%Q{Request:}%f%q%F{green}%R{Response:}%f%r)\fP +.sp +Specifies the format for terminal output. +You can specify arguments immediately after the format \(aqverbs\(aq by wrapping +them in curly braces, as in \fB%Q{<arg>}\fP\&. +.sp +If you specify \fI\%\-\-format\fP, also specify \fBformat\fP as the value for the +\fI\%\-\-collect\fP option. +.sp +\fI\%\-\-format\fP supports the following verbs: +.INDENT 7.0 +.IP \(bu 2 +\fB%n\fP: namespace +.IP \(bu 2 +\fB%l\fP: latency +.IP \(bu 2 +\fB%t\fP: time. You may optionally specify the date layout using the +Go Programming Language\(aqs \fI\%time formatting\fP\&. Go +uses \fBMon Jan 2 15:04:05 MST 2006\fP as its reference time. You +must specify the time format using the reference time. Thus, if you +wanted to print the date in format \fByyyy\-mm\-dd hh:mm\fP, you would +specify \fB%t{2006\-01\-02 15:04}\fP\&. Refer to the Go \fI\%time formatting\fP +documentation for more information. +.IP \(bu 2 +\fB%T\fP: op time +.IP \(bu 2 +\fB%c\fP: command +.IP \(bu 2 +\fB%o\fP: number of connections +.IP \(bu 2 +\fB%i\fP: request ID +.IP \(bu 2 +\fB%q\fP: request. You may optinally specified a dot\-delimited field +within the JSON structure, as in, \fB%q{command_args.documents}\fP\&. +.IP \(bu 2 +\fB%r\fP: response. You may optinally specified a dot\-delimited field +within the JSON structure, as in, \fB%q{command_args.documents}\fP\&. +.IP \(bu 2 +\fB%Q{<arg>}\fP: display \fB<arg>\fP on presence of request data +.IP \(bu 2 +\fB%R{<arg>}\fP: display \fB<arg>\fP on presence of response data +.UNINDENT +.sp +In addition, \fI\%\-\-format\fP supports the following start/end ANSI escape sequences: +.INDENT 7.0 +.IP \(bu 2 +\fB%B\fP/\fB%b\fP: bold +.IP \(bu 2 +\fB%U\fP/\fB%u\fP: underline +.IP \(bu 2 +\fB%S\fP/\fB%s\fP: standout +.IP \(bu 2 +\fB%F\fP/\fB%f\fP: text color (required arg \-\- word or number, 8\-color) +.IP \(bu 2 +\fB%K\fP/\fB%k\fP: background color (required arg \-\- same as %F/%f) +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-colors +When set, removes colors from the \fI\%default format\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-playback\-file <path>, \-p <path> +Specifies the path from which to read the playback file. +.sp +If the playback file was created using the \fI\%\-\-gzip\fP option, you must also specify \fB\-\-gzip\fP +when running \fI\%play\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-speed number +\fIDefault\fP: 1.0 +.sp +Specifies a multiplier to adjust playback speed. \fB\-\-speed 1.0\fP +processes the playback file in real time; \fB\-\-speed 0.5\fP at half +speed; \fB\-\-speed 3.0\fP at triple speed. +.sp +The specified speed is a \fItarget\fP speed. If \fBmongoreplay play\fP encounters +a bottleneck, playback may be slower than the specified multiplier. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-host <uri connection string> +\fIDefault\fP: mongodb://localhost:27017 +.sp +Specifies a MongoDB connection string +for the MongoDB deployment to which to +play back the captured network traffic. +.sp +By default, \fI\%play\fP +attempts to connect to a \fBmongod\fP instance running on the localhost on +port number \fB27017\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in MongoDB 4.0, \fI\%mongoreplay play\fP supports a new +\fBMONGOREPLAY_HOST\fP environment variable that specifies the +connection string for the MongoDB deployment. The new environment +vairable can be used instead of the command\-line \fI\%\-\-host\fP option. +.sp +If \fI\%\-\-host\fP command\-line option is +specified, the \fI\%\-\-host\fP value overrides +the environment variable. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-repeat number +\fIDefault\fP: 1 +.sp +Specifies the number of times to play the playback file. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-queueTime number +\fIDefault\fP: 15 +.sp +Specifies the maximum time, in seconds, to queue operations in advance +of transmitting them. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-preprocess +When set, \fI\%play\fP does not preprocess the input file to pre\-map +data such as MongoDB cursor IDs. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-gzip <boolean> +If specified, \fI\%play\fP decompresses the playback file with gzip. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.SS See +.sp +\fI\%Use play\fP for examples of using +\fI\%mongoreplay\fP with the \fI\%play\fP command. +.UNINDENT +.UNINDENT +.SS \fBmongoreplay monitor\fP +.sp +\fI\%monitor\fP inspects live or pre\-recorded +MongoDB network traffic. +.sp +The following prototype uses \fI\%mongoreplay\fP to produce a +JSON report based on the \fBplayback.bson\fP playback file in the \fB~/recordings\fP directory: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay monitor \-\-collect json \-\-report ~/reports/monitor\-report.json \-p ~/recordings/playback.bson +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBmonitor\fP supports the following options: +.INDENT 0.0 +.TP +.B mongoreplay monitor +.UNINDENT +.INDENT 0.0 +.TP +.B monitor +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-collect <json|format|none> +\fIDefault\fP: format +.sp +Specifies the output format for the collected statistics. +.INDENT 7.0 +.IP \(bu 2 +\fBjson\fP: outputs stat information as json +.IP \(bu 2 +\fBformat\fP: uses the formatting specified in the \fB\-\-format\fP option +to produce the output file. +.IP \(bu 2 +\fBnone\fP: does not provide any output +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-report <path> +Specifies the path to which to write an execution report. +Use \fI\%\-\-collect\fP to specify the output format for the report. +.sp +If you do not specify \fB\-\-report\fP, \fI\%monitor\fP writes to STDOUT. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-truncate +If specified, disables truncation of large reply payload data in the +\fI\%monitor\fP log output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-format +\fIDefault\fP: \fB%F{blue}%t%f %F{cyan}(Connection: %o:%i)%f %F{yellow}%l%f +%F{red}%T %c%f %F{white}%n%f +%F{green}%Q{Request:}%f%q%F{green}%R{Response:}%f%r)\fP +.sp +Specifies the format for terminal output. +You can specify arguments immediately after the format \(aqverbs\(aq by wrapping +them in curly braces, as in \fB%Q{<arg>}\fP\&. +.sp +If you specify \fI\%\-\-format\fP, also specify \fBformat\fP as the value for the +\fI\%\-\-collect\fP option. +.sp +\fI\%\-\-format\fP supports the following verbs: +.INDENT 7.0 +.IP \(bu 2 +\fB%n\fP: namespace +.IP \(bu 2 +\fB%l\fP: latency +.IP \(bu 2 +\fB%t\fP: time. You may optionally specify the date layout using the +Go Programming Language\(aqs \fI\%time formatting\fP\&. Go +uses \fBMon Jan 2 15:04:05 MST 2006\fP as its reference time. You +must specify the time format using the reference time. Thus, if you +wanted to print the date in format \fByyyy\-mm\-dd hh:mm\fP, you would +specify \fB%t{2006\-01\-02 15:04}\fP\&. Refer to the Go \fI\%time formatting\fP +documentation for more information. +.IP \(bu 2 +\fB%T\fP: op time +.IP \(bu 2 +\fB%c\fP: command +.IP \(bu 2 +\fB%o\fP: number of connections +.IP \(bu 2 +\fB%i\fP: request ID +.IP \(bu 2 +\fB%q\fP: request. You may optinally specified a dot\-delimited field +within the JSON structure, as in, \fB%q{command_args.documents}\fP\&. +.IP \(bu 2 +\fB%r\fP: response. You may optinally specified a dot\-delimited field +within the JSON structure, as in, \fB%q{command_args.documents}\fP\&. +.IP \(bu 2 +\fB%Q{<arg>}\fP: display \fB<arg>\fP on presence of request data +.IP \(bu 2 +\fB%R{<arg>}\fP: display \fB<arg>\fP on presence of response data +.UNINDENT +.sp +In addition, \fI\%\-\-format\fP supports the following start/end ANSI escape sequences: +.INDENT 7.0 +.IP \(bu 2 +\fB%B\fP/\fB%b\fP: bold +.IP \(bu 2 +\fB%U\fP/\fB%u\fP: underline +.IP \(bu 2 +\fB%S\fP/\fB%s\fP: standout +.IP \(bu 2 +\fB%F\fP/\fB%f\fP: text color (required arg \-\- word or number, 8\-color) +.IP \(bu 2 +\fB%K\fP/\fB%k\fP: background color (required arg \-\- same as %F/%f) +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-colors +When set, removes colors from the \fI\%default format\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f <path> +Specifies the path to a pcap file that \fI\%monitor\fP should read to +produce a playback file. +.sp +Use \fB\-f\fP as an alternative to capturing network traffic using +\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include +both options, \fBmongoreplay monitor\fP produces an error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b <number> +Size of heap used to merge separate streams together. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-expr <filter expression>, \-e <filter expression> +An expression in \fI\%Berkeley Packet Filter (BPF) syntax\fP to apply to incoming traffic to +record. Required if you are capturing traffic from a network interface using +\fI\%\-i\fP\&. +.sp +For example, to capture traffic from a MongoDB instance running on +port 27017, you would specify \fB\-e \(aqport 27017\(aq\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i <interface> +Specifies the network interface that \fI\%monitor\fP should listen on to +capture network traffic. +.sp +Use with \fI\%\-e\fP\&. +.sp +Use \fB\-i\fP as an alternative to reading an existing pcap file with +\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include +both options, \fBmongoreplay monitor\fP produces an error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-paired +When specified, \fI\%monitor\fP outputs one line for each request/reply pair record. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-gzip <boolean> +If specified, \fI\%monitor\fP decompresses the playback file with gzip. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-playback\-file <path>, \-p <path> +Specifies the path from which to read the playback file. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.SS See +.sp +\fI\%Use monitor\fP for examples of using +\fI\%mongoreplay\fP with the \fI\%monitor\fP command. +.UNINDENT +.UNINDENT +.SH MONGOREPLAY REPORT FORMAT +.sp +\fI\%monitor\fP and \fI\%play\fP can produce +reports based on a playback file when run with the \fB\-\-report\fP option. +.SS Sample Record +.sp +The following is an example record from a JSON\-formatted +\fI\%monitor\fP report: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "order" : 21, + "op" : "op_msg", + "command" : "aggregate", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "aggregate" : "foo", + "cursor" : {}, + "lsid" : { + "id" : { + "$binary" : "eBZNIaAbRTiAoWkaNZ0T8Q==", + "$type" : "04" + } + }, + "pipeline" : [ + { "$match" : { "borough" : "Queens" } }, + { "$group" : { "_id" : "$cuisine", "count" : { "$sum": 1 } } } + ] + }, + "payloadType" : 0 + } + ] + }, + "connection_num" : 0, + "seen" : "2018\-11\-15T14:07:07.136794\-05:00", + "request_id" : 25 +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields +.sp +\fI\%mongoreplay\fP reports can include the following fields: +.INDENT 0.0 +.TP +.B order +A monotonically increasing key indicating the order in which the +operations were recorded and played back. This can be used to +reconstruct the ordering of the series of operations executed on a +connection, since the order in which they appear in the report file +may not match the playback order. +.UNINDENT +.INDENT 0.0 +.TP +.B op +The type of operation represented by the request: i.e. "query", +"insert", "command", "getmore". +.UNINDENT +.INDENT 0.0 +.TP +.B command +The name of the database command performed, such as \fBisMaster\fP or +\fBgetLastError\fP\&. This field is left blank for operations that are not +commands, such as queries and inserts. +.UNINDENT +.INDENT 0.0 +.TP +.B ns +The namespace on which the request was executed. +.UNINDENT +.INDENT 0.0 +.TP +.B request_data +The payload of the operation. +.INDENT 7.0 +.IP \(bu 2 +Query operations: \fBrequest_data\fP contains the actual +query that was issued. +.IP \(bu 2 +Insert operations: \fBrequest_data\fP contains the documents +being inserted. +.IP \(bu 2 +Update operations: \fBrequest_data\fP contains the query +selector and the update modifier. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B reply_data +The payload of the reply to the request. +.UNINDENT +.INDENT 0.0 +.TP +.B nreturned +The number of documents returned as a result of the operation. +.UNINDENT +.INDENT 0.0 +.TP +.B played_at +The time at which the \fI\%play\fP command executed +the operation. +.UNINDENT +.INDENT 0.0 +.TP +.B play_at +The time at which the operation was supposed to be executed by +the \fI\%play\fP command. +.UNINDENT +.INDENT 0.0 +.TP +.B playbacklag_us +The difference in microseconds in time between \fBplayed_at\fP +and \fBplay_at\fP\&. Higher values generally indicate that the +target server is not able to keep up with the rate at which requests +need to be executed according to the playback file. +.UNINDENT +.INDENT 0.0 +.TP +.B connection_num +A key that identifies the connection on which the request was +executed. All requests/replies that executed on the same connection +have the same value for \fBconnection_num\fP\&. +.sp +The \fBconnection_num\fP value +does \fInot\fP match the connection ID logged on the server side. +.UNINDENT +.INDENT 0.0 +.TP +.B latency_us +The time difference in microseconds between when the request was +sent by the client and when a response from the server was received. +.UNINDENT +.INDENT 0.0 +.TP +.B errors +Lists any errors returned from the server. +.UNINDENT +.INDENT 0.0 +.TP +.B msg +Lists the error message returned from the server. +.UNINDENT +.INDENT 0.0 +.TP +.B seen +The time at which the operation was originally captured. +.UNINDENT +.INDENT 0.0 +.TP +.B request_id +The ID of the MongoDB operation. The \fBrequest_id\fP for a request +operation is the same as the \fBresponse_id\fP for the corresponding +reply. +.UNINDENT +.SS Output Formatting with \fB\-\-format\fP +.sp +\fI\%monitor\fP and \fI\%play\fP output to either the +terminal or, when run with \fB\-\-report\fP (i.e. \fI\%monitor \-\-report\fP or \fI\%play \-\-report\fP), to a file. +.sp +Use the \fB\-\-collect\fP (\fI\%monitor \-\-collect\fP or \fI\%play \-\-collect\fP) +option to specify the format of the output: +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-collect json\fP produces JSON output, +.IP \(bu 2 +\fB\-\-collect format\fP outputs the data based on the formatting +specified by the \fB\-\-format\fP option for \fI\%monitor\fP and \fI\%play\fP . +.UNINDENT +.SH EXAMPLES +.SS Use \fI\%record\fP +.SS Capture TCP data with \fBrecord\fP +.sp +To create a recording of traffic, use the \fI\%record\fP command. The +following operation records traffic through port \fB27017\fP on the +\fBeth0\fP network interface and writes the captured traffic to +\fB~/recordings/recording.bson\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay record \-i eth0 \-e "port 27017" \-p ~/recordings/recording.bson +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The produced playback file contains everything needed to re\-execute +the workload on another system. +.SS Record a Playback File from Existing pcap Data +.sp +If you do not wish to use \fI\%mongoreplay\fP to capture traffic, you +can capture traffic using a utility such as \fBtcpdump\fP and then create a +\fI\%mongoreplay\fP recording from the static pcap file. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Only use root privileges when connecting to a trusted source. +.UNINDENT +.UNINDENT +.sp +The following operation uses \fBtcpdump\fP to capture traffic through +port \fB27017\fP on the \fBeth0\fP network interface and writes the captured +data to a pcap file called \fBtraffic.pcap\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +sudo tcpdump \-B $((100*1024)) \-i eth0 \-n "port 27017" \-w traffic.pcap +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To create the \fI\%mongoreplay\fP playback file, you can use +\fI\%record\fP with the \fI\%\-f\fP +option to specify the pcap file from which to create the playback file, +as in the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay record \-f traffic.pcap \-p ~/recordings/playback.bson +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The produced playback file contains everything needed to re\-execute +the workload on another system. +.SS Use \fI\%play\fP +.SS Execute a Playback File Against a Target Host +.sp +\fI\%play\fP takes a playback file and executes the +recorded operations against the \fBmongodb://example.com:27018\fP host. +Since the \fBmongod\fP enforces authentication, the +connection string specified to +\fI\%\-\-host\fP also includes the username, password, and authentication +database so that \fI\%mongoreplay\fP can write to the database. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay play \-p ~/recordings/recording.bson \-\-host mongodb://username:password@example.com:27018/admin +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +By default, \fB~bin.play\fP executes the playback +file at the rate of the recording. \fI\%\-\-speed\fP lets you modify +the playback speed. For example, the following operation executes +the operations in \fBrecording.bson\fP at twice the recording speed: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay play \-p ~/recordings/recording.bson \-\-speed=2.0 \-\-host mongodb://username:password@example.com:27018/admin +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Log Metrics About Execution Performance during Playback +.sp +\fI\%play\fP can produce a report with detailed metrics +about the performance of each operation executed during playback. +.sp +The following example executes playback against the +\fBmongodb://example.com:27017\fP host and produces a JSON report written to +\fB~/reports/playback\-report.json\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay play \-p ~/recordings/recording.bson \-\-report ~/reports/playback\-report.json \-\-collect json \-\-host mongodb://example.com:27017 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBplay\fP report contents would resemble: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "order" : 0, + "op" : "op_msg", + "command" : "isMaster", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "forShell" : 1, + "isMaster" : 1 + }, + "payloadType" : 0 + } + ] + }, + "reply_data" : { + "sections" : [ + { + "payload" : { + "ismaster" : true, + "localTime" : { + "$date" : "2018\-11\-15T21:35:01.843Z" + }, + "logicalSessionTimeoutMinutes" : 30, + "maxBsonObjectSize" : 16777216, + "maxMessageSizeBytes" : 48000000, + "maxWireVersion" : 7, + "maxWriteBatchSize" : 100000, + "minWireVersion" : 0, + "ok" : 1, + "readOnly" : false + }, + "payloadType" : 0 + } + ] + }, + "played_at" : "2018\-11\-15T16:35:01.84304\-05:00", + "play_at" : "2018\-11\-15T16:35:01.842903\-05:00", + "playbacklag_us" : 137, + "connection_num" : 1, + "latency_us" : 151, + "seen" : "2018\-11\-15T21:30:33.379675Z", + "request_id" : 21 +} +{ + "order" : 2, + "op" : "op_msg", + "command" : "listCollections", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "authorizedCollections" : true, + "filter" : { + + }, + "listCollections" : 1, + "lsid" : { + "id" : { + "$binary" : "esmcqhiXSIWSpKGb4sOekw==", + "$type" : "04" + } + }, + "nameOnly" : true + }, + "payloadType" : 0 + } + ] + }, + "reply_data" : { + "sections" : [ + { + "payload" : { + "cursor" : { + "firstBatch" : [ ], + "id" : { + "$numberLong" : "0" + }, + "ns" : "test.$cmd.listCollections" + }, + "ok" : 1 + }, + "payloadType" : 0 + } + ] + }, + "played_at" : "2018\-11\-15T16:35:08.715002\-05:00", + "play_at" : "2018\-11\-15T16:35:08.713539\-05:00", + "playbacklag_us" : 1463, + "connection_num" : 1, + "latency_us" : 331, + "seen" : "2018\-11\-15T21:30:40.250311Z", + "request_id" : 22 +} +{ + "order" : 4, + "op" : "op_msg", + "command" : "isMaster", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "forShell" : 1, + "isMaster" : 1 + }, + "payloadType" : 0 + } + ] + }, + "reply_data" : { + "sections" : [ + { + "payload" : { + "ismaster" : true, + "localTime" : { + "$date" : "2018\-11\-15T21:35:08.715Z" + }, + "logicalSessionTimeoutMinutes" : 30, + "maxBsonObjectSize" : 16777216, + "maxMessageSizeBytes" : 48000000, + "maxWireVersion" : 7, + "maxWriteBatchSize" : 100000, + "minWireVersion" : 0, + "ok" : 1, + "readOnly" : false + }, + "payloadType" : 0 + } + ] + }, + "played_at" : "2018\-11\-15T16:35:08.715554\-05:00", + "play_at" : "2018\-11\-15T16:35:08.71471\-05:00", + "playbacklag_us" : 844, + "connection_num" : 1, + "latency_us" : 208, + "seen" : "2018\-11\-15T21:30:40.251482Z", + "request_id" : 23 +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Refer to \fI\%mongoreplay Report Format\fP for a description of each field. +.SS Use \fI\%monitor\fP +.SS Inspect Recorded Operations +.sp +\fI\%monitor\fP can create a report based on the +contents of a playback file. \fI\%monitor\fP\(aqs report includes +\fIall\fP operations and some metadata about each operation\(aqs execution. +.sp +The following operation uses \fI\%monitor\fP to create a JSON +report based on the contents of the \fBrecording.bson\fP playback file +located in the \fB~/recordings\fP directory and write the report to +\fB~/reports/monitoring\-report.json\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay monitor \-p ~/recordings/recording.bson \-\-report ~/reports/monitoring\-report.json \-\-collect json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The report contents would resemble: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "order" : 0, + "op" : "op_msg", + "command" : "isMaster", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "forShell" : 1, + "isMaster" : 1 + }, + "payloadType" : 0 + } + ] + }, + "connection_num" : 0, + "seen" : "2018\-11\-15T21:30:33.379675Z", + "request_id" : 21 +} +{ + "order" : 1, + "op" : "op_msg", + "command" : "aggregate", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "aggregate" : "restaurants", + "cursor" : { + + }, + "lsid" : { + "id" : { + "$binary" : "esmcqhiXSIWSpKGb4sOekw==", + "$type" : "04" + } + }, + "pipeline" : [ + { + "$match" : { + "borough" : "Manhattan" + } + }, + { + "$group" : { + "_id" : "$cuisine" + } + } + ] + }, + "payloadType" : 0 + } + ] + }, + "connection_num" : 0, + "seen" : "2018\-11\-15T16:28:52.870007\-05:00", + "request_id" : 13 +} +{ + "order" : 1, + "op" : "op_msg", + "command" : "reply", + "reply_data" : { + "sections" : [ + { + "payload" : { + "ismaster" : true, + "localTime" : { + "$date" : "2018\-11\-15T21:30:33.379Z" + }, + "logicalSessionTimeoutMinutes" : 30, + "maxBsonObjectSize" : 16777216, + "maxMessageSizeBytes" : 48000000, + "maxWireVersion" : 7, + "maxWriteBatchSize" : 100000, + "minWireVersion" : 0, + "ok" : 1, + "readOnly" : false + }, + "payloadType" : 0 + } + ] + }, + "connection_num" : 0, + "latency_us" : 174, + "seen" : "2018\-11\-15T21:30:33.379849Z", + "request_id" : 21 +} +{ + "order" : 2, + "op" : "op_msg", + "command" : "listCollections", + "ns" : "test", + "request_data" : { + "sections" : [ + { + "payload" : { + "$db" : "test", + "authorizedCollections" : true, + "filter" : { + + }, + "listCollections" : 1, + "lsid" : { + "id" : { + "$binary" : "esmcqhiXSIWSpKGb4sOekw==", + "$type" : "04" + } + }, + "nameOnly" : true + }, + "payloadType" : 0 + } + ] + }, + "connection_num" : 0, + "seen" : "2018\-11\-15T21:30:40.250311Z", + "request_id" : 22 +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Refer to \fI\%mongoreplay Report Format\fP for a description of each field. +.SS Inspect Live MongoDB Traffic +.sp +\fI\%monitor\fP can also inspect live traffic and, optionally, +create a report based on the observed operations. +.sp +To monitor traffic in real time in your terminal, omit the +\fI\%\-\-report\fP option, as in the +following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay monitor \-i eth0 \-e \(aqport 27017\(aq \-\-collect json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Optionally, you can create a report based on the operations observed +using \fI\%monitor\fP\&. The following example creates a JSON +report written to \fB~/reports/monitor\-live.json\fP based on the traffic +through port \fB27017\fP on the \fBeth0\fP network interface: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoreplay monitor \-i eth0 \-e \(aqport 27017\(aq \-\-report ~/reports/monitor\-live.json \-\-collect json +.ft P +.fi +.UNINDENT +.UNINDENT +.SH AUTHOR +MongoDB Documentation Project +.SH COPYRIGHT +2008-2019 +.\" Generated by docutils manpage writer. +. diff --git a/debian/mongorestore.1 b/debian/mongorestore.1 index ce2e6bd4b2c..d75f598b099 100644 --- a/debian/mongorestore.1 +++ b/debian/mongorestore.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGORESTORE" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGORESTORE" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongorestore \- MongoDB Data Restoration Tool . @@ -35,6 +35,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .IP \(bu 2 \fI\%Synopsis\fP .IP \(bu 2 +\fI\%Usage in Backup Strategy\fP +.IP \(bu 2 \fI\%Syntax\fP .IP \(bu 2 \fI\%Behavior\fP @@ -59,9 +61,29 @@ The \fI\%mongorestore\fP program loads data from either a binary database dump created by \fBmongodump\fP or the standard input (starting in version 3.0.0) into a \fBmongod\fP or \fBmongos\fP instance. +.SH USAGE IN BACKUP STRATEGY +.SS Standalones/Replica Sets .sp -For an overview of \fI\%mongorestore\fP usage, see +For an overview of \fI\%mongorestore\fP usage as part of a +backup and recovery strategy, see /tutorial/backup\-and\-restore\-tools\&. +.SS Sharded Clusters +.sp +Starting in MongoDB 4.2, \fBmongodump\fP and +\fI\%mongorestore\fP \fBcannot\fP be part of a backup +strategy for sharded clusters. These manual tools do not maintain +the atomicity guarantees of transactions across shards. +.sp +To maintain the atomicity guarantees of transactions across shards, +use the coordinated backup and restore services provided by: +.INDENT 0.0 +.IP \(bu 2 +\fI\%MongoDB Atlas\fP, +.IP \(bu 2 +\fI\%MongoDB Cloud Manager\fP, or +.IP \(bu 2 +\fI\%MongoDB Ops Manager\fP\&. +.UNINDENT .SH SYNTAX .sp Run \fI\%mongorestore\fP from the system command line, not the \fBmongo\fP shell. @@ -810,6 +832,15 @@ patterns. If source directory or file (i.e. the directory/file from which you are restoring the data) does not contain data files that match the namespace pattern, no data will be restored. +.sp +For collection names that contain non\-ascii characters, +\fBmongodump\fP outputs the corresponding filenames with +percent\-encoded names. However, to restore these collections, do not +use the encoded names. Instead, use the namespace with the non\-ascii +characters. +.sp +For example, if the dump directory contains +\fBdump/test/caf%C3%A9s.bson\fP, specify \fB\-\-nsInclude "test.cafés"\fP\&. .UNINDENT .INDENT 0.0 .TP diff --git a/debian/mongos.1 b/debian/mongos.1 index f1a5c14f9b6..db9e626e3df 100644 --- a/debian/mongos.1 +++ b/debian/mongos.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOS" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOS" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongos \- MongoDB Sharded Cluster Query Router . @@ -791,12 +791,26 @@ mongos \-\-timeZoneInfo timezonedb\-2017b/ New in version 4.2. .sp -Outputs the resolved YAML configuration document for the \fBmongos\fP -to \fBstdout\fP and halts the \fBmongos\fP instance. For configuration -options using externally\-sourced\-values, \fI\%\-\-outputConfig\fP returns the -resolved value for those options. This may include any configured -passwords or secrets previously obfuscated through the external -source. +Outputs the \fBmongos\fP instance\(aqs configuration options, formatted +in YAML, to \fBstdout\fP and exits the \fBmongos\fP instance. For +configuration options that uses externally\-sourced\-values, +\fI\%\-\-outputConfig\fP returns the resolved value for those options. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This may include any configured passwords or secrets previously +obfuscated through the external source. +.UNINDENT +.UNINDENT +.sp +For usage examples, see: +.INDENT 7.0 +.IP \(bu 2 +expansion\-directive\-output +.IP \(bu 2 +/tutorial/convert\-command\-line\-options\-to\-yaml +.UNINDENT .UNINDENT .SS Sharded Cluster Options .INDENT 0.0 diff --git a/debian/mongostat.1 b/debian/mongostat.1 index 4cda514a21d..68d3c233fbe 100644 --- a/debian/mongostat.1 +++ b/debian/mongostat.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOSTAT" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOSTAT" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongostat \- MongoDB Use Statistics . diff --git a/debian/mongotop.1 b/debian/mongotop.1 index 23eb81c26bb..fd74b566724 100644 --- a/debian/mongotop.1 +++ b/debian/mongotop.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOTOP" "1" "Jul 25, 2019" "4.2" "mongodb-manual" +.TH "MONGOTOP" "1" "Aug 16, 2019" "4.2" "mongodb-manual" .SH NAME mongotop \- MongoDB Activity Monitor . |