[Pkg-shadow-devel] Bug#1005253: Bug#1005253: shadow: Improved manual page useradd.8
Serge E. Hallyn
serge at hallyn.com
Fri Feb 11 17:13:45 GMT 2022
On Wed, Feb 09, 2022 at 11:18:04PM +0100, Markus Hiereth wrote:
> Source: shadow
> Version: 4.8.1
> Severity: normal
>
> Dear Serge,
>
> attached to this bugreport the improved file useradd.8.xml and a diff.
> A last check is certainly reasonable.
Thanks. The diff is especially helpful. Although a few of these hunks
appear to be just changes to the line breaks.
...
> --- shadow-4.8.1/man/useradd.8.xml 2020-01-17 16:47:56.000000000 +0100
> +++ shadow-4.8.1_mh/man/useradd.8.xml 2022-02-09 23:09:13.241687932 +0100
> @@ -143,11 +143,11 @@
> </term>
> <listitem>
> <para>
> - The default base directory for the system if <option>-d</option> <replaceable>HOME_DIR</replaceable> is not specified.
> - <replaceable>BASE_DIR</replaceable> is
> - concatenated with the account name to define the home directory.
> - If the <option>-m</option> option is not used,
> - <replaceable>BASE_DIR</replaceable> must exist.
> + The default base directory for the system if
> + <option>-d</option> <replaceable>HOME_DIR</replaceable>
> + is not specified. <replaceable>BASE_DIR</replaceable> is
> + concatenated with the account name to define the home
> + directory.
> </para>
> <para>
> If this option is not specified, <command>useradd</command>
> @@ -165,7 +165,7 @@
> <listitem>
> <para>
> Any text string. It is generally a short description of the
> - login, and is currently used as the field for the user's full
> + account, and is currently used as the field for the user's full
> name.
> </para>
> </listitem>
> @@ -177,12 +177,14 @@
> <listitem>
> <para>
> The new user will be created using
> - <replaceable>HOME_DIR</replaceable> as the value for the user's
> - login directory. The default is to append the
> + <replaceable>HOME_DIR</replaceable> as the value for the
> + user's login directory. The default is to append the
> <replaceable>LOGIN</replaceable> name to
> - <replaceable>BASE_DIR</replaceable> and use that as the login
> - directory name. The directory <replaceable>HOME_DIR</replaceable>
> - does not have to exist but will not be created if it is missing.
> + <replaceable>BASE_DIR</replaceable> and use that as the
> + login directory name. If the directory
> + <replaceable>HOME_DIR</replaceable> does not exist, then
> + it will be created unless the <option>-M</option> option
> + is specified.
> </para>
> </listitem>
> </varlistentry>
> @@ -219,14 +221,17 @@
> </term>
> <listitem>
> <para>
> - The number of days after a password expires until the account is
> - permanently disabled. A value of 0 disables the account as soon
> - as the password has expired, and a value of -1 disables the
> - feature.
> + defines the number of days after the password exceeded its maximum
> + age where the user is expected to replace this password. The value
How about 'number of days after the password exceeded its maximum age
during which the user may login by immediately replacing this password. The value
is stored in the shadow password file.'
> + is stored in the shadow password file. An input of 0 will disable an
> + expired password with no delay. An input of -1 will blank the
> + respective field in the shadow password file. See <citerefentry>
> + <refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum>
> + </citerefentry>for more information.
> </para>
> <para>
> If not specified, <command>useradd</command> will use the
> - default inactivity period specified by the
> + default inactivity onset specified by the
"onset" is weird here.
> <option>INACTIVE</option> variable in
> <filename>/etc/default/useradd</filename>, or -1 by default.
> </para>
> @@ -237,8 +242,9 @@
> <option>-g</option>, <option>--gid</option> <replaceable>GROUP</replaceable>
> </term>
> <listitem>
> + <!--MH35-->
This i assume is leftover marker to be dropped.
> <para>
> - The group name or number of the user's initial login group. The
> + The name or the number of the user's primary group. The
> group name must exist. A group number must refer to an already
> existing group.
> </para>
> @@ -249,7 +255,7 @@
> set to <replaceable>yes</replaceable> (or
> <option>-U/--user-group</option> is specified on the command
> line), a group will be created for the user, with the same
> - name as her loginname. If the variable is set to
> + name as the loginname. If the variable is set to
> <replaceable>no</replaceable> (or
> <option>-N/--no-user-group</option> is specified on the
> command line), useradd will set the primary group of the new
> @@ -315,14 +321,17 @@
> (<option>UID_MIN</option>, <option>UID_MAX</option>,
> <option>UMASK</option>, <option>PASS_MAX_DAYS</option>
> and others).
> - <para>
> </para>
> - Example: <option>-K</option> <replaceable>PASS_MAX_DAYS</replaceable>=<replaceable>-1</replaceable>
> - can be used when creating system account to turn off password
> - aging, even though system account has no password at all.
> - Multiple <option>-K</option> options can be specified, e.g.:
> - <option>-K</option> <replaceable>UID_MIN</replaceable>=<replaceable>100</replaceable>
> - <option>-K</option> <replaceable>UID_MAX</replaceable>=<replaceable>499</replaceable>
> + <para>
> + Example:
> + <option>-K</option> <replaceable>PASS_MAX_DAYS
> + </replaceable>=<replaceable>-1</replaceable> can be used
> + when creating an account to turn off password aging.
> + Multiple <option>-K</option> options can be specified,
> + e.g.:
> + <option>-K</option> <replaceable>UID_MIN</replaceable>
> + =<replaceable>100</replaceable> <option>-K</option>
> + <replaceable>UID_MAX</replaceable>=<replaceable>499</replaceable>
> </para>
> <!--para>
> Note: <option>-K</option> <replaceable>UID_MIN</replaceable>=<replaceable>10</replaceable>,<replaceable>UID_MAX</replaceable>=<replaceable>499</replaceable>
> @@ -398,10 +407,18 @@
> <option>-o</option>, <option>--non-unique</option>
> </term>
> <listitem>
> - <para>Allow the creation of a user account with a duplicate (non-unique) UID.</para>
> + <para>
> + allows the creation of an account with an already existing
> + UID.
> + </para>
> <para>
> This option is only valid in combination with the
> - <option>-u</option> option.
> + <option>-u</option> option. As a user identity
> + serves as
> + key to map between users on one hand and permissions, file
> + ownerships and other aspects that determine the system's
> + behavior on the other hand, more than one login name
> + will access the account of the given UID.
> </para>
> </listitem>
> </varlistentry>
> @@ -410,14 +427,25 @@
> <option>-p</option>, <option>--password</option> <replaceable>PASSWORD</replaceable>
> </term>
> <listitem>
> + <!--MH37-->
Drop this?
> <para>
> - The encrypted password, as returned by <citerefentry>
> - <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
> - </citerefentry>. The default is to disable the password.
> + defines an initial password for the account. PASSWORD is expected to
> + be encrypted, as returned by <citerefentry><refentrytitle>crypt
> + </refentrytitle><manvolnum>3</manvolnum></citerefentry>. Within a
> + shell script, this option allows to create efficiently
> + batches of users.
> </para>
> <para>
> - <emphasis role="bold">Note:</emphasis> This option is not
> - recommended because the password (or encrypted password) will
> + Without this option, the new account will be locked and
> + with no password defined, i.e. a single exclamation mark
> + in the respective field of
> + <filename>/etc/shadow</filename>. This is a state where the
> + user won't be able to access the account or to define a
> + password himself.
> + </para>
> + <para>
> + <emphasis role="bold">Note:</emphasis>Avoid this option on the command
> + line because the password (or encrypted password) will
> be visible by users listing the processes.
> </para>
> <para>
> @@ -488,11 +516,11 @@
> </term>
> <listitem>
> <para>
> - The name of the user's login shell. The default is to leave this
> - field blank, which causes the system to select the default login
> - shell specified by the <option>SHELL</option> variable in
> - <filename>/etc/default/useradd</filename>, or an empty string
> - by default.
> + sets the path to the user's login shell. Without this option,
> + the system will use the <option>SHELL</option> variable specified
> + in <filename>/etc/default/useradd</filename>, or, if that is as
> + well not set, the field for the login shell in <filename>/etc/passwd
> + </filename>remains empty.
> </para>
> </listitem>
> </varlistentry>
> @@ -533,13 +561,16 @@
> </varlistentry>
> <varlistentry>
> <term>
> - <option>-Z</option>, <option>--selinux-user</option> <replaceable>SEUSER</replaceable>
> + <option>-Z</option>, <option>--selinux
> + -user</option> <replaceable>SEUSER</replaceable>
Is the line break here accidental?
> </term>
> <listitem>
> <para>
> - The SELinux user for the user's login. The default is to leave this
> - field blank, which causes the system to select the default SELinux
> - user.
> + defines the SELinux user for the new account. Without this
> + option, a SELinux uses the default user. Note that the
s/a SELinux/SELinux/
> + shadow system doesn't store the selinux-user, it uses
> + <citerefentry><refentrytitle>semanage</refentrytitle>
> + <manvolnum>8</manvolnum></citerefentry> for that.
> </para>
> </listitem>
> </varlistentry>
> @@ -561,7 +592,7 @@
> </term>
> <listitem>
> <para>
> - The path prefix for a new user's home directory. The
> + The path prefix for new users' home directory. The
the 'a' is more natural in English.
> user's name will be affixed to the end of
> <replaceable>BASE_DIR</replaceable> to form the new user's
> home directory name, if the <option>-d</option> option is not used
> @@ -578,7 +609,8 @@
> <option>-e</option>, <option>--expiredate</option> <replaceable>EXPIRE_DATE</replaceable>
> </term>
> <listitem>
> - <para>The date on which the user account is disabled.</para>
> + <!--MH43-->
> + <para>The date on which newly created user accounts are disabled.</para>
> <para>
> This option sets the <option>EXPIRE</option> variable in
> <filename>/etc/default/useradd</filename>.
> @@ -590,9 +622,12 @@
> <option>-f</option>, <option>--inactive</option> <replaceable>INACTIVE</replaceable>
> </term>
> <listitem>
> + <!--MH44--><!--MH45-->
> <para>
> - The number of days after a password has expired before the
> - account will be disabled.
> + defines the number of days after the password exceeded its maximum
> + age where the user is expected to replace this password. See <citerefentry>
maybe s/is expected to replace/is allowed to login after replacing/ ?
> + <refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum>
> + </citerefentry>for more information.
> </para>
> <para>
> This option sets the <option>INACTIVE</option> variable in
> @@ -605,13 +640,9 @@
> <option>-g</option>, <option>--gid</option> <replaceable>GROUP</replaceable>
> </term>
> <listitem>
> - <para>
> - The group name or ID for a new user's initial group (when
> - the <option>-N/--no-user-group</option> is used or when the
> - <option>USERGROUPS_ENAB</option> variable is set to
> - <replaceable>no</replaceable> in
> - <filename>/etc/login.defs</filename>). The named
> - group must exist, and a numerical group ID must have an
> + <para>sets the default primary group for newly created users,
> + accepting group names or a numerical group ID. The named
> + group must exist, and the GID must have an
> existing entry.
I think this should still point out that this default only applies
when using --no-user-group/USERGROUPS_ENAB=no.
> </para>
> <para>
> @@ -625,8 +656,9 @@
> <option>-s</option>, <option>--shell</option> <replaceable>SHELL</replaceable>
> </term>
> <listitem>
> + <!--MH50-->
> <para>
> - The name of a new user's login shell.
> + defines the default login shell for new users.
> </para>
> <para>
> This option sets the <option>SHELL</option> variable in
> _______________________________________________
> Pkg-shadow-devel mailing list
> Pkg-shadow-devel at alioth-lists.debian.net
> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-shadow-devel
More information about the Pkg-shadow-devel
mailing list