diff --git a/source/administration.txt b/source/administration.txt index 632e8f63ba7..416f92d8c99 100644 --- a/source/administration.txt +++ b/source/administration.txt @@ -14,6 +14,7 @@ documentation in other sections including: :doc:`/sharding`, administration/configuration administration/journaling administration/ssl + administration/snmp administration/monitoring administration/import-export administration/backups diff --git a/source/administration/snmp.txt b/source/administration/snmp.txt new file mode 100644 index 00000000000..f4666aac078 --- /dev/null +++ b/source/administration/snmp.txt @@ -0,0 +1,212 @@ +====================== +MongoDB SNMP Extension +====================== + +.. 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 +`_. + +Install MongoDB Subscriber Edition +---------------------------------- + +The MongoDB Subscriber Edition (including SSL and SNMP functionality) is +available on four platforms. For more information, see `MongoDB +Subscriber Edition `_. + +Included Files +-------------- + +The Subscriber Edition contains the following files: + +- ``MONGO-MIB.txt``: + + The ``MIB`` file that describes the data (i.e. schema) for MongoDB's + SNMP output + +- ``mongod.conf``: + + The SNMP configuration file for reading the SNMP output of + MongoDB. The SNMP configures the community names, permissions, + 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: + +- Ubuntu 11.04 requires ``libssl0.9.8``, ``snmp-mibs-downloader``, + ``snmp``, and ``snmpd``. Issue a command such as the + following to install these packages: + + .. code-block:: sh + + sudo apt-get install libssl0.9.8 snmp snmpd snmp-mibs-downloader + +- 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: + + .. code-block:: sh + + 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 such as the + following to install these packages: + + .. 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`` exists. If +not, issue the following command: + +.. code-block:: sh + + sudo mkdir -p /usr/share/snmp/mibs + +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/ + +Replace ``[/path/to/mongodb/distribution/]`` with the path to your +``MONGO-MIB.txt`` configuration file. + +Copy the ``mongod.conf`` file into the ``/etc/snmp`` directory +with the following command: + +.. code-block:: sh + + cp mongod.conf /etc/snmp/mongod.conf + +Start Up +-------- + +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: + +.. code-block:: sh + + mongod --help | grep snmp + +The above command should return the following output: + +.. code-block:: sh + + Module snmp options: + --snmp-subagent run snmp subagent + --snmp-master run snmp as master + +Ensure that the following directories exist: + +- ``/data/db/`` (This is the path where MongoDB stores the data files.) + +- ``/var/log/mongodb/`` (This is the path where MongoDB writes the log + output.) + +If they do not, issue the following command: + +.. code-block:: sh + + mkdir -p /var/log/mongodb/ /data/db/ + +Start the :program:`mongod` instance with the following command: + +.. code-block:: sh + + mongod --snmp-master --port 3001 --fork --dbpath /data/db/ --logpath /var/log/mongodb/1.log + +Optionally, you can set these options in a :doc:`configuration file +`. + +To check if :program:`mongod` is running with SNMP support, issue the +following command: + +.. code-block:: sh + + ps -ef | grep 'mongod --snmp' + +The command should return output that includes the following +line. This indicates that the proper :program:`mongod` instance is running: + +.. code-block:: sh + + systemuser 31415 10260 0 Jul13 pts/16 00:00:00 mongod --snmp-master --port 3001 # [...] + +Test the Set Up +--------------- + +Check for the snmp agent process listening on port ``1161`` with the +following command: :: + + sudo lsof -i :1161 + +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 + +Similarly, this command: + +.. code-block:: sh + + netstat -an | grep 1161 + +should return the following output: + +.. code-block:: sh + + udp 0 0 127.0.0.1:1161 0.0.0.0:* + +Run ``snmpwalk`` Locally +------------------------ + +``snmpwalk`` provides tools for retrieving and parsing the SNMP data +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 :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 + +You may also choose to specify a the path to the MIB file: + +.. code-block:: sh + + 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