Update some config option's help strings

Some config option's help strings are updated based on the
documentation/feedback in a previous patch that attempted
to document the config options, but we decided that it would
be better to update the help in the configs themselves:
    https://review.openstack.org/#/c/83577/

Change-Id: Ied2a4d69b735e919ab0597ac8d53df5dcd2a0ff6
Closes-Bug: 1324169

etc/ironic/ironic.conf.sample

@@ -73,7 +73,9 @@
 # Options defined in ironic.netconf
 #
 
-# IP address of this host. (string value)
+# IP address of this host. If unset, will determine the IP
+# programmatically. If unable to do so, will use "127.0.0.1".
+# (string value)
 #my_ip=10.0.0.1
 
 
@@ -81,12 +83,15 @@
 # Options defined in ironic.api.app
 #
 
-# Method to use for authentication: noauth or keystone.
+# Authentication strategy used by ironic-api: one of
-# (string value)
+# "keystone" or "noauth". "noauth" should not be used in a
+# production environment because all authentication will be
+# disabled. (string value)
 #auth_strategy=keystone
 
 # Enable pecan debug mode. WARNING: this is insecure and
-# should not be used in production. (boolean value)
+# should not be used in a production environment. (boolean
+# value)
 #pecan_debug=false
 
 
@@ -109,7 +114,10 @@
 # Options defined in ironic.common.exception
 #
 
-# Make exception message format errors fatal. (boolean value)
+# Used if there is a formatting error when generating an
+# exception message (a programming error). If True, raise an
+# exception; if False, use the unformatted message. (boolean
+# value)
 #fatal_exception_format_errors=false
 
 
@@ -143,7 +151,8 @@
 # Options defined in ironic.common.images
 #
 
-# Force backing images to raw format. (boolean value)
+# If True, convert backing images to "raw" disk image format.
+# (boolean value)
 #force_raw_images=true
 
 # Path to isolinux binary file. (string value)
@@ -366,6 +375,7 @@
 # (boolean value)
 #manage_tftp=true
 
+
 #
 # Options defined in ironic.drivers.modules.agent_base_vendor
 #
@@ -414,10 +424,10 @@
 # Options defined in ironic.api
 #
 
-# The listen IP for the Ironic API server. (string value)
+# The IP address on which ironic-api listens. (string value)
 #host_ip=0.0.0.0
 
-# The port for the Ironic API server. (integer value)
+# The TCP port on which ironic-api listens. (integer value)
 #port=6385
 
 # The maximum number of items returned in a single response
@@ -440,7 +450,8 @@
 #heartbeat_interval=10
 
 # Maximum time (in seconds) since the last check-in of a
-# conductor. (integer value)
+# conductor. A conductor is considered inactive when this time
+# has been exceeded. (integer value)
 #heartbeat_timeout=60
 
 # Interval between syncing the node power state to the
@@ -451,8 +462,8 @@
 # (integer value)
 #check_provision_state_interval=60
 
-# Timeout (seconds) for waiting callback from deploy ramdisk.
+# Timeout (seconds) to wait for a callback from a deploy
-# 0 - unlimited. (integer value)
+# ramdisk. Set to 0 to disable timeout. (integer value)
 #deploy_callback_timeout=1800
 
 # During sync_power_state, should the hardware power state be
@@ -1447,11 +1458,12 @@
 # is created. (string value)
 #default_ephemeral_format=ext4
 
-# Directory where images are stored on disk. (string value)
+# On the ironic-conductor node, directory where images are
+# stored on disk. (string value)
 #images_path=/var/lib/ironic/images/
 
-# Directory where master instance images are stored on disk.
+# On the ironic-conductor node, directory where master
-# (string value)
+# instance images are stored on disk. (string value)
 #instance_master_path=/var/lib/ironic/master_images
 
 # Maximum size (in MiB) of cache for master images, including
@@ -1471,22 +1483,23 @@
 # Options defined in ironic.drivers.modules.pxe
 #
 
-# Template file for PXE configuration. (string value)
+# On ironic-conductor node, template file for PXE
+# configuration. (string value)
 #pxe_config_template=$pybasedir/drivers/modules/pxe_config.template
 
-# Template file for PXE configuration for UEFI boot loader.
+# On ironic-conductor node, template file for PXE
-# (string value)
+# configuration for UEFI boot loader. (string value)
 #uefi_pxe_config_template=$pybasedir/drivers/modules/elilo_efi_pxe_config.template
 
-# IP address of Ironic compute node's tftp server. (string
+# IP address of ironic-conductor node's TFTP server. (string
 # value)
 #tftp_server=$my_ip
 
-# Ironic compute node's tftp root path. (string value)
+# ironic-conductor node's TFTP root path. (string value)
 #tftp_root=/tftpboot
 
-# Directory where master tftp images are stored on disk.
+# On ironic-conductor node, directory where master TFTP images
-# (string value)
+# are stored on disk. (string value)
 #tftp_master_path=/tftpboot/master_images
 
 # Bootfile DHCP parameter. (string value)
@@ -1495,17 +1508,18 @@
 # Bootfile DHCP parameter for UEFI boot mode. (string value)
 #uefi_pxe_bootfile_name=elilo.efi
 
-# Ironic compute node's HTTP server URL. Example:
+# ironic-conductor node's HTTP server URL. Example:
 # http://192.1.2.3:8080 (string value)
 #http_url=<None>
 
-# Ironic compute node's HTTP root path. (string value)
+# ironic-conductor node's HTTP root path. (string value)
 #http_root=/httpboot
 
 # Enable iPXE boot. (boolean value)
 #ipxe_enabled=false
 
-# The path to the main iPXE script file. (string value)
+# On ironic-conductor node, the path to the main iPXE script
+# file. (string value)
 #ipxe_boot_script=$pybasedir/drivers/modules/boot.ipxe
 
 
@@ -1540,7 +1554,7 @@
 # Options defined in ironic.drivers.modules.ssh
 #
 
-# libvirt uri (string value)
+# libvirt URI (string value)
 #libvirt_uri=qemu:///system
 
 

ironic/api/__init__.py

@@ -19,10 +19,10 @@ from oslo_config import cfg
 API_SERVICE_OPTS = [
     cfg.StrOpt('host_ip',
                default='0.0.0.0',
-               help='The listen IP for the Ironic API server.'),
+               help='The IP address on which ironic-api listens.'),
     cfg.IntOpt('port',
                default=6385,
-               help='The port for the Ironic API server.'),
+               help='The TCP port on which ironic-api listens.'),
     cfg.IntOpt('max_limit',
                default=1000,
                help='The maximum number of items returned in a single '

ironic/api/app.py

@@ -26,11 +26,13 @@ from ironic.api import middleware
 api_opts = [
     cfg.StrOpt('auth_strategy',
         default='keystone',
-        help='Method to use for authentication: noauth or keystone.'),
+        help='Authentication strategy used by ironic-api: one of "keystone" '
+             'or "noauth". "noauth" should not be used in a production '
+             'environment because all authentication will be disabled.'),
     cfg.BoolOpt('pecan_debug',
                 default=False,
                 help=('Enable pecan debug mode. WARNING: this is insecure '
-                      'and should not be used in production.')),
+                      'and should not be used in a production environment.')),
     ]
 
 CONF = cfg.CONF

ironic/common/exception.py

@@ -35,7 +35,10 @@ LOG = logging.getLogger(__name__)
 exc_log_opts = [
     cfg.BoolOpt('fatal_exception_format_errors',
                 default=False,
-                help='Make exception message format errors fatal.'),
+                help='Used if there is a formatting error when generating an '
+                     'exception message (a programming error). If True, '
+                     'raise an exception; if False, use the unformatted '
+                     'message.'),
 ]
 
 CONF = cfg.CONF

ironic/common/images.py

@@ -42,7 +42,8 @@ LOG = logging.getLogger(__name__)
 image_opts = [
     cfg.BoolOpt('force_raw_images',
                 default=True,
-                help='Force backing images to raw format.'),
+                help='If True, convert backing images to "raw" disk image '
+                     'format.'),
     cfg.StrOpt('isolinux_bin',
                 default='/usr/lib/syslinux/isolinux.bin',
                 help='Path to isolinux binary file.'),

ironic/conductor/manager.py

@@ -95,7 +95,8 @@ conductor_opts = [
         cfg.IntOpt('heartbeat_timeout',
                    default=60,
                    help='Maximum time (in seconds) since the last check-in '
-                        'of a conductor.'),
+                        'of a conductor. A conductor is considered inactive '
+                        'when this time has been exceeded.'),
         cfg.IntOpt('sync_power_state_interval',
                    default=60,
                    help='Interval between syncing the node power state to the '
@@ -106,8 +107,8 @@ conductor_opts = [
                         'in seconds.'),
         cfg.IntOpt('deploy_callback_timeout',
                    default=1800,
-                   help='Timeout (seconds) for waiting callback from deploy '
+                   help='Timeout (seconds) to wait for a callback from '
-                        'ramdisk. 0 - unlimited.'),
+                        'a deploy ramdisk. Set to 0 to disable timeout.'),
         cfg.BoolOpt('force_power_state_during_sync',
                    default=True,
                    help='During sync_power_state, should the hardware power '

ironic/drivers/modules/iscsi_deploy.py

@@ -52,11 +52,12 @@ pxe_opts = [
                     'if one is created.'),
     cfg.StrOpt('images_path',
                default='/var/lib/ironic/images/',
-               help='Directory where images are stored on disk.'),
+               help='On the ironic-conductor node, directory where images are '
+                    'stored on disk.'),
     cfg.StrOpt('instance_master_path',
                default='/var/lib/ironic/master_images',
-               help='Directory where master instance images are stored on '
+               help='On the ironic-conductor node, directory where master '
-                    'disk.'),
+                    'instance images are stored on disk.'),
     cfg.IntOpt('image_cache_size',
                default=20480,
                help='Maximum size (in MiB) of cache for master images, '

ironic/drivers/modules/pxe.py

@@ -52,21 +52,23 @@ pxe_opts = [
     cfg.StrOpt('pxe_config_template',
                default=paths.basedir_def(
                     'drivers/modules/pxe_config.template'),
-               help='Template file for PXE configuration.'),
+               help='On ironic-conductor node, template file for PXE '
+                    'configuration.'),
     cfg.StrOpt('uefi_pxe_config_template',
                default=paths.basedir_def(
                     'drivers/modules/elilo_efi_pxe_config.template'),
-               help='Template file for PXE configuration for UEFI boot'
+               help='On ironic-conductor node, template file for PXE '
-                    ' loader.'),
+                    'configuration for UEFI boot loader.'),
     cfg.StrOpt('tftp_server',
                default='$my_ip',
-               help='IP address of Ironic compute node\'s tftp server.'),
+               help='IP address of ironic-conductor node\'s TFTP server.'),
     cfg.StrOpt('tftp_root',
                default='/tftpboot',
-               help='Ironic compute node\'s tftp root path.'),
+               help='ironic-conductor node\'s TFTP root path.'),
     cfg.StrOpt('tftp_master_path',
                default='/tftpboot/master_images',
-               help='Directory where master tftp images are stored on disk.'),
+               help='On ironic-conductor node, directory where master TFTP '
+                    'images are stored on disk.'),
     # NOTE(dekehn): Additional boot files options may be created in the event
     #  other architectures require different boot files.
     cfg.StrOpt('pxe_bootfile_name',
@@ -76,18 +78,19 @@ pxe_opts = [
                default='elilo.efi',
                help='Bootfile DHCP parameter for UEFI boot mode.'),
     cfg.StrOpt('http_url',
-                help='Ironic compute node\'s HTTP server URL. '
+                help='ironic-conductor node\'s HTTP server URL. '
                      'Example: http://192.1.2.3:8080'),
     cfg.StrOpt('http_root',
                 default='/httpboot',
-                help='Ironic compute node\'s HTTP root path.'),
+                help='ironic-conductor node\'s HTTP root path.'),
     cfg.BoolOpt('ipxe_enabled',
                 default=False,
                 help='Enable iPXE boot.'),
     cfg.StrOpt('ipxe_boot_script',
                default=paths.basedir_def(
                     'drivers/modules/boot.ipxe'),
-               help='The path to the main iPXE script file.'),
+               help='On ironic-conductor node, the path to the main iPXE '
+                    'script file.'),
     ]
 
 LOG = logging.getLogger(__name__)

ironic/drivers/modules/ssh.py

@@ -46,7 +46,7 @@ from ironic.openstack.common import log as logging
 libvirt_opts = [
     cfg.StrOpt('libvirt_uri',
                default='qemu:///system',
-               help='libvirt uri')
+               help='libvirt URI')
 ]
 
 CONF = cfg.CONF

ironic/netconf.py

@@ -23,7 +23,9 @@ CONF = cfg.CONF
 netconf_opts = [
     cfg.StrOpt('my_ip',
                default=netutils.get_my_ipv4(),
-               help='IP address of this host.'),
+               help='IP address of this host. If unset, will determine the IP '
+                    'programmatically. If unable to do so, will use '
+                    '"127.0.0.1".'),
 ]
 
 CONF.register_opts(netconf_opts)