From 159496e4143084ad7a4fef2d3469d96c6b00f348 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 17 Dec 2012 22:45:05 -0500 Subject: [PATCH 1/3] DOCS-692 start and stop mongod --- source/administration/process-management.txt | 186 +++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 source/administration/process-management.txt diff --git a/source/administration/process-management.txt b/source/administration/process-management.txt new file mode 100644 index 00000000000..edf62754e3f --- /dev/null +++ b/source/administration/process-management.txt @@ -0,0 +1,186 @@ +====================== +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. +Fora list of options, see :doc:`/reference/mongod`. MongoDB can also run +as a Windows service. For details, see +:ref:`tutorial-mongod-as-windows-service`. + +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 +~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the directory where MongoDB stores data files, you must +create the directory and set its permissions appropriately. MongoDB does +not create the directory if the directory does not exist. + +You then use the ``--dbpath`` option when starting MongoDB. 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 several :program:`mongod` processes on a single machine, you +must assign each a different port. Only one can listen on the default +port of ``27017``. + +To specify the port that MongoDB listens on for client connections, use +the ``--port`` option. The following command starts :program:`mongod` +listening on port ``12345``: + +.. code-block:: sh + + mongod --port 12345 + +It is highly recommended that you use the default port number whenever +possible, to avoid any confusion. + +If you use the :option:`--configsvr ` or +:option:`--shardsvr ` options, those options select an +appropriate port number automatically. + +Run ``mongod`` as a Daemon +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To fork the :program:`mongod` process *and* redirect its output to a log +file, use the ``--fork`` and ``--logpath`` options. You must create the +log path directory ahead of time; however not 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``. The command also uses the +``--logappend`` option to ensure that :program:`mongod` appends new +entries to the end of the log file rather than overwriting the content +when the process restarts: + + --logappend +.. code-block:: sh + + mongod --fork --logpath /var/log/mongodb.log --logappend + +Stop ``mongod`` +--------------- + +If :program:`mongod` is running in the foreground, then to stop :program:`mongod` press ``Control+C``. +MongoDB does a clean exit when all ongoing operations are complete and flushes and closes all data files. + +Send shutdownServer() message from the mongo shell + +The shell can request that the server terminate. + +$ ./mongo +> use admin +> db.shutdownServer() + +This command only works from localhost or if one is authenticated. + +From a driver (where the helper function may not exist), one can run the +command + +{ "shutdown" : 1 } + +If this server is the primary in a replica set, it will go through the +following process (version 1.9.1+): + +Check how up-to-date the secondaries are +---------------------------------------- + +If no secondary within 10 seconds of the primary, return that we won't +shut down (optionally pass the timeoutSecs option 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, you can use ``force : true``: + +.. code-block:: javascript + + db.adminCommand({shutdown : 1, force : true}) + +You can also specify timeoutSecs : N, which will keep checking the +secondaries for N seconds if none are immediately up-to-date. If any of +the secondaries catch up within N seconds, the primary will shut down. +If no secondaries catch up, it will not shut down. + +.. code-block:: javascript + + db.adminCommand({shutdown : 1, timeoutSecs : 5}) + +or + +.. code-block:: javascript + + db.shutdownServer({timeoutSecs : 5}) + +This generates output similar to the following: + +.. code-block:: javascript + + { + "closest" : NumberLong(1307651781), + "difference" : NumberLong(1307651808), + "errmsg" : "no secondaries within 10 seconds of my optime", + "ok" : 0 + } + +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 a KILL signal kill -9 will probably cause damage if :program:`mongod` is +not running with Journaling. (Journaling is on by default for 64 bit +:program:`mongod`.) See also: repairDatabase command.) + +After a hard crash, when not using --journal, MongoDB will say it was +not shutdown cleanly, and ask you to do a repair of the database. + +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. +Basically, the size of mapped data is shown in the virtual size +parameter, and 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. From 2797dc4b5ec0855c6cef3db8690a90c8e92385e1 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 18 Dec 2012 00:08:25 -0500 Subject: [PATCH 2/3] DOCS-692 first draft complete --- source/administration/process-management.txt | 171 ++++++++++--------- 1 file changed, 95 insertions(+), 76 deletions(-) diff --git a/source/administration/process-management.txt b/source/administration/process-management.txt index edf62754e3f..0452c2dc55f 100644 --- a/source/administration/process-management.txt +++ b/source/administration/process-management.txt @@ -8,7 +8,8 @@ MongoDB runs as a standard program. You can start MongoDB from a command line by issuing the :program:`mongod` command and specifying options. Fora list of options, see :doc:`/reference/mongod`. MongoDB can also run as a Windows service. For details, see -:ref:`tutorial-mongod-as-windows-service`. +: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 @@ -35,13 +36,13 @@ To start MongoDB in default mode, issue the following command: Specify a Data Directory ~~~~~~~~~~~~~~~~~~~~~~~~ -To specify the directory where MongoDB stores data files, you must -create the directory and set its permissions appropriately. MongoDB does -not create the directory if the directory does not exist. +When you specify a data directory, the directory must already exist. If +it does not, create it and set its permissions appropriately. -You then use the ``--dbpath`` option when starting MongoDB. The -following command starts :program:`mongod` and stores data in the -``/var/lib/mongodb/`` directory: +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 @@ -51,19 +52,17 @@ Specify a TCP Port ~~~~~~~~~~~~~~~~~~ If you run several :program:`mongod` processes on a single machine, you -must assign each a different port. Only one can listen on the default -port of ``27017``. +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 that MongoDB listens on for client connections, use -the ``--port`` option. The following command starts :program:`mongod` -listening on port ``12345``: +To specify the port, use the ``--port`` option. The following command +starts :program:`mongod` listening on port ``12345``: .. code-block:: sh mongod --port 12345 -It is highly recommended that you use the default port number whenever -possible, to avoid any confusion. +Use the default port number whenever possible, to avoid any confusion. If you use the :option:`--configsvr ` or :option:`--shardsvr ` options, those options select an @@ -73,114 +72,134 @@ Run ``mongod`` as a Daemon ~~~~~~~~~~~~~~~~~~~~~~~~~~ To fork the :program:`mongod` process *and* redirect its output to a log -file, use the ``--fork`` and ``--logpath`` options. You must create the -log path directory ahead of time; however not the log file. MongoDB will -create the log file if it does not exist. +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``. The command also uses the -``--logappend`` option to ensure that :program:`mongod` appends new -entries to the end of the log file rather than overwriting the content -when the process restarts: +:option:`--logappend ` option to ensure that +:program:`mongod` appends new entries to the end of the log file rather +than overwriting the content when the process restarts: - --logappend .. code-block:: sh mongod --fork --logpath /var/log/mongodb.log --logappend +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`` --------------- -If :program:`mongod` is running in the foreground, then to stop :program:`mongod` press ``Control+C``. -MongoDB does a clean exit when all ongoing operations are complete and flushes and closes all data files. +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: -Send shutdownServer() message from the mongo shell + .. code-block:: javascript -The shell can request that the server terminate. + use admin + db.shutdownServer() -$ ./mongo -> use admin -> db.shutdownServer() +This command works only from ``localhost`` or if the user is +authenticated. -This command only works from localhost or if one is authenticated. +Alternately, you can shut down the :program:`mongod` instance: -From a driver (where the helper function may not exist), one can run the -command +- using the :option:`--shutdown` option -{ "shutdown" : 1 } +- from a driver using the :dbcommand:`shutdown`. For details, see the + :doc:`drivers documentation ` for your driver. -If this server is the primary in a replica set, it will go through the -following process (version 1.9.1+): +``mongod`` Shutdown and Replica Sets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Check how up-to-date the secondaries are ----------------------------------------- +If the :program:`mongod` is the :term:`primary` in a :term:`replica +set`, the :program:`mongod` will go through the following process: -If no secondary within 10 seconds of the primary, return that we won't -shut down (optionally pass the timeoutSecs option to wait for a -secondary to catch up. +1. Check how up-to-date the :term:`secondaries ` are. -If there is a secondary within 10 seconds of the primary, the primary -will step down and wait for the secondary to catch up. +#. 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. -After 60 seconds or once the secondary has caught up, the primary will -shut down. +#. 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, you can use ``force : true``: +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}) -You can also specify timeoutSecs : N, which will keep checking the -secondaries for N seconds if none are immediately up-to-date. If any of -the secondaries catch up within N seconds, the primary will shut down. -If no secondaries catch up, it will not shut down. +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}) -or +Alternately you can use the ``timeoutSecs`` argument with the +:method:`shutdownServer() ` method: .. code-block:: javascript db.shutdownServer({timeoutSecs : 5}) -This generates output similar to the following: - -.. code-block:: javascript - - { - "closest" : NumberLong(1307651781), - "difference" : NumberLong(1307651808), - "errmsg" : "no secondaries within 10 seconds of my optime", - "ok" : 0 - } - -Sending a Unix INT or TERM Signal +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. +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 a KILL signal kill -9 will probably cause damage if :program:`mongod` is -not running with Journaling. (Journaling is on by default for 64 bit -:program:`mongod`.) See also: repairDatabase command.) +Sending ``kill -9`` will probably cause damage if :program:`mongod` is +not running with :term:`journaling `. -After a hard crash, when not using --journal, MongoDB will say it was -not shutdown cleanly, and ask you to do a repair of the database. +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. -Basically, the size of mapped data is shown in the virtual size -parameter, and resident bytes shows how much data is being cached in -RAM. +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. +starting it fresh, with no connections, with an empty ``/data/db`` +directory and looking at the resident bytes. From fa9a82b434b7a42451c5ad313e8929c6135ff571 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 18 Dec 2012 10:48:59 -0500 Subject: [PATCH 3/3] DOCS-692 ready for merge --- source/administration/process-management.txt | 19 +++++++------------ source/administration/security.txt | 2 ++ 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/source/administration/process-management.txt b/source/administration/process-management.txt index 0452c2dc55f..3baf88b9d8e 100644 --- a/source/administration/process-management.txt +++ b/source/administration/process-management.txt @@ -6,7 +6,7 @@ Start and Stop MongoDB MongoDB runs as a standard program. You can start MongoDB from a command line by issuing the :program:`mongod` command and specifying options. -Fora list of options, see :doc:`/reference/mongod`. MongoDB can also run +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`. @@ -37,7 +37,9 @@ 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. +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 @@ -51,7 +53,7 @@ directory: Specify a TCP Port ~~~~~~~~~~~~~~~~~~ -If you run several :program:`mongod` processes on a single machine, you +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``. @@ -64,10 +66,6 @@ starts :program:`mongod` listening on port ``12345``: Use the default port number whenever possible, to avoid any confusion. -If you use the :option:`--configsvr ` or -:option:`--shardsvr ` options, those options select an -appropriate port number automatically. - Run ``mongod`` as a Daemon ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,14 +76,11 @@ 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``. The command also uses the -:option:`--logappend ` option to ensure that -:program:`mongod` appends new entries to the end of the log file rather -than overwriting the content when the process restarts: +output to ``/var/log/mongodb.log``. .. code-block:: sh - mongod --fork --logpath /var/log/mongodb.log --logappend + mongod --fork --logpath /var/log/mongodb.log Additional Configuration Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ----------