Merge "Add documentation for the IPMITool driver"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
599e544350
@ -13,6 +13,14 @@ nodes, and runs processes inside of a ramdisk.
|
|||||||
|
|
||||||
For more information on this, see :ref:`IPA`.
|
For more information on this, see :ref:`IPA`.
|
||||||
|
|
||||||
|
IPMITool
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
../drivers/ipmitool
|
||||||
|
|
||||||
DRAC
|
DRAC
|
||||||
----
|
----
|
||||||
|
|
||||||
|
|||||||
166
doc/source/drivers/ipmitool.rst
Normal file
166
doc/source/drivers/ipmitool.rst
Normal file
@ -0,0 +1,166 @@
|
|||||||
|
.. _IPMITOOL:
|
||||||
|
|
||||||
|
===============
|
||||||
|
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.
|
||||||
|
|
||||||
|
Currently there are 2 IPMITool drivers:
|
||||||
|
|
||||||
|
* ``agent_ipmitool``
|
||||||
|
* ``pxe_ipmitool``
|
||||||
|
|
||||||
|
Glossary
|
||||||
|
========
|
||||||
|
|
||||||
|
* IPMI - Intelligent Platform Management Interface.
|
||||||
|
* IPMB - Intelligent Platform Management Bus/Bridge.
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
#. Add ``pxe_ipmitool`` and/or ``agent_ipmitool`` to the list of
|
||||||
|
``enabled_drivers`` in */etc/ironic/ironic.conf*. For example::
|
||||||
|
|
||||||
|
[DEFAULT]
|
||||||
|
...
|
||||||
|
enabled_drivers = pxe_ipmitool,agent_ipmitool
|
||||||
|
|
||||||
|
#. Restart the Ironic conductor service::
|
||||||
|
|
||||||
|
service ironic-conductor restart
|
||||||
|
|
||||||
|
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``.
|
||||||
|
|
||||||
|
The following configuration value is required and has to be added to
|
||||||
|
the node's ``driver_info`` field:
|
||||||
|
|
||||||
|
- ``ipmi_address``: The IP address or hostname of the BMC.
|
||||||
|
|
||||||
|
Other options may be needed to match the configuration of the BMC, the
|
||||||
|
following options are optional, but in most cases, it's considered a
|
||||||
|
good practice to have them set:
|
||||||
|
|
||||||
|
- ``ipmi_username``: The username to access the BMC; defaults to *NULL* user.
|
||||||
|
- ``ipmi_password``: The password to access the BMC; defaults to *NULL*.
|
||||||
|
- ``ipmi_port``: The remote IPMI RMCP port. By default ipmitool will
|
||||||
|
use the port *623*.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
It is highly recommend that you setup a username and password for
|
||||||
|
your BMC.
|
||||||
|
|
||||||
|
The ``ironic node-create`` command can be used to enroll a node with
|
||||||
|
the IPMITool driver. For example::
|
||||||
|
|
||||||
|
ironic node-create -d pxe_ipmitool -i ipmi_address=<address>
|
||||||
|
-i ipmi_username=<username> -i ipmi_password=<password>
|
||||||
|
|
||||||
|
Advanced configuration
|
||||||
|
======================
|
||||||
|
|
||||||
|
When a simple configuration such as providing the ``address``,
|
||||||
|
``username`` and ``password`` is not enough, the IPMItool driver contains
|
||||||
|
many other options that can be used to address special usages.
|
||||||
|
|
||||||
|
Single/Double bridging functionality
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
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.
|
||||||
|
|
||||||
|
The following configuration values need to be added to the node's
|
||||||
|
``driver_info`` field so bridging can be used:
|
||||||
|
|
||||||
|
- ``ipmi_bridging``: The bridging type; default is *no*; other supported
|
||||||
|
values are *single* for single bridge or *dual* for double bridge.
|
||||||
|
- ``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.
|
||||||
|
- ``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
|
||||||
|
requests. Required only if ``ipmi_bridging`` is set to *single* or *dual*.
|
||||||
|
|
||||||
|
Double bridge specific options:
|
||||||
|
|
||||||
|
- ``ipmi_transit_address``: The transit address for bridged
|
||||||
|
requests. Required only if ``ipmi_bridging`` is set to *dual*.
|
||||||
|
- ``ipmi_transit_channel``: The transit channel for bridged
|
||||||
|
requests. Required only if ``ipmi_bridging`` is set to *dual*.
|
||||||
|
|
||||||
|
|
||||||
|
The parameter ``ipmi_bridging`` should specify the type of bridging
|
||||||
|
required: *single* or *dual* to access the bare metal node. If the
|
||||||
|
parameter is not specified, the default value will be set to *no*.
|
||||||
|
|
||||||
|
The ``ironic node-update`` command can be used to set the required
|
||||||
|
bridging information to the Ironic node enrolled with the IPMItool
|
||||||
|
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>
|
||||||
|
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>
|
||||||
|
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
|
||||||
|
IPMI protocol. By default, the version *2.0* is used.
|
||||||
|
|
||||||
|
In order to change the IPMI protocol version in the bare metal node,
|
||||||
|
the following option needs to be set to the node's ``driver_info`` field:
|
||||||
|
|
||||||
|
- ``ipmi_protocol_version``: The version of the IPMI protocol; default
|
||||||
|
is *2.0*. Supported values are *1.5* or *2.0*.
|
||||||
|
|
||||||
|
The ``ironic node-update`` command can be used to set the desired
|
||||||
|
protocol version::
|
||||||
|
|
||||||
|
ironic node-update add <UUID or name>
|
||||||
|
driver_info/ipmit_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.
|
||||||
|
|
||||||
|
.. TODO(lucasagomes): Write about privilege level
|
||||||
|
.. TODO(lucasagomes): Write about force boot device
|
||||||
Loading…
Reference in New Issue
Block a user