From f59a61de5e13765a462b126977a61e3dff6dd1aa Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 24 Mar 2014 16:04:35 -0400 Subject: [PATCH] DOCS-2502 configuration file options --- .../fact-audit-syslog-message-limit.rst | 3 - ...ct-directory-per-db-requires-migration.rst | 34 - .../fact-journal-commit-interval-length.rst | 6 - .../fact-journal-commit-interval-with-gle.rst | 4 - source/includes/manpage-options-audit.rst | 85 -- .../includes/manpage-options-auth-mongo.rst | 28 - source/includes/manpage-options-auth.rst | 30 - .../note-configuration-file-must-be-ascii.rst | 5 - source/includes/options-bsondump.yaml | 6 +- source/includes/options-conf.yaml | 956 +++++++++++++ source/includes/options-mongo.yaml | 6 +- source/includes/options-mongod.exe.yaml | 10 +- source/includes/options-mongod.yaml | 804 ++++++----- source/includes/options-mongodump.yaml | 18 +- source/includes/options-mongoexport.yaml | 16 +- source/includes/options-mongoimport.yaml | 4 +- source/includes/options-mongooplog.yaml | 4 +- source/includes/options-mongorestore.yaml | 14 +- source/includes/options-mongos.yaml | 147 +- source/includes/options-mongostat.yaml | 6 +- source/includes/options-shared.yaml | 164 ++- source/includes/setting-moveparanoia.rst | 7 - source/includes/warning-diaglogging-off.rst | 8 - source/reference/configuration-options.txt | 1211 ++--------------- source/reference/connection-string.txt | 2 +- source/reference/glossary.txt | 8 +- source/reference/parameters.txt | 50 +- source/reference/program/mongod.txt | 10 +- source/tutorial/configure-auditing.txt | 4 +- 29 files changed, 1769 insertions(+), 1881 deletions(-) delete mode 100644 source/includes/fact-audit-syslog-message-limit.rst delete mode 100644 source/includes/fact-directory-per-db-requires-migration.rst delete mode 100644 source/includes/fact-journal-commit-interval-length.rst delete mode 100644 source/includes/fact-journal-commit-interval-with-gle.rst delete mode 100644 source/includes/manpage-options-audit.rst delete mode 100644 source/includes/manpage-options-auth-mongo.rst delete mode 100644 source/includes/manpage-options-auth.rst delete mode 100644 source/includes/note-configuration-file-must-be-ascii.rst create mode 100755 source/includes/options-conf.yaml delete mode 100644 source/includes/setting-moveparanoia.rst delete mode 100644 source/includes/warning-diaglogging-off.rst diff --git a/source/includes/fact-audit-syslog-message-limit.rst b/source/includes/fact-audit-syslog-message-limit.rst deleted file mode 100644 index 73953249c79..00000000000 --- a/source/includes/fact-audit-syslog-message-limit.rst +++ /dev/null @@ -1,3 +0,0 @@ -The syslog message limit can result in the truncation of the audit -messages. The auditing system will neither detect the truncation nor -error upon its occurrence. diff --git a/source/includes/fact-directory-per-db-requires-migration.rst b/source/includes/fact-directory-per-db-requires-migration.rst deleted file mode 100644 index 17c1a93c249..00000000000 --- a/source/includes/fact-directory-per-db-requires-migration.rst +++ /dev/null @@ -1,34 +0,0 @@ -If you have an existing :program:`mongod` instance and -:setting:`dbpath`, and you want to enable -|directoryperdb-option-name|, you **must** migrate your existing -databases to directories before setting |directoryperdb-option-name| -to access those databases. - -.. example:: - - Given a :setting:`dbpath` directory with the following items: - - .. code-block:: none - - journal - mongod.lock - local.0 - local.1 - local.ns - test.0 - test.1 - test.ns - - To enable |directoryperdb-option-name| you would need to modify the - :setting:`dbpath` to resemble the following: - - .. code-block:: none - - journal - mongod.lock - local/local.0 - local/local.1 - local/local.ns - test/test.0 - test/test.1 - test/test.ns diff --git a/source/includes/fact-journal-commit-interval-length.rst b/source/includes/fact-journal-commit-interval-length.rst deleted file mode 100644 index 42434b32c20..00000000000 --- a/source/includes/fact-journal-commit-interval-length.rst +++ /dev/null @@ -1,6 +0,0 @@ -The default journal commit interval is 100 milliseconds if a single -block device (e.g. physical volume, RAID device, or LVM volume) -contains both the journal and the data files. - -If the journal is on a different block device than the data files the -default journal commit interval is 30 milliseconds. diff --git a/source/includes/fact-journal-commit-interval-with-gle.rst b/source/includes/fact-journal-commit-interval-with-gle.rst deleted file mode 100644 index 86407fd32d8..00000000000 --- a/source/includes/fact-journal-commit-interval-with-gle.rst +++ /dev/null @@ -1,4 +0,0 @@ -To force :program:`mongod` to commit to the journal more frequently, -you can specify ``j:true``. When a write operation with ``j:true`` -is pending, :program:`mongod` will reduce -:setting:`journalCommitInterval` to a third of the set value. diff --git a/source/includes/manpage-options-audit.rst b/source/includes/manpage-options-audit.rst deleted file mode 100644 index 6d8a1c93443..00000000000 --- a/source/includes/manpage-options-audit.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. option:: --auditDestination - - .. include:: /includes/note-audit-in-enterprise-only.rst - - Enable 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`. - -.. option:: --auditFormat - - .. include:: /includes/note-audit-in-enterprise-only.rst - - 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`. - -.. option:: --auditPath - - .. include:: /includes/note-audit-in-enterprise-only.rst - - 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. - -.. option:: --auditFilter - - .. include:: /includes/note-audit-in-enterprise-only.rst - - 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": } diff --git a/source/includes/manpage-options-auth-mongo.rst b/source/includes/manpage-options-auth-mongo.rst deleted file mode 100644 index edbfa4493e8..00000000000 --- a/source/includes/manpage-options-auth-mongo.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. use |binary-name| to refer to the tool - -.. option:: --authenticationDatabase - - .. versionadded:: 2.4 - - Specifies the database that holds the user's (e.g - :option:`--username <|binary-name| --username>`) credentials. - - By default, |binary-name| assumes that the database name specified - in the :ref:`db address ` is the database that - defines the user, unless you specify :option:`--authenticationDatabase`. - - See :doc:`/core/authentication` for more information on - authentication in MongoDB. - -.. option:: --authenticationMechanism - - .. 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|, - |binary-name| 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. diff --git a/source/includes/manpage-options-auth.rst b/source/includes/manpage-options-auth.rst deleted file mode 100644 index 09a7a852580..00000000000 --- a/source/includes/manpage-options-auth.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. use |binary-name| to refer to the tool - -.. option:: --authenticationDatabase - - .. versionadded:: 2.4 - - Specifies the database that holds the user's (e.g - :option:`--username <|binary-name| --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. - -.. option:: --authenticationMechanism - - .. 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|, - |binary-name| 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. diff --git a/source/includes/note-configuration-file-must-be-ascii.rst b/source/includes/note-configuration-file-must-be-ascii.rst deleted file mode 100644 index 228d69be1fc..00000000000 --- a/source/includes/note-configuration-file-must-be-ascii.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. note:: - - Ensure the configuration file uses ASCII - encoding. :program:`mongod` does not support configuration files - with non-ASCII encoding, including UTF-8. diff --git a/source/includes/options-bsondump.yaml b/source/includes/options-bsondump.yaml index 4017f1e4b7a..4843598a497 100644 --- a/source/includes/options-bsondump.yaml +++ b/source/includes/options-bsondump.yaml @@ -36,13 +36,13 @@ directive: option args: null description: | Validates each :term:`BSON` object before outputting it in :term:`JSON` - format. By default, {{program}} enables :option:`--objcheck`. + format. By default, {{program}} enables {{role}}. For objects with a high degree of sub-document nesting, - :option:`--objcheck` can have a small impact on performance. You can set + {{role}} can have a small impact on performance. You can set :option:`--noobjcheck` to disable object checking. .. versionchanged:: 2.4 - MongoDB enables :option:`--objcheck` by default, to prevent any + MongoDB enables {{role}} by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database. optional: true diff --git a/source/includes/options-conf.yaml b/source/includes/options-conf.yaml new file mode 100755 index 00000000000..56b470af3b0 --- /dev/null +++ b/source/includes/options-conf.yaml @@ -0,0 +1,956 @@ +# This file borrows content from: +# /includes/options-shared.yaml +# /includes/options-mongod.yaml +# /includes/options-mongos.yaml +# +# The {{program}} variable is generated by the system. +# +program: conf +name: systemLog.verbosity +type: integer +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: verbose + program: _shared + file: options-shared.yaml +description: | + Increases the amount of internal reporting returned on standard output + or in log files. To increase the amount of information reported, increase + the number. +--- +program: conf +name: systemLog.quiet +type: boolean +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: quiet + program: _shared + file: options-shared.yaml +post: | + This option is **not** recommended for production systems as it may make + tracking problems during particular connections much more difficult. +--- +program: conf +name: systemLog.traceAllExceptions +type: string +directive: setting +description: | + Prints verbose information for debugging. Used for additional logging in + support-related troubleshooting. +--- +program: conf +name: systemLog.syslogFacility +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: syslogFacility + program: mongod + file: options-mongod.yaml +--- +program: conf +name: systemLog.path +type: string +directive: setting +replacement: + program: ":program:`mongod` or :program:`mongos`" +inherit: + program: mongod + name: logpath + file: options-mongod.yaml +--- +program: conf +name: systemLog.logAppend +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: logappend + program: mongod + file: options-mongod.yaml +--- +program: conf +name: systemLog.destination +type: string +directive: setting +description: | + The path and name of the system log file. +--- +program: conf +name: systemLog.timeStampFormat +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: timeStampFormat + program: mongod + file: options-mongod.yaml +--- +program: conf +name: processDiagLog +type: integer +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: diaglog + program: mongod + file: options-mongod.yaml +--- +program: conf +name: processManagement.pidFilePath +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: pidfilepath + program: mongod + file: options-mongod.yaml +--- +program: conf +name: processManagement.fork +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: fork + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.port +type: integer +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: port + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.bindIp +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: bind_ip + program: mongod + file: options-mongod.yaml +post: | + To bind to multiple IP addresses, enter a list of comma separated values. +--- +program: conf +name: net.maxIncomingConnections +type: integer +default: 1000000 +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: maxConns + program: mongod + file: options-mongod.yaml +post: | + This is particularly useful for a :program:`mongos` if you have a client + that creates a number of connections but allows them to timeout rather + than close the connections. When you set this option, ensure the value + is slightly higher than the size of the connection pool or the total + number of connections, to prevent erroneous connection spikes from + propagating to the members of a sharded cluster. +--- +program: conf +name: net.wireObjectCheck +type: boolean +default: true +directive: setting +description: | + Forces the :program:`mongod` or :program:`mongos` instance to validate + all requests from clients upon receipt to prevent clients from inserting + malformed or invalid BSON into a MongoDB database. + + For objects with a high degree of sub-document nesting, {{role}} can + have a small impact on performance. +--- +program: conf +name: net.http.enabled +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: httpinterface + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.http.port +type: boolean +directive: setting +description: | + The port on which the HTTP interface listens. +--- +program: conf +name: net.unixDomainSocket.enabled +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: nounixsocket + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.unixDomainSocket.pathPrefix +type: string +default: /tmp +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: unixSocketPrefix + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.ipv6 +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: ipv6 + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.http.JSONPEnabled +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: jsonp + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: net.http.RESTInterfaceEnabled +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: rest + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: net.ssl.mode +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslMode + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.ssl.PEMKeyFile +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslPEMKeyFile + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.ssl.PEMKeyPassword +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslPEMKeyPassword + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.ssl.clusterFile +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslClusterFile + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.ssl.clusterPassword +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslClusterPassword + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.ssl.CAFile +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslCAFile + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.ssl.CRLFile +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslCRLFile + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.ssl.weakCertificateValidation +type: boolean +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslWeakCertificateValidation + program: mongod + file: options-mongod.yaml +--- +program: conf +name: net.ssl.allowInvalidCertificates +type: boolean +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslAllowInvalidCertificates + program: _shared + file: options-shared.yaml +--- +program: conf +name: net.ssl.FIPSMode +type: boolean +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: sslFIPSMode + program: _shared + file: options-shared.yaml +--- +program: conf +name: setParameter +type: document +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: setParameter + program: mongod + file: options-mongod.yaml +--- +program: conf +name: security.keyFile +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: keyFile + program: mongod + file: options-mongod.yaml +--- +program: conf +name: security.clusterAuthMode +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: clusterAuthMode + program: mongod + file: options-mongod.yaml +--- +program: conf +name: security.authentication +# The equivalent command-line option (auth) does not take string values as +# this option does. +type: string +directive: setting +description: | + Requires database authentication for users connecting from remote hosts. + Set this option to one of the following: + + .. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Value + + - Description + + * - ``optional`` + + - A client connect with or without authentication. + + * - ``allowSSL`` + + - Connections between servers do not use SSL. For incoming + connections, the server accepts both SSL and non-SSL. + + * - ``required`` + + - Clients must use authentication. + + 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. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: security.authenticationMechanisms +# the equivalent command-line option is set via setParameter. +type: strings +directive: setting +description: | + .. versionchanged:: 2.6 + Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication + mechanisms. + + Specifies the list of authentication mechanisms the server accepts. Set + this to one or more of the following values. If you specify multiple + values, use a comma-separated list and no spaces. For descriptions + of the authentication mechanisms, see :doc:`/core/authentication`. + + .. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Value + + - Description + + * - MONGODB-CR + + - MongoDB challenge/response authentication. + + * - MONGODB-X509 + + - MongoDB SSL certificate authentication. + + * - PLAIN + + - External authentication using LDAP. You can also use ``PLAIN`` + for authenticating in-database users. ``PLAIN`` transmits + passwords in plain text. This mechanism is available only in + `MongoDB Enterprise + `_. + + * - GSSAPI + + - External authentication using Kerberos. This mechanism is + available only in `MongoDB Enterprise + `_. +# Per DOCS-2940, combine this with similar info in +# /includes/options-shared +# /reference/connection-string +# /reference/parameters +# /tutorial/control-access-to-mongodb-windows-with-kerberos-authentication +# /tutorial/control-access-to-mongodb-with-kerberos-authentication.txt +--- +program: conf +name: security.enableLocalhostAuthBypass +# the equivalent command-line option is set via setParameter. +type: string +default: enabled +directive: setting +description: | + .. versionadded:: 2.6 + + Specify ``0`` to disable localhost authentication bypass. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: security.supportCompatibilityFormPrivilegeDocuments +# the equivalent command-line option is set via setParameter. +type: string +directive: setting +description: | + Disables backwards compatibility with the MongoDB 2.2 access control + roles. To disable backwards compatibility, set {{role}} to ``0``. In + general, you should set this option if your deployment does not need to + support legacy user documents. Typically legacy user documents are only + useful during the upgrade process and while you migrate applications to + the updated privilege document form. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: security.authSchemaVersion +# todo This option currently exists in the code but has no function. When +# a function is written, update this content. +type: string +directive: setting +description: | + This option is currently not used. +--- +program: conf +name: security.sasl.hostName +type: string +directive: setting +description: | + A fully qualified server domain name for the purpose of configuring SASL + and Kerberos authentication. The SASL hostname overrides the hostname + only for the configuration of SASL and Kerberos. +--- +program: conf +name: security.sasl.serviceName +type: string +directive: setting +description: | + Registered name of the service using SASL. This option allows you 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``. + + MongoDB permits setting this option only at startup. The + :dbcommand:`setParameter` can not change this setting. + + This option is available only in MongoDB Enterprise. + +.. important:: Ensure that your driver supports alternate service names. +--- +program: conf +name: security.sasl.saslauthdSocketPath +type: string +directive: setting +description: | + The path to the UNIX domain socket file for ``saslauthd``. +--- +program: conf +name: operationProfiling.slowOpThresholdMs +type: integer +default: 100 +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: slowms + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: operationProfiling.mode +type: integer +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: profile + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.dbPath +type: string +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: dbpath + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.directoryPerDB +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: directoryperdb + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.indexBuildRetry +type: boolean +default: true +directive: setting +description: | + Selects whether :program:`mongod` rebuilds incomplete indexes on the + next start up. This applies in cases where :program:`mongod` restarts + after it has shut down or stopped in the middle of an index build. In + such cases, :program:`mongod` always removes any incomplete indexes, + and then, by default, attemps to rebuild them. To stop :program:`mongod` + from rebuilding indexes, set this option to ``false``. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.preallocDataFiles +type: boolean +default: true +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: noprealloc + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.nsSize +type: integer +default: 16 +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: nssize + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.quota.maxFilesPerDB +type: integer +default: 8 +directive: setting +description: | + Sets a maximum limit for the number data files each database can have. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.smallFiles +type: boolean +default: false +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: smallfiles + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.syncPeriodSecs +type: number +default: 60 +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: syncdelay + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.repairPath +type: string +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: repairpath + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.journal.enabled +type: boolean +default: | + ``true`` on 64-bit systems, ``false`` on 32-bit systems +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: journal + program: _shared + file: options-shared.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.journal.debugFlags +type: integer +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: journalOptions + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: storage.journal.commitIntervalMs +type: number +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: journalCommitInterval + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: replication.oplogSizeMB +type: integer +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: oplogSize + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: replication.replSetName +type: string +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: replSet + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: replication.secondaryIndexPrefetch +type: string +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: replIndexPrefetch + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: sharding.clusterRole +type: string +directive: setting +description: | + Selects the role the :program:`mongod` instance has in the sharded + cluster. Set this option to one of the following: + + .. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Value + + - Description + + * - ``configsvr`` + + - Start this instance as a term:`config server`. The instance + starts on port ``27019`` by default. + + * - ``shardsvr`` + + - Start this instance as a :term:`shard`. The instance starts + on port ``27018`` by default. +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: moveParanoia +type: integer +directive: setting +inherit: + name: moveParanoia + program: mongod + file: options-mongod.yaml +--- +program: conf +name: auditLog.destination +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: auditDestination + program: mongod + file: options-mongod.yaml +--- +program: conf +name: auditLog.format +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: auditFormat + program: mongod + file: options-mongod.yaml +--- +program: conf +name: auditLog.path +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: auditPath + program: mongod + file: options-mongod.yaml +--- +program: conf +name: auditLog.filter +type: string +directive: setting +replacement: + program: ":program:`mongos` or :program:`mongod`" +inherit: + name: auditFilter + program: mongod + file: options-mongod.yaml +--- +program: conf +name: snmp.subagent +type: boolean +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: snmp-subagent + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: snmp.master +type: boolean +directive: setting +replacement: + program: ":program:`mongod`" +inherit: + name: snmp-master + program: mongod + file: options-mongod.yaml +post: | + The {{role}} option is available only in :program:`mongod`. +--- +program: conf +name: replication.localPingThresholdMs +type: integer +directive: setting +replacement: + program: ":program:`mongos`" +inherit: + name: localThreshold + program: mongos + file: options-mongos.yaml +--- +program: conf +name: sharding.autoSplit +type: boolean +directive: setting +replacement: + program: ":program:`mongos`" +inherit: + name: noAutoSplit + program: mongos + file: options-mongos.yaml +--- +program: conf +name: sharding.configDB +type: string +directive: setting +replacement: + program: ":program:`mongos`" +inherit: + name: configdb + program: mongos + file: options-mongos.yaml +--- +program: conf +name: sharding.chunkSize +type: integer +default: 64 +directive: setting +replacement: + program: ":program:`mongos`" +inherit: + name: chunkSize + program: mongos + file: options-mongos.yaml +... diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index 87154231295..534f8f37685 100644 --- a/source/includes/options-mongo.yaml +++ b/source/includes/options-mongo.yaml @@ -9,7 +9,7 @@ args: null description: | Enables the shell interface. If you invoke the {{program}} command and specify a JavaScript file as an argument, or use :option:`--eval` to - specify JavaScript on the command line, the :option:`--shell` option + specify JavaScript on the command line, the {{role}} option provides the user with a shell prompt after the file finishes executing. optional: true --- @@ -46,7 +46,7 @@ directive: option args: description: | Specifies the port where the :program:`mongod` or :program:`mongos` - instance is listening. If :option:`--port` is not specified, + instance is listening. If {{role}} is not specified, {{program}} attempts to connect to port ``27017``. optional: true --- @@ -89,7 +89,7 @@ replacement: | Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the :option:`--username` and :option:`--authenticationDatabase` options. To force {{program}} to - prompt for a password, enter the :option:`--password` option as the + prompt for a password, enter the {{role}} option as the last option and leave out the argument. --- program: mongo diff --git a/source/includes/options-mongod.exe.yaml b/source/includes/options-mongod.exe.yaml index 3d83a3e4bf5..0b55fe79450 100644 --- a/source/includes/options-mongod.exe.yaml +++ b/source/includes/options-mongod.exe.yaml @@ -12,7 +12,7 @@ description: | Removes the {{program}} Windows Service. If {{program}} is running, this operation will stop and then remove the service. - :option:`--remove` requires the :option:`--serviceName` if you + {{role}} requires the :option:`--serviceName` if you configured a non-default :option:`--serviceName` during the :option:`--install` operation. optional: true @@ -35,7 +35,7 @@ description: | Windows Service. Use this name with the ``net start `` and ``net stop `` operations. - You must use :option:`--serviceName` in conjunction with either + You must use {{role}} in conjunction with either the :option:`--install` or :option:`--remove` install option. optional: true --- @@ -57,7 +57,7 @@ default: "Mongo DB Server" description: | Sets the {{program}} service description. - You must use :option:`--serviceDescription` in conjunction with the + You must use {{role}} in conjunction with the :option:`--install` option. For descriptions that contain spaces, you must enclose the @@ -72,7 +72,7 @@ description: | Runs the {{program}} service in the context of a certain user. This user must have "Log on as a service" privileges. - You must use :option:`--serviceUser` in conjunction with the + You must use {{role}} in conjunction with the :option:`--install` option. optional: true @@ -85,7 +85,7 @@ description: | Sets the password for ```` for {{program}} when running with the :option:`--serviceUser` option. - You must use :option:`--servicePassword` in conjunction with the + You must use {{role}} in conjunction with the :option:`--install` option. optional: true ... diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 7334c2706fd..f3007f06d22 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -1,7 +1,9 @@ -# This file borrows content from: /includes/options-shared.yaml -# which uses {{program}} to refer to the tool. +# This file borrows content from: /includes/options-shared.yaml which uses +# {{program}} to refer to the tool. # -# This file lends content to: /includes/options-mongos.yaml +# This file lends content to: +# /includes/options-mongos.yaml +# /includes/options-conf.yaml # program: mongod name: help @@ -20,8 +22,8 @@ inherit: program: mongod name: config aliases: -f -directive: option args: +directive: option description: | Specifies a configuration file for runtime configuration options. The configuration file is the preferred method for runtime configuration of @@ -29,8 +31,9 @@ description: | 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. The {{program}} + instance does not support configuration files with non-ASCII encoding, + including UTF-8. optional: true --- program: mongod @@ -56,12 +59,12 @@ inherit: --- program: mongod name: bind_ip -directive: option args: +default: All interfaces +directive: option description: | - 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 + Specifies the IP address that {{program}} binds to in order to listen + for connections from applications. 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. @@ -69,13 +72,12 @@ optional: true --- program: mongod name: maxConns -directive: option args: +directive: option 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. + 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.6 MongoDB removed the upward limit on the :setting:`maxConns` setting. @@ -83,25 +85,25 @@ optional: true --- program: mongod name: objcheck -directive: option args: null +directive: option 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 + database. For objects with a high degree of sub-document nesting, the + {{role}} option can have a small impact on performance. You can set :option:`--noobjcheck` to disable object checking at runtime. .. versionchanged:: 2.4 - MongoDB enables :option:`--objcheck` by default, to prevent any - client from inserting malformed or invalid BSON into a MongoDB + MongoDB enables the {{role}} option by default in order to prevent + any client from inserting malformed or invalid BSON into a MongoDB database. optional: true --- program: mongod name: noobjcheck -directive: option args: null +directive: option description: | .. versionadded:: 2.4 @@ -111,39 +113,35 @@ optional: true --- program: mongod name: logpath -directive: option args: +directive: option description: | - Specifies the path for the log file that holds all diagnostic - logging information. + Sends all diagnostic logging information to a log file instead of to + standard output or to the host's :term:`syslog` system. MongoDB creates + the log file at the path you specify. - 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. + By default, MongoDB overwrites the log file when the process restarts. + To instead append to the log file, set the :option:`--logappend` option. +# todo:: Is the above still true about overwriting? optional: true --- program: mongod name: logappend -directive: option args: null +directive: option description: | - Appends new entries to the end of the logfile when the {{program}} restarts - instead of overwriting the content of the log. + Appends new entries to the end of the log file rather than overwriting + the content of the log when the {{program}} instance restarts. optional: true --- program: mongod name: timeStampFormat -directive: option args: +default: iso8601-local +directive: option description: | - Specifies the time format for timestamps in log messages. Specify one of - the following values: + The time format for timestamps in log messages. Specify one of the + following values: .. list-table:: :header-rows: 1 @@ -166,51 +164,49 @@ description: | * - ``iso8601-local`` - - Default value. Displays timestamps in local time in the ISO-8601 + - Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: ``1969-12-31T19:00:00.000+0500`` - optional: true --- program: mongod name: syslog -directive: option args: null +directive: option 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`. + than to standard output or to a log file. , as with :option:`--logpath`. - :option:`--syslog` is not supported on Windows. + The {{role}} option is not supported on Windows. optional: true --- program: mongod name: syslogFacility -directive: option args: +default: user +directive: option description: | - Specifies the facility level used when logging messages to syslog. The - default is ``user``. The value you specify must be supported by your + Specifies the facility level used when logging messages to syslog. + The value you specify must be supported by your operating system's implementation of syslog. To use this option, you must enable the :option:`--syslog` option. optional: true --- program: mongod name: pidfilepath -directive: option args: +directive: option description: | - 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:`--fork` option. - - Without a specified :option:`--pidfilepath` option, {{program}} - creates no PID file. + Specifies a file location to hold the process ID of the {{program}} + process. This is useful for tracking the {{program}} process in + combination with the :option:`--fork` option. Without a specified + {{role}} option, the process creates no PID file. optional: true --- program: mongod name: keyFile -directive: option args: +directive: option description: | Specifies the path to a key file to store authentication information. This option is used for interprocess authentication among @@ -220,13 +216,17 @@ optional: true --- program: mongod name: nounixsocket -directive: option args: null +directive: option 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``. + Disables listening on the UNIX domain socket. The {{program}} process + always listens on the UNIX socket unless one of the following is true: + + - {{role}} is set + + - :setting:`bind_ip` is not set + + - :setting:`bind_ip` does not specify ``127.0.0.1`` .. |mongodb-package| replace:: {{program}} @@ -235,35 +235,43 @@ optional: true --- program: mongod name: unixSocketPrefix -directive: option args: +default: /tmp +directive: option description: | - Specifies a path for the UNIX socket. If this option has no - value, {{program}} creates a socket with ``/tmp`` as a prefix. + The path for the UNIX socket. If this option has no value, the + {{program}} process creates a socket with ``/tmp`` as a prefix. MongoDB + creates and listens on a UNIX socket unless one of the following is true: - 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``. + - :option:`--nounixsocket` is set + + - :setting:`bind_ip` is not set + + -:setting:`bind_ip` does not specify ``127.0.0.1`` optional: true --- program: mongod name: fork -directive: option args: null +directive: option description: | - Enables a :term:`daemon` mode for {{program}} that runs the - process in the background. This is the normal mode of operation in - production and production-like environments but may not be - desirable for testing. + Enables a :term:`daemon` that runs the {{program}} process in 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 +# The description for this option (auth) applies specifically to the command +# line. The equivalent option in the config file (security.authentication) +# takes string values, which this option does not do. args: null +directive: option description: | - Enables database authentication for users connecting from remote - hosts. Configure users via the :doc:`mongo shell + Requires 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. @@ -274,61 +282,77 @@ optional: true --- program: mongod name: cpu -directive: option +# beginning in 2.6, cpu is command-line only args: null +directive: option 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. + Forces the {{program}} process to report the percentage of CPU time in + write lock. The process generates output every four seconds and writes + the data to standard output or, if you are using the :setting:`logpath` + option, to the log file. optional: true --- program: mongod name: dbpath -directive: option args: +default: | + ``/data/db`` on Linux and OS X, ``\data\db`` on Windows +directive: option 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 {{role}}. + The directory where the {{program}} instance stores its data. If you + installed MongoDB using a package management system, check the + ``/etc/mongodb.conf`` file provided by your packages to see which + directory is specified. optional: true --- program: mongod name: diaglog -directive: option args: +default: 0 +directive: option description: | .. deprecated:: 2.6 - :option:`--diaglog` is for internal use and not intended for most users. + {{role}} is for internal use and not intended for most users. - Creates a very verbose, :term:`diagnostic log` for troubleshooting and + 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. + The specified value configures the level of verbosity: + + .. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Value + + - Setting + + * - 0 + + - Off. No logging. + + * - 1 + + - Log write operations. + + * - 2 + + - Log read operations. + + * - 3 - ========= =================================== - **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. - ========= =================================== + - 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 + 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: @@ -336,18 +360,25 @@ description: | mongosniff --source DIAGLOG /data/db/diaglog.4f76a58c - .. include:: /includes/warning-diaglogging-off.rst + .. warning:: + + Setting the diagnostic level to ``0`` will cause :program:`mongod` + to stop writing data to the :term:`diagnostic log` file. However, + the :program:`mongod` instance will continue to keep the file open, + even if it is no longer writing data to the file. If you want to + rename, move, or delete the diagnostic log you must cleanly shut + down the :program:`mongod` instance before doing so. optional: true --- program: mongod name: directoryperdb -directive: option args: null +directive: option 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. + Stores each database's files in its own folder in the :term:`data + directory`. When applied to an existing system, the + :setting:`directoryperdb` option alters the storage pattern of the data + directory. Use this option in conjunction with your file system and device configuration so that MongoDB will store data on a number of distinct @@ -355,24 +386,49 @@ description: | .. warning:: - .. |directoryperdb-option-name| replace:: :option:`--directoryperdb` - .. include:: /includes/fact-directory-per-db-requires-migration.rst + To enable this option for an **existing** system, migrate the + database-specific data files to the new directory structure before + enabling :setting:`directoryperdb`. Database-specific data files + begin with the name of an existing database and end with either + "``ns``" or a number. For example, the following data directory + includes files for the ``local`` and ``test`` databases: + + .. code-block:: none + + journal + mongod.lock + local.0 + local.1 + local.ns + test.0 + test.1 + test.ns + + After migration, the data directory would have the following structure: + + .. code-block:: none + + journal + mongod.lock + local/local.0 + local/local.1 + local/local.ns + test/test.0 + test/test.1 + test/test.ns 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 +inherit: + name: journal + program: _shared + file: options-shared.yaml --- program: mongod name: journalOptions -directive: option args: +directive: option description: | Provides functionality for testing. Not for general use, and will affect data file integrity in the case of abnormal system shutdown. @@ -380,16 +436,26 @@ optional: true --- program: mongod name: journalCommitInterval -directive: option args: +default: 100 or 30 +directive: option 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. + The maximum amount of time the {{program}} process allows between + journal operations. Values can range from 2 to 300 milliseconds. Lower + values increase the durability of the journal, at the expense of disk + performance. + + The default journal commit interval is 100 milliseconds if a single + block device (e.g. physical volume, RAID device, or LVM volume) contains + both the journal and the data files. + + If the journal is on a different block device than the data files the + default journal commit interval is 30 milliseconds. - .. include:: /includes/fact-journal-commit-interval-length.rst - .. include:: /includes/fact-journal-commit-interval-with-gle.rst + To force :program:`mongod` to commit to the journal more frequently, you + can specify ``j:true``. When a write operation with ``j:true`` is + pending, :program:`mongod` will reduce :setting:`journalCommitInterval` + to a third of the set value. optional: true --- program: mongod @@ -401,21 +467,19 @@ inherit: --- program: mongod name: jsonp -directive: option args: null +directive: option 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` + Permits :term:`JSONP` access via an HTTP interface. Enabling the + interface can increase network exposure. The {{role}} option enables the + HTTP interface, even if the :setting:`HTTP interface ` + option is disabled. optional: true --- program: mongod name: noauth -directive: option args: null +directive: option description: | Disables authentication. Currently the default. Exists for future compatibility and clarity. @@ -423,8 +487,8 @@ optional: true --- program: mongod name: nohttpinterface -directive: option args: null +directive: option description: | .. deprecated:: 2.6 MongoDB disables the HTTP interface by default. @@ -438,8 +502,8 @@ optional: true --- program: mongod name: httpinterface -directive: option args: null +directive: option description: | .. versionadded:: 2.6 @@ -455,24 +519,63 @@ optional: true --- program: mongod name: clusterAuthMode -inherit: - name: clusterAuthMode - program: mongos - file: options-mongos.yaml +args: