diff --git a/source/administration/process-management.txt b/source/administration/process-management.txt new file mode 100644 index 00000000000..3baf88b9d8e --- /dev/null +++ b/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 `. + +To specify a data directory when starting MongoDB, use the +:option:`--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 ` and :option:`--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() ` 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 ` 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 ` 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() ` 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 `. + +To recover data if MongoDB does not shut down cleanly and if +:term:`journaling ` 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. diff --git a/source/administration/security.txt b/source/administration/security.txt index 1cb519de245..fc13546713a 100644 --- a/source/administration/security.txt +++ b/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 ----------