pw.8: Use more appropriate mdoc macros

MFC after:	1 week
This commit is contained in:
Mateusz Piotrowski 2022-04-01 13:52:39 +02:00
parent 61e11ed9bd
commit 77fd0356ef

View File

@ -321,9 +321,9 @@ databases.
.El
.Sh USER OPTIONS
The following options apply to the
.Ar useradd
.Cm useradd
and
.Ar usermod
.Cm usermod
commands:
.Bl -tag -width "-G grouplist"
.It Oo Fl n Oc Ar name
@ -332,15 +332,16 @@ Required unless
is given.
Specify the user/account name.
In the case of
.Ar usermod
can be a uid.
.Cm usermod
can be a
.Ar uid .
.It Fl u Ar uid
Required if
.Ar name
is not given.
Specify the user/account numeric id.
In the case of
.Ar usermod
.Cm usermod
if paired with
.Ar name ,
changes the numeric id of the named user/account.
@ -349,22 +350,22 @@ Usually, only one of these options is required,
as the account name will imply the uid, or vice versa.
However, there are times when both are needed.
For example, when changing the uid of an existing user with
.Ar usermod ,
.Cm usermod ,
or overriding the default uid when creating a new account with
.Ar useradd .
.Cm useradd .
To automatically allocate the uid to a new user with
.Ar useradd ,
.Cm useradd ,
then do
.Em not
use the
.Fl u
option.
Either the account or userid can also be provided immediately after the
.Ar useradd ,
.Ar userdel ,
.Ar usermod
.Cm useradd ,
.Cm userdel ,
.Cm usermod ,
or
.Ar usershow
.Cm usershow
keywords on the command line without using the
.Fl n
or
@ -444,7 +445,7 @@ This option instructs
.Nm
to attempt to create the user's home directory.
While primarily useful when adding a new account with
.Ar useradd ,
.Cm useradd ,
this may also be of use when moving an existing user's home directory elsewhere
on the file system.
The new home directory is populated with the contents of the
@ -459,7 +460,7 @@ prefix will be stripped.
When
.Fl m
is used on an account with
.Ar usermod ,
.Cm usermod ,
existing configuration files in the user's home directory are
.Em not
overwritten from the skeleton files.
@ -469,7 +470,7 @@ it will by default be a subdirectory of the
.Ar basehome
directory as specified by the
.Fl b
option (see below), bearing the name of the new account.
option, bearing the name of the new account.
This can be overridden by the
.Fl d
option on the command line, if desired.
@ -556,7 +557,7 @@ suitable for writing directly to the password database.
.El
.Pp
It is possible to use
.Ar useradd
.Cm useradd
to create a new account that duplicates an existing user id.
While this is normally considered an error and will be rejected, the
.Fl o
@ -568,7 +569,7 @@ directory, different shell) while providing basically the same
permissions for access to the user's files in each account.
.Pp
The
.Ar useradd
.Cm useradd
command also has the ability to set new user and group defaults by using the
.Fl D
option.
@ -653,8 +654,8 @@ See description of
.Fl k
for naming conventions of these files.
.It Xo
.Fl u Ar min , Ns Ar max ,
.Fl i Ar min , Ns Ar max
.Fl u Ar min Ns Cm \&, Ns Ar max ,
.Fl i Ar min Ns Cm \&, Ns Ar max
.Xc
Set the minimum and maximum user and group ids allocated for new
accounts and groups created by
@ -678,20 +679,20 @@ accounts.
is one of:
.Pp
.Bl -tag -width random -offset indent -compact
.It no
.It Cm no
disable login on newly created accounts
.It yes
.It Cm yes
force the password to be the account name
.It none
.It Cm none
force a blank password
.It random
.It Cm random
generate a random password
.El
.Pp
The
.Ql \&random
.Cm random
or
.Ql \&no
.Cm no
methods are the most secure; in the former case,
.Nm
generates a password and prints it to stdout,
@ -700,7 +701,7 @@ to select their own
.Pq possibly poorly chosen
password.
The
.Ql \&no
.Cm no
method requires that the superuser use
.Xr passwd 1
to render the account accessible with a password.
@ -718,7 +719,7 @@ servers.
.El
.Pp
The
.Ar userdel
.Cm userdel
command has three distinct options.
The
.Fl n Ar name
@ -736,7 +737,9 @@ The
utility errs on the side of caution when removing files from the system.
Firstly,
it will not do so if the uid of the account being removed is also used by
another account on the system, and the 'home' directory in the password file is
another account on the system, and the
.Dq home
directory in the password file is
a valid path that commences with the character
.Ql \&/ .
Secondly, it will only remove files and directories that are actually owned by
@ -746,26 +749,28 @@ will be removed.
If any additional cleanup work is required, this is left to the administrator.
.El
.Pp
Mail spool files and crontabs are always removed when an account is deleted as
Mail spool files and
.Xr crontab 5
files are always removed when an account is deleted as
these are unconditionally attached to the user name.
Jobs queued for processing by
.Ar at
.Xr at 1
are also removed if the user's uid is unique and not also used by another
account on the system.
.Pp
The
.Ar usermod
.Cm usermod
command adds one additional option:
.Bl -tag -width "-G grouplist"
.It Fl l Ar newname
This option allows changing of an existing account name to
.Ql \&newname .
.Ar newname .
The new name must not already exist, and any attempt to duplicate an
existing account name will be rejected.
.El
.Pp
The
.Ar usershow
.Cm usershow
command allows viewing of an account in one of two formats.
By default, the format is identical to the format used in
.Pa /etc/master.passwd
@ -789,7 +794,7 @@ forces
to print the details of an account even if it does not exist.
.Pp
The command
.Ar usernext
.Cm usernext
returns the next available user and group ids separated by a colon.
This is normally of interest only to interactive scripts or front-ends
that use
@ -809,7 +814,7 @@ Required unless
is given.
Specify the group name.
In the case of
.Ar groupmod
.Cm groupmod
can be a gid.
.It Fl g Ar gid
Required if
@ -817,7 +822,7 @@ Required if
is not given.
Specify the group numeric id.
In the case of
.Ar groupmod
.Cm groupmod
if paired with
.Ar name ,
changes the numeric id of the named group.
@ -829,8 +834,10 @@ You will only need to use both when setting a specific group id
against a new group or when changing the uid of an existing group.
.It Fl M Ar memberlist
This option provides an alternative way to add existing users to a
new group (in groupadd) or replace an existing membership list (in
groupmod).
new group
.Pq in Cm groupadd
or replace an existing membership list
.Pq in Cm groupmod .
.Ar memberlist
is a comma separated list of valid and existing user names or uids.
.It Fl m Ar newmembers
@ -853,7 +860,7 @@ Login names or user ids may be used, and duplicate users are
silently eliminated.
.El
.Pp
.Ar groupadd
.Cm groupadd
also has a
.Fl o
option that allows allocation of an existing group id to a new group.
@ -862,21 +869,21 @@ and this option overrides the check for duplicate group ids.
There is rarely any need to duplicate a group id.
.Pp
The
.Ar groupmod
.Cm groupmod
command adds one additional option:
.Bl -tag -width "-m newmembers"
.It Fl l Ar newname
This option allows changing of an existing group name to
.Ql \&newname .
.Ar newname .
The new name must not already exist,
and any attempt to duplicate an existing group
name will be rejected.
.El
.Pp
Options for
.Ar groupshow
.Cm groupshow
are the same as for
.Ar usershow ,
.Cm usershow ,
with the
.Fl g Ar gid
replacing
@ -885,11 +892,11 @@ to specify the group id.
The
.Fl 7
option does not apply to the
.Ar groupshow
.Cm groupshow
command.
.Pp
The command
.Ar groupnext
.Cm groupnext
returns the next available group id on standard output.
.Sh USER LOCKING
The
@ -899,13 +906,13 @@ supports a simple password locking mechanism for users; it works by
prepending the string
.Ql *LOCKED*
to the beginning of the password field in
.Pa master.passwd
.Xr master.passwd 5
to prevent successful authentication.
.Pp
The
.Ar lock
.Cm lock
and
.Ar unlock
.Cm unlock
commands take a user name or uid of the account to lock or unlock,
respectively.
The
@ -919,7 +926,9 @@ For a summary of options available with each command, you can use
.Dl pw [command] help
For example,
.Dl pw useradd help
lists all available options for the useradd operation.
lists all available options for the
.Cm useradd
operation.
.Pp
The
.Nm