|
| 1 | +====================== |
| 2 | +Start and Stop MongoDB |
| 3 | +====================== |
| 4 | + |
| 5 | +.. default-domain:: mongodb |
| 6 | + |
| 7 | +MongoDB runs as a standard program. You can start MongoDB from a command |
| 8 | +line by issuing the :program:`mongod` command and specifying options. |
| 9 | +For a list of options, see :doc:`/reference/mongod`. MongoDB can also run |
| 10 | +as a Windows service. For details, see |
| 11 | +:ref:`tutorial-mongod-as-windows-service`. To install MongoDB, see |
| 12 | +:doc:`/installation`. |
| 13 | + |
| 14 | +The following examples assume the directory containing the |
| 15 | +:program:`mongod` process is included in your system paths. The |
| 16 | +:program:`mongod` process is the primary database process that runs on |
| 17 | +an individual server. The sharding process is the :program:`mongos` |
| 18 | +process. The administrative shell is run by the :program:`mongo` |
| 19 | +process. |
| 20 | + |
| 21 | +This page discusses the :program:`mongod` process. |
| 22 | + |
| 23 | +Start ``mongod`` |
| 24 | +---------------- |
| 25 | + |
| 26 | +In default mode, MongoDB stores data in the ``/data/db`` directory. On |
| 27 | +Windows MongoDB stores data in ``C:\data\db``. On all platforms, MongoDB |
| 28 | +listens by default on port ``27017``. |
| 29 | + |
| 30 | +To start MongoDB in default mode, issue the following command: |
| 31 | + |
| 32 | +.. code-block:: sh |
| 33 | + |
| 34 | + mongod |
| 35 | + |
| 36 | +Specify a Data Directory |
| 37 | +~~~~~~~~~~~~~~~~~~~~~~~~ |
| 38 | + |
| 39 | +When you specify a data directory, the directory must already exist. If |
| 40 | +it does not, create it and set its permissions appropriately for access |
| 41 | +by :program:`mongod`. For more information on permissions, see the |
| 42 | +:ref:`security operations documentation <security-operations>`. |
| 43 | + |
| 44 | +To specify a data directory when starting MongoDB, use the |
| 45 | +:option:`--dbpath <mongod --dbpath>` option. The following command |
| 46 | +starts :program:`mongod` and stores data in the ``/var/lib/mongodb/`` |
| 47 | +directory: |
| 48 | + |
| 49 | +.. code-block:: sh |
| 50 | + |
| 51 | + mongod --dbpath /var/lib/mongodb/ |
| 52 | + |
| 53 | +Specify a TCP Port |
| 54 | +~~~~~~~~~~~~~~~~~~ |
| 55 | + |
| 56 | +If you run multiple :program:`mongod` processes on a single machine, you |
| 57 | +must assign each a different port to listen on for client connections. |
| 58 | +Only one can listen on the default port of ``27017``. |
| 59 | + |
| 60 | +To specify the port, use the ``--port`` option. The following command |
| 61 | +starts :program:`mongod` listening on port ``12345``: |
| 62 | + |
| 63 | +.. code-block:: sh |
| 64 | + |
| 65 | + mongod --port 12345 |
| 66 | + |
| 67 | +Use the default port number whenever possible, to avoid any confusion. |
| 68 | + |
| 69 | +Run ``mongod`` as a Daemon |
| 70 | +~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 71 | + |
| 72 | +To fork the :program:`mongod` process *and* redirect its output to a log |
| 73 | +file, use the :option:`--fork <mongod --fork>` and :option:`--logpath <mongod |
| 74 | +--logpath>` options. You must create the log directory ahead of time. |
| 75 | +However, you need not create the log file. MongoDB will create the log |
| 76 | +file if it does not exist. |
| 77 | + |
| 78 | +The following command runs :program:`mongod` as a daemon and records log |
| 79 | +output to ``/var/log/mongodb.log``. |
| 80 | + |
| 81 | +.. code-block:: sh |
| 82 | + |
| 83 | + mongod --fork --logpath /var/log/mongodb.log |
| 84 | + |
| 85 | +Additional Configuration Options |
| 86 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 87 | + |
| 88 | +For an overview of common configurations and examples of best-practice |
| 89 | +configurations for common use cases, see |
| 90 | +:doc:`/administration/configuration`. |
| 91 | + |
| 92 | +Stop ``mongod`` |
| 93 | +--------------- |
| 94 | + |
| 95 | +To stop a :program:`mongod` instance that is running in the foreground, |
| 96 | +press ``Control+C``. MongoDB stops when all ongoing operations are |
| 97 | +complete and does a clean exit, flushing and closing all data files. |
| 98 | + |
| 99 | +To stop a :program:`mongod` instance running in the background or foreground, |
| 100 | +issue the :method:`shutdownServer() <db.shutdownServer()>` method. Use the following sequence: |
| 101 | + |
| 102 | +1. To open the :program:`mongo` shell for a :program:`mongod` instance |
| 103 | + running on the default port of ``27017``, issue the following command: |
| 104 | + |
| 105 | + .. code-block:: sh |
| 106 | + |
| 107 | + mongo |
| 108 | + |
| 109 | +#. To switch to the ``admin`` database and shutdown the :program:`mongod` |
| 110 | + instance, issue the following commands: |
| 111 | + |
| 112 | + .. code-block:: javascript |
| 113 | + |
| 114 | + use admin |
| 115 | + db.shutdownServer() |
| 116 | + |
| 117 | +This command works only from ``localhost`` or if the user is |
| 118 | +authenticated. |
| 119 | + |
| 120 | +Alternately, you can shut down the :program:`mongod` instance: |
| 121 | + |
| 122 | +- using the :option:`--shutdown` option |
| 123 | + |
| 124 | +- from a driver using the :dbcommand:`shutdown`. For details, see the |
| 125 | + :doc:`drivers documentation </applications/drivers>` for your driver. |
| 126 | + |
| 127 | +``mongod`` Shutdown and Replica Sets |
| 128 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 129 | + |
| 130 | +If the :program:`mongod` is the :term:`primary` in a :term:`replica |
| 131 | +set`, the :program:`mongod` will go through the following process: |
| 132 | + |
| 133 | +1. Check how up-to-date the :term:`secondaries <secondary>` are. |
| 134 | + |
| 135 | +#. If no secondary is within 10 seconds of the primary, |
| 136 | + :program:`mongod` will return a message that it will not shut down. |
| 137 | + You can pass the the :dbcommand:`shutdown` command a ``timeoutSecs`` |
| 138 | + argument to wait for a secondary to catch up. |
| 139 | + |
| 140 | +#. If there is a secondary within 10 seconds of the primary, the primary |
| 141 | + will step down and wait for the secondary to catch up. |
| 142 | + |
| 143 | +#. After 60 seconds or once the secondary has caught up, the primary |
| 144 | + will shut down. |
| 145 | + |
| 146 | +If there is no up-to-date secondary and you want the primary to shut |
| 147 | +down, issue the :dbcommand:`shutdown` command with the ``force`` |
| 148 | +argument, as show in the following command: |
| 149 | + |
| 150 | +.. code-block:: javascript |
| 151 | + |
| 152 | + db.adminCommand({shutdown : 1, force : true}) |
| 153 | + |
| 154 | +To keep checking the secondaries for a specified number of seconds if |
| 155 | +none are immediately up-to-date, issue :dbcommand:`shutdown` with the |
| 156 | +``timeoutSecs`` argument. MongoDB will keep checking the secondaries for |
| 157 | +the specified number of seconds if none are immediately up-to-date. If |
| 158 | +any of the secondaries catch up within the allotted time, the primary |
| 159 | +will shut down. If no secondaries catch up, it will not shut down. |
| 160 | + |
| 161 | +The following command issues :dbcommand:`shutdown` with ``timeoutSecs`` |
| 162 | +set to ``5``: |
| 163 | + |
| 164 | +.. code-block:: javascript |
| 165 | + |
| 166 | + db.adminCommand({shutdown : 1, timeoutSecs : 5}) |
| 167 | + |
| 168 | +Alternately you can use the ``timeoutSecs`` argument with the |
| 169 | +:method:`shutdownServer() <db.shutdownServer()>` method: |
| 170 | + |
| 171 | +.. code-block:: javascript |
| 172 | + |
| 173 | + db.shutdownServer({timeoutSecs : 5}) |
| 174 | + |
| 175 | +Sending a UNIX INT or TERM Signal |
| 176 | +--------------------------------- |
| 177 | + |
| 178 | +You can cleanly stop :program:`mongod` using a SIGINT or SIGTERM signal |
| 179 | +on UNIX-like systems. Either ``^C``, ``kill -2 PID``, or ``kill -15 |
| 180 | +PID`` will work. |
| 181 | + |
| 182 | +Sending ``kill -9`` will probably cause damage if :program:`mongod` is |
| 183 | +not running with :term:`journaling <journal>`. |
| 184 | + |
| 185 | +To recover data if MongoDB does not shut down cleanly and if |
| 186 | +:term:`journaling <journal>` is disabled, see |
| 187 | +:doc:`/tutorial/recover-data-following-unexpected-shutdown`. |
| 188 | + |
| 189 | +Memory Usage |
| 190 | +------------ |
| 191 | + |
| 192 | +MongoDB uses memory-mapped files to access data, which results in large |
| 193 | +numbers being displayed in tools like ``top`` for the :program:`mongod` |
| 194 | +process. This is not a concern and is normal when using memory-mapped |
| 195 | +files. The size of mapped data is shown in the virtual size parameter. |
| 196 | +Resident bytes shows how much data is being cached in RAM. |
| 197 | + |
| 198 | +You can get a feel for the "inherent" memory footprint of MongoDB by |
| 199 | +starting it fresh, with no connections, with an empty ``/data/db`` |
| 200 | +directory and looking at the resident bytes. |
0 commit comments