Merge "Update ipmitool installation and usage documentation"

doc/source/drivers/ipmitool.rst

@@ -1,5 +1,3 @@
-.. _IPMITOOL:
-
 ===============
 IPMITool driver
 ===============
@@ -7,54 +5,66 @@ IPMITool driver
 Overview
 ========
 
-The IPMITool driver enables managing nodes by using the Intelligent
+The IPMI_ (Intelligent Platform Management Interface) drivers manage nodes
-Platform Management Interface (IPMI) versions 2.0 or 1.5. The name of
+by using IPMI protocol versions 2.0 or 1.5. They use the IPMItool_ utility
-the driver comes from the utility ``ipmitool`` which is an open-source
+which is an open-source command-line interface (CLI) for controlling
-command-line interface (CLI) for controlling IPMI-enabled devices.
+IPMI-enabled devices.
 
-Currently there are 2 IPMITool drivers:
+The following hardware types and classic drivers use IPMItool for power and
+management:
 
-* ``agent_ipmitool``
+* hardware types:
-* ``pxe_ipmitool``
+
+  * ``ipmi``
+
+* classic drivers:
+
+  * ``agent_ipmitool``
+  * ``pxe_ipmitool``
+  * ``agent_ipmitool_socat``
+  * ``pxe_ipmitool_socat``
 
 Glossary
 ========
 
-* IPMI - Intelligent Platform Management Interface.
+* IPMI_ - Intelligent Platform Management Interface.
 * IPMB - Intelligent Platform Management Bus/Bridge.
-* BMC  - Baseboard Management Controller.
+* BMC_  - Baseboard Management Controller.
 * RMCP - Remote Management Control Protocol.
 
-Prerequisites
-=============
-
-* The `ipmitool utility <https://sourceforge.net/projects/ipmitool>`_
-  should be installed on the ironic conductor node. On most distros,
-  this is provided as part of the ``ipmitool`` package.
-
 Enabling the IPMITool driver(s)
 ===============================
 
-.. note::
+Please see `IPMI configuration guide`_ for the required dependencies.
-    The ``pxe_ipmitool`` driver is the default driver in Ironic, so if
-    no extra configuration is provided the driver will be enabled.
 
-#. Add ``pxe_ipmitool`` and/or ``agent_ipmitool`` to the list of
+#. The ``ipmi`` hardware type is enabled by default starting with the Ocata
-   ``enabled_drivers`` in */etc/ironic/ironic.conf*. For example::
+   release. To enable it explicitly, add the following to your ``ironic.conf``:
+
+   .. code-block:: ini
+
+    [DEFAULT]
+    enabled_hardware_types = ipmi
+
+#. The ``pxe_ipmitool`` classic driver is enabled by default. To enable one or
+   more of the other ipmitool classic drivers, add them to the
+   ``enabled_drivers`` configuration option in your ``ironic.conf``.
+   The following enables ``pxe_ipmitool`` and ``agent_ipmitool`` drivers:
+
+   .. code-block:: ini
 
     [DEFAULT]
-    ...
     enabled_drivers = pxe_ipmitool,agent_ipmitool
 
-#. Restart the Ironic conductor service::
+#. Restart the Ironic conductor service.
 
-    service ironic-conductor restart
+Please see `documentation on enabling drivers`_ for more details.
 
 Registering a node with the IPMItool driver
 ===========================================
 
-Nodes configured to use the IPMItool drivers should have the ``driver``
+Nodes configured to use the IPMItool drivers should have the driver field set
-property set to ``pxe_ipmitool`` or ``agent_ipmitool``.
+to ``ipmi`` (hardware type) or to the name of one of the classic drivers
+that support ipmitool.
 
 The following configuration value is required and has to be added to
 the node's ``driver_info`` field:
@@ -75,10 +85,10 @@ good practice to have them set:
    your BMC.
 
 The ``ironic node-create`` command can be used to enroll a node with
-the IPMITool driver. For example::
+an IPMITool-based driver. For example::
 
-    ironic node-create -d pxe_ipmitool -i ipmi_address=<address>
+    ironic node-create -d ipmi -i ipmi_address=<address> \
-    -i ipmi_username=<username> -i ipmi_password=<password>
+        -i ipmi_username=<username> -i ipmi_password=<password>
 
 Advanced configuration
 ======================
@@ -91,11 +101,11 @@ Single/Double bridging functionality
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
-   A version of ``ipmitool`` higher or equal to 1.8.12 is required to use
+   A version of IPMItool higher or equal to 1.8.12 is required to use
    the bridging functionality.
 
 There are two different bridging functionalities supported by the
-IPMITool driver: *single* bridge and *dual* bridge.
+IPMITool-based drivers: *single* bridge and *dual* bridge.
 
 The following configuration values need to be added to the node's
 ``driver_info`` field so bridging can be used:
@@ -105,7 +115,7 @@ The following configuration values need to be added to the node's
 - ``ipmi_local_address``: The local IPMB address for bridged requests.
    Required only if ``ipmi_bridging`` is set to *single* or *dual*. This
    configuration is optional, if not specified it will be auto discovered
-   by ipmitool.
+   by IPMItool.
 - ``ipmi_target_address``: The destination address for bridged
   requests. Required only if ``ipmi_bridging`` is set to *single* or *dual*.
 - ``ipmi_target_channel``: The destination channel for bridged
@@ -129,21 +139,21 @@ driver. For example:
 
 * Single Bridging::
 
-    ironic node-update add <UUID or name> driver_info/ipmi_local_address=<address>
+    ironic node-update add <UUID or name> driver_info/ipmi_local_address=<address> \
-    driver_info/ipmi_bridging=single driver_info/ipmi_target_channel=<channel>
+        driver_info/ipmi_bridging=single driver_info/ipmi_target_channel=<channel> \
-    driver_info/ipmi_target_address=<target address>
+        driver_info/ipmi_target_address=<target address>
 
 * Double Bridging::
 
-    ironic node-update add <UUID or name> driver_info/ipmi_local_address=<address>
+    ironic node-update add <UUID or name> driver_info/ipmi_local_address=<address> \
-    driver_info/ipmi_bridging=dual driver_info/ipmi_transit_channel=<transit channel>
+        driver_info/ipmi_bridging=dual driver_info/ipmi_transit_channel=<transit channel> \
-    driver_info/ipmi_transit_address=<transit address> driver_info/ipmi_target_channel=<target channel>
+        driver_info/ipmi_transit_address=<transit address> driver_info/ipmi_target_channel=<target channel> \
-    driver_info/ipmi_target_address=<target address>
+        driver_info/ipmi_target_address=<target address>
 
 Changing the version of the IPMI protocol
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The IPMItool driver works with the versions *2.0* and *1.5* of the
+The IPMItool-based drivers works with the versions *2.0* and *1.5* of the
 IPMI protocol. By default, the version *2.0* is used.
 
 In order to change the IPMI protocol version in the bare metal node,
@@ -158,8 +168,14 @@ protocol version::
     ironic node-update add <UUID or name> driver_info/ipmi_protocol_version=<version>
 
 .. warning::
-   The version *1.5* of the IPMI protocol does not support encryption. So
+   Version *1.5* of the IPMI protocol does not support encryption.
-   it's very recommended that the version *2.0* is used.
+   Therefore, it is highly recommended that version 2.0 is used.
 
 .. TODO(lucasagomes): Write about privilege level
 .. TODO(lucasagomes): Write about force boot device
+
+.. _IPMItool: https://sourceforge.net/projects/ipmitool/
+.. _IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface
+.. _BMC: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface#Baseboard_management_controller
+.. _IPMI configuration guide: https://docs.openstack.org/project-install-guide/baremetal/draft/configure-ipmi.html
+.. _documentation on enabling drivers: https://docs.openstack.org/project-install-guide/baremetal/draft/enabling-drivers.html

install-guide/source/configure-ipmi.rst

@@ -5,7 +5,7 @@ Installing ipmitool command
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To enable one of the drivers that use IPMI_ protocol for power and management
-actions (e.g. ``ipmi``, ``pxe_ipmitool`` and ``agent_ipmitool``), the
+actions (for example, ``ipmi``, ``pxe_ipmitool`` and ``agent_ipmitool``), the
 ``ipmitool`` command must be present on the service node(s) where
 ``ironic-conductor`` is running. On most distros, it is provided as part
 of the ``ipmitool`` package. Source code is available at
@@ -17,6 +17,12 @@ http://ipmitool.sourceforge.net/.
     ``openipmi`` as it relies on error handling options not provided by
     this tool.
 
+Please refer to the `ipmitool driver page`_ for information on how to use
+IPMItool-based drivers.
+
+Validation and troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Check that you can connect to, and authenticate with, the IPMI
 controller in your bare metal server by running ``ipmitool``::
 
@@ -76,3 +82,4 @@ these are ``Temperature``, ``Fan``, ``Voltage``, ``Current``.
 Special value ``All`` (the default) designates all supported sensor types.
 
 .. _IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface
+.. _ipmitool driver page: https://docs.openstack.org/developer/ironic/drivers/ipmitool.html

install-guide/source/enabling-drivers.rst

@@ -138,6 +138,12 @@ vendor
     is a place for vendor extensions to be exposed in API. See `vendor
     methods documentation`_ for details.
 
+    .. code-block:: ini
+
+        [DEFAULT]
+        enabled_hardware_types = ipmi,redfish,ilo,irmc
+        enabled_vendor_interfaces = ipmitool,no-vendor
+
 Here is a complete configuration example, enabling two generic protocols,
 IPMI and Redfish, with a few additional features:
 
@@ -153,7 +159,7 @@ IPMI and Redfish, with a few additional features:
     enabled_network_interfaces = flat,neutron
     enabled_power_interfaces = ipmitool,redfish
     enabled_raid_interfaces = agent
-    enabled_vendor_interfaces = no-vendor
+    enabled_vendor_interfaces = ipmitool,no-vendor
 
 Note that some interfaces have implementations named ``no-<TYPE>`` where
 ``<TYPE>`` is the interface type. These implementations do nothing and return