merge: DOCS-692

Author: Sam Kleinman

source/administration/process-management.txt

@@ -0,0 +1,200 @@
+======================
+Start and Stop MongoDB
+======================
+
+.. default-domain:: mongodb
+
+MongoDB runs as a standard program. You can start MongoDB from a command
+line by issuing the :program:`mongod` command and specifying options.
+For a list of options, see :doc:`/reference/mongod`. MongoDB can also run
+as a Windows service. For details, see
+:ref:`tutorial-mongod-as-windows-service`. To install MongoDB, see
+:doc:`/installation`.
+
+The following examples assume the directory containing the
+:program:`mongod` process is included in your system paths. The
+:program:`mongod` process is the primary database process that runs on
+an individual server. The sharding process is the :program:`mongos`
+process. The administrative shell is run by the :program:`mongo`
+process.
+
+This page discusses the :program:`mongod` process.
+
+Start ``mongod``
+----------------
+
+In default mode, MongoDB stores data in the ``/data/db`` directory. On
+Windows MongoDB stores data in ``C:\data\db``. On all platforms, MongoDB
+listens by default on port ``27017``.
+
+To start MongoDB in default mode, issue the following command:
+
+.. code-block:: sh
+
+   mongod
+
+Specify a Data Directory
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you specify a data directory, the directory must already exist. If
+it does not, create it and set its permissions appropriately for access
+by :program:`mongod`. For more information on permissions, see the
+:ref:`security operations documentation <security-operations>`.
+
+To specify a data directory when starting MongoDB, use the
+:option:`--dbpath <mongod --dbpath>` option. The following command
+starts :program:`mongod` and stores data in the ``/var/lib/mongodb/``
+directory:
+
+.. code-block:: sh
+
+   mongod --dbpath /var/lib/mongodb/
+
+Specify a TCP Port
+~~~~~~~~~~~~~~~~~~
+
+If you run multiple :program:`mongod` processes on a single machine, you
+must assign each a different port to listen on for client connections.
+Only one can listen on the default port of ``27017``.
+
+To specify the port, use the ``--port`` option. The following command
+starts :program:`mongod` listening on port ``12345``:
+
+.. code-block:: sh
+
+   mongod --port 12345
+
+Use the default port number whenever possible, to avoid any confusion.
+
+Run ``mongod`` as a Daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To fork the :program:`mongod` process *and* redirect its output to a log
+file, use the :option:`--fork <mongod --fork>` and :option:`--logpath <mongod
+--logpath>` options. You must create the log directory ahead of time.
+However, you need not create the log file. MongoDB will create the log
+file if it does not exist.
+
+The following command runs :program:`mongod` as a daemon and records log
+output to ``/var/log/mongodb.log``.
+
+.. code-block:: sh
+
+   mongod --fork --logpath /var/log/mongodb.log
+
+Additional Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For an overview of common configurations and examples of best-practice
+configurations for common use cases, see
+:doc:`/administration/configuration`.
+
+Stop ``mongod``
+---------------
+
+To stop a :program:`mongod` instance that is running in the foreground,
+press ``Control+C``. MongoDB stops when all ongoing operations are
+complete and does a clean exit, flushing and closing all data files.
+
+To stop a :program:`mongod` instance running in the background or foreground,
+issue the :method:`shutdownServer() <db.shutdownServer()>` method. Use the following sequence:
+
+1. To open the :program:`mongo` shell for a :program:`mongod` instance
+   running on the default port of ``27017``, issue the following command:
+
+   .. code-block:: sh
+
+      mongo
+
+#. To switch to the ``admin`` database and shutdown the :program:`mongod`
+   instance, issue the following commands:
+
+   .. code-block:: javascript
+
+      use admin
+      db.shutdownServer()
+
+This command works only from ``localhost`` or if the user is
+authenticated.
+
+Alternately, you can shut down the :program:`mongod` instance:
+
+- using the :option:`--shutdown` option
+
+- from a driver using the :dbcommand:`shutdown`. For details, see the
+  :doc:`drivers documentation </applications/drivers>` for your driver.
+
+``mongod`` Shutdown and Replica Sets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the :program:`mongod` is the :term:`primary` in a :term:`replica
+set`, the :program:`mongod` will go through the following process:
+
+1. Check how up-to-date the :term:`secondaries <secondary>` are.
+
+#. If no secondary is within 10 seconds of the primary,
+   :program:`mongod` will return a message that it will not shut down.
+   You can pass the the :dbcommand:`shutdown` command a ``timeoutSecs``
+   argument to wait for a secondary to catch up.
+
+#. If there is a secondary within 10 seconds of the primary, the primary
+   will step down and wait for the secondary to catch up.
+
+#. After 60 seconds or once the secondary has caught up, the primary
+   will shut down.
+
+If there is no up-to-date secondary and you want the primary to shut
+down, issue the :dbcommand:`shutdown` command with the ``force``
+argument, as show in the following command:
+
+.. code-block:: javascript
+
+   db.adminCommand({shutdown : 1, force : true})
+
+To keep checking the secondaries for a specified number of seconds if
+none are immediately up-to-date, issue :dbcommand:`shutdown` with the
+``timeoutSecs`` argument. MongoDB will keep checking the secondaries for
+the specified number of seconds if none are immediately up-to-date. If
+any of the secondaries catch up within the allotted time, the primary
+will shut down. If no secondaries catch up, it will not shut down.
+
+The following command issues :dbcommand:`shutdown` with ``timeoutSecs``
+set to ``5``:
+
+.. code-block:: javascript
+
+   db.adminCommand({shutdown : 1, timeoutSecs : 5})
+
+Alternately you can use the ``timeoutSecs`` argument with the
+:method:`shutdownServer() <db.shutdownServer()>` method:
+
+.. code-block:: javascript
+
+   db.shutdownServer({timeoutSecs : 5})
+
+Sending a UNIX INT or TERM Signal
+---------------------------------
+
+You can cleanly stop :program:`mongod` using a SIGINT or SIGTERM signal
+on UNIX-like systems. Either ``^C``, ``kill -2 PID``, or ``kill -15
+PID`` will work.
+
+Sending ``kill -9`` will probably cause damage if :program:`mongod` is
+not running with :term:`journaling <journal>`.
+
+To recover data if MongoDB does not shut down cleanly and if
+:term:`journaling <journal>` is disabled, see
+:doc:`/tutorial/recover-data-following-unexpected-shutdown`.
+
+Memory Usage
+------------
+
+MongoDB uses memory-mapped files to access data, which results in large
+numbers being displayed in tools like ``top`` for the :program:`mongod`
+process. This is not a concern and is normal when using memory-mapped
+files. The size of mapped data is shown in the virtual size parameter.
+Resident bytes shows how much data is being cached in RAM.
+
+You can get a feel for the "inherent" memory footprint of MongoDB by
+starting it fresh, with no connections, with an empty ``/data/db``
+directory and looking at the resident bytes.

source/administration/security.txt

@@ -226,6 +226,8 @@ clients. Furthermore, because VPNs provide a secure tunnel, using a
 VPN connection to control access to your MongoDB instance, you can
 prevent tampering and "man-in-the-middle" attacks.
 
+.. _security-operations:
+
 Operations
 ----------