From 52cfdabcb5de5c23a221be5ac88d0a832d5a4fea Mon Sep 17 00:00:00 2001 From: Marc Muehlfeld Date: Mon, 18 Jun 2018 12:07:48 +0200 Subject: Ticket 49793 - Updated descriptions in dscreate example INF file 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: ? --- src/lib389/lib389/cli_ctl/instance.py | 3 + src/lib389/lib389/instance/options.py | 80 ++++++++++++++------------- 2 files changed, 45 insertions(+), 38 deletions(-) diff --git a/src/lib389/lib389/cli_ctl/instance.py b/src/lib389/lib389/cli_ctl/instance.py index 507a457c8..268c66d44 100644 --- a/src/lib389/lib389/cli_ctl/instance.py +++ b/src/lib389/lib389/cli_ctl/instance.py @@ -79,6 +79,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) diff --git a/src/lib389/lib389/instance/options.py b/src/lib389/lib389/instance/options.py index 1dee6f5f0..0df06be38 100644 --- a/src/lib389/lib389/instance/options.py +++ b/src/lib389/lib389/instance/options.py @@ -90,12 +90,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 # @@ -109,32 +113,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 # @@ -149,144 +153,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): -- 2.17.1