Ticket 49793 - Updated descriptions in dscreate example INF file

Description: This patch changes the format of the "dscreate example"
             output to:

                 parameter_name (type) [REQUIRED|optional]
                 Description: ...
                 Default value: ...

             Additionally, the patch updates the parameter descriptions
             to be more descriptive.

https://pagure.io/389-ds-base/issue/49793

Reviewed by: mreynolds

Signed-off-by: Mark Reynolds <[email protected]>

src/lib389/lib389/cli_ctl/instance.py

@@ -84,6 +84,9 @@ def instance_example(inst, log, args):
 ;
 ; The special value {instance_name} is substituted at installation time.
 ;
+; By default, all configuration parameters in this file are commented out.
+; To use an INF file with dscreate, you must at least set the parameters
+; flagged with [REQUIRED].
 
     """
     g2b = General2Base(log)

src/lib389/lib389/instance/options.py

@@ -92,12 +92,16 @@ class Options2(object):
     def collect_help(self):
         helptext = "[%s]\n" % self._section
         for k in sorted(self._options.keys()):
-            helptext += "# %s: %s\n" % (k, self._helptext[k])
-            helptext += "# type: %s\n" % (self._type[k].__name__)
             if self._example_comment[k]:
-                helptext += "; %s = %s\n\n" % (k, self._options[k])
+                helptext += "# %s (%s) [optional]\n" % (k, self._type[k].__name__)
+                helptext += "# Description: %s\n" % (self._helptext[k])
+                helptext += "# Default value: %s \n" % (self._options[k])
+                helptext += ";%s = %s\n\n" % (k, self._options[k])
             else:
-                helptext += "%s = %s\n\n" % (k, self._options[k])
+                helptext += "# %s (%s) [REQUIRED]\n" % (k, self._type[k].__name__)
+                helptext += "# Description: %s\n" % (self._helptext[k])
+                helptext += "# Default value: %s \n" % (self._options[k])
+                helptext += ";%s = %s\n\n" % (k, self._options[k])
         return helptext
 
 #
@@ -112,32 +116,32 @@ class General2Base(Options2):
 
         self._options['config_version'] = 2
         self._type['config_version'] = int
-        self._helptext['config_version'] = "The format version of the inf answer file."
+        self._helptext['config_version'] = "Sets the format version of this INF file. To use the INF file with dscreate, you must set this parameter to \"2\"."
         self._example_comment['config_version'] = False
 
         self._options['full_machine_name'] = socket.gethostname()
         self._type['full_machine_name'] = str
-        self._helptext['full_machine_name'] = "The fully qualified hostname of this system."
+        self._helptext['full_machine_name'] = "Sets the fully qualified hostname (FQDN) of this system. When installing this instance with GSSAPI authentication behind a load balancer, set this parameter to the FQDN of the load balancer and, additionally, set \"strict_host_checking\" to \"false\"."
         self._example_comment['full_machine_name'] = False
 
         self._options['strict_host_checking'] = True
         self._type['strict_host_checking'] = bool
-        self._helptext['strict_host_checking'] = "If true, will validate forward and reverse dns names for full_machine_name"
+        self._helptext['strict_host_checking'] = "Sets whether the server verifies the forward and reverse record set in the \"full_machine_name\" parameter. When installing this instance with GSSAPI authentication behind a load balancer, set this parameter to \"false\"."
         self._example_comment['strict_host_checking'] = True
 
         self._options['selinux'] = True
         self._type['selinux'] = bool
-        self._helptext['selinux'] = "Enable SELinux detection and integration. Normally, this should always be True, and will correctly detect when SELinux is not present."
+        self._helptext['selinux'] = "Enables SELinux detection and integration during the installation of this instance. If set to \"True\", dscreate auto-detects whether SELinux is enabled. Set this parameter only to \"False\" in a development environment."
         self._example_comment['selinux'] = True
 
         self._options['systemd'] = ds_paths.with_systemd
         self._type['systemd'] = bool
-        self._helptext['systemd'] = "Enable systemd platform features. This is autodetected on your platform. You should not alter this value without good reason."
+        self._helptext['systemd'] = "Enables systemd platform features. If set to \"True\", dscreate auto-detects whether systemd is installed. Set this only to \"False\" in a development environment."
         self._example_comment['systemd'] = True
 
         self._options['defaults'] = INSTALL_LATEST_CONFIG
         self._type['defaults'] = str
-        self._helptext['defaults'] = "Set the configuration defaults version. If set to %{LATEST}, always use the latest values available for the slapd section. This allows pinning default values in cn=config to specific Directory Server releases. This maps to our versions such as 1.3.5 -> 001003005. The leading 0's are important.".format(LATEST=INSTALL_LATEST_CONFIG)
+        self._helptext['defaults'] = "Directory Server enables administrators to use the default values for cn=config entries from a specific version. If you set this parameter to \"{LATEST}\", which is the default, the instance always uses the default values of the latest version. For example, to configure that the instance uses default values from version 1.3.5, set this parameter to \"001003005\". The format of this value is XXXYYYZZZ, where X is the major version, Y the minor version, and Z the patch level. Note that each part of the value uses 3 digits and must be filled with leading zeros if necessary.".format(LATEST=INSTALL_LATEST_CONFIG)
         self._example_comment['defaults'] = True
 
 #
@@ -153,144 +157,144 @@ class Slapd2Base(Options2):
 
         self._options['instance_name'] = 'localhost'
         self._type['instance_name'] = str
-        self._helptext['instance_name'] = "The name of the instance. Cannot be changed post installation."
+        self._helptext['instance_name'] = "Sets the name of the instance. You can refer to this value in other parameters of this INF file using the \"{instance_name}\" variable. Note that this name cannot be changed after the installation!"
         self._example_comment['instance_name'] = False
 
         self._options['user'] = ds_paths.user
         self._type['user'] = str
-        self._helptext['user'] = "The user account ns-slapd will drop privileges to during operation."
+        self._helptext['user'] = "Sets the user name the ns-slapd process will use after the service started."
         self._example_comment['user'] = True
 
         self._options['group'] = ds_paths.group
         self._type['group'] = str
-        self._helptext['group'] = "The group ns-slapd will drop privilleges to during operation."
+        self._helptext['group'] = "Sets the group name the ns-slapd process will use after the service started."
         self._example_comment['group'] = True
 
         self._options['root_dn'] = ds_paths.root_dn
         self._type['root_dn'] = str
-        self._helptext['root_dn'] = "The Distinquished Name of the Administrator account. This is equivalent to root of your Directory Server."
+        self._helptext['root_dn'] = "Sets the Distinquished Name (DN) of the administrator account for this instance."
         self._example_comment['root_dn'] = True
 
         self._options['root_password'] = 'directory manager password'
         self._type['root_password'] = str
-        self._helptext['root_password'] = "The password for the root_dn account. "
+        self._helptext['root_password'] = "Sets the password of the account specified in the \"root_dn\" parameter. You can either set this parameter to a plain text password dscreate hashes during the installation or to a \"{algorithm}hash\" string generated by the pwdhash utility. Note that setting a plain text password can be a security risk if unprivileged users can read this INF file!"
         self._example_comment['root_password'] = False
 
         self._options['prefix'] = ds_paths.prefix
         self._type['prefix'] = str
-        self._helptext['prefix'] = "The filesystem prefix for all other locations. Unless you are developing DS, you likely never need to set this. This value can be reffered to in other fields with {prefix}, and can be set with the environment variable PREFIX."
+        self._helptext['prefix'] = "Sets the file system prefix for all other directories. You can refer to this value in other fields using the {prefix} variable or the $PREFIX environment variable. Only set this parameter in a development environment."
         self._example_comment['prefix'] = True
 
         self._options['port'] = 389
         self._type['port'] = int
-        self._helptext['port'] = "The TCP port that Directory Server will listen on for LDAP connections."
+        self._helptext['port'] = "Sets the TCP port the instance uses for LDAP connections."
         self._example_comment['port'] = True
 
         self._options['secure_port'] = 636
         self._type['secure_port'] = int
-        self._helptext['secure_port'] = "The TCP port that Directory Server will listen on for TLS secured LDAP connections."
+        self._helptext['secure_port'] = "Sets the TCP port the instance uses for TLS-secured LDAP connections (LDAPS)."
         self._example_comment['secure_port'] = True
 
         self._options['self_sign_cert'] = True
         self._type['self_sign_cert'] = bool
-        self._helptext['self_sign_cert'] = "Issue a self signed certificate during the setup process. This is not suitable for production TLS, but aids simplifying setup of TLS (you only need to replace a certificate instead)"
+        self._helptext['self_sign_cert'] = "Sets whether the setup creates a self-signed certificate and enables TLS encryption during the installation. This is not suitable for production, but it enables administrators to use TLS right after the installation. You can replace the self-signed certificate with a certificate issued by a Certificate Authority."
         self._example_comment['self_sign_cert'] = True
 
         self._options['self_sign_cert_valid_months'] = 24
         self._type['self_sign_cert_valid_months'] = int
-        self._helptext['self_sign_cert_valid_months'] = "Set a number of months for which the self signed cert will be issued."
+        self._helptext['self_sign_cert_valid_months'] = "Set the number of months the issued self-signed certificate will be valid."
         self._example_comment['self_sign_cert_valid_months'] = True
 
         # In the future, make bin and sbin /usr/[s]bin, but we may need autotools assistance from Ds
         self._options['bin_dir'] = ds_paths.bin_dir
         self._type['bin_dir'] = str
-        self._helptext['bin_dir'] = "The location Directory Server can find binaries. You should not need to alter this value."
+        self._helptext['bin_dir'] = "Sets the location where the Directory Server binaries are stored. Only set this parameter in a development environment."
         self._example_comment['bin_dir'] = True
 
         self._options['sbin_dir'] = ds_paths.sbin_dir
         self._type['sbin_dir'] = str
-        self._helptext['sbin_dir'] = "The location Directory Server can find systemd administration binaries. You should not need to alter this value."
+        self._helptext['sbin_dir'] = "Sets the location where the Directory Server administration binaries are stored. Only set this parameter in a development environment."
         self._example_comment['sbin_dir'] = True
 
         self._options['sysconf_dir'] = ds_paths.sysconf_dir
         self._type['sysconf_dir'] = str
-        self._helptext['sysconf_dir'] = "The location of the system configuration directory. You should not need to alter this value."
+        self._helptext['sysconf_dir'] = "Sets the location of the system's configuration directory. Only set this parameter in a development environment."
         self._example_comment['sysconf_dir'] = True
 
         self._options['initconfig_dir'] = ds_paths.initconfig_dir
         self._type['initconfig_dir'] = str
-        self._helptext['initconfig_dir'] = "The location of the system rc configuration directory. You should not need to alter this value."
+        self._helptext['initconfig_dir'] = "Sets the directory of the operating system's rc configuration directory. Only set this parameter in a development environment."
         self._example_comment['initconfig_dir'] = True
 
         # In the future, make bin and sbin /usr/[s]bin, but we may need autotools assistance from Ds
         self._options['data_dir'] = ds_paths.data_dir
         self._type['data_dir'] = str
-        self._helptext['data_dir'] = "The location of shared static data. You should not need to alter this value."
+        self._helptext['data_dir'] = "Sets the location of Directory Server shared static data. Only set this parameter in a development environment."
         self._example_comment['data_dir'] = True
 
         self._options['local_state_dir'] = ds_paths.local_state_dir
         self._type['local_state_dir'] = str
-        self._helptext['local_state_dir'] = "The location prefix to variable data. You should not need to alter this value."
+        self._helptext['local_state_dir'] = "Sets the location of Directory Server variable data. Only set this parameter in a development environment."
         self._example_comment['local_state_dir'] = True
 
         self._options['lib_dir'] = ds_paths.lib_dir
         self._type['lib_dir'] = str
-        self._helptext['lib_dir'] = "The location to Directory Server shared libraries. You should not need to alter this value."
+        self._helptext['lib_dir'] = "Sets the location of Directory Server shared libraries. Only set this parameter in a development environment."
         self._example_comment['lib_dir'] = True
 
         self._options['cert_dir'] = ds_paths.cert_dir
         self._type['cert_dir'] = str
-        self._helptext['cert_dir'] = "The location where NSS will store certificates."
+        self._helptext['cert_dir'] = "Sets the directory of the instance's Network Security Services (NSS) database."
         self._example_comment['cert_dir'] = True
 
         self._options['config_dir'] = ds_paths.config_dir
         self._type['config_dir'] = str
-        self._helptext['config_dir'] = "The location where dse.ldif and other configuration will be stored. You should not need to alter this value."
+        self._helptext['config_dir'] = "Sets the configuration directory of the instance."
         self._example_comment['config_dir'] = True
 
         self._options['inst_dir'] = ds_paths.inst_dir
         self._type['inst_dir'] = str
-        self._helptext['inst_dir'] = "The location of the Directory Server databases, ldif and backups. You should not need to alter this value."
+        self._helptext['inst_dir'] = "Sets the directory of instance-specific scripts."
         self._example_comment['inst_dir'] = True
 
         self._options['backup_dir'] = ds_paths.backup_dir
         self._type['backup_dir'] = str
-        self._helptext['backup_dir'] = "The location where Directory Server will export and import backups from. You should not need to alter this value."
+        self._helptext['backup_dir'] = "Set the backup directory of the instance."
         self._example_comment['backup_dir'] = True
 
         self._options['db_dir'] = ds_paths.db_dir
         self._type['db_dir'] = str
-        self._helptext['db_dir'] = "The location where Directory Server will store databases. You should not need to alter this value."
+        self._helptext['db_dir'] = "Sets the database directory of the instance."
         self._example_comment['db_dir'] = True
 
         self._options['ldif_dir'] = ds_paths.ldif_dir
         self._type['ldif_dir'] = str
-        self._helptext['ldif_dir'] = "The location where Directory Server will export and import ldif from. You should not need to alter this value."
+        self._helptext['ldif_dir'] = "Sets the LDIF export and import directory of the instance."
         self._example_comment['ldif_dir'] = True
 
         self._options['lock_dir'] = ds_paths.lock_dir
         self._type['lock_dir'] = str
-        self._helptext['lock_dir'] = "The location where Directory Server will store lock files. You should not need to alter this value."
+        self._helptext['lock_dir'] = "Sets the lock directory of the instance."
         self._example_comment['lock_dir'] = True
 
         self._options['log_dir'] = ds_paths.log_dir
         self._type['log_dir'] = str
-        self._helptext['log_dir'] = "The location where Directory Server will write log files. You should not need to alter this value."
+        self._helptext['log_dir'] = "Sets the log directory of the instance."
         self._example_comment['log_dir'] = True
 
         self._options['run_dir'] = ds_paths.run_dir
         self._type['run_dir'] = str
-        self._helptext['run_dir'] = "The location where Directory Server will create pid files. You should not need to alter this value."
+        self._helptext['run_dir'] = "Sets PID directory of the instance."
         self._example_comment['run_dir'] = True
 
         self._options['schema_dir'] = ds_paths.schema_dir
         self._type['schema_dir'] = str
-        self._helptext['schema_dir'] = "The location where Directory Server will store and write schema. You should not need to alter this value."
+        self._helptext['schema_dir'] = "Sets schema directory of the instance."
         self._example_comment['schema_dir'] = True
 
         self._options['tmp_dir'] = ds_paths.tmp_dir
         self._type['tmp_dir'] = str
-        self._helptext['tmp_dir'] = "The location where Directory Server will write temporary files. You should not need to alter this value."
+        self._helptext['tmp_dir'] = "Sets the temporary directory of the instance."
         self._example_comment['tmp_dir'] = True
 
     def _format(self, d):