DOCS-5269: Advise caution when changing some config settings

Author: i80and

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
+...

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 </core/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 <sharding>`. 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
-...
+...

source/includes/options-mongod.yaml

@@ -130,17 +130,18 @@ 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
 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.
 

source/reference/configuration-options.txt

@@ -38,19 +38,20 @@ File Format
 .. versionchanged:: 2.6
 
 MongoDB configuration files use the `YAML <http://www.yaml.org>`_ format
-[#yaml-json]_.
-The following example configuration file contains several
+[#yaml-json]_. The following sample configuration file contains several
 :program:`mongod` settings:
 
 .. note::
 
    YAML does not accept tabs; use spaces instead.
 
+   Do not use this example without modifying it for your installation.
+
 .. code-block:: yaml
 
    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