From c7d483f20030f4d8a60cf56585d3f4053d615365 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 1 Feb 2013 12:49:53 -0500 Subject: [PATCH 1/2] DOCS-1055 snmp --- source/administration.txt | 1 + source/administration/snmp.txt | 184 +++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 source/administration/snmp.txt 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..56c445a8abd --- /dev/null +++ b/source/administration/snmp.txt @@ -0,0 +1,184 @@ +.. include:: header.tmpl + +================================== +MongoDB SNMP Support Documentation +================================== + +This document outlines the use and operation of MongoDB's SNMP +extension, which is is only available in the `MongoDB Subscriber Edition +`_ +(https://www.10gen.com/mongodb-subscriber-edition-download). + +MongoDB Installation +-------------------- + +The MongoDB Subscriber Edition (including SSL and SNMP functionality) is +available on four platforms. See the page on the `subscriber edition +`_ for more +information. + +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 that resembles the + following to install these packages: :: + + 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``. + + .. ``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`` + + Issue a command that resembles the following to + install these packages: :: + + 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: :: + + 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: :: + + sudo mkdir -p /usr/share/snmp/mibs + +Use the following command to create a symbolic link: :: + + 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: :: + + cp mongod.conf /etc/snmp/mongod.conf + +Replace ``[/path/to/mongodb/distribution/]`` with the path to your +``mongod.conf`` file. + +Start Up +-------- + +You can control the subscriber edition of MongoDB as any other +``mongod``, using default or custom or control scripts. + +Use the following command to view all SNMP options available in your +MongoDB: :: + + mongod --help | grep snmp + +The above command should return the following output: :: + + Module snmp options: + --snmp-subagent run snmp subagent + --snmp-master run snmp as master + +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: :: + + mkdir -p /var/log/mongodb/ /data/db/ + +Start the ``mongod`` instance with the following command: :: + + mongod --snmp-master --port 3001 --fork --dbpath /data/db/ --logpath /var/log/mongodb/1.log + +You may set all of these options in a `configuration file`_ at your +discretion. + +To check if ``mongod`` is running with SNMP support, issue the +following command: :: + + ps -ef | grep 'mongod --snmp' + +The command should return output that includes the following +line. This indicates that the proper ``mongod`` instance is running: :: + + systemuser 31415 10260 0 Jul13 pts/16 00:00:00 mongod --snmp-master --port 3001 # [...] + +.. _`configuration file`: http://docs.mongodb.org/manual/reference/configuration-options/ + +.. raw:: latex + + \newpage + +Troubleshooting +--------------- + +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: :: + + [SNMPAgent] warning: error starting SNMPAgent as master err:1 + +indicates that the ``mongod`` cannot read the +``/etc/snmp/mongod.conf`` file. + +Initial Testing +--------------- + +Check for the snmp agent process listening on port 1161 with the +following command: :: + + sudo lsof -i :1161 + +which return the following output: :: + + COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME + mongod 9238 sysadmin 10u IPv4 96469 0t0 UDP localhost:health-polling + +Similarly, the next command: :: + + netstat -an | grep 1161 + +should return the following output: :: + + 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 ``mongod`` using +SNMP: :: + + 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: :: + + snmpwalk -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. From 9c6dbb56581e73d9395dcb93822d4c760654dba2 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 1 Feb 2013 15:00:43 -0500 Subject: [PATCH 2/2] DOCS-1055 snmp edits --- source/administration/snmp.txt | 198 +++++++++++++++++++-------------- 1 file changed, 113 insertions(+), 85 deletions(-) diff --git a/source/administration/snmp.txt b/source/administration/snmp.txt index 56c445a8abd..f4666aac078 100644 --- a/source/administration/snmp.txt +++ b/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 -`_ -(https://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 -`_ for more -information. +available on four platforms. For more information, see `MongoDB +Subscriber Edition `_. 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 +`. -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