From d3ea000db614487879f3c61f4e4554a37115574e Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Mon, 22 May 2017 15:28:30 +0200 Subject: [PATCH] Update ipmitool installation and usage documentation * Mention the IPMI hardware type in usage docs * Cross-link between usage and install docs * Add missing ipmitool vendor interface example * Stop pretending that there is one "IPMItool driver" * Fix several small issues Change-Id: I3c8928abc319d04b84f8581226627860c57a1abc Related-Bug: #1524745 --- doc/source/drivers/ipmitool.rst | 104 +++++++++++++--------- install-guide/source/configure-ipmi.rst | 9 +- install-guide/source/enabling-drivers.rst | 8 +- 3 files changed, 75 insertions(+), 46 deletions(-) diff --git a/doc/source/drivers/ipmitool.rst b/doc/source/drivers/ipmitool.rst index 03917e5f7d..6aee2a2ab5 100644 --- a/doc/source/drivers/ipmitool.rst +++ b/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 -Platform Management Interface (IPMI) versions 2.0 or 1.5. The name of -the driver comes from the utility ``ipmitool`` which is an open-source -command-line interface (CLI) for controlling IPMI-enabled devices. +The IPMI_ (Intelligent Platform Management Interface) drivers manage nodes +by using IPMI protocol versions 2.0 or 1.5. They use the IPMItool_ utility +which is an open-source command-line interface (CLI) for controlling +IPMI-enabled devices. -Currently there are 2 IPMITool drivers: +The following hardware types and classic drivers use IPMItool for power and +management: -* ``agent_ipmitool`` -* ``pxe_ipmitool`` +* hardware types: + + * ``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 `_ - 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:: - The ``pxe_ipmitool`` driver is the default driver in Ironic, so if - no extra configuration is provided the driver will be enabled. +Please see `IPMI configuration guide`_ for the required dependencies. -#. Add ``pxe_ipmitool`` and/or ``agent_ipmitool`` to the list of - ``enabled_drivers`` in */etc/ironic/ironic.conf*. For example:: +#. The ``ipmi`` hardware type is enabled by default starting with the Ocata + 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`` -property set to ``pxe_ipmitool`` or ``agent_ipmitool``. +Nodes configured to use the IPMItool drivers should have the driver field set +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=
- -i ipmi_username= -i ipmi_password= + ironic node-create -d ipmi -i ipmi_address=
\ + -i ipmi_username= -i ipmi_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 driver_info/ipmi_local_address=
- driver_info/ipmi_bridging=single driver_info/ipmi_target_channel= - driver_info/ipmi_target_address= + ironic node-update add driver_info/ipmi_local_address=
\ + driver_info/ipmi_bridging=single driver_info/ipmi_target_channel= \ + driver_info/ipmi_target_address= * Double Bridging:: - ironic node-update add driver_info/ipmi_local_address=
- driver_info/ipmi_bridging=dual driver_info/ipmi_transit_channel= - driver_info/ipmi_transit_address= driver_info/ipmi_target_channel= - driver_info/ipmi_target_address= + ironic node-update add driver_info/ipmi_local_address=
\ + driver_info/ipmi_bridging=dual driver_info/ipmi_transit_channel= \ + driver_info/ipmi_transit_address= driver_info/ipmi_target_channel= \ + driver_info/ipmi_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 driver_info/ipmi_protocol_version= .. warning:: - The version *1.5* of the IPMI protocol does not support encryption. So - it's very recommended that the version *2.0* is used. + Version *1.5* of the IPMI protocol does not support encryption. + 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 diff --git a/install-guide/source/configure-ipmi.rst b/install-guide/source/configure-ipmi.rst index 7412ecaad0..453ca6fc84 100644 --- a/install-guide/source/configure-ipmi.rst +++ b/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 diff --git a/install-guide/source/enabling-drivers.rst b/install-guide/source/enabling-drivers.rst index 17000c2453..edb8bade8a 100644 --- a/install-guide/source/enabling-drivers.rst +++ b/install-guide/source/enabling-drivers.rst @@ -135,6 +135,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: @@ -150,7 +156,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-`` where ```` is the interface type. These implementations do nothing and return