DOCS-11052: Improve Monitor MongoDB with SNMP on Linux page

source/includes/steps-monitor-with-snmp.yaml

@@ -2,31 +2,83 @@ title: Copy configuration files.
 stepnum: 1
 ref: copy-config-files
 pre: |
-  Use the following sequence of commands to move the SNMP
-  configuration files to the SNMP service configuration directory.
+  Create the SNMP configuration directory if needed, then copy the
+  configuration files from the |mongod-program| installation directory to the
+  SNMP service configuration directory.
 
-  First, create the SNMP configuration directory if needed and then, from
-  the installation directory, copy the configuration files to the SNMP
-  service configuration directory:
+  MongoDB uses the configuration in ``/etc/snmp/mongod.conf`` when running in
+  sub-agent mode.
 action:
   language: sh
   code: |
     mkdir -p /etc/snmp/
     cp MONGOD-MIB.txt /usr/share/snmp/mibs/MONGOD-MIB.txt
     cp mongod.conf.subagent /etc/snmp/mongod.conf
   post: |
-    The configuration filename is tool-dependent. For example, when
-    using ``net-snmp`` the configuration file is ``snmpd.conf``.
-
     By default SNMP uses UNIX domain for communication between the
-    agent (i.e. ``snmpd`` or the master) and sub-agent (i.e. MongoDB).
+    agent (``snmpd`` or the master) and sub-agent (MongoDB).
+---
+title: Set permissions.
+stepnum: 2
+ref: snmp-permissions
+pre: |
+  In the ``Access Control`` section of the master configuration file, permit
+  access to the SNMP tree.
+
+  The configuration file for the SNMP daemon running as master may vary
+  depending on the tool. For example, ``net-snmp`` uses
+  ``/etc/snmp/snmpd.conf``.
+
+  .. important::
+
+     These steps for configuring ``snmpd`` as a master are given as an example
+     only. While MongoDB support can provide guidance on configuring MongoDB
+     for SNMP, configuring SNMP on operating systems is out of scope.
+action:
+  language: sh
+  code: |
+    # sec.name          source         community
+      com2sec local     localhost       mongodb
+
+    # group.name        sec.model  sec.name
+      group MyRWGroup   any        local
+
+    # incl/excl   subtree            mask
+      view all    included  .1       80
+
+    # context               sec.model sec.level prefix read   write  notif
+      access MyRWGroup ""   any       noauth    0      all    all    all
 post: |
-  Ensure that the ``agentXAddress`` specified in the SNMP
-  configuration file for MongoDB matches the ``agentXAddress`` in the
-  SNMP master configuration file.
+  These settings:
+
+  - map all connections to localhost to the security name ``local``
+  - map all secure accesses using any protocol to the group ``MyRWGroup``
+  - allow the view ``all`` to access the entire SNMP tree
+  - create an ACL that maps the ``all`` view to the group ``MyRWGroup``
+---
+title: Configure AgentX.
+stepnum: 3
+ref: agentx-config
+pre: |
+  In the master configuration file, ensure that the ``master agentX`` mode is
+  enabled. Set the ``AgentXSocket`` path to match the one configured in
+  ``/etc/snmp/mongod.conf``, and give it the required permissions:
+action:
+  language: sh
+  code: |
+    master agentx
+
+    AgentXSocket /tmp/agentx/master
+
+    AgentXPerms 0777 0777 mongod mongod
+post:
+  Note that ``mongod`` is the |mongod-program| user on some Linux
+  distributions (for example RHEL and SUSE), while others (for example Ubuntu
+  and Debian) use ``mongodb``. If the ``mongod/mongodb`` user cannot access the
+  ``/var/agentx/master`` file, run ``chmod 755 /var/agentx``.
 ---
 title: Start MongoDB.
-stepnum: 2
+stepnum: 4
 ref: start-with-snmp
 pre: |
   Start |mongod-program| with the :setting:`snmp-subagent` to send data
@@ -36,23 +88,21 @@ action:
   code: mongod --snmp-subagent
 ---
 title: Confirm SNMP data retrieval.
-stepnum: 3
+stepnum: 5
 ref: test-snmp
 pre: |
-  Use ``snmpwalk`` to collect data from |mongod-program|:
-
   Connect an SNMP client to verify the ability to collect SNMP data
-  from MongoDB.
+  from |mongod-program|.
 
-  Install the `net-snmp <http://www.net-snmp.org/>`_ package to access
-  the ``snmpwalk`` client. ``net-snmp`` provides the ``snmpwalk``
-  SNMP client.
+  This example uses the ``snmpwalk`` client, which is provided by the `net-snmp
+  <http://www.net-snmp.org/>`_ utilities.
 action:
   language: sh
   code: |
     snmpwalk -m /usr/share/snmp/mibs/MONGOD-MIB.txt -v 2c -c mongodb 127.0.0.1:<port> 1.3.6.1.4.1.34601
 post: |
-  ``<port>`` refers to the port defined by the SNMP master,
-  *not* the primary :setting:`~net.port` used by |mongod-program| for
-  client communication.
+  Replace ``<port>`` with the agent address port specified in the master
+  configuration file (default is 161). Note that this is the port defined by
+  the SNMP master, *not* the primary :setting:`~net.port` used by
+  |mongod-program| for client communication.
 ...