openstack/ironic
Code Issues Proposed changes

Merge "Update ipmitool installation and usage documentation"

Browse Source
This commit is contained in:
Jenkins 2017-05-30 15:34:28 +00:00 committed by Gerrit Code Review
commit 82e8a40b93
3 changed files with 75 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
doc/source/drivers/ipmitool.rst
View File

@ -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 <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::
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,9 +85,9 @@ 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>
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>
driver_info/ipmi_bridging=single driver_info/ipmi_target_channel=<channel>
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_target_address=<target address>
* Double Bridging::
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_transit_address=<transit address> driver_info/ipmi_target_channel=<target channel>
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_transit_address=<transit address> driver_info/ipmi_target_channel=<target channel> \
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
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

9
install-guide/source/configure-ipmi.rst
View File

@ -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

8
install-guide/source/enabling-drivers.rst
View File

@ -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