DOCS-1055 snmp edits

Author: Bob Grabar

source/administration/snmp.txt

@@ -1,26 +1,29 @@
-.. include:: header.tmpl
+======================
+MongoDB SNMP Extension
+======================
 
-==================================
-MongoDB SNMP Support Documentation
-==================================
+.. versionadded:: 2.2
+
+.. admonition:: Subscriber Only Feature
+
+   This feature is only available in the Subscriber Edition of
+   MongoDB.
 
 This document outlines the use and operation of MongoDB's SNMP
 extension, which is is only available in the `MongoDB Subscriber Edition
-<http://www.10gen.com/mongodb-subscriber-edition-download>`_
-(https://www.10gen.com/mongodb-subscriber-edition-download).
+<http://www.10gen.com/mongodb-subscriber-edition-download>`_.
 
-MongoDB Installation
---------------------
+Install MongoDB Subscriber Edition
+----------------------------------
 
 The MongoDB Subscriber Edition (including SSL and SNMP functionality) is
-available on four platforms. See the page on the `subscriber edition
-<https://www.10gen.com/mongodb-subscriber-edition-download>`_ for more
-information.
+available on four platforms. For more information, see `MongoDB
+Subscriber Edition <http://www.10gen.com/mongodb-subscriber-edition-download>`_.
 
 Included Files
 --------------
 
-The subscriber edition contains the following files:
+The Subscriber Edition contains the following files:
 
 - ``MONGO-MIB.txt``:
 
@@ -31,138 +34,147 @@ The subscriber edition contains the following files:
 
   The SNMP configuration file for reading the SNMP output of
   MongoDB. The SNMP configures the community names, permissions,
-  access controls etc.
+  access controls, etc.
 
 Required Packages
 -----------------
 
 To use SNMP, you must install several prerequisites. The names of the
-pacakges vary by distribution, and are as follows:
+pacakges vary by distribution and are as follows:
 
-- *Ubuntu 11.04* requires ``libssl0.9.8``, ``snmp-mibs-downloader``,
-  ``snmp``, and ``snmpd``. Issue a command that resembles the
-  following to install these packages: ::
+- Ubuntu 11.04 requires ``libssl0.9.8``, ``snmp-mibs-downloader``,
+  ``snmp``, and ``snmpd``. Issue a command such as the
+  following to install these packages:
 
-      sudo apt-get install libssl0.9.8 snmp snmpd snmp-mibs-downloader
+  .. code-block:: sh
 
-- *Red Hat Enterprise Linux 6.x series and Amazon Linux AMI* require:
-  ``libssl``, ``net-snmp``, ``net-snmp-libs``, and ``net-snmp-utils``.
+     sudo apt-get install libssl0.9.8 snmp snmpd snmp-mibs-downloader
 
-  .. ``libssl.so.10``, ``net-snmp-5.5-37.9.amzn1.x86_64``, ``net-snmp-libs-5.5-37.9.amzn1.x86_64``
-     ``net-snmp-utils-5.5-37.9.amzn1.x86_64``
+- Red Hat Enterprise Linux 6.x series and Amazon Linux AMI require
+  ``libssl``, ``net-snmp``, ``net-snmp-libs``, and ``net-snmp-utils``.
+  Issue a command such as the following to install these packages:
 
-  Issue a command that resembles the following to
-  install these packages: ::
+  .. code-block:: sh
 
-      sudo yum install libssl net-snmp net-snmp-libs net-snmp-utils
+     sudo yum install libssl net-snmp net-snmp-libs net-snmp-utils
 
 - SUSE Enterprise Linux requires ``libopenssl0_9_8``, ``libsnmp15``,
-  ``slessp1-libsnmp15``, and ``snmp-mibs``. Issue a command that
-  resembles the following to install these packages: ::
+  ``slessp1-libsnmp15``, and ``snmp-mibs``. Issue a command such as the
+  following to install these packages:
 
-      sudo zypper install libopenssl0_9_8 libsnmp15 slessp1-libsnmp15 snmp-mibs
+  .. code-block:: sh
+
+     sudo zypper install libopenssl0_9_8 libsnmp15 slessp1-libsnmp15 snmp-mibs
 
 Install MIB Configuration Files
 -------------------------------
 
-Ensure that the MIB directory, at ``/usr/share/snmp/mibs`` exits, by
-issuing the following command: ::
+Ensure that the MIB directory, at ``/usr/share/snmp/mibs`` exists. If
+not, issue the following command:
+
+.. code-block:: sh
+
+   sudo mkdir -p /usr/share/snmp/mibs
 
-    sudo mkdir -p /usr/share/snmp/mibs
+Use the following command to create a symbolic link:
 
-Use the following command to create a symbolic link: ::
+.. code-block:: sh
 
-    sudo ln -s [/path/to/mongodb/distribution/]MONGO-MIB.txt /usr/share/snmp/mibs/
+   sudo ln -s [/path/to/mongodb/distribution/]MONGO-MIB.txt /usr/share/snmp/mibs/
 
 Replace ``[/path/to/mongodb/distribution/]`` with the path to your
 ``MONGO-MIB.txt`` configuration file.
 
-Finally the ``mongod.conf`` file into the ``/etc/snmp`` directory
-with the following command: ::
+Copy the ``mongod.conf`` file into the ``/etc/snmp`` directory
+with the following command:
 
-    cp mongod.conf /etc/snmp/mongod.conf
+.. code-block:: sh
 
-Replace ``[/path/to/mongodb/distribution/]`` with the path to your
-``mongod.conf`` file.
+   cp mongod.conf /etc/snmp/mongod.conf
 
 Start Up
 --------
 
-You can control the subscriber edition of MongoDB as any other
-``mongod``, using default or custom or control scripts.
+You can control the Subscriber Edition of MongoDB using default or
+custom or control scripts, just as you can any other :program:`mongod`:
 
 Use the following command to view all SNMP options available in your
-MongoDB: ::
+MongoDB:
 
-    mongod --help | grep snmp
+.. code-block:: sh
 
-The above command should return the following output: ::
+   mongod --help | grep snmp
 
-    Module snmp options:
-      --snmp-subagent       run snmp subagent
-      --snmp-master         run snmp as master
+The above command should return the following output:
 
-Ensure that the ``/data/db/`` (i.e. the path where MongoDB stores the
-data files.) and ``/var/log/mongodb/`` (i.e. the path where MongoDB
-writes the log output) exist, by issuing the following command: ::
+.. code-block:: sh
 
-    mkdir -p /var/log/mongodb/ /data/db/
+   Module snmp options:
+     --snmp-subagent       run snmp subagent
+     --snmp-master         run snmp as master
 
-Start the ``mongod`` instance with the following command: ::
+Ensure that the following directories exist:
 
-    mongod --snmp-master --port 3001 --fork --dbpath /data/db/  --logpath /var/log/mongodb/1.log
+- ``/data/db/`` (This is the path where MongoDB stores the data files.)
 
-You may set all of these options in a `configuration file`_ at your
-discretion.
+- ``/var/log/mongodb/`` (This is the path where MongoDB writes the log
+  output.)
 
-To check if ``mongod`` is running with SNMP support, issue the
-following command: ::
+If they do not, issue the following command:
 
-    ps -ef | grep 'mongod --snmp'
+.. code-block:: sh
 
-The command should return output that includes the following
-line. This indicates that the proper ``mongod`` instance is running: ::
+   mkdir -p /var/log/mongodb/ /data/db/
 
-    systemuser 31415 10260  0 Jul13 pts/16   00:00:00 mongod --snmp-master --port 3001 # [...]
+Start the :program:`mongod` instance with the following command:
 
-.. _`configuration file`: http://docs.mongodb.org/manual/reference/configuration-options/
+.. code-block:: sh
 
-.. raw:: latex
+   mongod --snmp-master --port 3001 --fork --dbpath /data/db/  --logpath /var/log/mongodb/1.log
 
-   \newpage
+Optionally, you can set these options in a :doc:`configuration file
+</reference/configuration-options>`.
 
-Troubleshooting
----------------
+To check if :program:`mongod` is running with SNMP support, issue the
+following command:
+
+.. code-block:: sh
 
-Always check the logs for errors if something doesn't run as
-expected, see the log at ``/var/log/mongodb/1.log``. The presence of
-the following line:  ::
+   ps -ef | grep 'mongod --snmp'
 
-    [SNMPAgent] warning: error starting SNMPAgent as master err:1
+The command should return output that includes the following
+line. This indicates that the proper :program:`mongod` instance is running:
+
+.. code-block:: sh
 
-indicates that the ``mongod`` cannot read the
-``/etc/snmp/mongod.conf`` file.
+   systemuser 31415 10260  0 Jul13 pts/16   00:00:00 mongod --snmp-master --port 3001 # [...]
 
-Initial Testing
+Test the Set Up
 ---------------
 
-Check for the snmp agent process listening on port 1161 with the
+Check for the snmp agent process listening on port ``1161`` with the
 following command: ::
 
     sudo lsof -i :1161
 
-which return the following output: ::
+which return the following output:
+
+.. code-block:: sh
+
+   COMMAND  PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
+   mongod  9238 sysadmin   10u  IPv4  96469      0t0  UDP localhost:health-polling
 
-    COMMAND  PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
-    mongod  9238 sysadmin   10u  IPv4  96469      0t0  UDP localhost:health-polling
+Similarly, this command:
 
-Similarly, the next command: ::
+.. code-block:: sh
 
-    netstat -an | grep 1161
+   netstat -an | grep 1161
 
-should return the following output: ::
+should return the following output:
 
-    udp        0      0 127.0.0.1:1161              0.0.0.0:*
+.. code-block:: sh
+
+   udp        0      0 127.0.0.1:1161              0.0.0.0:*
 
 Run ``snmpwalk`` Locally
 ------------------------
@@ -171,14 +183,30 @@ Run ``snmpwalk`` Locally
 according to the MIB. If you installed all of the required packages
 above, your system will have ``snmpwalk``.
 
-Issue the following command to collect data from ``mongod`` using
-SNMP: ::
+Issue the following command to collect data from :program:`mongod` using
+SNMP:
+
+.. code-block:: sh
+
+   snmpwalk -m MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601
 
-     snmpwalk -m MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601
+You may also choose to specify a the path to the MIB file:
 
-You may also choose to specify a the path to the MIB file: ::
+.. code-block:: sh
 
-     snmpwalk -m /usr/share/snmp/mibs/MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601
+   nmpwalk -m /usr/share/snmp/mibs/MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601
 
 Use this command *only* to ensure that you can retrieve and validate
 SNMP data from MongoDB.
+
+Troubleshooting
+---------------
+
+Always check the logs for errors if something does not run as expected,
+see the log at ``/var/log/mongodb/1.log``. The presence of the following
+line indicates that the :program:`mongod` cannot read the
+``/etc/snmp/mongod.conf`` file:
+
+.. code-block:: sh
+
+   [SNMPAgent] warning: error starting SNMPAgent as master err:1