From f94b12015e20f3237831b59d43342c9e8ac7db47 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 4 Feb 2014 17:35:35 -0500 Subject: [PATCH 1/8] add mongorestore path option to yaml files --- source/includes/options-mongorestore.yaml | 9 +++++++++ source/reference/program/mongorestore.txt | 6 +----- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/source/includes/options-mongorestore.yaml b/source/includes/options-mongorestore.yaml index 4ccd6e68295..5eba2b5aa50 100644 --- a/source/includes/options-mongorestore.yaml +++ b/source/includes/options-mongorestore.yaml @@ -291,4 +291,13 @@ description: | :program:`mongorestore` does not wait for a response for :ref:`write acknowledgment `. optional: true +--- +program: mongorestore +name: +directive: option +description: | + The final argument of the :program:`mongorestore` command is a + directory path. This argument specifies the location of the + database dump from which to restore. +optional: true ... diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt index b03a23c11d4..0c92f39de2d 100644 --- a/source/reference/program/mongorestore.txt +++ b/source/reference/program/mongorestore.txt @@ -127,11 +127,7 @@ Options .. _mongorestore-path-option: -.. option:: - - The final argument of the :program:`mongorestore` command is a - directory path. This argument specifies the location of the - database dump from which to restore. +.. include:: /includes/option/option-mongorestore-.rst Use --- From 5a5396579e42eca222f7f85ec37b68ab3af3b096 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 10:01:00 -0500 Subject: [PATCH 2/8] DOCS-2501 minor --- source/includes/options-mongorestore.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/source/includes/options-mongorestore.yaml b/source/includes/options-mongorestore.yaml index 5eba2b5aa50..c472d791a9d 100644 --- a/source/includes/options-mongorestore.yaml +++ b/source/includes/options-mongorestore.yaml @@ -295,6 +295,7 @@ optional: true program: mongorestore name: directive: option +args: null description: | The final argument of the :program:`mongorestore` command is a directory path. This argument specifies the location of the From 3f6cd198b60af46ff7a191e93d5bb4f918c89987 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 10:02:59 -0500 Subject: [PATCH 3/8] DOCS-2501 runtime options: mongoperf --- source/includes/options-mongoperf.yaml | 43 ++++++++++++++++++++++++++ source/reference/program/mongoperf.txt | 36 ++------------------- 2 files changed, 45 insertions(+), 34 deletions(-) create mode 100644 source/includes/options-mongoperf.yaml diff --git a/source/includes/options-mongoperf.yaml b/source/includes/options-mongoperf.yaml new file mode 100644 index 00000000000..035bc90b603 --- /dev/null +++ b/source/includes/options-mongoperf.yaml @@ -0,0 +1,43 @@ +# This file borrows content from /includes/options-shared.yaml, which uses +# {{program}} to refer to the tool. +# +program: mongoperf +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongoperf +name: +directive: option +args: null +description: | + :program:`mongoperf` accepts configuration options in the form of a + file that holds a :term:`JSON` document. You must stream the + content of this file into :program:`mongoperf`, as in the following + operation: + + .. code-block:: sh + + mongoperf < config + + In this example ``config`` is the name of a file that holds a JSON + document that resembles the following example: + + .. code-block:: javascript + + { + nThreads:, + fileSizeMB:, + sleepMicros:, + mmf:, + r:, + w:, + recSizeKB:, + syncDelay: + } + + See the :ref:`mongoperf-fields` section for documentation of each + of these fields. +... diff --git a/source/reference/program/mongoperf.txt b/source/reference/program/mongoperf.txt index 9d52f66907c..35747b6159b 100644 --- a/source/reference/program/mongoperf.txt +++ b/source/reference/program/mongoperf.txt @@ -39,41 +39,9 @@ Options .. program:: mongoperf -.. option:: --help +.. include:: /includes/option/option-mongoperf-help.rst - Displays the options to :program:`mongoperf`. Specify options to - :program:`mongoperf` with a JSON document described in the - :ref:`mongoperf-fields` section. - -.. option:: - - :program:`mongoperf` accepts configuration options in the form of a - file that holds a :term:`JSON` document. You must stream the - content of this file into :program:`mongoperf`, as in the following - operation: - - .. code-block:: sh - - mongoperf < config - - In this example ``config`` is the name of a file that holds a JSON - document that resembles the following example: - - .. code-block:: javascript - - { - nThreads:, - fileSizeMB:, - sleepMicros:, - mmf:, - r:, - w:, - recSizeKB:, - syncDelay: - } - - See the :ref:`mongoperf-fields` section for documentation of each - of these fields. +.. include:: /includes/option/option-mongoperf-.rst .. _mongoperf-fields: From ace8bf4fecef008bf4b1546f93d567149e7d5fe2 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 10:03:42 -0500 Subject: [PATCH 4/8] DOCS-2501 runtime options: mongostat --- source/includes/manpage-options-ssl-tools.rst | 90 --------- source/includes/options-mongostat.yaml | 178 ++++++++++++++++++ source/includes/replace-pem-path-name.rst | 2 - source/reference/program/mongostat.txt | 120 +++--------- 4 files changed, 201 insertions(+), 189 deletions(-) delete mode 100644 source/includes/manpage-options-ssl-tools.rst create mode 100644 source/includes/options-mongostat.yaml delete mode 100644 source/includes/replace-pem-path-name.rst diff --git a/source/includes/manpage-options-ssl-tools.rst b/source/includes/manpage-options-ssl-tools.rst deleted file mode 100644 index 9ac4a605ea3..00000000000 --- a/source/includes/manpage-options-ssl-tools.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. COMMENT because the common settings are not quite commong - -- different versions added, - -- invalid certificate check differ for mongod/mongos vs mongo, - -- description differ for sslPEMKeyFile - using separate rsts for mongod/s, mongo, tools - -.. COMMENT this tools include file, unlike mongod/mongos/mongo - uses the replacement holder of |tool-binary| to take - advantage of the replace statement already in place in the - individual program's file. - -.. include:: /includes/replace-pem-path-name.rst - -.. option:: --ssl - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Enable connection to a :program:`mongod` or - :program:`mongos` that has SSL support enabled. - -.. option:: --sslPEMKeyFile - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Specifies the :file:`.pem` file that contains both the SSL - certificate and key. |pem-path-name| - - Required when using the :option:`--ssl` option to connect to - :program:`mongod` or :program:`mongos` that have - :setting:`sslCAFile` enabled *without* - :setting:`sslWeakCertificateValidation`. - -.. option:: --sslPEMKeyPassword - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Specifies the password to de-crypt the certificate-key file - (i.e. :option:`--sslPEMKeyFile`). Only use - :option:`--sslPEMKeyPassword` if the certificate-key file is - encrypted. In all cases, |tool-binary| will redact the password from - all logging and reporting output. - - If the private key in the PEM file is encrypted and you do not - specify :option:`--sslPEMKeyPassword`, |tool-binary| will prompt for - a passphrase. See :ref:`ssl-certificate-password`. - -.. option:: --sslCAFile - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Specifies the :file:`.pem` file that contains the root certificate - chain from the Certificate Authority. |pem-path-name| - -.. option:: --sslCRLFile - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Specifies the :file:`.pem` file that contains the Certificate - Revocation List. |pem-path-name| - -.. option:: --sslFIPSMode - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - When specified, |binary-name| will use the FIPS mode of the - installed OpenSSL library. Your system must have a FIPS compliant - OpenSSL library to use :option:`--sslFIPSMode`. - -.. option:: --sslAllowInvalidCertificates - - .. versionadded:: 2.5.4 - - .. include:: /includes/note-general-ssl-support.rst - - Bypasses the validation checks for server certificates and allows - the use of invalid certificates. When using the - :setting:`sslAllowInvalidCertificates` setting, MongoDB logs as a - warning the use of the invalid certificate. diff --git a/source/includes/options-mongostat.yaml b/source/includes/options-mongostat.yaml new file mode 100644 index 00000000000..8f0d4f21f2c --- /dev/null +++ b/source/includes/options-mongostat.yaml @@ -0,0 +1,178 @@ +# This file borrows content from /includes/options-shared.yaml, which uses +# {{program}} to refer to the tool. +# +program: mongostat +name: all +directive: option +args: null +description: | + Configures :program:`mongostat` to return all optional :ref:`fields + `. +optional: true +--- +program: mongostat +name: authenticationDatabase +inherit: + name: authenticationDatabase + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: authenticationMechanism +inherit: + name: authenticationMechanism + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: discover +directive: option +args: null +description: | + Discovers and reports on statistics from all members of a :term:`replica + set` or :term:`sharded cluster`. When connected to any member of a + replica set, :option:`--discover` all non-:term:`hidden members ` of the replica set. When connected to a :program:`mongos`, + :program:`mongostat` will return data from all :term:`shards ` in + the cluster. If a replica set provides a shard in the sharded cluster, + :program:`mongostat` will report on non-hidden members of that replica + set. + + The :option:`mongostat --host` option is not required but + potentially useful in this case. + + .. versionchanged:: 2.5.3 + When running with :option:`--discover`, :program:`mongostat` now + respects :option:--rowcount`. +optional: true +--- +program: mongostat +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: host +inherit: + name: host + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: http +directive: option +args: null +description: | + Configures :program:`mongostat` to collect data using the HTTP interface + rather than a raw database connection. +optional: true +--- +program: mongostat +name: ipv6 +inherit: + name: ipv6 + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: noheaders +directive: option +args: null +description: | + Disables the output of column or field names. +optional: true +--- +program: mongostat +name: password +inherit: + name: password + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: port +inherit: + name: port + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: rowcount +aliases:-n +directive: option +args: +description: | + Controls the number of rows to output. Use in conjunction with + the ``sleeptime`` argument to control the duration of a + :program:`mongostat` operation. + + Unless :option:`--rowcount` is specified, :program:`mongostat` + will return an infinite number of rows (e.g. value of ``0``.) +optional: true +--- +program: mongostat +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslAllowInvalidCertificates +inherit: + name: sslAllowInvalidCertificates + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslCAFile +inherit: + name: sslCAFile + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslCRLFile +inherit: + name: sslCRLFile + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslFIPSMode +inherit: + name: sslFIPSMode + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslPEMKeyFile +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml +--- +program: mongostat +name: +directive: option +args: null +description: | + The final argument is the length of time, in seconds, that + :program:`mongostat` waits in between calls. By default :program:`mongostat` + returns one call every second. + + :program:`mongostat` returns values that reflect the operations + over a 1 second period. For values of ```` greater + than 1, :program:`mongostat` averages data to reflect average + operations per second. +optional: true +... diff --git a/source/includes/replace-pem-path-name.rst b/source/includes/replace-pem-path-name.rst deleted file mode 100644 index 547225b9bd6..00000000000 --- a/source/includes/replace-pem-path-name.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. |pem-path-name| replace:: Specify the file name of the :file:`.pem` - file using relative or absolute paths diff --git a/source/reference/program/mongostat.txt b/source/reference/program/mongostat.txt index 67a2c0018cf..49ee6709486 100644 --- a/source/reference/program/mongostat.txt +++ b/source/reference/program/mongostat.txt @@ -45,125 +45,51 @@ Options .. program:: mongostat -.. option:: --help +.. include:: /includes/option/option-mongostat-help.rst - Returns a basic help and usage text. +.. include:: /includes/option/option-mongostat-verbose.rst -.. option:: --verbose, -v +.. include:: /includes/option/option-mongostat-version.rst - Increases the amount of internal reporting returned on the command - line. Increase the verbosity with the ``-v`` form by including - the option multiple times, (e.g. ``-vvvvv``.) +.. include:: /includes/option/option-mongostat-host.rst -.. option:: --version +.. include:: /includes/option/option-mongostat-port.rst - Returns the version of the :program:`mongostat` utility. +.. include:: /includes/option/option-mongostat-ipv6.rst -.. option:: --host <:port> +.. include:: /includes/option/option-mongostat-ssl.rst - Specifies a resolvable hostname for the :program:`mongod` from which you - want to export data. By default :program:`mongostat` attempts to connect - to a MongoDB instance running on the localhost port number ``27017``. +.. include:: /includes/option/option-mongostat-sslCAFile.rst - Optionally, specify a port number to connect a MongoDB instance - running on a port other than ``27017``. +.. include:: /includes/option/option-mongostat-sslPEMKeyFile.rst - .. include:: /includes/fact-multiple-hosts.rst +.. include:: /includes/option/option-mongostat-sslPEMKeyPassword.rst -.. option:: --port +.. include:: /includes/option/option-mongostat-sslCRLFile.rst - Specifies the port number, if the MongoDB instance is not running on - the standard port. (i.e. ``27017``) You may also specify a port - number using the :option:`mongostat --host` command. +.. include:: /includes/option/option-mongostat-sslAllowInvalidCertificates.rst -.. option:: --ipv6 +.. include:: /includes/option/option-mongostat-sslFIPSMode.rst - Enables IPv6 support that allows :program:`mongostat` to connect - to the MongoDB instance using an IPv6 network. All MongoDB programs - and processes, including :program:`mongostat`, disable IPv6 - support by default. +.. include:: /includes/option/option-mongostat-username.rst -.. include:: /includes/manpage-options-ssl-tools.rst +.. include:: /includes/option/option-mongostat-password.rst -.. option:: --username , -u +.. include:: /includes/option/option-mongostat-authenticationDatabase.rst - Specifies a username to authenticate to the MongoDB instance, if your - database requires authentication. Use in conjunction with the - :option:`mongostat --password` option to supply a password. +.. include:: /includes/option/option-mongostat-authenticationMechanism.rst - .. important:: This user must have sufficient credentials to run - the :dbcommand:`serverStatus` command, which is the - :authrole:`clusterAdmin` role. See - :doc:`/reference/built-in-roles` and - :doc:`/reference/privilege-documents` for more information. +.. include:: /includes/option/option-mongostat-noheaders.rst -.. option:: --password , -p +.. include:: /includes/option/option-mongostat-rowcount.rst - Specifies a password to authenticate to the MongoDB instance. Use - in conjunction with the :option:`mongostat --username` option to - supply a username. +.. include:: /includes/option/option-mongostat-http.rst - If you specify a :option:`--username`, and do do not pass an - argument to :option:`--password`, :program:`mongostat` will prompt - for a password interactively. If you do not specify a password on - the command line, :option:`--password` must be the last argument - specified. +.. include:: /includes/option/option-mongostat-discover.rst -.. |binary-name| replace:: :program:`mongostat` -.. include:: /includes/manpage-options-auth.rst +.. include:: /includes/option/option-mongostat-all.rst -.. option:: --noheaders - - Disables the output of column or field names. - -.. option:: --rowcount , -n - - Controls the number of rows to output. Use in conjunction with - the ``sleeptime`` argument to control the duration of a - :program:`mongostat` operation. - - Unless :option:`--rowcount` is specified, :program:`mongostat` - will return an infinite number of rows (e.g. value of ``0``.) - -.. option:: --http - - Configures :program:`mongostat` to collect data using the HTTP interface - rather than a raw database connection. - -.. option:: --discover - - With this option :program:`mongostat` discovers and reports on - statistics from all members of a :term:`replica set` or - :term:`sharded cluster`. When connected to any member of a replica - set, :option:`--discover` all non-:term:`hidden members ` of the replica set. When connected to a :program:`mongos`, - :program:`mongostat` will return data from all :term:`shards - ` in the cluster. If a replica set provides a shard in the - sharded cluster, :program:`mongostat` will report on non-hidden - members of that replica set. - - The :option:`mongostat --host` option is not required but - potentially useful in this case. - - .. versionchanged:: 2.5.3 - When running with :option:`--discover`, :program:`mongostat` now - respects :option:--rowcount`. - -.. option:: --all - - Configures :program:`mongostat` to return all optional :ref:`fields - `. - -.. option:: - - The final argument is the length of time, in seconds, that - :program:`mongostat` waits in between calls. By default :program:`mongostat` - returns one call every second. - - :program:`mongostat` returns values that reflect the operations - over a 1 second period. For values of ```` greater - than 1, :program:`mongostat` averages data to reflect average - operations per second. +.. include:: /includes/option/option-mongostat-.rst .. _mongostat-fields: From 43ea81c598de07de4c280af6e5dc9b0ef5e82225 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 14:57:55 -0500 Subject: [PATCH 5/8] DOCS-2501 runtime options: reordering options in yaml files to same order they are in the reference pages, to narrow the room for error. PART I: _shared, sondump, mongodump, mongoexport, mongofiles --- source/includes/options-bsondump.yaml | 61 ++-- source/includes/options-mongodump.yaml | 313 ++++++++--------- source/includes/options-mongoexport.yaml | 415 ++++++++++++----------- source/includes/options-mongofiles.yaml | 195 ++++++----- source/includes/options-shared.yaml | 274 +++++++-------- source/reference/program/mongodump.txt | 1 + 6 files changed, 648 insertions(+), 611 deletions(-) diff --git a/source/includes/options-bsondump.yaml b/source/includes/options-bsondump.yaml index f14c9f2005e..4017f1e4b7a 100644 --- a/source/includes/options-bsondump.yaml +++ b/source/includes/options-bsondump.yaml @@ -10,22 +10,25 @@ inherit: file: options-shared.yaml --- program: bsondump -name: filter -directive: option -args: '' -description: | - Limits the documents that {{program}} exports to only those - documents that match the :term:`JSON document` specified as - ``''``. Be sure to include the document in single quotes to avoid - interaction with your system's shell environment. -optional: true +name: verbose +inherit: + name: verbose + program: _shared + file: options-shared.yaml --- program: bsondump -name: noobjcheck +name: quiet inherit: - name: noobjcheck - program: mongod - file: options-mongod.yaml + name: quiet + program: _shared + file: options-shared.yaml +--- +program: bsondump +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml --- program: bsondump name: objcheck @@ -45,6 +48,24 @@ description: | optional: true --- program: bsondump +name: noobjcheck +inherit: + name: noobjcheck + program: mongod + file: options-mongod.yaml +--- +program: bsondump +name: filter +directive: option +args: '' +description: | + Limits the documents that {{program}} exports to only those + documents that match the :term:`JSON document` specified as + ``''``. Be sure to include the document in single quotes to avoid + interaction with your system's shell environment. +optional: true +--- +program: bsondump name: type directive: option args: <=json|=debug> @@ -54,20 +75,6 @@ description: | optional: true --- program: bsondump -name: verbose -inherit: - name: verbose - program: _shared - file: options-shared.yaml ---- -program: bsondump -name: version -inherit: - name: version - program: _shared - file: options-shared.yaml ---- -program: bsondump name: directive: option description: | diff --git a/source/includes/options-mongodump.yaml b/source/includes/options-mongodump.yaml index 9fef46cc5e4..86389311bba 100644 --- a/source/includes/options-mongodump.yaml +++ b/source/includes/options-mongodump.yaml @@ -2,91 +2,44 @@ # {{role}} to refer to the tool. # program: mongodump -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongodump -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongodump -name: collection -aliases: -c -directive: option -args: -description: | - Specifies a collection to backup. If you do not specify a collection, - this option copies all collections in the specified database or instance - to the dump files. -optional: true ---- -program: mongodump -name: db -aliases: -d -directive: option -args: -description: | - Specifies a database to backup. If you do not specify a database, - :program:`mongodump` copies all databases in this instance into the dump - files. -optional: true ---- -program: mongodump -name: dbpath +name: quiet inherit: - name: dbpath + name: quiet program: _shared file: options-shared.yaml --- program: mongodump -name: directoryperdb +name: version inherit: - name: directoryperdb + name: version program: _shared file: options-shared.yaml --- program: mongodump -name: forceTableScan -directive: option -args: null -description: | - Forces :program:`mongodump` to scan the data store directly: typically, - :program:`mongodump` saves entries as they appear in the index of the - ``_id`` field. Use :option:`--forceTableScan` to skip the index and scan - the data directly. Typically there are two cases where this behavior is - preferable to the default: - - 1. If you have key sizes over 800 bytes that would not be present in the - ``_id`` index. - - 2. Your database uses a custom ``_id`` field. - - When you run with :option:`--forceTableScan`, :program:`mongodump` does - not use :operator:`$snapshot`. As a result, the dump produced by - :program:`mongodump` can reflect the state of the database at many - different points in time. - - .. important:: Use :option:`--forceTableScan` with extreme caution and - consideration. -optional: true ---- -program: mongodump -name: help +name: host inherit: - name: help + name: host program: _shared file: options-shared.yaml --- program: mongodump -name: host +name: port inherit: - name: host + name: port program: _shared file: options-shared.yaml --- @@ -98,102 +51,37 @@ inherit: file: options-shared.yaml --- program: mongodump -name: journal +name: ssl inherit: - name: journal + name: ssl program: _shared file: options-shared.yaml --- program: mongodump -name: oplog -directive: option -args: null -description: | - Use this option to ensure that :program:`mongodump` creates a dump of - the database that includes a partial :term:`oplog` containing operations - from the duration of the :program:`mongodump` operation. This oplog - produces an effective point-in-time snapshot of the state of a - :program:`mongod` instance. To restore to a specific point-in-time - backup, use the output created with this option in conjunction with - :option:`mongorestore --oplogReplay`. - - Without :option:`--oplog`, if there are write operations during the dump - operation, the dump will not reflect a single moment in time. Changes - made to the database during the update process can affect the output of - the backup. - - :option:`--oplog` has no effect when running :program:`mongodump` - against a :program:`mongos` instance to dump the entire contents of a - sharded cluster. However, you can use :option:`--oplog` to dump - individual shards. - - :option:`--oplog` only works against nodes that maintain an - :term:`oplog`. This includes all members of a replica set, as well as - :term:`master` nodes in master/slave replication deployments. - - :option:`--oplog` does not dump the oplog collection. -optional: true ---- -program: mongodump -name: out -aliases: -o -directive: option -args: -description: | - Specifies the directory where :program:`mongodump` saves the output of - the database dump. By default, :program:`mongodump` saves output files - in a directory named ``dump`` in the current working directory. - - To send the database dump to standard output, specify "``-``" instead of - a path. Write to standard output if you want process the output before - saving it, such as to use ``gzip`` to compress the dump. When writing - standard output, :program:`mongodump` does not write the metadata that - writes in a ``.metadata.json`` file when writing to files - directly. -optional: true ---- -program: mongodump -name: password +name: sslCAFile inherit: - name: password + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongodump -name: port +name: sslPEMKeyFile inherit: - name: port + name: sslPEMKeyFile program: _shared file: options-shared.yaml --- program: mongodump -name: query -aliases: -q -directive: option -args: -description: | - Provides a :term:`JSON document` as a query that optionally limits the - documents included in the output of :program:`mongodump`. -optional: true ---- -program: mongodump -name: repair -directive: option -args: null -description: | - Use this option to run a repair option in addition to dumping the - database. The repair option attempts to repair a database that may be in - an invalid state as a result of an improper shutdown or - :program:`mongod` crash. - - The :option:`--repair` option uses aggressive data-recovery algorithms - that may produce a large amount of duplication. -optional: true +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml --- program: mongodump -name: ssl +name: sslCRLFile inherit: - name: ssl + name: sslCRLFile program: _shared file: options-shared.yaml --- @@ -205,58 +93,177 @@ inherit: file: options-shared.yaml --- program: mongodump -name: sslCAFile +name: sslFIPSMode inherit: - name: sslCAFile + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongodump -name: sslCRLFile +name: username inherit: - name: sslCRLFile + name: username program: _shared file: options-shared.yaml --- program: mongodump -name: sslFIPSMode +name: password inherit: - name: sslFIPSMode + name: password program: _shared file: options-shared.yaml --- program: mongodump -name: sslPEMKeyFile +name: authenticationDatabase inherit: - name: sslPEMKeyFile + name: authenticationDatabase program: _shared file: options-shared.yaml --- program: mongodump -name: sslPEMKeyPassword +name: authenticationMechanism inherit: - name: sslPEMKeyPassword + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongodump -name: username +name: dbpath inherit: - name: username + name: dbpath program: _shared file: options-shared.yaml --- program: mongodump -name: verbose +name: directoryperdb inherit: - name: verbose + name: directoryperdb program: _shared file: options-shared.yaml --- program: mongodump -name: version +name: journal inherit: - name: version + name: journal program: _shared file: options-shared.yaml +--- +program: mongodump +name: db +aliases: -d +directive: option +args: +description: | + Specifies a database to backup. If you do not specify a database, + :program:`mongodump` copies all databases in this instance into the dump + files. +optional: true +--- +program: mongodump +name: collection +aliases: -c +directive: option +args: +description: | + Specifies a collection to backup. If you do not specify a collection, + this option copies all collections in the specified database or instance + to the dump files. +optional: true +--- +program: mongodump +name: out +aliases: -o +directive: option +args: +description: | + Specifies the directory where :program:`mongodump` saves the output of + the database dump. By default, :program:`mongodump` saves output files + in a directory named ``dump`` in the current working directory. + + To send the database dump to standard output, specify "``-``" instead of + a path. Write to standard output if you want process the output before + saving it, such as to use ``gzip`` to compress the dump. When writing + standard output, :program:`mongodump` does not write the metadata that + writes in a ``.metadata.json`` file when writing to files + directly. +optional: true +--- +program: mongodump +name: query +aliases: -q +directive: option +args: +description: | + Provides a :term:`JSON document` as a query that optionally limits the + documents included in the output of :program:`mongodump`. +optional: true +--- +program: mongodump +name: oplog +directive: option +args: null +description: | + Use this option to ensure that :program:`mongodump` creates a dump of + the database that includes a partial :term:`oplog` containing operations + from the duration of the :program:`mongodump` operation. This oplog + produces an effective point-in-time snapshot of the state of a + :program:`mongod` instance. To restore to a specific point-in-time + backup, use the output created with this option in conjunction with + :option:`mongorestore --oplogReplay`. + + Without :option:`--oplog`, if there are write operations during the dump + operation, the dump will not reflect a single moment in time. Changes + made to the database during the update process can affect the output of + the backup. + + :option:`--oplog` has no effect when running :program:`mongodump` + against a :program:`mongos` instance to dump the entire contents of a + sharded cluster. However, you can use :option:`--oplog` to dump + individual shards. + + :option:`--oplog` only works against nodes that maintain an + :term:`oplog`. This includes all members of a replica set, as well as + :term:`master` nodes in master/slave replication deployments. + + :option:`--oplog` does not dump the oplog collection. +optional: true +--- +program: mongodump +name: repair +directive: option +args: null +description: | + Use this option to run a repair option in addition to dumping the + database. The repair option attempts to repair a database that may be in + an invalid state as a result of an improper shutdown or + :program:`mongod` crash. + + The :option:`--repair` option uses aggressive data-recovery algorithms + that may produce a large amount of duplication. +optional: true +--- +program: mongodump +name: forceTableScan +directive: option +args: null +description: | + Forces :program:`mongodump` to scan the data store directly: typically, + :program:`mongodump` saves entries as they appear in the index of the + ``_id`` field. Use :option:`--forceTableScan` to skip the index and scan + the data directly. Typically there are two cases where this behavior is + preferable to the default: + + 1. If you have key sizes over 800 bytes that would not be present in the + ``_id`` index. + + 2. Your database uses a custom ``_id`` field. + + When you run with :option:`--forceTableScan`, :program:`mongodump` does + not use :operator:`$snapshot`. As a result, the dump produced by + :program:`mongodump` can reflect the state of the database at many + different points in time. + + .. important:: Use :option:`--forceTableScan` with extreme caution and + consideration. +optional: true ... diff --git a/source/includes/options-mongoexport.yaml b/source/includes/options-mongoexport.yaml index 21f61ae5332..61a22eabc4f 100644 --- a/source/includes/options-mongoexport.yaml +++ b/source/includes/options-mongoexport.yaml @@ -2,206 +2,210 @@ # {{program}} to refer to the tool. # program: mongoexport -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongoexport -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongoexport -name: collection -aliases: -c -directive: option -args: -description: | - Specifies the collection to export. -optional: true +name: quiet +inherit: + name: quiet + program: _shared + file: options-shared.yaml --- program: mongoexport -name: csv -directive: option -args: null -description: | - Changes the export format to a comma-separated-values (CSV) - format. By default :program:`mongoexport` writes data using one - :term:`JSON` document for every MongoDB document. - - If you specify :option:`--csv`, then you must also use either - the :option:`--fields` or the :option:`--fieldFile` option to - declare the fields to export from the collection. -optional: true +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml --- program: mongoexport -name: db +name: host inherit: - name: db + name: host program: _shared file: options-shared.yaml --- program: mongoexport -name: dbpath +name: port inherit: - name: dbpath + name: port program: _shared file: options-shared.yaml --- program: mongoexport -name: directoryperdb -directive: option -args: null -description: | - When used in conjunction with the corresponding option in - :program:`mongod`, allows :program:`mongoexport` to export data from - MongoDB instances that have every database's files saved in discrete - directories on the disk. This option is only relevant when specifying - the :option:`--dbpath` option. -optional: true +name: ipv6 +inherit: + name: ipv6 + program: _shared + file: options-shared.yaml --- program: mongoexport -name: fieldFile -directive: option -args: -description: | - As an alternative to :option:`--fields `, the - :option:`--fieldFile ` option allows you to - specify in a file the field or fields to *include* in the export and is - **only valid** with the :option:`--csv ` option. The - file must have only one field per line, and the line(s) must end with - the LF character (``0x0A``). - - :program:`mongoexport` includes only the specified field(s). The - specified field(s) can be a field within a sub-document. -optional: true +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml --- program: mongoexport -name: fields -aliases: -f -directive: option -args: -description: | - Specifies a field or fields to *include* in the export. Use a comma - separated list of fields to specify multiple fields. - - For :option:`--csv ` output formats, - :program:`mongoexport` includes only the specified field(s), and the - specified field(s) can be a field within a sub-document. - - For :term:`JSON` output formats, :program:`mongoexport` includes - only the specified field(s) **and** the ``_id`` field, and if the - specified field(s) is a field within a sub-document, the - :program:`mongoexport` includes the sub-document with all - its fields, not just the specified field within the document. -optional: true +name: sslCAFile +inherit: + name: sslCAFile + program: _shared + file: options-shared.yaml --- program: mongoexport -name: forceTableScan -directive: option -args: null -description: | - .. versionadded:: 2.2 - - Forces :program:`mongoexport` to scan the data store directly: - typically, :program:`mongoexport` saves entries as they appear in the - index of the ``_id`` field. Use :option:`--forceTableScan` to skip - the index and scan the data directly. Typically there are two cases - where this behavior is preferable to the default: - - 1. If you have key sizes over 800 bytes that would not be present - in the ``_id`` index. - - 2. Your database uses a custom ``_id`` field. - - When you run with :option:`--forceTableScan`, :program:`mongoexport` - does not use :operator:`$snapshot`. As a result, the export produced - by :program:`mongoexport` can reflect the state of the database at - many different points in time. - - .. warning:: Use :option:`--forceTableScan` with extreme caution - and consideration. -optional: true +name: sslPEMKeyFile +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml --- program: mongoexport -name: help +name: sslPEMKeyPassword inherit: - name: help + name: sslPEMKeyPassword program: _shared file: options-shared.yaml --- program: mongoexport -name: host +name: sslCRLFile inherit: - name: host + name: sslCRLFile program: _shared file: options-shared.yaml --- program: mongoexport -name: ipv6 +name: sslAllowInvalidCertificates inherit: - name: ipv6 + name: sslAllowInvalidCertificates program: _shared file: options-shared.yaml --- program: mongoexport -name: journal +name: sslFIPSMode inherit: - name: journal + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongoexport -name: jsonArray -directive: option -args: null -description: | - Modifies the output of :program:`mongoexport` to write the - entire contents of the export as a single :term:`JSON` array. By - default :program:`mongoexport` writes data using one JSON document - for every MongoDB document. -optional: true +name: username +inherit: + name: username + program: _shared + file: options-shared.yaml --- program: mongoexport -name: limit -directive: option -args: -description: | - Specifies a maximum number of documents to include in the - export. See :method:`~cursor.limit()` for information about - the underlying operation. -optional: true +name: password +inherit: + name: password + program: _shared + file: options-shared.yaml --- program: mongoexport -name: out -aliases: -o +name: authenticationDatabase +inherit: + name: authenticationDatabase + program: _shared + file: options-shared.yaml +--- +program: mongoexport +name: authenticationMechanism +inherit: + name: authenticationMechanism + program: _shared + file: options-shared.yaml +--- +program: mongoexport +name: dbpath +inherit: + name: dbpath + program: _shared + file: options-shared.yaml +--- +program: mongoexport +name: directoryperdb directive: option -args: +args: null description: | - Specifies a file to write the export to. If you do not specify a file - name, the :program:`mongoexport` writes data to standard output - (e.g. ``stdout``). + When used in conjunction with the corresponding option in + :program:`mongod`, allows :program:`mongoexport` to export data from + MongoDB instances that have every database's files saved in discrete + directories on the disk. This option is only relevant when specifying + the :option:`--dbpath` option. optional: true --- program: mongoexport -name: password +name: journal inherit: - name: password + name: journal program: _shared file: options-shared.yaml --- program: mongoexport -name: port +name: db inherit: - name: port + name: db program: _shared file: options-shared.yaml --- program: mongoexport +name: collection +aliases: -c +directive: option +args: +description: | + Specifies the collection to export. +optional: true +--- +program: mongoexport +name: fields +aliases: -f +directive: option +args: +description: | + Specifies a field or fields to *include* in the export. Use a comma + separated list of fields to specify multiple fields. + + For :option:`--csv ` output formats, + :program:`mongoexport` includes only the specified field(s), and the + specified field(s) can be a field within a sub-document. + + For :term:`JSON` output formats, :program:`mongoexport` includes + only the specified field(s) **and** the ``_id`` field, and if the + specified field(s) is a field within a sub-document, the + :program:`mongoexport` includes the sub-document with all + its fields, not just the specified field within the document. +optional: true +--- +program: mongoexport +name: fieldFile +directive: option +args: +description: | + As an alternative to :option:`--fields `, the + :option:`--fieldFile ` option allows you to + specify in a file the field or fields to *include* in the export and is + **only valid** with the :option:`--csv ` option. The + file must have only one field per line, and the line(s) must end with + the LF character (``0x0A``). + + :program:`mongoexport` includes only the specified field(s). The + specified field(s) can be a field within a sub-document. +optional: true +--- +program: mongoexport name: query aliases: -q directive: option @@ -238,13 +242,39 @@ description: | optional: true --- program: mongoexport -name: skip +name: csv directive: option -args: +args: null description: | - Use :option:`--skip` to control where :program:`mongoexport` begins - exporting documents. See :method:`~cursor.skip()` for information about - the underlying operation. + Changes the export format to a comma-separated-values (CSV) + format. By default :program:`mongoexport` writes data using one + :term:`JSON` document for every MongoDB document. + + If you specify :option:`--csv`, then you must also use either + the :option:`--fields` or the :option:`--fieldFile` option to + declare the fields to export from the collection. +optional: true +--- +program: mongoexport +name: out +aliases: -o +directive: option +args: +description: | + Specifies a file to write the export to. If you do not specify a file + name, the :program:`mongoexport` writes data to standard output + (e.g. ``stdout``). +optional: true +--- +program: mongoexport +name: jsonArray +directive: option +args: null +description: | + Modifies the output of :program:`mongoexport` to write the + entire contents of the export as a single :term:`JSON` array. By + default :program:`mongoexport` writes data using one JSON document + for every MongoDB document. optional: true --- program: mongoexport @@ -263,6 +293,53 @@ description: | optional: true --- program: mongoexport +name: forceTableScan +directive: option +args: null +description: | + .. versionadded:: 2.2 + + Forces :program:`mongoexport` to scan the data store directly: + typically, :program:`mongoexport` saves entries as they appear in the + index of the ``_id`` field. Use :option:`--forceTableScan` to skip + the index and scan the data directly. Typically there are two cases + where this behavior is preferable to the default: + + 1. If you have key sizes over 800 bytes that would not be present + in the ``_id`` index. + + 2. Your database uses a custom ``_id`` field. + + When you run with :option:`--forceTableScan`, :program:`mongoexport` + does not use :operator:`$snapshot`. As a result, the export produced + by :program:`mongoexport` can reflect the state of the database at + many different points in time. + + .. warning:: Use :option:`--forceTableScan` with extreme caution + and consideration. +optional: true +--- +program: mongoexport +name: skip +directive: option +args: +description: | + Use :option:`--skip` to control where :program:`mongoexport` begins + exporting documents. See :method:`~cursor.skip()` for information about + the underlying operation. +optional: true +--- +program: mongoexport +name: limit +directive: option +args: +description: | + Specifies a maximum number of documents to include in the + export. See :method:`~cursor.limit()` for information about + the underlying operation. +optional: true +--- +program: mongoexport name: sort directive: option args: @@ -283,74 +360,4 @@ description: | See :method:`~cursor.sort()` for information about the underlying operation. optional: true ---- -program: mongoexport -name: ssl -inherit: - name: ssl - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslAllowInvalidCertificates -inherit: - name: sslAllowInvalidCertificates - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslCAFile -inherit: - name: sslCAFile - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslCRLFile -inherit: - name: sslCRLFile - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslFIPSMode -inherit: - name: sslFIPSMode - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslPEMKeyFile -inherit: - name: sslPEMKeyFile - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: sslPEMKeyPassword -inherit: - name: sslPEMKeyPassword - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: username -inherit: - name: username - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: verbose -inherit: - name: verbose - program: _shared - file: options-shared.yaml ---- -program: mongoexport -name: version -inherit: - name: version - program: _shared - file: options-shared.yaml ... diff --git a/source/includes/options-mongofiles.yaml b/source/includes/options-mongofiles.yaml index 7365e34c015..755fcc68785 100644 --- a/source/includes/options-mongofiles.yaml +++ b/source/includes/options-mongofiles.yaml @@ -3,54 +3,30 @@ # {{program}} to refer to the tool. # program: mongofiles -name: authenticationDatabase -inherit: - name: authenticationDatabase - program: _shared - file: options-shared.yaml ---- -program: mongofiles -name: authenticationMechanism -inherit: - name: authenticationMechanism - program: _shared - file: options-shared.yaml ---- -program: mongofiles -name: collection -aliases: -c -directive: option -args: -description: | - This option has no use in this context and a future release may - remove it. See :issue:`SERVER-4931` for more information. -optional: true ---- -program: mongofiles -name: db +name: help inherit: - name: db + name: help program: _shared file: options-shared.yaml --- program: mongofiles -name: dbpath +name: verbose inherit: - name: dbpath + name: verbose program: _shared file: options-shared.yaml --- program: mongofiles -name: directoryperdb +name: quiet inherit: - name: directoryperdb + name: quiet program: _shared file: options-shared.yaml --- program: mongofiles -name: help +name: version inherit: - name: help + name: version program: _shared file: options-shared.yaml --- @@ -68,67 +44,51 @@ description: | optional: true --- program: mongofiles -name: ipv6 +name: port inherit: - name: ipv6 + name: port program: _shared file: options-shared.yaml --- program: mongofiles -name: journal +name: ipv6 inherit: - name: journal + name: ipv6 program: _shared file: options-shared.yaml --- program: mongofiles -name: local -aliases: -l -directive: option -args: -description: | - Specifies the local filesystem name of a file for get and put - operations. - - In the :command:`mongofiles put` and :command:`mongofiles get` commands, - the required ```` modifier refers to the name the object will - have in GridFS. :program:`mongofiles` assumes that this reflects the - file's name on the local file system. This setting overrides this - default. -optional: true +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml --- program: mongofiles -name: password +name: sslCAFile inherit: - name: password + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongofiles -name: port +name: sslPEMKeyFile inherit: - name: port + name: sslPEMKeyFile program: _shared file: options-shared.yaml --- program: mongofiles -name: replace -aliases: -r -directive: option -args: null -description: | - Alters the behavior of :command:`mongofiles put` to replace existing - GridFS objects with the specified local file, rather than adding an - additional object with the same name. - - In the default operation, files will not be overwritten by a - :command:`mongofiles put` option. -optional: true +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml --- program: mongofiles -name: ssl +name: sslCRLFile inherit: - name: ssl + name: sslCRLFile program: _shared file: options-shared.yaml --- @@ -140,70 +100,117 @@ inherit: file: options-shared.yaml --- program: mongofiles -name: sslCAFile +name: sslFIPSMode inherit: - name: sslCAFile + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongofiles -name: sslCRLFile +name: username inherit: - name: sslCRLFile + name: username program: _shared file: options-shared.yaml --- program: mongofiles -name: sslFIPSMode +name: password inherit: - name: sslFIPSMode + name: password program: _shared file: options-shared.yaml --- program: mongofiles -name: sslPEMKeyFile +name: authenticationDatabase inherit: - name: sslPEMKeyFile + name: authenticationDatabase program: _shared file: options-shared.yaml --- program: mongofiles -name: sslPEMKeyPassword +name: authenticationMechanism inherit: - name: sslPEMKeyPassword + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongofiles -name: type -directive: option -args: -description: | - Provides the ability to specify a :term:`MIME` type to describe the file - inserted into GridFS storage. :program:`mongofiles` omits this option in - the default operation. - - Use only with :command:`mongofiles put` operations. -optional: true +name: dbpath +inherit: + name: dbpath + program: _shared + file: options-shared.yaml --- program: mongofiles -name: username +name: directoryperdb inherit: - name: username + name: directoryperdb program: _shared file: options-shared.yaml --- program: mongofiles -name: verbose +name: journal inherit: - name: verbose + name: journal program: _shared file: options-shared.yaml --- program: mongofiles -name: version +name: db inherit: - name: version + name: db program: _shared file: options-shared.yaml +--- +program: mongofiles +name: collection +aliases: -c +directive: option +args: +description: | + This option has no use in this context and a future release may + remove it. See :issue:`SERVER-4931` for more information. +optional: true +--- +program: mongofiles +name: local +aliases: -l +directive: option +args: +description: | + Specifies the local filesystem name of a file for get and put + operations. + + In the :command:`mongofiles put` and :command:`mongofiles get` commands, + the required ```` modifier refers to the name the object will + have in GridFS. :program:`mongofiles` assumes that this reflects the + file's name on the local file system. This setting overrides this + default. +optional: true +--- +program: mongofiles +name: type +directive: option +args: +description: | + Provides the ability to specify a :term:`MIME` type to describe the file + inserted into GridFS storage. :program:`mongofiles` omits this option in + the default operation. + + Use only with :command:`mongofiles put` operations. +optional: true +--- +program: mongofiles +name: replace +aliases: -r +directive: option +args: null +description: | + Alters the behavior of :command:`mongofiles put` to replace existing + GridFS objects with the specified local file, rather than adding an + additional object with the same name. + + In the default operation, files will not be overwritten by a + :command:`mongofiles put` option. +optional: true ... diff --git a/source/includes/options-shared.yaml b/source/includes/options-shared.yaml index 3bc3d680003..91a140b9491 100644 --- a/source/includes/options-shared.yaml +++ b/source/includes/options-shared.yaml @@ -3,82 +3,39 @@ # This file uses {{program}} to refer to the tool. # program: _shared -name: authenticationDatabase -directive: option -args: -description: | - .. versionadded:: 2.4 - - Specifies the database that holds the user's (e.g :option:`--username - <{{program}} --username>`) credentials. - - .. build system replaces this with - /includes/fact-authentication-source-mongo on the mongo shell - man page. - - .. include:: /includes/fact-authentication-source-tool.rst - - See :doc:`/core/access-control` for more information on authentication - in MongoDB. - -optional: true ---- -program: _shared -name: authenticationMechanism -directive: option -args: -description: | - .. versionadded:: 2.4 - - Specifies the authentication mechanism. By default, the authentication - mechanism is ``MONGODB-CR``, which is the MongoDB challenge/response - authentication mechanism. In |ent-build|, {{program}} also includes - support for ``GSSAPI`` to handle Kerberos authentication. - - See :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` - for more information about Kerberos authentication. -optional: true ---- -program: _shared -name: db -aliases: -d +name: help +aliases: -h directive: option -args: +args: null description: | - Specifies the name of the database on which to run {{program}}. + Returns the options and usage information. optional: true --- program: _shared -name: dbpath +name: verbose +aliases: -v directive: option -args: +args: null description: | - Specifies the directory of the MongoDB data files. If used, the - ``--dbpath`` option enables {{program}} to attach directly to local data - files without a running :program:`mongod`. When run with ``--dbpath``, - {{program}} locks access to the data directory. No :program:`mongod` can - access the same path while the process runs. + Increases the amount of internal reporting returned on standard output + or in log files. Increase the verbosity with the ``-v`` form by + including the option multiple times, (e.g. ``-vvvvv``.) optional: true --- program: _shared -name: directoryperdb +name: quiet directive: option args: null description: | - When used in conjunction with the corresponding option in - :program:`mongod`, allows {{program}} to access data from MongoDB - instances that use an on-disk format where every database has a distinct - directory. This option is only relevant when specifying the - ``--dbpath`` option. + .. tbd optional: true --- program: _shared -name: help -aliases: -h +name: version directive: option args: null description: | - Returns the options and usage information. + Returns the {{program}} release number. optional: true --- program: _shared @@ -103,44 +60,23 @@ description: | optional: false --- program: _shared -name: ipv6 +name: port directive: option -args: null +args: description: | - Enables IPv6 support. Allows {{program}} to connect to the MongoDB - instance using an IPv6 network. By default, MongoDB programs and - processes disable IPv6 support. + Specifies the port number when the MongoDB instance is not running on the + standard port of ``27017``. You may also specify the port number + using the ``--host`` option. optional: true --- program: _shared -name: journal +name: ipv6 directive: option args: null description: | - Allows {{program}} operations to use the durability :term:`journal` to - ensure data files remain valid and recoverable. This option is only - relevant when specifying the :option:`--dbpath` option. -optional: true ---- -program: _shared -name: password -aliases: -p -directive: option -args: -description: | - Specifies a password to authenticate to a MongoDB database that requires - authentication. Use in conjunction with the ``--username`` and - ``--authenticationDatabase`` options. -optional: true ---- -program: _shared -name: port -directive: option -args: -description: | - Specifies the port number when the MongoDB instance is not running on the - standard port of ``27017``. You may also specify the port number - using the ``--host`` option. + Enables IPv6 support. Allows {{program}} to connect to the MongoDB + instance using an IPv6 network. By default, MongoDB programs and + processes disable IPv6 support. optional: true --- program: _shared @@ -158,100 +94,100 @@ description: | optional: true --- program: _shared -name: sslAllowInvalidCertificates +name: sslCAFile directive: option -args: null +args: description: | .. versionadded:: 2.5.4 - Bypasses the validation checks for server certificates and allows - the use of invalid certificates. When using the - :setting:`sslAllowInvalidCertificates` setting, MongoDB logs as a - warning the use of the invalid certificate. + Specifies the :file:`.pem` file that contains the root certificate chain + from the Certificate Authority. Specify the file name of the + :file:`.pem` file using relative or absolute paths. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. optional: true --- program: _shared -name: sslCAFile +name: sslPEMKeyFile directive: option args: description: | .. versionadded:: 2.5.4 - Specifies the :file:`.pem` file that contains the root certificate chain - from the Certificate Authority. Specify the file name of the - :file:`.pem` file using relative or absolute paths. + Specifies the :file:`.pem` file that contains both the SSL certificate + and key. Specify the file name of the :file:`.pem` file using relative + or absolute paths. + + This option is required when using the :option:`--ssl` option to connect + to a :program:`mongod` or :program:`mongos` that has + :setting:`sslCAFile` enabled *without* + :setting:`sslWeakCertificateValidation`. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. optional: true --- program: _shared -name: sslCRLFile +name: sslPEMKeyPassword directive: option -args: +args: description: | .. versionadded:: 2.5.4 - Specifies the :file:`.pem` file that contains the Certificate Revocation - List. Specify the file name of the :file:`.pem` file using relative or - absolute paths. + Specifies the password to de-crypt the certificate-key file (i.e. + :option:`--sslPEMKeyFile`). Only use :option:`--sslPEMKeyPassword` if + the certificate-key file is encrypted. In all cases, {{program}} will + redact the password from all logging and reporting output. + + If the private key in the PEM file is encrypted and you do not specify + :option:`--sslPEMKeyPassword`, {{program}} will prompt for a passphrase. + See :ref:`ssl-certificate-password`. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. optional: true --- program: _shared -name: sslFIPSMode +name: sslCRLFile directive: option -args: null +args: description: | .. versionadded:: 2.5.4 - Uses the FIPS mode of the installed OpenSSL library. Your system must - have a FIPS compliant OpenSSL library to use :option:`--sslFIPSMode`. + Specifies the :file:`.pem` file that contains the Certificate Revocation + List. Specify the file name of the :file:`.pem` file using relative or + absolute paths. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. optional: true --- program: _shared -name: sslPEMKeyFile +name: sslAllowInvalidCertificates directive: option -args: +args: null description: | .. versionadded:: 2.5.4 - Specifies the :file:`.pem` file that contains both the SSL certificate - and key. Specify the file name of the :file:`.pem` file using relative - or absolute paths. - - This option is required when using the :option:`--ssl` option to connect - to a :program:`mongod` or :program:`mongos` that has - :setting:`sslCAFile` enabled *without* - :setting:`sslWeakCertificateValidation`. + Bypasses the validation checks for server certificates and allows + the use of invalid certificates. When using the + :setting:`sslAllowInvalidCertificates` setting, MongoDB logs as a + warning the use of the invalid certificate. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. optional: true --- program: _shared -name: sslPEMKeyPassword +name: sslFIPSMode directive: option -args: +args: null description: | .. versionadded:: 2.5.4 - Specifies the password to de-crypt the certificate-key file (i.e. - :option:`--sslPEMKeyFile`). Only use :option:`--sslPEMKeyPassword` if - the certificate-key file is encrypted. In all cases, {{program}} will - redact the password from all logging and reporting output. - - If the private key in the PEM file is encrypted and you do not specify - :option:`--sslPEMKeyPassword`, {{program}} will prompt for a passphrase. - See :ref:`ssl-certificate-password`. + Uses the FIPS mode of the installed OpenSSL library. Your system must + have a FIPS compliant OpenSSL library to use :option:`--sslFIPSMode`. The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see :doc:`/tutorial/configure-ssl`. @@ -270,21 +206,93 @@ description: | optional: true --- program: _shared -name: verbose -aliases: -v +name: password +aliases: -p +directive: option +args: +description: | + Specifies a password to authenticate to a MongoDB database that requires + authentication. Use in conjunction with the ``--username`` and + ``--authenticationDatabase`` options. +optional: true +--- +program: _shared +name: authenticationDatabase +directive: option +args: +description: | + .. versionadded:: 2.4 + + Specifies the database that holds the user's (e.g :option:`--username + <{{program}} --username>`) credentials. + + .. build system replaces this with + /includes/fact-authentication-source-mongo on the mongo shell + man page. + + .. include:: /includes/fact-authentication-source-tool.rst + + See :doc:`/core/access-control` for more information on authentication + in MongoDB. + +optional: true +--- +program: _shared +name: authenticationMechanism +directive: option +args: +description: | + .. versionadded:: 2.4 + + Specifies the authentication mechanism. By default, the authentication + mechanism is ``MONGODB-CR``, which is the MongoDB challenge/response + authentication mechanism. In |ent-build|, {{program}} also includes + support for ``GSSAPI`` to handle Kerberos authentication. + + See :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` + for more information about Kerberos authentication. +optional: true +--- +program: _shared +name: dbpath +directive: option +args: +description: | + Specifies the directory of the MongoDB data files. If used, the + ``--dbpath`` option enables {{program}} to attach directly to local data + files without a running :program:`mongod`. When run with ``--dbpath``, + {{program}} locks access to the data directory. No :program:`mongod` can + access the same path while the process runs. +optional: true +--- +program: _shared +name: directoryperdb directive: option args: null description: | - Increases the amount of internal reporting returned on standard output - or in log files. Increase the verbosity with the ``-v`` form by - including the option multiple times, (e.g. ``-vvvvv``.) + When used in conjunction with the corresponding option in + :program:`mongod`, allows {{program}} to access data from MongoDB + instances that use an on-disk format where every database has a distinct + directory. This option is only relevant when specifying the + ``--dbpath`` option. optional: true --- program: _shared -name: version +name: journal directive: option args: null description: | - Returns the {{program}} release number. + Allows {{program}} operations to use the durability :term:`journal` to + ensure data files remain valid and recoverable. This option is only + relevant when specifying the :option:`--dbpath` option. +optional: true +--- +program: _shared +name: db +aliases: -d +directive: option +args: +description: | + Specifies the name of the database on which to run {{program}}. optional: true ... diff --git a/source/reference/program/mongodump.txt b/source/reference/program/mongodump.txt index c8990688adc..6d39983632c 100644 --- a/source/reference/program/mongodump.txt +++ b/source/reference/program/mongodump.txt @@ -119,6 +119,7 @@ Options .. include:: /includes/option/option-mongodump-forceTableScan.rst +.. this doesn't exist: .. include:: /includes/option/option-mongodump-dumpDbUsersAndRoles.rst Use From 9846aba6fe09eba0601d6c212defac464e77f411 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 15:30:09 -0500 Subject: [PATCH 6/8] DOCS-2501 runtime options: reordering options PART II: mongoimport, mongooplog, mongorestore, mongosniff, mongostat, mongotop --- source/includes/options-mongoimport.yaml | 287 +++++++++--------- source/includes/options-mongooplog.yaml | 213 +++++++------ source/includes/options-mongorestore.yaml | 345 +++++++++++----------- source/includes/options-mongosniff.yaml | 34 +-- source/includes/options-mongostat.yaml | 177 ++++++----- source/includes/options-mongotop.yaml | 87 +++--- source/reference/program/mongoimport.txt | 4 +- source/reference/program/mongorestore.txt | 3 +- 8 files changed, 608 insertions(+), 542 deletions(-) diff --git a/source/includes/options-mongoimport.yaml b/source/includes/options-mongoimport.yaml index aa83ee7738d..3bc14e57ffa 100644 --- a/source/includes/options-mongoimport.yaml +++ b/source/includes/options-mongoimport.yaml @@ -2,230 +2,204 @@ # {{program}} to refer to the tool. # program: mongoimport -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongoimport -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongoimport -name: collection -aliases: -c -directive: option -args: -description: | - Specifies the collection to import. - - .. versionadded:: 2.5.3 - If you do not specify :option:`--collection`, - :program:`mongoimport` 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. -optional: true ---- -program: mongoimport -name: db +name: quiet inherit: - name: db + name: quiet program: _shared file: options-shared.yaml --- program: mongoimport -name: dbpath +name: version inherit: - name: dbpath + name: version program: _shared file: options-shared.yaml --- program: mongoimport -name: directoryperdb +name: host inherit: - name: directoryperdb + name: host program: _shared file: options-shared.yaml --- program: mongoimport -name: drop -directive: option -args: null -description: | - Modifies the import process so that the target instance drops - every collection before importing the collection from the input. -optional: true ---- -program: mongoimport -name: fieldFile -directive: option -args: -description: | - As an alternative to :option:`--fields`, the :option:`--fieldFile` - option allows you to specify a file that holds a list of field names if - your :term:`csv` or :term:`tsv` file does not include field names in the - first line of the file (i.e. header). Place one field per line. -optional: true ---- -program: mongoimport -name: fields -aliases: -f -directive: option -args: -description: | - Specify a comma separated list of field names when importing :term:`csv` - or :term:`tsv` files that do not have field names in the first (i.e. - header) line of the file. -optional: true ---- -program: mongoimport -name: file -directive: option -args: -description: | - Specifies the location and name of a file containing the data to import. - If you do not specify a file, :program:`mongoimport` reads data from - standard input (e.g. "stdin"). -optional: true +name: port +inherit: + name: port + program: _shared + file: options-shared.yaml --- program: mongoimport -name: help +name: ipv6 inherit: - name: help + name: ipv6 program: _shared file: options-shared.yaml --- program: mongoimport -name: headerline -directive: option -args: null -description: | - If using :option:`--type csv ` or :option:`--type - tsv `, uses the first line as field names. - Otherwise, :program:`mongoimport` will import the first line as a - distinct document. -optional: true +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml --- program: mongoimport -name: host +name: sslCAFile inherit: - name: host + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongoimport -name: ignoreBlanks -directive: option -args: null -description: | - Ignores empty fields in :term:`csv` and :term:`tsv` exports. If not - specified, :program:`mongoimport` creates fields without values in - imported documents. -optional: true +name: sslPEMKeyFile +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml --- program: mongoimport -name: ipv6 +name: sslPEMKeyPassword inherit: - name: ipv6 + name: sslPEMKeyPassword program: _shared file: options-shared.yaml --- program: mongoimport -name: journal +name: sslCRLFile inherit: - name: journal + name: sslCRLFile program: _shared file: options-shared.yaml --- program: mongoimport -name: jsonArray -directive: option -args: null -description: | - Accepts the import of data expressed with multiple MongoDB documents - within a single :term:`JSON` array. - - Used in conjunction with :option:`mongoexport --jsonArray` to - import data written as a single :term:`JSON` array. Limited to - imports of 16 MB or smaller. -optional: true +name: sslAllowInvalidCertificates +inherit: + name: sslAllowInvalidCertificates + program: _shared + file: options-shared.yaml --- program: mongoimport -name: password +name: sslFIPSMode inherit: - name: password + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongoimport -name: port +name: username inherit: - name: port + name: username program: _shared file: options-shared.yaml --- program: mongoimport -name: ssl +name: password inherit: - name: ssl + name: password program: _shared file: options-shared.yaml --- program: mongoimport -name: sslAllowInvalidCertificates +name: authenticationDatabase inherit: - name: sslAllowInvalidCertificates + name: authenticationDatabase program: _shared file: options-shared.yaml --- program: mongoimport -name: sslCAFile +name: authenticationMechanism inherit: - name: sslCAFile + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongoimport -name: sslCRLFile +name: dbpath inherit: - name: sslCRLFile + name: dbpath program: _shared file: options-shared.yaml --- program: mongoimport -name: sslFIPSMode +name: directoryperdb inherit: - name: sslFIPSMode + name: directoryperdb program: _shared file: options-shared.yaml --- program: mongoimport -name: sslPEMKeyFile +name: journal inherit: - name: sslPEMKeyFile + name: journal program: _shared file: options-shared.yaml --- program: mongoimport -name: sslPEMKeyPassword +name: db inherit: - name: sslPEMKeyPassword + name: db program: _shared file: options-shared.yaml --- program: mongoimport -name: stopOnError +name: collection +aliases: -c directive: option -args: null +args: description: | - .. versionadded:: 2.2 + Specifies the collection to import. - Forces :program:`mongoimport` to halt the import operation at the - first error rather than continuing the operation despite errors. + .. versionadded:: 2.5.3 + If you do not specify :option:`--collection`, + :program:`mongoimport` 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. +optional: true +--- +program: mongoimport +name: fields +aliases: -f +directive: option +args: +description: | + Specify a comma separated list of field names when importing :term:`csv` + or :term:`tsv` files that do not have field names in the first (i.e. + header) line of the file. +optional: true +--- +program: mongoimport +name: fieldFile +directive: option +args: +description: | + As an alternative to :option:`--fields`, the :option:`--fieldFile` + option allows you to specify a file that holds a list of field names if + your :term:`csv` or :term:`tsv` file does not include field names in the + first line of the file (i.e. header). Place one field per line. +optional: true +--- +program: mongoimport +name: ignoreBlanks +directive: option +args: null +description: | + Ignores empty fields in :term:`csv` and :term:`tsv` exports. If not + specified, :program:`mongoimport` creates fields without values in + imported documents. optional: true --- program: mongoimport @@ -238,6 +212,36 @@ description: | optional: true --- program: mongoimport +name: file +directive: option +args: +description: | + Specifies the location and name of a file containing the data to import. + If you do not specify a file, :program:`mongoimport` reads data from + standard input (e.g. "stdin"). +optional: true +--- +program: mongoimport +name: drop +directive: option +args: null +description: | + Modifies the import process so that the target instance drops + every collection before importing the collection from the input. +optional: true +--- +program: mongoimport +name: headerline +directive: option +args: null +description: | + If using :option:`--type csv ` or :option:`--type + tsv `, uses the first line as field names. + Otherwise, :program:`mongoimport` will import the first line as a + distinct document. +optional: true +--- +program: mongoimport name: upsert directive: option args: null @@ -267,23 +271,26 @@ description: | optional: true --- program: mongoimport -name: username -inherit: - name: username - program: _shared - file: options-shared.yaml ---- -program: mongoimport -name: verbose -inherit: - name: verbose - program: _shared - file: options-shared.yaml +name: stopOnError +directive: option +args: null +description: | + .. versionadded:: 2.2 + + Forces :program:`mongoimport` to halt the import operation at the + first error rather than continuing the operation despite errors. +optional: true --- program: mongoimport -name: version -inherit: - name: version - program: _shared - file: options-shared.yaml +name: jsonArray +directive: option +args: null +description: | + Accepts the import of data expressed with multiple MongoDB documents + within a single :term:`JSON` array. + + Used in conjunction with :option:`mongoexport --jsonArray` to + import data written as a single :term:`JSON` array. Limited to + imports of 16 MB or smaller. +optional: true ... diff --git a/source/includes/options-mongooplog.yaml b/source/includes/options-mongooplog.yaml index fb079a23599..232c0e81c3e 100644 --- a/source/includes/options-mongooplog.yaml +++ b/source/includes/options-mongooplog.yaml @@ -3,63 +3,30 @@ # {{program}} to refer to the tool. # program: mongooplog -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongooplog -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongooplog -name: dbpath -directive: option -args: -description: | - Specifies a directory, containing MongoDB data files, to which - :program:`mongooplog` will apply operations from the :term:`oplog` of - the database specified with the :option:`--from ` - option. - - When used, the :option:`--dbpath` option enables :program:`mongo` to - attach directly to local data files and write data without a running - :program:`mongod` instance. - - To run with :option:`--dbpath`, :program:`mongooplog` needs to restrict - access to the data directory: as a result, no :program:`mongod` can be - access the same path while the process runs. -optional: true ---- -program: mongooplog -name: directoryperdb +name: quiet inherit: - name: directoryperdb + name: quiet program: _shared file: options-shared.yaml --- program: mongooplog -name: from -directive: option -args: -description: | - Specify the host for :program:`mongooplog` to retrieve :term:`oplog` - operations from. :program:`mongooplog` *requires* this option. - - Unless you specify the :option:`--host ` option, - :program:`mongooplog` will apply the operations collected with this - option to the oplog of the :program:`mongod` instance running on the - localhost interface connected to port ``27017``. -optional: true ---- -program: mongooplog -name: help +name: version inherit: - name: help + name: version program: _shared file: options-shared.yaml --- @@ -89,6 +56,18 @@ description: | optional: false --- program: mongooplog +name: port +directive: option +args: null +description: | + Specifies the port number of the :program:`mongod` instance where + :program:`mongooplog` will apply :term:`oplog` entries. Specify + this option only if the MongoDB instance to connect to is not + running on the standard port of ``27017``. You may also specify a + port number using the :option:`--host ` command. +optional: true +--- +program: mongooplog name: ipv6 inherit: name: ipv6 @@ -96,59 +75,37 @@ inherit: file: options-shared.yaml --- program: mongooplog -name: journal +name: ssl inherit: - name: journal + name: ssl program: _shared file: options-shared.yaml --- program: mongooplog -name: oplogns -directive: option -args: -description: | - Specify a namespace in the :option:`--from ` host - where the oplog resides. The default value is ``local.oplog.rs``, which - is the where :term:`replica set` members store their operation log. - However, if you've copied :term:`oplog` entries into another database or - collection, use this option to copy oplog entries stored in another - location. Namespaces take the form of ``[database].[collection]``. -optional: true ---- -program: mongooplog -name: password +name: sslCAFile inherit: - name: password + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongooplog -name: port -directive: option -args: null -description: | - Specifies the port number of the :program:`mongod` instance where - :program:`mongooplog` will apply :term:`oplog` entries. Specify - this option only if the MongoDB instance to connect to is not - running on the standard port of ``27017``. You may also specify a - port number using the :option:`--host ` command. -optional: true +name: sslPEMKeyFile +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml --- program: mongooplog -name: seconds -aliases: -s -directive: option -args: -description: | - Specify a number of seconds of operations for :program:`mongooplog` to - pull from the :option:`remote host `. Unless - specified the default value is ``86400`` seconds, or 24 hours. -optional: true +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml --- program: mongooplog -name: ssl +name: sslCRLFile inherit: - name: ssl + name: sslCRLFile program: _shared file: options-shared.yaml --- @@ -160,58 +117,124 @@ inherit: file: options-shared.yaml --- program: mongooplog -name: sslCAFile +name: sslFIPSMode inherit: - name: sslCAFile + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongooplog -name: sslCRLFile +name: username inherit: - name: sslCRLFile + name: username program: _shared file: options-shared.yaml --- program: mongooplog -name: sslFIPSMode +name: password inherit: - name: sslFIPSMode + name: password program: _shared file: options-shared.yaml --- program: mongooplog -name: sslPEMKeyFile +name: authenticationDatabase inherit: - name: sslPEMKeyFile + name: authenticationDatabase program: _shared file: options-shared.yaml --- program: mongooplog -name: sslPEMKeyPassword +name: authenticationMechanism inherit: - name: sslPEMKeyPassword + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongooplog -name: username +name: dbpath +directive: option +args: +description: | + Specifies a directory, containing MongoDB data files, to which + :program:`mongooplog` will apply operations from the :term:`oplog` of + the database specified with the :option:`--from ` + option. + + When used, the :option:`--dbpath` option enables :program:`mongo` to + attach directly to local data files and write data without a running + :program:`mongod` instance. + + To run with :option:`--dbpath`, :program:`mongooplog` needs to restrict + access to the data directory: as a result, no :program:`mongod` can be + access the same path while the process runs. +optional: true +--- +program: mongooplog +name: directoryperdb inherit: - name: username + name: directoryperdb program: _shared file: options-shared.yaml --- program: mongooplog -name: verbose +name: journal inherit: - name: verbose + name: journal program: _shared file: options-shared.yaml --- program: mongooplog -name: version +name: db inherit: - name: version + name: db program: _shared file: options-shared.yaml +--- +program: mongooplog +name: collection +aliases: -c +directive: option +args: +description: | + Specifies the collection to export. +optional: true +--- +program: mongooplog +name: seconds +aliases: -s +directive: option +args: +description: | + Specify a number of seconds of operations for :program:`mongooplog` to + pull from the :option:`remote host `. Unless + specified the default value is ``86400`` seconds, or 24 hours. +optional: true +--- +program: mongooplog +name: from +directive: option +args: +description: | + Specify the host for :program:`mongooplog` to retrieve :term:`oplog` + operations from. :program:`mongooplog` *requires* this option. + + Unless you specify the :option:`--host ` option, + :program:`mongooplog` will apply the operations collected with this + option to the oplog of the :program:`mongod` instance running on the + localhost interface connected to port ``27017``. +optional: true +--- +program: mongooplog +name: oplogns +directive: option +args: +description: | + Specify a namespace in the :option:`--from ` host + where the oplog resides. The default value is ``local.oplog.rs``, which + is the where :term:`replica set` members store their operation log. + However, if you've copied :term:`oplog` entries into another database or + collection, use this option to copy oplog entries stored in another + location. Namespaces take the form of ``[database].[collection]``. +optional: true ... diff --git a/source/includes/options-mongorestore.yaml b/source/includes/options-mongorestore.yaml index c472d791a9d..fb1a4d1484f 100644 --- a/source/includes/options-mongorestore.yaml +++ b/source/includes/options-mongorestore.yaml @@ -3,104 +3,142 @@ # {{program}} to refer to the tool. # program: mongorestore -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongorestore -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongorestore -name: collection -aliases: -c -directive: option -args: -description: | - Specifies a single collection for :program:`mongorestore` to restore. If - you do not specify :option:`--collection`, :program:`mongorestore` takes - the collection name from the input filename. If the input file has an - extension, MongoDB omits the extension of the file from the collection - name. -optional: true +name: quiet +inherit: + name: quiet + program: _shared + file: options-shared.yaml --- program: mongorestore -name: db -aliases: -d -directive: option -args: -description: | - Specifies a database for :program:`mongorestore` to restore data *into*. - If the database does not exist, :program:`mongorestore` creates the - database. If you do not specify a ````, :program:`mongorestore` - creates new databases that correspond to the databases where data - originated and data may be overwritten. Use this option to restore data - into a MongoDB instance that already has data. - - :option:`--db` does *not* control which :term:`BSON` files - :program:`mongorestore` restores. You must use the - :program:`mongorestore` :ref:`path option ` to - limit that restored data. -optional: true +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml --- program: mongorestore -name: dbpath +name: host inherit: - name: dbpath + name: host program: _shared file: options-shared.yaml --- program: mongorestore -name: directoryperdb +name: port inherit: - name: directoryperdb + name: port program: _shared file: options-shared.yaml --- program: mongorestore -name: drop -directive: option -args: null -description: | - Modifies the restoration procedure to drop every collection from the - target database before restoring the collection from the dumped backup. -optional: true +name: ipv6 +inherit: + name: ipv6 + program: _shared + file: options-shared.yaml --- program: mongorestore -name: filter -directive: option -args: '' -description: | - Limits the documents that :program:`mongorestore` imports to only those - documents that match the JSON document specified as ``''``. Be - sure to include the document in single quotes to avoid interaction with - your system's shell environment. For an example of :option:`--filter`, - see :ref:`backup-restore-filter`. -optional: true +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml --- program: mongorestore -name: help +name: sslCAFile inherit: - name: help + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongorestore -name: host +name: sslPEMKeyFile inherit: - name: host + name: sslPEMKeyFile program: _shared file: options-shared.yaml --- program: mongorestore -name: ipv6 +name: sslPEMKeyPassword inherit: - name: ipv6 + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: sslCRLFile +inherit: + name: sslCRLFile + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: sslAllowInvalidCertificates +inherit: + name: sslAllowInvalidCertificates + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: sslFIPSMode +inherit: + name: sslFIPSMode + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: username +inherit: + name: username + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: password +inherit: + name: password + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: authenticationDatabase +inherit: + name: authenticationDatabase + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: authenticationMechanism +inherit: + name: authenticationMechanism + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: dbpath +inherit: + name: dbpath + program: _shared + file: options-shared.yaml +--- +program: mongorestore +name: directoryperdb +inherit: + name: directoryperdb program: _shared file: options-shared.yaml --- @@ -112,23 +150,52 @@ inherit: file: options-shared.yaml --- program: mongorestore -name: keepIndexVersion +name: db +aliases: -d directive: option -args: null +args: description: | - Prevents :program:`mongorestore` from upgrading the index to the latest - version during the restoration process. + Specifies a database for :program:`mongorestore` to restore data *into*. + If the database does not exist, :program:`mongorestore` creates the + database. If you do not specify a ````, :program:`mongorestore` + creates new databases that correspond to the databases where data + originated and data may be overwritten. Use this option to restore data + into a MongoDB instance that already has data. + + :option:`--db` does *not* control which :term:`BSON` files + :program:`mongorestore` restores. You must use the + :program:`mongorestore` :ref:`path option ` to + limit that restored data. optional: true --- program: mongorestore -name: noIndexRestore +name: collection +aliases: -c +directive: option +args: +description: | + Specifies a single collection for :program:`mongorestore` to restore. If + you do not specify :option:`--collection`, :program:`mongorestore` takes + the collection name from the input filename. If the input file has an + extension, MongoDB omits the extension of the file from the collection + name. +optional: true +--- +program: mongorestore +name: objcheck directive: option args: null description: | - .. versionadded:: 2.2 + Forces :program:`mongorestore` to validate all requests from clients + upon receipt to ensure that clients never insert invalid documents into + the database. For objects with a high degree of sub-document nesting, + :option:`--objcheck` can have a small impact on performance. You can set + :option:`--noobjcheck` to disable object checking at run-time. - Prevents :program:`mongorestore` from restoring and building indexes as - specified in the corresponding :program:`mongodump` output. + .. versionchanged:: 2.4 + MongoDB enables :option:`--objcheck` by default, to prevent any + client from inserting malformed or invalid BSON into a MongoDB + database. optional: true --- program: mongorestore @@ -139,32 +206,35 @@ inherit: file: options-mongod.yaml --- program: mongorestore -name: noOptionsRestore +name: filter +directive: option +args: '' +description: | + Limits the documents that :program:`mongorestore` imports to only those + documents that match the JSON document specified as ``''``. Be + sure to include the document in single quotes to avoid interaction with + your system's shell environment. For an example of :option:`--filter`, + see :ref:`backup-restore-filter`. +optional: true +--- +program: mongorestore +name: drop directive: option args: null description: | - .. versionadded:: 2.2 - - Prevents :program:`mongorestore` from setting the collection options, - such as those specified by the :dbcommand:`collMod` :term:`database - command`, on restored collections. + Modifies the restoration procedure to drop every collection from the + target database before restoring the collection from the dumped backup. optional: true --- program: mongorestore -name: objcheck +name: oplogReplay directive: option args: null description: | - Forces :program:`mongorestore` to validate all requests from clients - upon receipt to ensure that clients never insert invalid documents into - the database. For objects with a high degree of sub-document nesting, - :option:`--objcheck` can have a small impact on performance. You can set - :option:`--noobjcheck` to disable object checking at run-time. - - .. versionchanged:: 2.4 - MongoDB enables :option:`--objcheck` by default, to prevent any - client from inserting malformed or invalid BSON into a MongoDB - database. + Replays the :term:`oplog` after restoring the dump to ensure that the + current state of the database reflects the point-in-time backup captured + with the ":option:`mongodump --oplog`" command. For an example of + :option:`--oplogReplay`, see :ref:`backup-restore-oplogreplay`. optional: true --- program: mongorestore @@ -185,99 +255,36 @@ description: | optional: true --- program: mongorestore -name: oplogReplay +name: keepIndexVersion directive: option args: null description: | - Replays the :term:`oplog` after restoring the dump to ensure that the - current state of the database reflects the point-in-time backup captured - with the ":option:`mongodump --oplog`" command. For an example of - :option:`--oplogReplay`, see :ref:`backup-restore-oplogreplay`. + Prevents :program:`mongorestore` from upgrading the index to the latest + version during the restoration process. optional: true --- program: mongorestore -name: password -inherit: - name: password - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: port -inherit: - name: port - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: ssl -inherit: - name: ssl - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslAllowInvalidCertificates -inherit: - name: sslAllowInvalidCertificates - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslCAFile -inherit: - name: sslCAFile - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslCRLFile -inherit: - name: sslCRLFile - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslFIPSMode -inherit: - name: sslFIPSMode - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslPEMKeyFile -inherit: - name: sslPEMKeyFile - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: sslPEMKeyPassword -inherit: - name: sslPEMKeyPassword - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: username -inherit: - name: username - program: _shared - file: options-shared.yaml ---- -program: mongorestore -name: verbose -inherit: - name: verbose - program: _shared - file: options-shared.yaml +name: noIndexRestore +directive: option +args: null +description: | + .. versionadded:: 2.2 + + Prevents :program:`mongorestore` from restoring and building indexes as + specified in the corresponding :program:`mongodump` output. +optional: true --- program: mongorestore -name: version -inherit: - name: version - program: _shared - file: options-shared.yaml +name: noOptionsRestore +directive: option +args: null +description: | + .. versionadded:: 2.2 + + Prevents :program:`mongorestore` from setting the collection options, + such as those specified by the :dbcommand:`collMod` :term:`database + command`, on restored collections. +optional: true --- program: mongorestore name: w diff --git a/source/includes/options-mongosniff.yaml b/source/includes/options-mongosniff.yaml index d30c5c4de10..cf5c10025e5 100644 --- a/source/includes/options-mongosniff.yaml +++ b/source/includes/options-mongosniff.yaml @@ -3,6 +3,13 @@ # {{program}} to refer to the tool. # program: mongosniff +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongosniff name: forward directive: option args: <:port> @@ -22,23 +29,6 @@ description: | optional: true --- program: mongosniff -name: help -inherit: - name: help - program: _shared - file: options-shared.yaml ---- -program: mongosniff -name: objcheck -directive: option -args: null -description: | - Displays invalid BSON objects only and nothing else. Use this option for - troubleshooting driver development. This option has some performance - impact on the performance of {{program}}. -optional: true ---- -program: mongosniff name: source directive: option args: , , @@ -54,6 +44,16 @@ description: | optional: true --- program: mongosniff +name: objcheck +directive: option +args: null +description: | + Displays invalid BSON objects only and nothing else. Use this option for + troubleshooting driver development. This option has some performance + impact on the performance of {{program}}. +optional: true +--- +program: mongosniff name: directive: option description: | diff --git a/source/includes/options-mongostat.yaml b/source/includes/options-mongostat.yaml index 8f0d4f21f2c..5b66ceb762a 100644 --- a/source/includes/options-mongostat.yaml +++ b/source/includes/options-mongostat.yaml @@ -2,54 +2,23 @@ # {{program}} to refer to the tool. # program: mongostat -name: all -directive: option -args: null -description: | - Configures :program:`mongostat` to return all optional :ref:`fields - `. -optional: true ---- -program: mongostat -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongostat -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongostat -name: discover -directive: option -args: null -description: | - Discovers and reports on statistics from all members of a :term:`replica - set` or :term:`sharded cluster`. When connected to any member of a - replica set, :option:`--discover` all non-:term:`hidden members ` of the replica set. When connected to a :program:`mongos`, - :program:`mongostat` will return data from all :term:`shards ` in - the cluster. If a replica set provides a shard in the sharded cluster, - :program:`mongostat` will report on non-hidden members of that replica - set. - - The :option:`mongostat --host` option is not required but - potentially useful in this case. - - .. versionchanged:: 2.5.3 - When running with :option:`--discover`, :program:`mongostat` now - respects :option:--rowcount`. -optional: true ---- -program: mongostat -name: help +name: version inherit: - name: help + name: version program: _shared file: options-shared.yaml --- @@ -61,13 +30,11 @@ inherit: file: options-shared.yaml --- program: mongostat -name: http -directive: option -args: null -description: | - Configures :program:`mongostat` to collect data using the HTTP interface - rather than a raw database connection. -optional: true +name: port +inherit: + name: port + program: _shared + file: options-shared.yaml --- program: mongostat name: ipv6 @@ -77,45 +44,37 @@ inherit: file: options-shared.yaml --- program: mongostat -name: noheaders -directive: option -args: null -description: | - Disables the output of column or field names. -optional: true +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml --- program: mongostat -name: password +name: sslCAFile inherit: - name: password + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongostat -name: port +name: sslPEMKeyFile inherit: - name: port + name: sslPEMKeyFile program: _shared file: options-shared.yaml --- program: mongostat -name: rowcount -aliases:-n -directive: option -args: -description: | - Controls the number of rows to output. Use in conjunction with - the ``sleeptime`` argument to control the duration of a - :program:`mongostat` operation. - - Unless :option:`--rowcount` is specified, :program:`mongostat` - will return an infinite number of rows (e.g. value of ``0``.) -optional: true +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml --- program: mongostat -name: ssl +name: sslCRLFile inherit: - name: ssl + name: sslCRLFile program: _shared file: options-shared.yaml --- @@ -127,41 +86,103 @@ inherit: file: options-shared.yaml --- program: mongostat -name: sslCAFile +name: sslFIPSMode inherit: - name: sslCAFile + name: sslFIPSMode program: _shared file: options-shared.yaml --- program: mongostat -name: sslCRLFile +name: username inherit: - name: sslCRLFile + name: username program: _shared file: options-shared.yaml --- program: mongostat -name: sslFIPSMode +name: password inherit: - name: sslFIPSMode + name: password program: _shared file: options-shared.yaml --- program: mongostat -name: sslPEMKeyFile +name: authenticationDatabase inherit: - name: sslPEMKeyFile + name: authenticationDatabase program: _shared file: options-shared.yaml --- program: mongostat -name: sslPEMKeyPassword +name: authenticationMechanism inherit: - name: sslPEMKeyPassword + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongostat +name: noheaders +directive: option +args: null +description: | + Disables the output of column or field names. +optional: true +--- +program: mongostat +name: rowcount +aliases:-n +directive: option +args: +description: | + Controls the number of rows to output. Use in conjunction with + the ``sleeptime`` argument to control the duration of a + :program:`mongostat` operation. + + Unless :option:`--rowcount` is specified, :program:`mongostat` + will return an infinite number of rows (e.g. value of ``0``.) +optional: true +--- +program: mongostat +name: http +directive: option +args: null +description: | + Configures :program:`mongostat` to collect data using the HTTP interface + rather than a raw database connection. +optional: true +--- +program: mongostat +name: discover +directive: option +args: null +description: | + Discovers and reports on statistics from all members of a :term:`replica + set` or :term:`sharded cluster`. When connected to any member of a + replica set, :option:`--discover` all non-:term:`hidden members ` of the replica set. When connected to a :program:`mongos`, + :program:`mongostat` will return data from all :term:`shards ` in + the cluster. If a replica set provides a shard in the sharded cluster, + :program:`mongostat` will report on non-hidden members of that replica + set. + + The :option:`mongostat --host` option is not required but + potentially useful in this case. + + .. versionchanged:: 2.5.3 + When running with :option:`--discover`, :program:`mongostat` now + respects :option:--rowcount`. +optional: true +--- +program: mongostat +name: all +directive: option +args: null +description: | + Configures :program:`mongostat` to return all optional :ref:`fields + `. +optional: true +--- +program: mongostat name: directive: option args: null diff --git a/source/includes/options-mongotop.yaml b/source/includes/options-mongotop.yaml index 98810284074..b399ce0f25b 100644 --- a/source/includes/options-mongotop.yaml +++ b/source/includes/options-mongotop.yaml @@ -3,61 +3,51 @@ # {{program}} to refer to the tool. # program: mongotop -name: authenticationDatabase +name: help inherit: - name: authenticationDatabase + name: help program: _shared file: options-shared.yaml --- program: mongotop -name: authenticationMechanism +name: verbose inherit: - name: authenticationMechanism + name: verbose program: _shared file: options-shared.yaml --- program: mongotop -name: help +name: quiet inherit: - name: help + name: quiet program: _shared file: options-shared.yaml --- program: mongotop -name: host +name: version inherit: - name: host + name: version program: _shared file: options-shared.yaml --- program: mongotop -name: ipv6 +name: host inherit: - name: ipv6 + name: host program: _shared file: options-shared.yaml --- program: mongotop -name: locks -directive: option -args: null -description: | - Toggles the mode of :program:`mongotop` to report on use of per-database - :ref:`locks `. These data are useful for measuring concurrent - operations and lock percentage. -optional: true ---- -program: mongotop -name: password +name: port inherit: - name: password + name: port program: _shared file: options-shared.yaml --- program: mongotop -name: port +name: ipv6 inherit: - name: port + name: ipv6 program: _shared file: options-shared.yaml --- @@ -69,44 +59,44 @@ inherit: file: options-shared.yaml --- program: mongotop -name: sslAllowInvalidCertificates +name: sslCAFile inherit: - name: sslAllowInvalidCertificates + name: sslCAFile program: _shared file: options-shared.yaml --- program: mongotop -name: sslCAFile +name: sslPEMKeyFile inherit: - name: sslCAFile + name: sslPEMKeyFile program: _shared file: options-shared.yaml --- program: mongotop -name: sslCRLFile +name: sslPEMKeyPassword inherit: - name: sslCRLFile + name: sslPEMKeyPassword program: _shared file: options-shared.yaml --- program: mongotop -name: sslFIPSMode +name: sslCRLFile inherit: - name: sslFIPSMode + name: sslCRLFile program: _shared file: options-shared.yaml --- program: mongotop -name: sslPEMKeyFile +name: sslAllowInvalidCertificates inherit: - name: sslPEMKeyFile + name: sslAllowInvalidCertificates program: _shared file: options-shared.yaml --- program: mongotop -name: sslPEMKeyPassword +name: sslFIPSMode inherit: - name: sslPEMKeyPassword + name: sslFIPSMode program: _shared file: options-shared.yaml --- @@ -118,20 +108,37 @@ inherit: file: options-shared.yaml --- program: mongotop -name: verbose +name: password inherit: - name: verbose + name: password program: _shared file: options-shared.yaml --- program: mongotop -name: version +name: authenticationDatabase inherit: - name: version + name: authenticationDatabase + program: _shared + file: options-shared.yaml +--- +program: mongotop +name: authenticationMechanism +inherit: + name: authenticationMechanism program: _shared file: options-shared.yaml --- program: mongotop +name: locks +directive: option +args: null +description: | + Toggles the mode of :program:`mongotop` to report on use of per-database + :ref:`locks `. These data are useful for measuring concurrent + operations and lock percentage. +optional: true +--- +program: mongotop directive: option name: description: | diff --git a/source/reference/program/mongoimport.txt b/source/reference/program/mongoimport.txt index 87e6670d56b..e745eb33332 100644 --- a/source/reference/program/mongoimport.txt +++ b/source/reference/program/mongoimport.txt @@ -43,10 +43,10 @@ Options .. include:: /includes/option/option-mongoimport-host.rst -.. include:: /includes/option/option-mongoimport-ipv6.rst - .. include:: /includes/option/option-mongoimport-port.rst +.. include:: /includes/option/option-mongoimport-ipv6.rst + .. include:: /includes/option/option-mongoimport-ssl.rst .. include:: /includes/option/option-mongoimport-sslCAFile.rst diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt index 0c92f39de2d..a2a941fc7e5 100644 --- a/source/reference/program/mongorestore.txt +++ b/source/reference/program/mongorestore.txt @@ -121,7 +121,8 @@ Options .. include:: /includes/option/option-mongorestore-noOptionsRestore.rst -.. include:: /includes/option/option-mongorestore-restoreDbUserasAndRoles.rst +.. this does not exist: +.. .. include:: /includes/option/option-mongorestore-restoreDbUserasAndRoles.rst .. include:: /includes/option/option-mongorestore-w.rst From 02b1ec57e81f96a21d2acf6f0620aa73a4b3260e Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Feb 2014 16:16:40 -0500 Subject: [PATCH 7/8] DOCS-2501 runtime options: mongod --- source/includes/options-mongod.yaml | 309 ++++++++++++++++++++++++- source/includes/options-mongodump.yaml | 2 +- source/includes/options-mongos.yaml | 39 ++++ source/includes/options-shared.yaml | 11 +- source/reference/program/mongod.txt | 220 ++++++------------ 5 files changed, 424 insertions(+), 157 deletions(-) create mode 100644 source/includes/options-mongos.yaml diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 6534d503efb..431277b5ea9 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -3,6 +3,105 @@ # {{program}} to refer to the tool. # program: mongod +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongod +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml +--- +program: mongod +name: config +aliases: -f +directive: option +args: +description: | + Specifies a configuration file, that you can use to specify + runtime-configurations. While the options are equivalent and + accessible via the other command line arguments, the configuration + file is the preferred method for runtime configuration of + mongod. See the :doc:`/reference/configuration-options` document + for more information about these options. + + Ensure the configuration file uses ASCII + encoding. {{program}} does not support configuration files + with non-ASCII encoding, including UTF-8. +optional: true +--- +program: mongod +name: verbose +inherit: + name: verbose + program: _shared + file: options-shared.yaml +--- +program: mongod +name: quiet +inherit: + name: quiet + program: _shared + file: options-shared.yaml +--- +program: mongod +name: port +description: | + By default :program:`mongod` listens for connections on port `27017`. +inherit: + name: port + program: _shared + file: options-shared.yaml +--- +program: mongod +name: bind_ip +directive: option +args: +description: | + The IP address that the {{program}} process binds to and listens for + connections on. By default {{program}} listens for connections for all + interfaces. You may attach {{program}} to any interface. When attaching + {{program}} to a publicly accessible interface, ensure that you have + implemented proper authentication and firewall restrictions to protect + the integrity of your database. +optional: true +--- +program: mongod +name: maxConns +directive: option +args: +description: | + Specifies the maximum number of simultaneous connections that + {{program}} will accept. This setting has no effect if it is + higher than your operating system's configured maximum connection + tracking threshold. + + .. versionchanged:: 2.5.0 + MongoDB removed the upward limit on the :setting:`maxConns` setting. +optional: true +--- +program: mongod +name: objcheck +directive: option +args: null +description: | + Forces the {{program}} to validate all requests from clients upon + receipt to ensure that clients never insert invalid documents into the + database. For objects with a high degree of sub-document nesting, + :option:`--objcheck` can have a small impact on performance. You can set + :option:`--noobjcheck` to disable object checking at run-time. + + .. versionchanged:: 2.4 + MongoDB enables :option:`--objcheck` by default, to prevent any + client from inserting malformed or invalid BSON into a MongoDB + database. +optional: true +--- +program: mongod name: noobjcheck directive: option args: null @@ -12,9 +111,207 @@ description: | Disables the default document validation that MongoDB performs on all incoming BSON documents. optional: true -# -# -# This yaml file is in-progress -# -# -... \ No newline at end of file +--- +program: mongod +name: logpath +directive: option +args: +description: | + Specify a path for the log file that will hold all diagnostic + logging information. + + Unless specified, {{program}} will output all log information + to the standard output. Additionally, unless you also specify + :option:`--logappend`, the logfile will be overwritten when the + process restarts. + + .. note:: + + The behavior of the logging system may change in the near + future in response to the :issue:`SERVER-4499` case. +optional: true +--- +program: mongod +name: logappend +directive: option +args: null +description: | + When specified, this option ensures that {{program}} appends + new entries to the end of the logfile rather than overwriting the + content of the log when the process restarts. +optional: true +--- +program: mongod +name: syslog +directive: option +args: null +description: | + Sends all logging output to the host's :term:`syslog` system rather + than to standard output or a log file as with :option:`--logpath`. + + .. important:: You cannot use :option:`--syslog` with :option:`--logpath`. +optional: true +--- +program: mongod +name: pidfilepath +directive: option +args: +description: | + Specify a file location to hold the ":term:`PID`" or process ID of the + {{program}} process. Useful for tracking the {{program}} process in + combination with the :option:`mongod --fork` option. + + Without a specified :option:`--pidfilepath` option, :program:`mongos` + creates no PID file. +optional: true +--- +program: mongod +name: ssl +inherit: + name: ssl + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslCAFile +inherit: + name: sslCAFile + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslPEMKeyFile +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslPEMKeyPassword +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslCRLFile +inherit: + name: sslCRLFile + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslAllowInvalidCertificates +inherit: + name: sslAllowInvalidCertificates + program: _shared + file: options-shared.yaml +--- +program: mongod +name: sslFIPSMode +inherit: + name: sslFIPSMode + program: _shared + file: options-shared.yaml +--- +program: mongod +name: auditDestination +directive: option +args: null +description: | + Enables auditing. The :option:`--auditDestination` option can have one of + the following values: + + .. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Value + + - Description + + * - ``syslog`` + + - Output the audit events to syslog in JSON format. Not available on + Windows. Audit messages have a syslog severity level of ``info`` + and a facility level of ``user``. + + .. include:: /includes/fact-audit-syslog-message-limit.rst + + * - ``console`` + + - Output the audit events to ``stdout`` in JSON format. + + * - ``file`` + + - Output the audit events to the file specified in + :option:`--auditPath` in the format specified in + :option:`-auditFormat`. + + .. include:: /includes/note-audit-in-enterprise-only.rst +optional: true +--- +program: mongod +name: auditFormat +directive: option +args: null +description: | + Specify the format of the output file if + :option:`--auditDestination` is ``file``. The + :option:`--auditFormat` can have one of the following values: + + .. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Value + + - Description + + * - ``JSON`` + + - Output the audit events in JSON format to the file specified in + :option:`--auditPath`. + + * - ``BSON`` + + - Output the audit events in BSON binary format to the file + specified in :option:`--auditPath`. + .. include:: /includes/note-audit-in-enterprise-only.rst +optional: true +--- +program: mongod +name: auditPath +directive: option +args: null +description: | + Specify the output file for auditing if :option:`--auditDestination` + has value of ``file``. The :option:`--auditPath` option can take + either a full path name or a relative path name. + + .. include:: /includes/note-audit-in-enterprise-only.rst +optional: true +--- +program: mongod +name: auditFilter +aliases: +directive: option +args: null +description: | + Specify the filter to limit the :ref:`types of operations + ` the audit system records. The option + takes a document of the form: + + .. code-block:: javascript + + { atype: } + + For authentication operations, the option can also take a document of + the form: + + .. code-block:: javascript + + { atype: , "param.db": } + .. include:: /includes/note-audit-in-enterprise-only.rst +optional: true +... diff --git a/source/includes/options-mongodump.yaml b/source/includes/options-mongodump.yaml index 86389311bba..285b25e4538 100644 --- a/source/includes/options-mongodump.yaml +++ b/source/includes/options-mongodump.yaml @@ -1,5 +1,5 @@ # This file borrows content from /includes/options-shared.yaml, which uses -# {{role}} to refer to the tool. +# {{program}} to refer to the tool. # program: mongodump name: help diff --git a/source/includes/options-mongos.yaml b/source/includes/options-mongos.yaml new file mode 100644 index 00000000000..dd983e7f901 --- /dev/null +++ b/source/includes/options-mongos.yaml @@ -0,0 +1,39 @@ +# This file borrows content from other files, including +# /includes/options-shared.yaml, which uses +# {{program}} to refer to the tool. +# +program: mongos +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongos +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml +--- +program: mongos +name: config +inherit: + name: config + program: mongod + file: options-mongod.yaml + + + + + + + + + + + + + + +... diff --git a/source/includes/options-shared.yaml b/source/includes/options-shared.yaml index 91a140b9491..cf6e5a387c9 100644 --- a/source/includes/options-shared.yaml +++ b/source/includes/options-shared.yaml @@ -27,7 +27,16 @@ name: quiet directive: option args: null description: | - .. tbd + Runs {{program}} in a quiet mode that attempts to limit the amount of + output. This option suppresses: + + - output from :term:`database commands ` + + - replication activity + + - connection accepted events + + - connection closed events optional: true --- program: _shared diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index d0804cbec80..12e91932ff8 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -34,130 +34,35 @@ Core Options .. program:: mongod -.. option:: --help, -h +.. include:: /includes/option/option-mongod-help.rst - Returns a basic help and usage text. +.. include:: /includes/option/option-mongod-version.rst -.. option:: --version +.. include:: /includes/option/option-mongod-config.rst - Returns the version of the :program:`mongod` daemon. +.. include:: /includes/option/option-mongod-verbose.rst -.. option:: --config , -f +.. include:: /includes/option/option-mongod-quiet.rst - Specifies a configuration file, that you can use to specify - runtime-configurations. While the options are equivalent and - accessible via the other command line arguments, the configuration - file is the preferred method for runtime configuration of - mongod. See the :doc:`/reference/configuration-options` document - for more information about these options. +.. include:: /includes/option/option-mongod-port.rst - .. include:: /includes/note-configuration-file-must-be-ascii.rst +.. include:: /includes/option/option-mongod-bind_ip.rst -.. option:: --verbose, -v +.. include:: /includes/option/option-mongod-maxConns.rst - Increases the amount of internal reporting returned on standard - output or in the log file specified by :option:`--logpath`. Use the - ``-v`` form to control the level of verbosity by including the - option multiple times, (e.g. ``-vvvvv``.) - -.. option:: --quiet - - Runs the :program:`mongod` instance in a quiet mode that attempts to limit - the amount of output. This option suppresses: - - - output from :term:`database commands `, - including :dbcommand:`drop`, :dbcommand:`dropIndexes`, - :dbcommand:`validate`, and :dbcommand:`clean`. - - - replication activity. - - - connection accepted events. - - - connection closed events. - -.. option:: --port - - Specifies a TCP port for the :program:`mongod` to listen for client - connections. By default :program:`mongod` listens for connections on - port 27017. - - UNIX-like systems require root privileges to use ports with numbers - lower than 1024. - -.. option:: --bind_ip - - The IP address that the :program:`mongod` process will bind to and - listen for connections. By default :program:`mongod` listens for - connections all interfaces. You may attach :program:`mongod` to any - interface; however, when attaching :program:`mongod` to a publicly - accessible interface ensure that you have implemented proper - authentication and/or firewall restrictions to protect the - integrity of your database. - -.. option:: --maxConns - - Specifies the maximum number of simultaneous connections that - :program:`mongod` will accept. This setting will have no effect if - it is higher than your operating system's configured maximum - connection tracking threshold. - - .. include:: /includes/note-max-conns-max.rst - -.. option:: --objcheck - - Forces the :program:`mongod` to validate all requests from clients - upon receipt to ensure that clients never insert invalid documents - into the database. For objects with a high degree of sub-document - nesting, :option:`--objcheck` can have a small impact on - performance. You can set :option:`--noobjcheck` to disable object - checking at run-time. - - .. versionchanged:: 2.4 - MongoDB enables :option:`--objcheck` by default, to prevent any - client from inserting malformed or invalid BSON into a MongoDB - database. +.. include:: /includes/option/option-mongod-objcheck.rst .. include:: /includes/option/option-mongod-noobjcheck.rst -.. option:: --logpath - - Specify a path for the log file that will hold all diagnostic - logging information. +.. include:: /includes/option/option-mongod-logpath.rst - Unless specified, :program:`mongod` will output all log information - to the standard output. Additionally, unless you also specify - :option:`--logappend`, the logfile will be overwritten when the - process restarts. +.. include:: /includes/option/option-mongod-logappend.rst - .. note:: - - The behavior of the logging system may change in the near - future in response to the :issue:`SERVER-4499` case. - -.. option:: --logappend - - When specified, this option ensures that :program:`mongod` appends - new entries to the end of the logfile rather than overwriting the - content of the log when the process restarts. - -.. option:: --syslog +.. include:: /includes/option/option-mongod-syslog.rst - .. versionadded:: 2.1.0 - - Sends all logging output to the host's :term:`syslog` system rather - than to standard output or a log file as with :option:`--logpath`. - - .. important:: You cannot use :option:`--syslog` with :option:`--logpath`. - -.. option:: --pidfilepath - - Specify a file location to hold the ":term:`PID`" or process ID of - the :program:`mongod` process. Useful for tracking the - :program:`mongod` process in combination with the :option:`mongod --fork` - option. +.. include:: /includes/option/option-mongod-pidfilepath.rst - Without a specified :option:`--pidfilepath` option, - :program:`mongos` creates no PID file. +.. include:: /includes/option/option-mongod-.rst .. option:: --keyFile @@ -170,19 +75,19 @@ Core Options .. option:: --nounixsocket - Disables listening on the UNIX socket. :program:`mongod` always + Disables listening on the UNIX socket. {{program}} always listens on the UNIX socket, unless :option:`--nounixsocket` is set, :setting:`bind_ip` is *not* set, or :setting:`bind_ip` does *not* specify ``127.0.0.1``. - .. |mongodb-package| replace:: :program:`mongod` + .. |mongodb-package| replace:: {{program}} .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst .. option:: --unixSocketPrefix Specifies a path for the UNIX socket. Unless this option has a - value :program:`mongod` creates a socket with ``/tmp`` as a + value {{program}} creates a socket with ``/tmp`` as a prefix. MongoDB will *always* create and listen on a UNIX socket, unless @@ -191,7 +96,7 @@ Core Options .. option:: --fork - Enables a :term:`daemon` mode for :program:`mongod` that runs the + Enables a :term:`daemon` mode for {{program}} that runs the process to the background. This is the normal mode of operation, in production and production-like environments, but may *not* be desirable for testing. @@ -228,18 +133,18 @@ Core Options .. option:: --cpu - Forces :program:`mongod` to report the percentage of CPU time in - write lock. :program:`mongod` generates output every four + Forces {{program}} to report the percentage of CPU time in + write lock. {{program}} generates output every four seconds. MongoDB writes this data to standard output or the logfile if using the :setting:`logpath` option. .. option:: --dbpath - Specify a directory for the :program:`mongod` instance to store its + Specify a directory for the {{program}} instance to store its data. Typical locations include: ``/srv/mongodb``, ``/var/lib/mongodb`` or ``/opt/mongodb`` - Unless specified, :program:`mongod` will look for data files in the + Unless specified, {{program}} will look for data files in the default ``/data/db`` directory. (Windows systems use the ``\data\db`` directory.) If you installed using a package management system. Check the ``/etc/mongodb.conf`` file provided by @@ -301,7 +206,7 @@ Core Options .. option:: --journal Enables operation journaling to ensure write durability and data file - validity. :program:`mongod` enables journaling by default on + validity. {{program}} enables journaling by default on 64-bit builds of versions after 2.0. .. option:: --journalOptions @@ -311,7 +216,7 @@ Core Options .. option:: --journalCommitInterval - Specifies the maximum amount of time for :program:`mongod` to allow + Specifies the maximum amount of time for {{program}} to allow between journal operations. Possible values are between 2 and 300 milliseconds. Lower values increase the durability of the journal, at the expense of disk performance. @@ -322,9 +227,9 @@ Core Options .. option:: --ipv6 Specify this option to enable IPv6 support. This will allow clients - to connect to :program:`mongod` using IPv6 - networks. :program:`mongod` disables IPv6 support by default in - :program:`mongod` and all utilities. + to connect to {{program}} using IPv6 + networks. {{program}} disables IPv6 support by default in + {{program}} and all utilities. .. option:: --jsonp @@ -366,7 +271,7 @@ Core Options .. option:: --nojournal - Disables the durability journaling. By default, :program:`mongod` + Disables the durability journaling. By default, {{program}} enables journaling in 64-bit versions after v2.0. .. option:: --noprealloc @@ -396,7 +301,7 @@ Core Options .. option:: --profile Changes the level of database profiling, which inserts information - about operation performance into output of :program:`mongod` or the log + about operation performance into output of {{program}} or the log file. The following levels are available: ========= ================================== @@ -445,13 +350,13 @@ Core Options .. versionchanged:: 2.1.2 If you run the repair option *and* have data in a journal file, - :program:`mongod` refuses to start. In these cases you should - start :program:`mongod` without the :option:`--repair` option to - allow :program:`mongod` to recover data from the journal. This + {{program}} refuses to start. In these cases you should + start {{program}} without the :option:`--repair` option to + allow {{program}} to recover data from the journal. This completes more quickly and is more likely to produce valid data files. To continue the repair operation despite the journal files, shut down - :program:`mongod` cleanly and restart with the :option:`--repair` + {{program}} cleanly and restart with the :option:`--repair` option. .. note:: @@ -460,7 +365,7 @@ Core Options new data files in the :setting:`repairpath`, and then replaces the original data files with the repaired data files. *If* :setting:`repairpath` is on the same device as - :setting:`dbpath`, you *may* interrupt a :program:`mongod` + :setting:`dbpath`, you *may* interrupt a {{program}} running :option:`--repair` without affecting the integrity of the data set. @@ -488,7 +393,7 @@ Core Options Defines the value of "slow," for the :option:`--profile` option. The database logs all slow queries to the log, even when the profiler is not turned on. When the database profiler is on, - :program:`mongod` the profiler writes to the ``system.profile`` + {{program}} the profiler writes to the ``system.profile`` collection. See the :dbcommand:`profile` command for more information on the database profiler. @@ -502,14 +407,14 @@ Core Options Use :option:`--smallfiles` if you have a large number of databases that each holds a small quantity of data. :option:`--smallfiles` can - lead your :program:`mongod` to create a large number of files, + lead your {{program}} to create a large number of files, which may affect performance for larger databases. .. option:: --shutdown Used in :term:`control scripts `, the :option:`--shutdown` will cleanly and safely terminate the - :program:`mongod` process. When invoking :program:`mongod` with this + {{program}} process. When invoking {{program}} with this option you must set the :option:`--dbpath` option either directly or by way of the :doc:`configuration file ` and the :option:`--config` @@ -519,7 +424,7 @@ Core Options .. option:: --syncdelay - :program:`mongod` writes data very quickly to the journal, and + {{program}} writes data very quickly to the journal, and lazily to the data files. :option:`--syncdelay` controls how much time can pass before MongoDB flushes data to the *database files* via an :term:`fsync` operation. The default setting is 60 seconds. @@ -550,7 +455,7 @@ Core Options Upgrades the on-disk data format of the files specified by the :option:`--dbpath` to the latest version, if needed. - This option only affects the operation of :program:`mongod` if the + This option only affects the operation of {{program}} if the data files are in an old format. .. note:: @@ -570,10 +475,10 @@ Core Options .. option:: --noIndexBuildRetry - By default, :program:`mongod` will attempt to rebuild indexes upon + By default, {{program}} will attempt to rebuild indexes upon start-up *if* :program:`mongod` shuts down or stops in the middle of an index build. When you specify :option:`--noIndexBuildRetry`, - :program:`mongod` will not attempt to rebuild the index. + {{program}} will not attempt to rebuild the index. .. _cli-mongod-replica-set: @@ -595,11 +500,11 @@ Replication Options .. option:: --oplogSize Specifies a maximum size in megabytes for the replication operation - log (e.g. :term:`oplog`.) By :program:`mongod` creates an + log (e.g. :term:`oplog`.) By {{program}} creates an :term:`oplog` based on the maximum amount of space available. For 64-bit systems, the op log is typically 5% of available disk space. - Once the :program:`mongod` has created the oplog for the first + Once the {{program}} has created the oplog for the first time, changing :option:`--oplogSize` will not affect the size of the oplog. @@ -608,13 +513,13 @@ Replication Options In the context of :term:`replica set` replication, set this option if you have seeded this member with a snapshot of the :term:`dbpath` of another member of the set. Otherwise the - :program:`mongod` will attempt to perform an initial sync, + {{program}} will attempt to perform an initial sync, as though the member were a new member. .. warning:: If the data is not perfectly synchronized *and* - :program:`mongod` starts with :setting:`fastsync`, then the + {{program}} starts with :setting:`fastsync`, then the secondary or slave will be permanently out of sync with the primary, which may cause significant consistency problems. @@ -634,7 +539,7 @@ Replication Options 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 ``_id`` index. Specify - ``_id_only`` or ``none`` to prevent the :program:`mongod` from + ``_id_only`` or ``none`` to prevent the {{program}} from loading *any* index into memory. .. _cli-mongod-master-slave: @@ -648,12 +553,12 @@ replica sets are the preferred configuration for database replication. .. option:: --master - Configures :program:`mongod` to run as a replication + Configures {{program}} to run as a replication :term:`master`. .. option:: --slave - Configures :program:`mongod` to run as a replication + Configures {{program}} to run as a replication :term:`slave`. .. option:: --source <:port> @@ -691,11 +596,11 @@ Sharding Cluster Options .. option:: --configsvr - Declares that this :program:`mongod` instance serves as the + Declares that this {{program}} instance serves as the :term:`config database` of a sharded cluster. When running with this option, clients will not be able to write data to any database other than ``config`` and ``admin``. The default port for a - :program:`mongod` with this option is ``27019`` and the default + {{program}} with this option is ``27019`` and the default :option:`--dbpath` directory is ``/data/configdb``, unless specified. @@ -711,7 +616,7 @@ Sharding Cluster Options .. option:: --shardsvr - Configures this :program:`mongod` instance as a shard in a + Configures this {{program}} instance as a shard in a partitioned cluster. The default port for these instances is ``27018``. The only effect of :option:`--shardsvr` is to change the port number. @@ -730,13 +635,30 @@ SSL Options .. see:: :doc:`/tutorial/configure-ssl` for full documentation of MongoDB's support. -.. |binary-name| replace:: :program:`mongod` -.. include:: /includes/manpage-options-ssl.rst +.. include:: /includes/option/option-mongod-ssl.rst + +.. include:: /includes/option/option-mongod-sslCAFile.rst + +.. include:: /includes/option/option-mongod-sslPEMKeyFile.rst + +.. include:: /includes/option/option-mongod-sslPEMKeyPassword.rst + +.. include:: /includes/option/option-mongod-sslCRLFile.rst + +.. include:: /includes/option/option-mongod-sslAllowInvalidCertificates.rst + +.. include:: /includes/option/option-mongod-sslFIPSMode.rst Audit Options ~~~~~~~~~~~~~ -.. include:: /includes/manpage-options-audit.rst +.. include:: /includes/option/option-mongod-auditDestination.rst + +.. include:: /includes/option/option-mongod-auditFormat.rst + +.. include:: /includes/option/option-mongod-auditPath.rst + +.. include:: /includes/option/option-mongod-auditFilter.rst Use --- From da3dd2c039ab2f89b6c54729d4600bb6db57f214 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 7 Feb 2014 10:54:26 -0500 Subject: [PATCH 8/8] DOCS-2501 runtime options: mongod PART II --- source/includes/note-repair.rst | 10 +- source/includes/options-mongod.yaml | 772 +++++++++++++++++++++++++++- source/reference/program/mongod.txt | 563 ++------------------ 3 files changed, 803 insertions(+), 542 deletions(-) diff --git a/source/includes/note-repair.rst b/source/includes/note-repair.rst index 15dab13bfc3..28b28719e17 100644 --- a/source/includes/note-repair.rst +++ b/source/includes/note-repair.rst @@ -1,6 +1,4 @@ -.. note:: - - When using :term:`journaling `, there is almost never - any need to run :dbcommand:`repairDatabase`. In the event of an - unclean shutdown, the server will be able restore the data files - to a pristine state automatically. +When using :term:`journaling `, there is almost never +any need to run :dbcommand:`repairDatabase`. In the event of an +unclean shutdown, the server will be able restore the data files +to a pristine state automatically. diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 431277b5ea9..ed561495609 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -22,16 +22,14 @@ aliases: -f directive: option args: description: | - Specifies a configuration file, that you can use to specify - runtime-configurations. While the options are equivalent and - accessible via the other command line arguments, the configuration - file is the preferred method for runtime configuration of - mongod. See the :doc:`/reference/configuration-options` document - for more information about these options. + Specifies a configuration file for runtime configuration options. The + configuration file is the preferred method for runtime configuration of + :program:`mongod`. The options are equivalent to the command-line + configuration options. See :doc:`/reference/configuration-options` for + more information. - Ensure the configuration file uses ASCII - encoding. {{program}} does not support configuration files - with non-ASCII encoding, including UTF-8. + Ensure the configuration file uses ASCII encoding. {{program}} does not + support configuration files with non-ASCII encoding, including UTF-8. optional: true --- program: mongod @@ -62,12 +60,12 @@ name: bind_ip directive: option args: description: | - The IP address that the {{program}} process binds to and listens for - connections on. By default {{program}} listens for connections for all - interfaces. You may attach {{program}} to any interface. When attaching - {{program}} to a publicly accessible interface, ensure that you have - implemented proper authentication and firewall restrictions to protect - the integrity of your database. + Specifies the IP address that the {{program}} process binds to and + listens for connections on. By default {{program}} listens for + connections for all interfaces. You may attach {{program}} to any + interface. When attaching {{program}} to a publicly accessible + interface, ensure that you have implemented proper authentication and + firewall restrictions to protect the integrity of your database. optional: true --- program: mongod @@ -117,7 +115,7 @@ name: logpath directive: option args: description: | - Specify a path for the log file that will hold all diagnostic + Specifies the path for the log file that holds all diagnostic logging information. Unless specified, {{program}} will output all log information @@ -136,9 +134,8 @@ name: logappend directive: option args: null description: | - When specified, this option ensures that {{program}} appends - new entries to the end of the logfile rather than overwriting the - content of the log when the process restarts. + Appends new entries to the end of the logfile when the {{program}} restarts + instead of overwriting the content of the log. optional: true --- program: mongod @@ -157,7 +154,7 @@ name: pidfilepath directive: option args: description: | - Specify a file location to hold the ":term:`PID`" or process ID of the + Specifies a file location to hold the ":term:`PID`" or process ID of the {{program}} process. Useful for tracking the {{program}} process in combination with the :option:`mongod --fork` option. @@ -166,6 +163,734 @@ description: | optional: true --- program: mongod +name: keyFile +directive: option +args: +description: | + Specifies the path to a key file to store authentication + information. This option is only useful for the connection between + :term:`replica set` members. +optional: true +--- +program: mongod +name: nounixsocket +directive: option +args: null +description: | + Disables listening on the UNIX socket. {{program}} always + listens on the UNIX socket, unless either: :option:`--nounixsocket` + is set, :setting:`bind_ip` is not set, or :setting:`bind_ip` + does not specify ``127.0.0.1``. + + .. |mongodb-package| replace:: {{program}} + + .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst +optional: true +--- +program: mongod +name: unixSocketPrefix +directive: option +args: +description: | + Specifies a path for the UNIX socket. Unless this option has a + value {{program}} creates a socket with ``/tmp`` as a prefix. + + MongoDB will always create and listen on a UNIX socket, unless + :option:`--nounixsocket` is set, :setting:`bind_ip` is not set, + or :setting:`bind_ip` does not specify ``127.0.0.1``. +optional: true +--- +program: mongod +name: fork +directive: option +args: null +description: | + Enables a :term:`daemon` mode for {{program}} that runs the + process to the background. This is the normal mode of operation in + production and production-like environments but may not be + desirable for testing. +optional: true +--- +program: mongod +name: auth +directive: option +args: null +description: | + Enables database authentication for users connecting from remote + hosts. Configure users via the :doc:`mongo shell + `. If no users exist, the localhost interface + will continue to have access to the database until the you create + the first user. + + See :doc:`Security and Authentication ` + for more information. +optional: true +--- +program: mongod +name: saslServiceName +directive: option +args: null +description: | + .. versionadded:: 2.4.6 + Allows users to override the default :doc:`Kerberos + ` + service name component of the :doc:`Kerberos + ` + principal name, on a per-instance basis. If unspecified, the + default value is ``mongodb``. + + Only available on MongoDB Enterprise. + + Only settable during start-up. The :dbcommand:`setParameter` command + does not change this setting. + + **Ensure that your driver supports alternate service names.** + +optional: true +--- +program: mongod +name: cpu +directive: option +args: null +description: | + Forces {{program}} to report the percentage of CPU time in + write lock. {{program}} generates output every four + seconds. MongoDB writes this data to standard output or the logfile + if using the :setting:`logpath` option. +optional: true +--- +program: mongod +name: dbpath +directive: option +args: +description: | + Specifies the directory where the {{program}} instance stores its + data. Typical locations include: ``/srv/mongodb``, ``/var/lib/mongodb`` + or ``/opt/mongodb`` + + Unless specified, {{program}} will look for data files in the default + ``/data/db`` directory. (Windows systems use the ``\data\db`` + directory.) If you installed using a package management system. Check + the ``/etc/mongodb.conf`` file provided by your packages to see the + configuration of the :setting:`dbpath`. +optional: true +--- +program: mongod +name: diaglog +directive: option +args: +description: | + .. deprecated:: 2.6 + + :option:`--diaglog` is for internal use and not intended for most users. + + Creates a very verbose, :term:`diagnostic log` for troubleshooting and + recording various errors. MongoDB writes these log files in the + :setting:`dbpath` directory in a series of files that begin with the + string ``diaglog`` and end with the initiation time of the logging as a + hex string. + + The specified value configures the level of verbosity. Possible values, + and their impact are as follows. + + ========= =================================== + **Value** **Setting** + --------- ----------------------------------- + 0 off. No logging. + 1 Log write operations. + 2 Log read operations. + 3 Log both read and write operations. + 7 Log write and some read operations. + ========= =================================== + + You can use the :program:`mongosniff` tool to replay this output for + investigation. Given a typical diaglog file, located at + ``/data/db/diaglog.4f76a58c``, you might use a command in the following + form to read these files: + + .. code-block:: sh + + mongosniff --source DIAGLOG /data/db/diaglog.4f76a58c + + .. include:: /includes/warning-diaglogging-off.rst +optional: true +--- +program: mongod +name: directoryperdb +directive: option +args: null +description: | + + Alters the storage pattern of the data directory to store each + database's files in a distinct folder. This option will create + directories within the :option:`--dbpath` named for each directory. + + Use this option in conjunction with your file system and device + configuration so that MongoDB will store data on a number of distinct + disk devices to increase write throughput or disk capacity. + + .. warning:: + + .. |directoryperdb-option-name| replace:: :option:`--directoryperdb` + .. include:: /includes/fact-directory-per-db-requires-migration.rst +optional: true +--- +program: mongod +name: journal +directive: option +args: null +description: | + Enables operation journaling to ensure write durability and data file + validity. {{program}} enables journaling by default on + 64-bit builds of versions after 2.0. +optional: true +--- +program: mongod +name: journalOptions +directive: option +args: +description: | + Provides functionality for testing. Not for general use, and will affect data + file integrity in the case of abnormal system shutdown. +optional: true +--- +program: mongod +name: journalCommitInterval +directive: option +args: +description: | + Specifies the maximum amount of time for {{program}} to allow + between journal operations. Possible values are between 2 and 300 + milliseconds. Lower values increase the durability of the journal, + at the expense of disk performance. + + .. include:: /includes/fact-journal-commit-interval-length.rst + .. include:: /includes/fact-journal-commit-interval-with-gle.rst +optional: true +--- +program: mongod +name: ipv6 +inherit: + name: ipv6 + program: _shared + file: options-shared.yaml +--- +program: mongod +name: jsonp +directive: option +args: null +description: | + Permits :term:`JSONP` access via an HTTP interface. Consider the + security implications of allowing this activity before enabling this + option. If the HTTP interface is disabled, the :option:`--jsonp` also + enables the HTTP interface. + + .. seealso:: :option:`--httpinterface` to enable the HTTP interface. +optional: true +--- +program: mongod +name: noauth +directive: option +args: null +description: | + Disables authentication. Currently the default. Exists for future + compatibility and clarity. +optional: true +--- +program: mongod +name: nohttpinterface +directive: option +args: null +description: | + .. deprecated:: 2.6 + MongoDB disables the HTTP interface by default. + + Disables the HTTP interface. + + Do not use in conjunction with :option:`--rest` or :option:`--jsonp`. + + .. include:: /includes/note-kerberos-unsupported-in-http-console.rst +optional: true +--- +program: mongod +name: httpinterface +directive: option +args: null +description: | + .. versionadded:: 2.6 + + Enables the HTTP interface. Enabling the interface can increase + network exposure. + + Leave the HTTP interface *disabled* for production deployments. If you + *do* enable this interface, you should only allow trusted clients to + access this port. See :ref:`security-firewalls`. + + .. include:: /includes/note-kerberos-unsupported-in-http-console.rst +optional: true +--- +program: mongod +name: nojournal +directive: option +args: null +description: | + Disables the durability journaling. By default, {{program}} + enables journaling in 64-bit versions after v2.0. +optional: true +--- +program: mongod +name: noprealloc +directive: option +args: null +description: | + Disables the preallocation of data files. This shortens the + start up time in some cases and can cause significant performance + penalties during normal operations. +optional: true +--- +program: mongod +name: noscripting +directive: option +args: null +description: | + Disables the scripting engine. +optional: true +--- +program: mongod +name: notablescan +directive: option +args: null +description: | + Forbids operations that require a table scan. +optional: true +--- +program: mongod +name: nssize +directive: option +args: +description: | + Specifies the default size for namespace files (i.e ``.ns``). This + option has no impact on the size of existing namespace files. The + maximum size is 2047 megabytes. + + The default value is 16 megabytes, which provides for approximately + 24,000 namespaces. Each collection, as well as each index, counts as + a namespace. +optional: true +--- +program: mongod +name: profile +directive: option +args: +description: | + Changes the level of database profiling, which inserts information + about operation performance into output of {{program}} or the log + file. The following levels are available: + + ========= ================================== + **Level** **Setting** + --------- ---------------------------------- + 0 Off. No profiling. + 1 On. Only includes slow operations. + 2 On. Includes all operations. + ========= ================================== + + Profiling is off by default. Database profiling can impact database + performance. Enable this option only after careful consideration. +optional: true +--- +program: mongod +name: quota +directive: option +args: null +description: | + Enables a maximum limit for the number data files each database can + have. When running with :option:`--quota`, there are a maximum of + 8 data files per database. Adjust the quota with the + :option:`--quotaFiles` option. +optional: true +--- +program: mongod +name: quotaFiles +directive: option +args: +description: | + Modifies the limit on the number of data files per database. This + option requires the :option:`--quota` setting. The default value + for :option:`--quotaFiles` is 8. +optional: true +--- +program: mongod +name: rest +directive: option +args: null +description: | + Enables the simple :term:`REST` API. Consider the security + implications of allowing this activity before enabling this option. + + If the HTTP interface is disabled, the :option:`--rest` setting + also enables the HTTP interface. + + .. seealso:: :option:`--httpinterface` to enable the HTTP interface. +optional: true +--- +program: mongod +name: repair +directive: option +args: null +description: | + Runs a repair routine on all databases. This is equivalent + to shutting down and running the :dbcommand:`repairDatabase` database + command on all databases. + + .. include:: /includes/warning-repair.rst + + .. include:: /includes/note-repair.rst + + .. versionchanged:: 2.1.2 + + If you run the repair option *and* have data in a journal file, + {{program}} refuses to start. In these cases you should start + {{program}} without the :option:`--repair` option to allow {{program}} + to recover data from the journal. This completes more quickly and is + more likely to produce valid data files. To continue the repair + operation despite the journal files, shut down {{program}} cleanly and + restart with the :option:`--repair` option. + + :option:`--repair` copies data from the source data files into new data + files in the :setting:`repairpath`, and then replaces the original data + files with the repaired data files. *If* :setting:`repairpath` is on the + same device as :setting:`dbpath`, you *may* interrupt a {{program}} + running :option:`--repair` without affecting the integrity of the data + set. +optional: true +--- +program: mongod +name: repairpath +directive: option +args: +description: | + Specifies the root directory containing MongoDB data files to use + for the :option:`--repair` operation. Defaults to a ``_tmp`` + directory within the :setting:`dbpath`. +optional: true +--- +program: mongod +name: setParameter +directive: option +args: +description: | + .. versionadded:: 2.4 + + Specifies an option to configure on startup. Specify multiple options + with multiple :option:`--setParameter` options. See + :doc:`/reference/parameters` for full documentation of these parameters. + The :dbcommand:`setParameter` database command provides access to many + of these parameters. :option:`--setParameter` supports the following + options: + + .. include:: /includes/list-set-parameters-mongod.rst +optional: true +--- +program: mongod +name: slowms +directive: option +args: +description: | + Defines the value of "slow," for the :option:`--profile` + option. The database logs all slow queries to the log, even when + the profiler is not turned on. When the database profiler is on, + {{program}} the profiler writes to the ``system.profile`` + collection. See the :dbcommand:`profile` command for more information on the + database profiler. +optional: true +--- +program: mongod +name: smallfiles +directive: option +args: null +description: | + Enables a mode where MongoDB uses a smaller default file + size. Specifically, :option:`--smallfiles` reduces the initial + size for data files and limits them to 512 + megabytes. :option:`--smallfiles` also reduces the size of each + :term:`journal` files from 1 gigabyte to 128 megabytes. + + Use :option:`--smallfiles` if you have a large number of databases + that each holds a small quantity of data. :option:`--smallfiles` can + lead your {{program}} to create a large number of files, + which may affect performance for larger databases. +optional: true +--- +program: mongod +name: shutdown +directive: option +args: null +description: | + Used in :term:`control scripts `, the + :option:`--shutdown` cleanly and safely terminates the {{program}} + process. When invoking {{program}} with this option you must set the + :option:`--dbpath` option either directly or by way of the + :doc:`configuration file ` and the + :option:`--config` option. + + The :option:`--shutdown` option is available only on Linux systems. +optional: true +--- +program: mongod +name: syncdelay +directive: option +args: +description: | + Controls how much time can pass before MongoDB flushes data to the data + files via an :term:`fsync` operation. **Do not set this value on + production systems.** In almost every situation you should not set this + value and use the default setting. + + .. warning:: + + If you set :option:`--syncdelay` to ``0``, MongoDB will not sync the + memory mapped files to disk. + + {{program}} writes data very quickly to the journal and lazily to the + data files. The default :setting:`syncdelay` setting is 60 seconds. + :setting:`syncdelay` has no effect on the :setting:`journal` files or + :doc:`journaling `. + + The :dbcommand:`serverStatus` command reports the background flush + thread's status via the :data:`~serverStatus.backgroundFlushing` field. +optional: true +--- +program: mongod +name: sysinfo +directive: option +args: null +description: | + Returns diagnostic system information and then exits. The + information provides the page size, the number of physical pages, + and the number of available physical pages. +optional: true +--- +program: mongod +name: upgrade +directive: option +args: null +description: | + Upgrades the on-disk data format of the files specified by the + :option:`--dbpath` to the latest version, if needed. + + This option only affects the operation of {{program}} if the data files + are in an old format. + + In most cases you should **not** set this value, so you can exercise the + most control over your upgrade process. See the MongoDB `release notes + `_ (on the download page) for more + information about the upgrade process. +optional: true +--- +program: mongod +name: traceExceptions +directive: option +args: null +description: | + For internal diagnostic use only. + + .. see SERVER-6667a +optional: true +--- +program: mongod +name: noIndexBuildRetry +directive: option +args: null +description: | + Stops {{program}} from rebuilding indexes on the next start-up after the + program had shut down or stopped in the middle of an index build. +optional: true +--- +program: mongod +name: replSet +directive: option +args: +description: | + Configures replication. Specify a replica set name as an argument to + this set. All hosts in the replica set must have the same set name. + + .. include:: /includes/important-unique-replica-set-names.rst +optional: true +--- +program: mongod +name: oplogSize +directive: option +args: +description: | + Specifies a maximum size in megabytes for the replication operation log + (e.g. :term:`oplog`.) By {{program}} creates an :term:`oplog` based on + the maximum amount of space available. For 64-bit systems, the op log is + typically 5% of available disk space. Once the {{program}} has created + the oplog for the first time, changing :option:`--oplogSize` will not + affect the size of the oplog. +optional: true +--- +program: mongod +name: fastsync +directive: option +args: null +description: | + In the context of :term:`replica set` replication, set this option + if you have seeded this member with a snapshot of the + :term:`dbpath` of another member of the set. Otherwise the + {{program}} will attempt to perform an initial sync, + as though the member were a new member. + + In the context of :term:`replica set` replication, set this option + if you have seeded this member with a snapshot of the + :term:`dbpath` of another member of the set. Otherwise the + {{program}} will attempt to perform an initial sync, + as though the member were a new member. + + .. warning:: + If the data is not perfectly synchronized *and* + {{program}} starts with :setting:`fastsync`, then the + secondary or slave will be permanently out of sync with the + primary, which may cause significant consistency problems. +optional: true +--- +program: mongod +name: replIndexPrefetch +directive: option +args: null +description: | + .. versionadded:: 2.2 + + You must use :option:`--replIndexPrefetch` in conjunction with + :setting:`replSet`. The default value is ``all`` and available + options are: + + - ``none`` + + - ``all`` + + - ``_id_only`` + + By default :term:`secondary` members of a :term:`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 ``_id`` index. Specify ``_id_only`` or + ``none`` to prevent the {{program}} from loading *any* index into + memory. +optional: true +--- +program: mongod +name: master +directive: option +args: null +description: | + Configures {{program}} to run as a replication :term:`master`. +optional: true +--- +program: mongod +name: slave +directive: option +args: null +description: | + Configures {{program}} to run as a replication :term:`slave`. +optional: true +--- +program: mongod +name: source +directive: option +args: <:port> +description: | + For use with the :option:`--slave` option, the ``--source`` option + designates the server that this instance will replicate. +optional: true +--- +program: mongod +name: only +directive: option +args: +description: | + For use with the :option:`--slave` option, the ``--only`` option + specifies only a single :term:`database` to replicate. +optional: true +--- +program: mongod +name: slavedelay +directive: option +args: +description: | + For use with the :option:`--slave` option, the ``--slavedelay`` + option configures a "delay" in seconds, for this slave to wait to + apply operations from the :term:`master` node. +optional: true +--- +program: mongod +name: autoresync +directive: option +args: null +description: | + For use with the :option:`--slave` option. When set, + :option:`--autoresync` option allows this slave to automatically + resync if it is more than 10 seconds behind the master. This + setting may be problematic if the :option:`--oplogSize` specifies + a too small oplog. + + If the :term:`oplog` is not large enough to store the difference in + changes between the master's current state and the state of the + slave, this instance will forcibly resync itself + unnecessarily. When you set the :setting:`autoresync` option to + ``false``, the slave will not attempt an automatic resync more than + once in a ten minute period. +optional: true +--- +program: mongod +name: configsvr +directive: option +args: null +description: | + Declares that this {{program}} instance serves as the + :term:`config database` of a sharded cluster. When running with + this option, clients will not be able to write data to any database + other than ``config`` and ``admin``. The default port for a + {{program}} with this option is ``27019`` and the default + :option:`--dbpath` directory is ``/data/configdb``, unless + specified. + + .. versionchanged:: 2.2 + :option:`--configsvr` also sets :option:`--smallfiles`. + + .. versionchanged:: 2.4 + :option:`--configsvr` creates a local :term:`oplog`. + + Do not use :option:`--configsvr` with :option:`--replSet` or + :option:`--shardsvr`. Config servers cannot be a shard + server or part of a :term:`replica set`. +optional: true +--- +program: mongod +name: shardsvr +directive: option +args: null +description: | + Configures this {{program}} instance as a shard in a + partitioned cluster. The default port for these instances is + ``27018``. The only effect of :option:`--shardsvr` is to change + the port number. +optional: true +--- +program: mongod +name: moveParanoia +directive: option +args: null +description: | + .. |move-paranoia-opt| replace:: :option:`--moveParanoia` + + .. versionadded:: 2.4 + + .. include:: /includes/setting-moveparanoia.rst +optional: true +--- +program: mongod name: ssl inherit: name: ssl @@ -256,7 +981,7 @@ name: auditFormat directive: option args: null description: | - Specify the format of the output file if + Specifies the format of the output file if :option:`--auditDestination` is ``file``. The :option:`--auditFormat` can have one of the following values: @@ -285,7 +1010,7 @@ name: auditPath directive: option args: null description: | - Specify the output file for auditing if :option:`--auditDestination` + Specifies the output file for auditing if :option:`--auditDestination` has value of ``file``. The :option:`--auditPath` option can take either a full path name or a relative path name. @@ -294,11 +1019,10 @@ optional: true --- program: mongod name: auditFilter -aliases: directive: option args: null description: | - Specify the filter to limit the :ref:`types of operations + Specifies the filter to limit the :ref:`types of operations ` the audit system records. The option takes a document of the form: diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index 12e91932ff8..a3e1ffdce6d 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -62,485 +62,94 @@ Core Options .. include:: /includes/option/option-mongod-pidfilepath.rst -.. include:: /includes/option/option-mongod-.rst +.. include:: /includes/option/option-mongod-keyFile.rst -.. option:: --keyFile +.. include:: /includes/option/option-mongod-nounixsocket.rst - Specify the path to a key file to store authentication - information. This option is only useful for the connection between - replica set members. +.. include:: /includes/option/option-mongod-unixSocketPrefix.rst - .. seealso:: :ref:`Replica Set Security ` - and :doc:`/administration/replica-sets`. +.. include:: /includes/option/option-mongod-fork.rst -.. option:: --nounixsocket +.. include:: /includes/option/option-mongod-auth.rst - Disables listening on the UNIX socket. {{program}} always - listens on the UNIX socket, unless :option:`--nounixsocket` is set, - :setting:`bind_ip` is *not* set, or :setting:`bind_ip` does *not* - specify ``127.0.0.1``. +.. include:: /includes/option/option-mongod-saslServiceName.rst - .. |mongodb-package| replace:: {{program}} +.. include:: /includes/option/option-mongod-cpu.rst - .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst +.. include:: /includes/option/option-mongod-dbpath.rst -.. option:: --unixSocketPrefix +.. include:: /includes/option/option-mongod-diaglog.rst - Specifies a path for the UNIX socket. Unless this option has a - value {{program}} creates a socket with ``/tmp`` as a - prefix. +.. include:: /includes/option/option-mongod-directoryperdb.rst - MongoDB will *always* create and listen on a UNIX socket, unless - :option:`--nounixsocket` is set, :setting:`bind_ip` is *not* set, - or :setting:`bind_ip` does *not* specify ``127.0.0.1``. +.. include:: /includes/option/option-mongod-journal.rst -.. option:: --fork +.. include:: /includes/option/option-mongod-journalOptions.rst - Enables a :term:`daemon` mode for {{program}} that runs the - process to the background. This is the normal mode of operation, in - production and production-like environments, but may *not* be - desirable for testing. +.. include:: /includes/option/option-mongod-journalCommitInterval.rst -.. option:: --auth +.. include:: /includes/option/option-mongod-ipv6.rst - Enables database authentication for users connecting from remote - hosts. Configure users via the :doc:`mongo shell - `. If no users exist, the localhost interface - will continue to have access to the database until the you create - the first user. +.. include:: /includes/option/option-mongod-jsonp.rst - See the :doc:`Security and Authentication ` - page for more information regarding this functionality. +.. include:: /includes/option/option-mongod-noauth.rst -.. option:: --saslServiceName +.. include:: /includes/option/option-mongod-nohttpinterface.rst - .. versionadded:: 2.4.6 - Allows users to override the default :doc:`Kerberos - ` - service name component of the :doc:`Kerberos - ` - principal name, on a per-instance basis. If unspecified, the - default value is ``mongodb``. +.. include:: /includes/option/option-mongod-httpinterface.rst - Only settable during start-up. The :dbcommand:`setParameter` command - does not change this setting. +.. include:: /includes/option/option-mongod-nojournal.rst - Only available on MongoDB Enterprise. +.. include:: /includes/option/option-mongod-noprealloc.rst - .. important:: +.. include:: /includes/option/option-mongod-noscripting.rst - Ensure that your driver supports alternate service names. +.. include:: /includes/option/option-mongod-notablescan.rst -.. option:: --cpu +.. include:: /includes/option/option-mongod-nssize.rst - Forces {{program}} to report the percentage of CPU time in - write lock. {{program}} generates output every four - seconds. MongoDB writes this data to standard output or the logfile - if using the :setting:`logpath` option. +.. include:: /includes/option/option-mongod-profile.rst -.. option:: --dbpath +.. include:: /includes/option/option-mongod-quota.rst - Specify a directory for the {{program}} instance to store its - data. Typical locations include: ``/srv/mongodb``, - ``/var/lib/mongodb`` or ``/opt/mongodb`` +.. include:: /includes/option/option-mongod-quotaFiles.rst - Unless specified, {{program}} will look for data files in the - default ``/data/db`` directory. (Windows systems use the - ``\data\db`` directory.) If you installed using a package - management system. Check the ``/etc/mongodb.conf`` file provided by - your packages to see the configuration of the :setting:`dbpath`. +.. include:: /includes/option/option-mongod-rest.rst -.. option:: --diaglog +.. include:: /includes/option/option-mongod-repair.rst - .. deprecated:: 2.6 +.. include:: /includes/option/option-mongod-repairpath.rst - Creates a very verbose, :term:`diagnostic log` for troubleshooting - and recording various errors. MongoDB writes these log files in the - :setting:`dbpath` directory in a series of files that begin with - the string ``diaglog`` and end with the initiation time of the - logging as a hex string. +.. include:: /includes/option/option-mongod-setParameter.rst - The specified value configures the level of verbosity. Possible - values, and their impact are as follows. +.. include:: /includes/option/option-mongod-slowms.rst - ========= =================================== - **Value** **Setting** - --------- ----------------------------------- - 0 off. No logging. - 1 Log write operations. - 2 Log read operations. - 3 Log both read and write operations. - 7 Log write and some read operations. - ========= =================================== +.. include:: /includes/option/option-mongod-smallfiles.rst - You can use the :program:`mongosniff` tool to replay this output - for investigation. Given a typical diaglog file, located at - ``/data/db/diaglog.4f76a58c``, you might use a command in the - following form to read these files: +.. include:: /includes/option/option-mongod-shutdown.rst - .. code-block:: sh +.. include:: /includes/option/option-mongod-syncdelay.rst - mongosniff --source DIAGLOG /data/db/diaglog.4f76a58c +.. include:: /includes/option/option-mongod-sysinfo.rst - :option:`--diaglog` is for internal use and not intended for most - users. +.. include:: /includes/option/option-mongod-upgrade.rst - .. include:: /includes/warning-diaglogging-off.rst +.. include:: /includes/option/option-mongod-traceExceptions.rst -.. option:: --directoryperdb - - Alters the storage pattern of the data directory to store each - database's files in a distinct folder. This option will create - directories within the :option:`--dbpath` named for each directory. - - Use this option in conjunction with your file system and device - configuration so that MongoDB will store data on a number of - distinct disk devices to increase write throughput or disk - capacity. - - .. warning:: - - .. |directoryperdb-option-name| replace:: :option:`--directoryperdb` - .. include:: /includes/fact-directory-per-db-requires-migration.rst - -.. option:: --journal - - Enables operation journaling to ensure write durability and data file - validity. {{program}} enables journaling by default on - 64-bit builds of versions after 2.0. - -.. option:: --journalOptions - - Provides functionality for testing. Not for general use, and will affect data - file integrity in the case of abnormal system shutdown. - -.. option:: --journalCommitInterval - - Specifies the maximum amount of time for {{program}} to allow - between journal operations. Possible values are between 2 and 300 - milliseconds. Lower values increase the durability of the journal, - at the expense of disk performance. - - .. include:: /includes/fact-journal-commit-interval-length.rst - .. include:: /includes/fact-journal-commit-interval-with-gle.rst - -.. option:: --ipv6 - - Specify this option to enable IPv6 support. This will allow clients - to connect to {{program}} using IPv6 - networks. {{program}} disables IPv6 support by default in - {{program}} and all utilities. - -.. option:: --jsonp - - Permits :term:`JSONP` access via an HTTP interface. Consider the - security implications of allowing this activity before enabling this - option. If the HTTP interface is disabled, the :option:`--jsonp` - also enables the HTTP interface. - - .. seealso:: :option:`--httpinterface` to enable the HTTP interface. - -.. option:: --noauth - - Disable authentication. Currently the default. Exists for future - compatibility and clarity. - -.. option:: --nohttpinterface - - .. deprecated:: 2.6 - MongoDB disables the HTTP interface by default. - - Disables the HTTP interface. - - Do not use in conjunction with :option:`--rest` or :option:`--jsonp`. - - .. include:: /includes/note-kerberos-unsupported-in-http-console.rst - -.. option:: --httpinterface - - .. versionadded:: 2.6 - - Enables the HTTP interface. Enabling the interface can increase - network exposure. - - Leave the HTTP interface *disabled* for production deployments. If - you *do* enable this interface, you should only allow trusted - clients to access this port. See :ref:`security-firewalls`. - - .. include:: /includes/note-kerberos-unsupported-in-http-console.rst - -.. option:: --nojournal - - Disables the durability journaling. By default, {{program}} - enables journaling in 64-bit versions after v2.0. - -.. option:: --noprealloc - - Disables the preallocation of data files. This will shorten the - start up time in some cases, but can cause significant performance - penalties during normal operations. - -.. option:: --noscripting - - Disables the scripting engine. - -.. option:: --notablescan - - Forbids operations that require a table scan. - -.. option:: --nssize - - Specifies the default size for namespace files (i.e ``.ns``). This - option has no impact on the size of existing namespace files. The - maximum size is 2047 megabytes. - - The default value is 16 megabytes; this provides for approximately - 24,000 namespaces. Each collection, as well as each index, counts as - a namespace. - -.. option:: --profile - - Changes the level of database profiling, which inserts information - about operation performance into output of {{program}} or the log - file. The following levels are available: - - ========= ================================== - **Level** **Setting** - --------- ---------------------------------- - 0 Off. No profiling. - 1 On. Only includes slow operations. - 2 On. Includes all operations. - ========= ================================== - - Profiling is off by default. Database profiling can impact database - performance. Enable this option only after careful consideration. - -.. option:: --quota - - Enables a maximum limit for the number data files each database can - have. When running with :option:`--quota`, there are a maximum of - 8 data files per database. Adjust the quota with the - :option:`--quotaFiles` option. - -.. option:: --quotaFiles - - Modify limit on the number of data files per database. This option - requires the :option:`--quota` setting. The default value for - :option:`--quotaFiles` is 8. - -.. option:: --rest - - Enables the simple :term:`REST` API. Consider the security - implications of allowing this activity before enabling this option. - If the HTTP interface is disabled, the :option:`--rest` setting - also enables the HTTP interface. - - .. seealso:: :option:`--httpinterface` to enable the HTTP interface. - -.. option:: --repair - - Runs a repair routine on all databases. This is equivalent - to shutting down and running the :dbcommand:`repairDatabase` database - command on all databases. - - .. include:: /includes/warning-repair.rst - - .. include:: /includes/note-repair.rst - - .. versionchanged:: 2.1.2 - - If you run the repair option *and* have data in a journal file, - {{program}} refuses to start. In these cases you should - start {{program}} without the :option:`--repair` option to - allow {{program}} to recover data from the journal. This - completes more quickly and is more likely to produce valid data files. - - To continue the repair operation despite the journal files, shut down - {{program}} cleanly and restart with the :option:`--repair` - option. - - .. note:: - - :option:`--repair` copies data from the source data files into - new data files in the :setting:`repairpath`, and then replaces - the original data files with the repaired data files. *If* - :setting:`repairpath` is on the same device as - :setting:`dbpath`, you *may* interrupt a {{program}} - running :option:`--repair` without affecting the integrity of - the data set. - -.. option:: --repairpath - - Specifies the root directory containing MongoDB data files, to use - for the :option:`--repair` operation. Defaults to a ``_tmp`` - directory within the :setting:`dbpath`. - -.. option:: --setParameter - - .. versionadded:: 2.4 - - Specifies an option to configure on startup. Specify multiple - options with multiple :option:`--setParameter` options. See - :doc:`/reference/parameters` for full documentation of these - parameters. The :dbcommand:`setParameter` database command provides - access to many of these parameters. :option:`--setParameter` supports the - following options: - - .. include:: /includes/list-set-parameters-mongod.rst - -.. option:: --slowms - - Defines the value of "slow," for the :option:`--profile` - option. The database logs all slow queries to the log, even when - the profiler is not turned on. When the database profiler is on, - {{program}} the profiler writes to the ``system.profile`` - collection. See the :dbcommand:`profile` command for more information on the - database profiler. - -.. option:: --smallfiles - - Enables a mode where MongoDB uses a smaller default file - size. Specifically, :option:`--smallfiles` reduces the initial - size for data files and limits them to 512 - megabytes. :option:`--smallfiles` also reduces the size of each - :term:`journal` files from 1 gigabyte to 128 megabytes. - - Use :option:`--smallfiles` if you have a large number of databases - that each holds a small quantity of data. :option:`--smallfiles` can - lead your {{program}} to create a large number of files, - which may affect performance for larger databases. - -.. option:: --shutdown - - Used in :term:`control scripts `, the - :option:`--shutdown` will cleanly and safely terminate the - {{program}} process. When invoking {{program}} with this - option you must set the :option:`--dbpath` option either directly - or by way of the :doc:`configuration file - ` and the :option:`--config` - option. - - The :option:`--shutdown` option is available only on Linux systems. - -.. option:: --syncdelay - - {{program}} writes data very quickly to the journal, and - lazily to the data files. :option:`--syncdelay` controls how much - time can pass before MongoDB flushes data to the *database files* - via an :term:`fsync` operation. The default setting is 60 seconds. - In almost every situation you should not set this value and use the - default setting. - - The :dbcommand:`serverStatus` command reports the background flush - thread's status via the :data:`~serverStatus.backgroundFlushing` - field. - - :setting:`syncdelay` has no effect on the :setting:`journal` - files or :doc:`journaling `. - - .. warning:: - - If you set :option:`--syncdelay` to ``0``, MongoDB will not - sync the memory mapped files to disk. Do not set this value on - production systems. - -.. option:: --sysinfo - - Returns diagnostic system information and then exits. The - information provides the page size, the number of physical pages, - and the number of available physical pages. - -.. option:: --upgrade - - Upgrades the on-disk data format of the files specified by the - :option:`--dbpath` to the latest version, if needed. - - This option only affects the operation of {{program}} if the - data files are in an old format. - - .. note:: - - .. todo:: change link to release notes here - - In most cases you should **not** set this value, so you can - exercise the most control over your upgrade process. See the MongoDB - `release notes `_ (on the - download page) for more information about the upgrade process. - -.. option:: --traceExceptions - - For internal diagnostic use only. - - .. see SERVER-6667a - -.. option:: --noIndexBuildRetry - - By default, {{program}} will attempt to rebuild indexes upon - start-up *if* :program:`mongod` shuts down or stops in the middle - of an index build. When you specify :option:`--noIndexBuildRetry`, - {{program}} will not attempt to rebuild the index. +.. include:: /includes/option/option-mongod-noIndexBuildRetry.rst .. _cli-mongod-replica-set: Replication Options ~~~~~~~~~~~~~~~~~~~ -.. option:: --replSet - - Use this option to configure replication with replica sets. Specify - a replica set name as an argument to this set. All hosts in the - replica set must have the same set name. +.. include:: /includes/option/option-mongod-replSet.rst - .. include:: /includes/important-unique-replica-set-names.rst +.. include:: /includes/option/option-mongod-oplogSize.rst - .. seealso:: :doc:`/replication`, - :doc:`/administration/replica-sets`, and - :doc:`/reference/replica-configuration` +.. include:: /includes/option/option-mongod-fastsync.rst -.. option:: --oplogSize - - Specifies a maximum size in megabytes for the replication operation - log (e.g. :term:`oplog`.) By {{program}} creates an - :term:`oplog` based on the maximum amount of space available. For - 64-bit systems, the op log is typically 5% of available disk space. - - Once the {{program}} has created the oplog for the first - time, changing :option:`--oplogSize` will not affect the size of - the oplog. - -.. option:: --fastsync - - In the context of :term:`replica set` replication, set this option - if you have seeded this member with a snapshot of the - :term:`dbpath` of another member of the set. Otherwise the - {{program}} will attempt to perform an initial sync, - as though the member were a new member. - - .. warning:: - - If the data is not perfectly synchronized *and* - {{program}} starts with :setting:`fastsync`, then the - secondary or slave will be permanently out of sync with the - primary, which may cause significant consistency problems. - -.. option:: --replIndexPrefetch - - .. versionadded:: 2.2 - - You must use :option:`--replIndexPrefetch` in conjunction with - :setting:`replSet`. The default value is ``all`` and available - options are: - - - ``none`` - - ``all`` - - ``_id_only`` - - By default :term:`secondary` members of a :term:`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 ``_id`` index. Specify - ``_id_only`` or ``none`` to prevent the {{program}} from - loading *any* index into memory. +.. include:: /includes/option/option-mongod-replIndexPrefetch.rst .. _cli-mongod-master-slave: @@ -551,83 +160,26 @@ These options provide access to conventional master-slave database replication. While this functionality remains accessible in MongoDB, replica sets are the preferred configuration for database replication. -.. option:: --master - - Configures {{program}} to run as a replication - :term:`master`. - -.. option:: --slave - - Configures {{program}} to run as a replication - :term:`slave`. - -.. option:: --source <:port> +.. include:: /includes/option/option-mongod-master.rst - For use with the :option:`--slave` option, the ``--source`` option - designates the server that this instance will replicate. +.. include:: /includes/option/option-mongod-slave.rst -.. option:: --only +.. include:: /includes/option/option-mongod-source.rst - For use with the :option:`--slave` option, the ``--only`` option - specifies only a single :term:`database` to replicate. +.. include:: /includes/option/option-mongod-only.rst -.. option:: --slavedelay +.. include:: /includes/option/option-mongod-slavedelay.rst - For use with the :option:`--slave` option, the ``--slavedelay`` - option configures a "delay" in seconds, for this slave to wait to - apply operations from the :term:`master` node. - -.. option:: --autoresync - - For use with the :option:`--slave` option. When set, - :option:`--autoresync` option allows this slave to automatically - resync if it is more than 10 seconds behind the master. This - setting may be problematic if the :option:`--oplogSize` specifies - a too small oplog. - If the :term:`oplog` is not large enough to store the difference in - changes between the master's current state and the state of the - slave, this instance will forcibly resync itself - unnecessarily. When you set the :setting:`autoresync` option to - ``false``, the slave will not attempt an automatic resync more than - once in a ten minute period. +.. include:: /includes/option/option-mongod-autoresync.rst Sharding Cluster Options ~~~~~~~~~~~~~~~~~~~~~~~~ -.. option:: --configsvr - - Declares that this {{program}} instance serves as the - :term:`config database` of a sharded cluster. When running with - this option, clients will not be able to write data to any database - other than ``config`` and ``admin``. The default port for a - {{program}} with this option is ``27019`` and the default - :option:`--dbpath` directory is ``/data/configdb``, unless - specified. - - .. versionchanged:: 2.2 - :option:`--configsvr` also sets :option:`--smallfiles`. - - .. versionchanged:: 2.4 - :option:`--configsvr` creates a local :term:`oplog`. - - Do not use :option:`--configsvr` with :option:`--replSet` or - :option:`--shardsvr`. Config servers cannot be a shard - server or part of a :term:`replica set`. - -.. option:: --shardsvr - - Configures this {{program}} instance as a shard in a - partitioned cluster. The default port for these instances is - ``27018``. The only effect of :option:`--shardsvr` is to change - the port number. +.. include:: /includes/option/option-mongod-configsvr.rst -.. option:: --moveParanoia +.. include:: /includes/option/option-mongod-shardsvr.rst - .. |move-paranoia-opt| replace:: :option:`--moveParanoia` - - .. versionadded:: 2.4 - - .. include:: /includes/setting-moveparanoia.rst +.. include:: /includes/option/option-mongod-moveParanoia.rst SSL Options ~~~~~~~~~~~ @@ -659,16 +211,3 @@ Audit Options .. include:: /includes/option/option-mongod-auditPath.rst .. include:: /includes/option/option-mongod-auditFilter.rst - -Use ---- - -In common usage, the invocation of :program:`mongod` will resemble the -following in the context of an initialization or control script: - -.. code-block:: sh - - mongod --config /etc/mongodb.conf - -See the :doc:`/reference/configuration-options` for more information -on how to configure :program:`mongod` using the configuration file.