From 52cfdabcb5de5c23a221be5ac88d0a832d5a4fea Mon Sep 17 00:00:00 2001
From: Marc Muehlfeld <mmuehlfeld@redhat.com>
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
Attached a new patch with updated header that follows the project's
conventions.
Ticket: https://pagure.io/389-ds-base/issue/49793
Regards,
Marc
On 18.06.2018 12:51, Marc Muehlfeld wrote:
> Hi,
>
> with regard to documentation, I made some changes to the "dscreate
> example" output:
>
> 1) I slightly changed the format of the comments to:
> parameter_name (type) [REQUIRED|optional]
> Description: ...
> Default value: ...
>
> 2) I rewrote the parameter descriptions. They should be now
> more clear.
>
> 3) By default, all parameters are now commented out. I added a note
> to the intro that the [REQUIRED]-flagged parameters must be
> set.
>
> With these changes, writing the documentation simplifies:
> * I can tell in the docs to uncomment the [REQUIRED]
> parameters and set them to have a minimal INF file.
> Previously, it was harder to to identify the required
> parameters (the ones which were not commented out).
> * Instead of describing the parameters in the RH docs, I can
> now refer to the "dscreate example" output, because the
> descriptions should be more detailed.
>
> Please review the attached patch and push. Thanks.
>
>
> Regards,
> Marc
>
>
>
>
>
> _______________________________________________
> 389-devel mailing list -- 389-devel@lists.fedoraproject.org
> To unsubscribe send an email to 389-devel-leave@lists.fedoraproject.org
> Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html
> List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
> List Archives: https://lists.fedoraproject.org/archives/list/389-devel@lists.fedoraproject.org/message/FGTFMLU5U5QBHTI5WSEADLVAWDFWN7YR/
>
--
Marc Muehlfeld
Senior Technical Writer, Customer Content Services
Red Hat GmbH
Technopark II,
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
Email: mmuehlfeld@redhat.com
_______________________________________________________________________________
Red Hat GmbH, http://www.de.redhat.com/, Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Michael Cunningham,
Michael O'Neill, Eric Shander
No comments:
Post a Comment