Merge "Documentation for 'snmp' hardware type" into stable/pike

doc/source/admin/drivers/snmp.rst

@@ -60,34 +60,96 @@ Software Requirements
 Enabling the SNMP Power Driver
 ==============================
 
-- Add ``pxe_snmp`` to the list of ``enabled_drivers`` in
-  ``/etc/ironic/ironic.conf``
-- Ironic Conductor must be restarted for the new driver to be loaded.
+#. Add ``snmp`` to the list of ``enabled_hardware_types`` in ``ironic.conf``.
+   Also update ``enabled_management_interfaces`` and
+   ``enabled_power_interfaces`` in ``ironic.conf`` as shown below:
+
+   .. code-block:: ini
+
+    [DEFAULT]
+    enabled_hardware_types = snmp
+    enabled_management_interfaces = fake
+    enabled_power_interfaces = snmp
+
+#. Alternatively, if you prefer using the classic driver instead of the
+   ``snmp`` hardware type, add ``pxe_snmp`` to the list of ``enabled_drivers``
+   in ``ironic.conf``:
+
+   .. code-block:: ini
+
+    [DEFAULT]
+    enabled_drivers = pxe_snmp
+
+#. To set the default boot option, update ``default_boot_option`` in
+   ``ironic.conf``:
+
+   .. code-block:: ini
+
+    [DEFAULT]
+    default_boot_option = netboot
+
+   .. note::
+      Currently the default value of ``default_boot_option`` is ``netboot``
+      but it will be changed to ``local`` in the future. It is recommended
+      to set an explicit value for this option.
+
+   .. note::
+      It is important to set ``boot_option`` to ``netboot`` as SNMP drivers
+      do not support setting of boot devices. One can also configure a node
+      to boot using ``netboot`` by setting its ``capabilities`` and updating
+      Nova flavor as described below:
+
+        .. code-block:: console
+
+         openstack baremetal node set --property capabilities="boot_option:netboot" <node-uuid>
+         openstack flavor set --property "capabilities:boot_option"="netboot" ironic-flavor
+
+
+#. Restart the Ironic conductor service.
+
+   .. code-block:: bash
+
+    service ironic-conductor restart
 
 Ironic Node Configuration
 =========================
 
-Nodes are configured for SNMP control by setting the Ironic node object's
-``driver`` property to be ``pxe_snmp``.  Further configuration values are
-added to ``driver_info``:
+Nodes configured to use the SNMP driver should have the ``driver`` field
+set to the hardware type ``snmp`` (preferred) or to the classic driver
+``pxe_snmp``.
+
+The following property values have to be added to the node's
+``driver_info`` field:
 
 - ``snmp_driver``: PDU manufacturer driver
 - ``snmp_address``: the IPv4 address of the PDU controlling this node.
 - ``snmp_port``: (optional) A non-standard UDP port to use for SNMP operations.
   If not specified, the default port (161) is used.
 - ``snmp_outlet``: The power outlet on the PDU (1-based indexing).
-- ``snmp_protocol``: (optional) SNMP protocol version
+- ``snmp_version``: (optional) SNMP protocol version
   (permitted values ``1``, ``2c`` or ``3``). If not specified, SNMPv1
   is chosen.
 - ``snmp_community``: (Required for SNMPv1 and SNMPv2c) SNMP community
   parameter for reads and writes to the PDU.
-- ``snmp_security``: (Required for SNMPv3) SNMP security string.
+- ``snmp_security``: (Required for SNMPv3) SNMPv3 User-based Security Model
+  (USM) user name.
+
+The following command can be used to enroll a node with the ``snmp`` driver:
+
+.. code-block:: bash
+
+  openstack baremetal node create --os-baremetal-api-version=1.31 \
+    --driver snmp --driver-info snmp_driver=<pdu_manufacturer> \
+    --driver-info snmp_address=<ip_address> \
+    --driver-info snmp_outlet=<outlet_index> \
+    --driver-info snmp_community=<community_string> \
+    --properties capabilities=boot_option:netboot
 
 PDU Configuration
 =================
 
-This version of the SNMP power driver does not support handling
-PDU authentication credentials. When using SNMPv3, the PDU must be
-configured for ``NoAuthentication`` and ``NoEncryption``. The
-security name is used analogously to the SNMP community in early
-SNMP versions.
+This version of the SNMP power driver does not support SNMPv3 authentication
+or encryption features. When using SNMPv3, the SNMPv3 agent at the PDU must
+be configured in ``noAuthNoPriv`` mode. Also, the ``snmp_security`` parameter
+is used to configure SNMP USM user name to the SNMP manager at the power
+driver.  The same USM user name must be configured to the target SNMP agent.

ironic/drivers/modules/snmp.py

@@ -73,7 +73,8 @@ OPTIONAL_PROPERTIES = {
         _("SNMP community.  Required for versions %(v1)s and %(v2c)s")
         % {"v1": SNMP_V1, "v2c": SNMP_V2C},
     'snmp_security':
-        _("SNMP security name.  Required for version %(v3)s")
+        _("SNMPv3 User-based Security Model (USM) username. "
+          "Required for version %(v3)s")
         % {"v3": SNMP_V3},
 }
 COMMON_PROPERTIES = REQUIRED_PROPERTIES.copy()