Expand the IPMI documentation

Explaing which cipher suites must be used and how to pre-configure the
BMC. Also explain the privilege levels.

Change-Id: I93845ac9dd068b0ddb52693afe4993804857e5ea

doc/source/admin/drivers/ipmitool.rst

@@ -168,6 +168,8 @@ protocol version::
    Version *1.5* of the IPMI protocol does not support encryption.
    Therefore, it is highly recommended that version 2.0 is used.
 
+.. _ipmi-cipher-suites:
+
 Cipher suites
 ~~~~~~~~~~~~~
 
@@ -186,7 +188,9 @@ commands fail with
 
 Another possible problem is ``ipmitool`` commands taking very long (tens of
 seconds or even minutes) because the BMC does not support cipher suite
-negotiation. In both cases you can specify the required suite yourself, e.g.::
+negotiation. In both cases you can specify the required suite yourself, e.g.
+
+.. code-block:: console
 
     baremetal node set <UUID or name> --driver-info ipmi_cipher_suite=3
 
@@ -216,6 +220,25 @@ To find the suitable values for this configuration, you can check the field
   MAC Address             : <MAC>
   RMCP+ Cipher Suites     : 0,1,2,3,6,7,8,11,12
 
+.. warning::
+   Only the cipher suites 3 and 17 are considered secure by the modern
+   standards. Cipher suite 0 means "no security at all".
+
+.. _ipmi-priv-level:
+
+Using a different privilege level
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default Ironic requests the ``ADMINISTRATOR`` privilege level of all
+commands. This is the easiest option, but if it's not available for you, you
+can change it to ``CALLBACK``, ``OPERATOR`` or ``USER`` this way:
+
+.. code-block:: console
+
+    baremetal node set <UUID or name> --driver-info ipmi_priv_level=OPERATOR
+
+You must ensure that the user can still change power state and boot devices.
+
 Static boot order configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/install/configure-ipmi.rst

@@ -17,7 +17,27 @@ http://ipmitool.sourceforge.net/.
     this tool.
 
 Please refer to the :doc:`/admin/drivers/ipmitool` for information on how to
-use IPMItool-based drivers.
+configure and use IPMItool-based drivers.
+
+Configuring hardware
+~~~~~~~~~~~~~~~~~~~~
+
+IPMI is a relatively old protocol and may require additional set up on the
+hardware side that the Bare Metal service cannot do automatically:
+
+#. Make sure IPMI is enabled and the account you use have the permissions
+   to change power and boot devices. By default the adminstrator rights are
+   expected, you can change it: see :ref:`ipmi-priv-level`.
+
+#. Make sure the cipher suites are configured for maximum security. Suite 17 is
+   recommended, 3 can be used if it's not available. Cipher suite 0 **must** be
+   disabled as it provides unauthenticated access to the BMC.
+
+   .. seealso:: :ref:`ipmi-cipher-suites`
+
+#. Make sure the boot mode correspond to the expected boot mode on the node
+   (see :ref:`boot_mode_support`). Some hardware is able to change the boot
+   mode to the requested by Ironic, some does not.
 
 Validation and troubleshooting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~