From 20888316bd762fb605fe2185fbd46c9adf6ac781 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Tue, 16 Jun 2015 13:12:57 -0400 Subject: [PATCH] DOCS-5269: Advise caution when changing some config settings --- .../extracts-linux-config-expectations.yaml | 27 ++++++++++++ source/includes/options-conf.yaml | 42 +++++++++++-------- source/includes/options-mongod.yaml | 27 ++++++------ source/reference/configuration-options.txt | 12 ++++-- 4 files changed, 74 insertions(+), 34 deletions(-) create mode 100644 source/includes/extracts-linux-config-expectations.yaml diff --git a/source/includes/extracts-linux-config-expectations.yaml b/source/includes/extracts-linux-config-expectations.yaml new file mode 100644 index 00000000000..b6ede6c28ad --- /dev/null +++ b/source/includes/extracts-linux-config-expectations.yaml @@ -0,0 +1,27 @@ +ref: _linux-config-expectations +content: | + The Linux package init scripts do not expect {{option}} to change from the + defaults. If you use the Linux packages and change {{option}}, you will have + to use your own init scripts and disable the built-in scripts. +--- +ref: linux-config-expectations-systemlog-path +replacement: + option: ":setting:`systemLog.path`" +inherit: + ref: _linux-config-expectations + file: extracts-linux-config-expectations.yaml +--- +ref: linux-config-expectations-processmanagement-fork +replacement: + option: ":setting:`processManagement.fork`" +inherit: + ref: _linux-config-expectations + file: extracts-linux-config-expectations.yaml +--- +ref: linux-config-expectations-storage-dbpath +replacement: + option: ":setting:`storage.dbPath`" +inherit: + ref: _linux-config-expectations + file: extracts-linux-config-expectations.yaml +... diff --git a/source/includes/options-conf.yaml b/source/includes/options-conf.yaml index 3e3651b07f4..5d3a0776fc4 100644 --- a/source/includes/options-conf.yaml +++ b/source/includes/options-conf.yaml @@ -140,7 +140,7 @@ post: | If :setting:`systemLog.component.storage.journal.verbosity` is unset, :setting:`systemLog.component.storage.verbosity` level also applies to journaling components. - + .. include:: /includes/log-verbosity-levels.rst --- program: conf @@ -221,6 +221,8 @@ inherit: program: mongod name: logpath file: options-mongod.yaml +post: | + .. include:: /includes/extracts/linux-config-expectations-systemlog-path.rst --- program: conf name: systemLog.logAppend @@ -243,7 +245,7 @@ description: | The destination to which MongoDB sends all log output. Specify either ``file`` or ``syslog``. If you specify ``file``, you must also specify :setting:`systemLog.path`. - + If you do not specify :setting:`systemLog.destination`, MongoDB sends all log output to standard output. --- @@ -294,6 +296,8 @@ inherit: name: fork program: mongod file: options-mongod.yaml +post: | + .. include:: /includes/extracts/linux-config-expectations-processmanagement-fork.rst --- program: conf name: processManagement.windowsService.serviceName @@ -446,21 +450,21 @@ inherit: file: options-mongod.yaml post: | When {{role}} is ``true``, {{program}} listens on the UNIX socket. - + The {{program}} process always listens on the UNIX socket unless one of the following is true: - + - {{role}} is ``false`` - + - :option:`--nounixsocket` is set. The command line option takes precedence over the configuration file setting. - + - :setting:`net.bindIp` is not set - + - :setting:`net.bindIp` does not specify ``127.0.0.1`` - + .. |mongodb-package| replace:: {{program}} - + .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst --- program: conf @@ -827,7 +831,7 @@ description: | .. versionadded:: 2.6 Enable or disable localhost authentication bypass. - + Specify ``0`` to disable localhost authentication bypass. post: | The {{role}} setting is available only for :program:`mongod`. @@ -839,8 +843,8 @@ type: string directive: setting description: | Enable or disable backwards compatibility with the MongoDB 2.2 access control - roles. - + 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 @@ -957,6 +961,8 @@ inherit: file: options-mongod.yaml post: | The {{role}} setting is available only for :program:`mongod`. + + .. include:: /includes/extracts/linux-config-expectations-storage-dbpath.rst --- program: conf name: storage.directoryPerDB @@ -1164,7 +1170,7 @@ inherit: description: | The name of the replica set that the {{program}} is part of. All hosts in the replica set must have the same set name. - + .. include:: /includes/fact-unique-replica-set-names.rst post: | The {{role}} setting is available only for :program:`mongod`. @@ -1239,7 +1245,7 @@ inherit: file: options-mongod.yaml pre: | .. versionadded:: 2.6 - + When set, {{role}} enables :doc:`auditing ` and specifies where {{program}} sends all audit events. --- @@ -1332,8 +1338,8 @@ description: | Enables or disables the automatic splitting of chunks for :term:`sharded collections `. If {{role}} is ``false`` on all {{program}} instances, MongoDB does not create new chunks as the - data in a collection grows. - + data in a collection grows. + Because any {{program}} in a cluster can create a split, to totally disable splitting in a cluster, you must set {{role}} to ``false`` on all {{program}}. @@ -1497,8 +1503,8 @@ description: | specified hostname. .. include:: /includes/fact-ssl-supported.rst - + replacement: program: ":program:`mongod`" optional: true -... \ No newline at end of file +... diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 26205a6a5b3..4f5835d201e 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -130,8 +130,8 @@ description: | standard output or to the host's :term:`syslog` system. MongoDB creates the log file at the path you specify. - By default, MongoDB overwrites the log file when the process restarts. - To instead append to the log file, set the :option:`--logappend` option. + By default, MongoDB will move any existing log file rather than overwrite + it. To instead append to the log file, set the :option:`--logappend` option. optional: true --- program: mongod @@ -139,8 +139,9 @@ name: logappend args: null directive: option description: | - {{intro}} new entries to the end of the log file rather than overwriting - the content of the log when the {{program}} instance restarts. + {{intro}} new entries to the end of the existing log file when the {{program}} + instance restarts. Without this option, :program:`mongod` will back up the + existing log and create a new file. optional: true replacement: intro: "Appends" @@ -289,7 +290,7 @@ directive: option description: | The path for the UNIX socket. {{role}} applies only to Unix-based systems. - + 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: @@ -906,8 +907,8 @@ default: 60 directive: option description: | {{intro}} can pass before MongoDB flushes data to the data - files via an :term:`fsync` operation. - + files via an :term:`fsync` operation. + **Do not set this value on production systems.** In almost every situation, you should use the default setting. @@ -1041,8 +1042,8 @@ description: | {{intro}} :term:`secondary` members of a :term:`replica set` load into memory before applying operations from the oplog. By default secondaries load all indexes related to an operation into memory - before applying operations from the oplog. - + before applying operations from the oplog. + Set this {{directive}} to one of the following: .. list-table:: @@ -1350,8 +1351,8 @@ description: | .. versionadded:: 2.6 {{verb}} the validation checks for TLS/SSL certificates on other servers - in the cluster and allows the use of invalid certificates. - + in the cluster and allows the use of invalid certificates. + When using the {{role}} setting, MongoDB logs a warning regarding the use of the invalid certificate. @@ -1760,9 +1761,9 @@ default: "true" description: | .. versionadded:: 3.0.0 - + Enables or disables :term:`prefix compression` for index data. - + Specify ``true`` for {{role}} to enable :term:`prefix compression` for index data, or ``false`` to disable prefix compression for index data. diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index c9a8f1bf673..00c5e041df1 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -39,8 +39,9 @@ File Format MongoDB configuration files use the `YAML `_ format [#yaml-json]_. -The following example configuration file contains several -:program:`mongod` settings: + +The following sample configuration file contains several :program:`mongod` +settings that you may adapt to your local configuration: .. note:: @@ -50,7 +51,7 @@ The following example configuration file contains several systemLog: destination: file - path: "/var/log/mongodb/mongodb.log" + path: "/var/log/mongodb/mongod.log" logAppend: true storage: journal: @@ -64,6 +65,11 @@ The following example configuration file contains several enableLocalhostAuthBypass: false ... +The Linux package init scripts included in the official MongoDB packages depend +on specific values for :setting:`systemLog.path`, :setting:`storage.dbpath`, and +:setting:`processManagement.fork`. If you modify these settings in the default +configuration file, :program:`mongod` may not start. + .. [#yaml-json] YAML is a superset of :term:`JSON`. Use the Configuration File