From 4fedb93868555f54de89762a894548e59c6c7357 Mon Sep 17 00:00:00 2001
From: Michael Paik <michael.paik@10gen.com>
Date: Mon, 8 Sep 2014 15:53:07 -0400
Subject: [PATCH] DOCS-3953 - ulimit clarification and other options for
 upstart and systemd

---
 source/reference/ulimit.txt | 110 +++++++++++++++++++++++++++++-------
 1 file changed, 91 insertions(+), 19 deletions(-)

diff --git a/source/reference/ulimit.txt b/source/reference/ulimit.txt
index f071d2334b2..b63603f3d4d 100644
--- a/source/reference/ulimit.txt
+++ b/source/reference/ulimit.txt
@@ -73,7 +73,6 @@ For :program:`mongos`, consider the following behaviors:
 
 - You can limit the number of incoming connections using
   the :setting:`~net.maxIncomingConnections` run-time option.
-
   By restricting the number of incoming connections you can prevent a
   cascade effect where the :program:`mongos` creates too many
   connections on the :program:`mongod` instances.
@@ -101,6 +100,10 @@ Review and Set Resource Limits
    grows too high. For this reason, it is extremely important to set
    *both* ``ulimit`` values to the recommended values.
 
+   ``ulimit`` will modify both "hard" and "soft" values unless the
+   :setting:`-H` or :setting:`-S` modifiers are specified when
+   modifying limit values.
+
 You can use the ``ulimit`` command at the system prompt to check
 system limits, as in the following example:
 
@@ -157,6 +160,90 @@ system limits on running systems.
    system a system restart. Check your distribution and operating
    system documentation for more information.
 
+Recommended ``ulimit`` Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every deployment may have unique requirements and settings; however,
+the following thresholds and settings are particularly important for
+:program:`mongod` and :program:`mongos` deployments:
+
+- ``-f`` (file size): ``unlimited``
+- ``-t`` (cpu time): ``unlimited``
+- ``-v`` (virtual memory): ``unlimited`` [#memory-size]_
+- ``-n`` (open files): ``64000``
+- ``-m`` (memory size): ``unlimited`` [#memory-size]_ [#rss-linux]_
+- ``-u`` (processes/threads): ``64000``
+
+Always remember to restart your :program:`mongod` and
+:program:`mongos` instances after changing the ``ulimit`` settings to
+ensure that the changes take effect.
+
+Linux distributions using Upstart
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For Linux distributions that use Upstart, you can specify
+limits within service scripts if you start :program:`mongod` and/or :program:`mongos`
+instances as Upstart services. You can do this by using ``limit``
+`stanzas <http://upstart.ubuntu.com/wiki/Stanzas#limit>`_.
+
+The appropriate resources to specify are, e.g. using the recommended values specified
+above:
+
+.. code-block:: sh
+
+   limit fsize unlimited unlimited  # (file size)
+   limit cpu unlimited unlimited    # (cpu time)
+   limit as unlimited unlimited     # (virtual memory size)
+   limit nofile 64000 64000         # (open files)
+   limit nproc 64000 64000          # (processes/threads)
+
+Each ``limit`` stanza sets the "soft" limit to the first value specified and the "hard"
+limit to the second.
+
+Restart the applicable service using
+
+.. code-block:: sh
+
+   restart <service name>
+
+after changing ``limit`` stanzas to ensure that the changes take effect.
+
+Linux distributions using ``systemd``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For Linux distributions that use ``systemd``, you can specify
+limits within the ``[Service]`` sections of service scripts if you start `mongod` and/or
+`mongos` instances as ``systemd`` services. You can do this by using `resource limit
+directives
+<http://www.freedesktop.org/software/systemd/man/systemd.exec.html#LimitCPU=>`_.
+
+The appropriate directives to specify are, e.g. using the recommended values specified
+above:
+
+.. code-block:: sh
+
+   [Service]
+   # Other directives omitted
+   # (file size)
+   LimitFSIZE=infinity
+   # (cpu time)
+   LimitCPU=infinity
+   # (virtual memory size)
+   LimitAS=infinity
+   # (open files)
+   LimitNOFILE=64000
+   # (processes/threads)
+   LimitNPROC=64000
+
+Each ``systemd`` limit directive sets both the "hard" and "soft" limits to the value
+specified.
+
+Restart the applicable service using
+
+.. code-block:: sh
+
+   systemctl restart <service name>
+
+after changing limit directives to ensure that the changes take effect.
+
 .. _proc-file-system:
 
 ``/proc`` File System
@@ -202,24 +289,9 @@ invocations:
    return-limits mongos
    return-limits mongod mongos
 
-Recommended Settings
---------------------
-
-Every deployment may have unique requirements and settings; however,
-the following thresholds and settings are particularly important for
-:program:`mongod` and :program:`mongos` deployments:
-
-- ``-f`` (file size): ``unlimited``
-- ``-t`` (cpu time): ``unlimited``
-- ``-v`` (virtual memory): ``unlimited`` [#memory-size]_
-- ``-n`` (open files): ``64000``
-- ``-m`` (memory size): ``unlimited`` [#memory-size]_
-- ``-u`` (processes/threads): ``64000``
-
-Always remember to restart your :program:`mongod` and
-:program:`mongos` instances after changing the ``ulimit`` settings to
-make sure that the settings change takes effect.
-
 .. [#memory-size] If you limit virtual or resident memory size on a
    system running MongoDB the operating system will refuse to honor
    additional allocation requests.
+
+.. [#rss-linux] The ``-m`` parameter to ``ulimit`` has no effect on Linux systems with
+   kernel versions more recent than 2.4.30 and can be safely omitted.