Add documentation for the IPMI retry timeout option

It is difficult to have a universal default for the retry_timeout
option in the [impi] configuration section. This patch adds
documentation of the tradeoffs involved, while leaving the
conservative default in place.

Closes-Bug: 1383432
Change-Id: Ic7973cf7fee60cc817e5c0f5f9bfc84b3bca91c7

doc/source/deploy/install-guide.rst

@@ -776,6 +776,12 @@ controller in your bare metal server by using ``ipmitool``::
      checked by just pinging the IPMI controller IP from the conductor
      node.
 
+.. note::
+   If there are slow or unresponsive BMCs in the environment, the retry_timeout
+   configuration option in the [ipmi] section may need to be lowered. The
+   default is fairly conservative, as setting this timeout too low can cause
+   older BMCs to crash and require a hard-reset.
+
 Ironic supports sending IPMI sensor data to Ceilometer with pxe_ipmitool,
 pxe_ipminative, agent_ipmitool, agent_pyghmi, agent_ilo, iscsi_ilo and pxe_ilo
 drivers. By default, support for sending IPMI sensor data to Ceilometer is

etc/ironic/ironic.conf.sample

@@ -191,7 +191,7 @@
 #
 
 # IP address of this host. (string value)
-#my_ip=192.168.122.1
+#my_ip=10.0.0.1
 
 
 #
@@ -457,10 +457,6 @@
 # to be searched. (multi valued)
 #policy_dirs=policy.d
 
-[keystone]
-
-#The region used for getting endpoints of OpenStack services.
-#region_name =
 
 [agent]
 
@@ -478,6 +474,11 @@
 # Neutron bootfile DHCP parameter. (string value)
 #agent_pxe_bootfile_name=pxelinux.0
 
+
+#
+# Options defined in ironic.drivers.modules.agent_base_vendor
+#
+
 # Maximum interval (in seconds) for agent heartbeats. (integer
 # value)
 #heartbeat_timeout=300
@@ -498,7 +499,7 @@
 # Options defined in ironic.drivers.modules.amt.common
 #
 
-# protocol used for AMT endpoint, support http/https (string
+# Protocol used for AMT endpoint, support http/https (string
 # value)
 #protocol=http
 
@@ -924,8 +925,12 @@
 # Options defined in ironic.drivers.modules.ipminative
 #
 
-# Maximum time in seconds to retry IPMI operations. (integer
-# value)
+# Maximum time in seconds to retry IPMI operations. There is a
+# tradeoff when setting this value. Setting this too low may
+# cause older BMCs to crash and require a hard reset. However,
+# setting too high can cause the sync power state periodic
+# task to hang when there are slow or unresponsive BMCs.
+# (integer value)
 #retry_timeout=60
 
 # Minimum time, in seconds, between IPMI operations sent to a
@@ -953,6 +958,17 @@
 #client_timeout=60
 
 
+[keystone]
+
+#
+# Options defined in ironic.common.keystone
+#
+
+# The region used for getting endpoints of OpenStackservices.
+# (string value)
+#region_name=<None>
+
+
 [keystone_authtoken]
 
 #

ironic/drivers/modules/ipminative.py

@@ -46,7 +46,12 @@ if pyghmi:
 opts = [
     cfg.IntOpt('retry_timeout',
                default=60,
-               help='Maximum time in seconds to retry IPMI operations.'),
+               help='Maximum time in seconds to retry IPMI operations. There '
+                    'is a tradeoff when setting this value. Setting this too '
+                    'low may cause older BMCs to crash and require a hard '
+                    'reset. However, setting too high can cause the sync '
+                    'power state periodic task to hang when there are slow '
+                    'or unresponsive BMCs.'),
     cfg.IntOpt('min_command_interval',
                default=5,
                help='Minimum time, in seconds, between IPMI operations '