summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJenkins <jenkins@review.openstack.org>2016-03-10 16:37:59 +0000
committerGerrit Code Review <review@openstack.org>2016-03-10 16:37:59 +0000
commit599e5443504279b49a7250a9085e5bd34d86f0fd (patch)
tree7aa1ddbff39d045cfb7e7b8ba2b35a00bf4192bd /doc
parent6d1b7c6d0df2b6e64ec944f85837460a219d472e (diff)
parent198ae29c438b9581b2268f729b06203ab9910a3a (diff)
downloadironic-599e5443504279b49a7250a9085e5bd34d86f0fd.tar.gz
Merge "Add documentation for the IPMITool driver"5.0.0
Diffstat (limited to 'doc')
-rw-r--r--doc/source/deploy/drivers.rst8
-rw-r--r--doc/source/drivers/ipmitool.rst166
2 files changed, 174 insertions, 0 deletions
diff --git a/doc/source/deploy/drivers.rst b/doc/source/deploy/drivers.rst
index db8654699..ce1152777 100644
--- a/doc/source/deploy/drivers.rst
+++ b/doc/source/deploy/drivers.rst
@@ -13,6 +13,14 @@ nodes, and runs processes inside of a ramdisk.
For more information on this, see :ref:`IPA`.
+IPMITool
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ ../drivers/ipmitool
+
DRAC
----
diff --git a/doc/source/drivers/ipmitool.rst b/doc/source/drivers/ipmitool.rst
new file mode 100644
index 000000000..f046c6b86
--- /dev/null
+++ b/doc/source/drivers/ipmitool.rst
@@ -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