pw(8) -- a backend utility to manage the user and group databases.

sysinstall's new User&group menu will use it, hence it's a 2.2
candidate despite of providing new functionality.

Submitted by:	David L. Nugent, <davidn@blaze.net.au>

1 files changed, 648 insertions, 0 deletions

diff --git a/pw/pw.8 b/pw/pw.8
new file mode 100644
index 0000000..c7b021d
--- /dev/null
+++ b/pw/pw.8
@@ -0,0 +1,648 @@
+.\" Copyright (c) 1996
+.\"	David L. Nugent.
+.\"	Password Maintenance
+.\"
+.\"	$Id: pw.8,v 1.3 1996/11/18 03:09:01 davidn Exp $
+.\"
+.Dd November 13, 1996
+.Dt PW 8
+.Os
+.Sh NAME
+.Nm pw
+.Nd create, remove and modify system users and groups
+.Sh SYNOPSIS
+.Nm pw
+.Ar useradd
+.Op name|uid
+.Op Fl C Ar config
+.Op Fl q
+.Op Fl n Ar name
+.Op Fl u Ar uid
+.Op Fl c Ar comment
+.Op Fl d Ar dir
+.Op Fl e Ar date
+.Op Fl p Ar date
+.Op Fl g Ar group
+.Op Fl G Ar grouplist
+.Op Fl m
+.Op Fl k Ar dir
+.Op Fl s Ar shell
+.Op Fl o
+.Op Fl L Ar class
+.Op Fl h Ar fd
+.Nm pw
+.Ar useradd
+.Op name|uid
+.Op Fl D
+.Op Fl C Ar config
+.Op Fl q
+.Op Fl b Ar dir
+.Op Fl e Ar days
+.Op Fl p Ar days
+.Op Fl g Ar group
+.Op Fl G Ar grouplist
+.Op Fl k Ar dir
+.Op Fl u Ar min,max
+.Op Fl i Ar min,max
+.Op Fl w Ar method
+.Op Fl s Ar shell
+.Nm pw
+.Ar userdel
+.Op name|uid
+.Op Fl n Ar name
+.Op Fl u Ar uid
+.Op Fl r
+.Nm pw
+.Ar usermod
+.Op name|uid
+.Op Fl C Ar config
+.Op Fl q
+.Op Fl n Ar name
+.Op Fl u Ar uid
+.Op Fl c Ar comment
+.Op Fl d Ar dir
+.Op Fl e Ar date
+.Op Fl p Ar date
+.Op Fl g Ar group
+.Op Fl G Ar grouplist
+.Op Fl l Ar name
+.Op Fl m
+.Op Fl k Ar dir
+.Op Fl s Ar shell
+.Op Fl L Ar class
+.Op Fl h Ar fd
+.Nm pw
+.Ar usershow
+.Op name|uid
+.Op Fl n Ar name
+.Op Fl u Ar uid
+.Op Fl F
+.Op Fl p
+.Op Fl a
+.Nm pw
+.Ar groupadd
+.Op group|gid
+.Op Fl C Ar config
+.Op Fl q
+.Op Fl n Ar group
+.Op Fl g Ar gid
+.Op Fl o
+.Op Fl h Ar fd
+.Nm pw
+.Ar groupdel
+.Op Fl n Ar name
+.Op Fl g Ar gid
+.Nm pw
+.Ar groupmod
+.Op Fl C Ar config
+.Op Fl q
+.Op Fl F
+.Op Fl n Ar name
+.Op Fl g Ar gid
+.Op Fl l Ar name
+.Op Fl h Ar fd
+.Nm pw
+.Ar groupshow
+.Op Fl n Ar name
+.Op Fl g Ar gid
+.Op Fl F
+.Op Fl p
+.Op Fl a
+.Sh DESCRIPTION
+.Nm pw
+is a command-line based editor for the system
+.Em user
+and
+.Em group
+files, allowing the superuser and easy to use and standardised way of adding,
+modifying and removing users and groups.
+Note that
+.Nm pw
+only operates on the local user and group files; NIS users and groups must be
+maintained on the NIS server.
+.Nm pw
+handles updating the passwd, master.passwd, group and the secure and insecure
+password database files, and must be run as root.
+.Pp
+The first one or two keywords provided on
+.Xr pw 8 's
+command line provide the context for the remainder of the arguments.
+One of the keywords
+.Ar user
+and
+.Ar group
+may be combined or provided separately with
+.Ar add ,
+.Ar del ,
+.Ar mod
+or
+.Ar show ,
+and may be specified in either order (ie. showuser, usershow, show user and user show
+are all considered to be the same thing).
+This flexiblity is useful for interactive scripts which call
+.Nm pw 
+for the actual user and group database manipulation.
+Following these keywords, you may optionally specify the user or group name or numeric
+id as an alternative to using the
+.Fl n Ar name ,
+.Fl u Ar uid ,
+.Fl g Ar gid
+switches.
+.Pp
+The following flags are common to most modes of operation:
+.Pp
+.Bl -tag -width "-C config"
+.It Fl C Ar config
+By default,
+.Nm pw
+reads the file
+.Pa /etc/pw.conf
+to obtain policy information on how new user accounts and groups are to be created,
+and the
+.Fl c
+option overrides this to read a different file.
+Most of the contents in the configuration file may be overridden via command line
+options, but it may be more useful to set up standard information for addition of
+new accounts in the configuration
+file.
+.It Fl q
+Use of this option causes
+.Nm pw
+to suppress error messages, which may be useful in interactive environments where it
+is preferable to interpret status codes returned by
+.Nm pw
+rather than messing up a carefully formatted display.
+.El
+.Pp
+.Sh USER OPTIONS
+The following options apply to the
+.Ar useradd ,
+and
+.Ar usermod ,
+commands:
+.Pp
+.Bl -tag -width "-C config"
+.It Fl n Ar name
+Specifies the user/account name.
+.It Fl u Ar uid
+Specifies the user/account numeric id.
+.Pp
+Usually, you need only to provide one or the other of these options, as the account
+name will imply the uid, and vice verca.
+Also, you may provide either the account or userid immediately after the
+.Ar useradd ,
+.Ar userdel ,
+.Ar usermod
+or
+.Ar usershow
+keyword on the command line without the need to use
+.Ql Fl n
+or
+.Ql Fl u .
+There are times, however, were you need to provide both.
+For example, when changing the uid of an existing user with
+.Ar usermod ,
+or overriding the default uid when creating a new account.
+If you wish
+.Nm pw
+to automatically allocate the uid to a new user on
+.Ar useradd ,
+then you should
+.Em not
+use the
+.Ql Fl u
+switch.
+.El
+.Pp
+Options available with both
+.Ar useradd
+and
+.Ar usermod
+are:
+.Bl -tag -width "-G grouplist"
+.It Fl c Ar comment
+This field sets the contents of the passwd GECOS field, which normally contains up
+to four comma-separated fields containing the user's full name, office or location,
+work and home phone numbers.
+These sub-fields are used by convention only, however, and are optional.
+If this field is to contain spaces, you need to quote the comment itself with double
+quotes
+.Ql \&" .
+Avoid using commas in this field as these are used as sub-field separators, and the
+colon
+.Ql \&:
+character also cannot be used as this is the field separator in the passwd file.
+.It Fl d Ar dir
+This option sets the account's home directory.
+Normally, you will only use this if the home directory is to be different from the
+default (which is determined from pw.conf, which specifies the base home directory
+- normally /home - with the account name as a subdirectory).
+.It Fl e Ar date
+Sets the account's expiration date. 
+Format of the date is either a UNIX time in decimal, or a date in
+.Ql \& dd-mmm-yy[yy]
+format, where dd is the day, mmm is the month, either in numeric or alphabetic format
+('Jan', 'Feb' etc) and year is either a two or four digit year.
+This option also accepts a relative date in the form
+.Ql \&+n[mhdwoy]
+where
+.Ql \&n
+is a decimal, octal (leading 0) or hexadecimal (leading 0x) digit followed by the
+number of Minutes, Hours, Days, Weeks, mOnths or Years from the current date at
+which the expiry date is to be set.
+.It Fl p Ar date
+Sets the account's password expiration date.
+This field is identical to the account expiration date option, except that it
+applies to forced password changes.
+The same formats are accepted as with the account expiratino option.
+.It Fl g Ar group
+Sets the account's primary group to the given group.
+.Ar group
+may be either the group name or its corresponding group id number.
+.It Fl G Ar grouplist
+Sets the additional groups to which an account belongs.
+.Ar grouplist
+is a comma-separated list or group names or group ids.
+When adding a user, the user's name is added to the group lists in
+.Pa /etc/group ,
+and when editing a user, the user's name is also added to the group lists, and
+removed from any groups not specified in
+.Ar grouplist .
+Note: a user should not be added to their primary group in
+.Pa /etc/group .
+Also, group membership changes do not take effect immediately for current logins,
+only logins subsequent to the change.
+.It Fl m
+This option instructs
+.Nm pw
+to attempt to create the user's home directory.
+While primarily useful when adding a new account with
+.Ar useradd ,
+this may also be of use when moving an existing user's home directory elsewhere on
+the filesystem.
+The new home directory is populated with the contents of the
+.Ar skeleton
+directory, which typically contains a set of shell configuration files that the
+user may personalise to taste.
+When
+.Ql Fl m
+is used on an account with
+.Ar usermod ,
+any existing configuration files in the user's home directory are
+.Em not
+overwritten with the prototype files.
+.Pp
+When a user's home directory is created, it will be default be as a subdirectory of the
+.Ar basehome
+directory specified with the
+.Ql Fl b Ar dir
+option (see below), and will be named the same as the account.
+This may be overridden with the
+.Ql Fl d Ar dir
+option on the command line, if desired.
+.It Fl k Ar dir
+Sets the
+.Ar skeleton
+subdirectory, from which the basic startup and configuration files are copied when
+the user's home directory is created.
+This option only has meaning when used with
+.Ql Fl D
+(see below) or
+.Ql Fl m .
+.It Fl s Ar shell
+Sets or changes the user's login shell to
+.Ar shell .
+If the path to the shell program is omitted,
+.Nm pw
+searches the
+.Ar shellpath
+specified in
+.Pa /etc/pw.conf
+and fills it in as appropriate.
+Note that unless you have a specific reason to do so, you should avoid
+specifying the path - this will allow
+.Nm pw
+to validate that the program exists and is executable.
+Specifying a full path (or supplying a blank "" shell) avoids this check
+and allows for such entries as
+.Ql \& /nonexistent
+that should be set for accounts not intended for interactive login.
+.It Fl L Ar class
+Sets the
+.Em class
+field in the user's passwd record.
+This field is not currently used, but will be in the future used to specify a
+.Em termcap
+entry like tag (see
+.Xr passwd 5
+for details).
+.It Fl h Ar fd
+This option provides a special interface by which interactive scripts can
+set an account password using
+.Nm pw .
+Because the command line and environment are fundamental insecure mechanisms
+by which programs can accept information,
+.Nm pw
+will only allow setting of account and group passwords via a file descriptor
+(usually a pipe between an interactive script and the program).
+.Ar sh ,
+.Ar bash ,
+.Ar ksh
+and
+.Ar perl
+all posses mechanisms by which this can be done.
+Alternatively,
+.Nm pw
+will prompt for the user's password if
+.Ql Fl h Ar 0
+is given, nominating
+.Em stdin
+as the file descriptor on which to read the password.
+Note that this password will be read once and once only and is intended
+for use by a script or similar rather than interactive use.
+If you wish to have new password confirmation along the lines of
+.Xr passwd 1 ,
+this must be implemented as part of the interactive script that calls
+.Nm pw .
+.Pp
+If a value of
+.Ql \&-
+is given as the argument
+.Ar fd ,
+then the password will be set to
+.Ql \&* ,
+rendering the account inaccessible via passworded login.
+.El
+.Pp
+It is possible to use
+.Ar useradd
+to create a new account that duplicates an existing user id.
+While this is normally considered an error and will be rejected, the
+.Ql Fl o
+switch overrides the check for duplicates and allows the duplication of the user id.
+This may be useful if you allow the same user to login under different contexts
+(different group allocations, different home directory, different shell) while
+providing basically the same permissions for access to the user's files in each
+account.
+.Pp
+The
+.Ar useradd
+command also has the ability to set new user and group defaults by using the
+.Ql Fl D
+switch.
+Instead of adding a new user,
+.Nm pw
+writes a new set of defaults to its configuration file,
+.Pa /etc/pw.conf .
+When using the
+.Ql Fl D
+switch, you must not use either
+.Ql Fl n Ar name
+or
+.Ql Fl u Ar uid
+or an error will result.
+Use of
+.Ql Fl D
+adds switches and changes the meaning of several command line switches in the
+.Ar useradd
+command.
+These are:
+.Bl -tag -width "-G grouplist"
+.It Fl D
+Set default values in
+.Pa /etc/pw.conf
+configuration file, or a different named configuration file if the
+.Ql Fl C Ar config
+switch is used.
+.It Fl b Ar dir
+Sets the root directory in which user home directories are created.
+The default value for this is
+.Ql \&/home ,
+but it may be set elsewhere as desired.
+.It Fl e Ar days
+Sets the default account expiration period in days.
+Unlike use without
+.Ql Fl D ,
+the argument must be numeric, which specifies the number of days after creation when
+the account is to expire.
+A value of 0 suppresses automatic calculation of the expiry date.
+.It Fl p Ar days
+Sets the default password expiration period in days.
+.It Fl g Ar group
+Sets the default group for new users.
+If a blank group is specified using
+.Ql Fl g Ar \&"" ,
+then new users will be allocated their own private primary group (a new group created
+with the same name as their login name).
+If a group is supplied, either its name or uid may be given as an argument.
+.It Fl G Ar grouplist
+Sets the default groups in which new users are made members.
+This is a separate set of groups from the primary group, and you should avoid
+nominating the same group as both the primary and in extra groups.
+In other words, these extra groups determine membership in groups
+.Em other than
+the primary group.
+.Ar grouplist
+is a comma-separated list of group names or ids, or a mixture of both, and are always
+stored in
+.Pa /etc/pw.conf
+by their symbolic names.
+.It Fl k Ar dir
+Sets the default
+.Em skeleton
+directory, from which prototype shell and other initialisation files are copied when
+.Nm pw
+creates a user's home directory.
+.It Fl u Ar min,max
+.It Fl i Ar min,max
+These switches set the minimum and maximum user and group ids allocated for new accounts
+and groups created by
+.Nm pw .
+The default values for each is 1000 minimum and 32000 maximum.
+.Ar min
+and
+.Ar max
+are both numbers, where max must be greater than min, and both must be between 0
+and 32767.
+In general, user and group ids less than 100 are reserved for use by the system,
+and numbers greater than 32000 may also be reserved for special purposes (used by
+some system daemons).
+.It Fl w Ar method
+The
+.Ql Fl w
+switch sets the default method used to set passwords for newly created user accounts.
+.Ar method
+is one of:
+.Pp
+.Bl -tag -width random -offset indent -compact
+.It no
+disables login on newly created accounts
+.It yes
+forces the password to be the account name
+.It none
+forces a blank password
+.It random
+Generates a random password
+.El
+.Pp
+The
+.Ql \&random
+or
+.Ql \&no
+methods are the most secure; in the former case,
+.Nm pw
+generates a password and prints it to stdout, which is suitable where you issue
+users with passwords to access their accounts rather than having the user nominate
+their own (possibly poorly chosen) password.
+The
+.Ql \&no
+method requires that the superuser use
+.Xr passwd 1
+to render the account accessible with a password.
+.El
+.Pp
+The
+.Ar userdel
+command has only three valid switches. The
+.Ql Fl n Ar name
+and
+.Ql Fl u Ar uid
+switches have already been covered above.
+The additional switch is:
+.Bl -tag -width flag
+.It Fl r
+This tells
+.Nm pw
+to remove the user's home directory and all of its contents.
+.Nm pw
+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
+a valid path that commences with the character
+.Ql \&/ .
+Secondly, it will only remove files and directories that are actually owned by
+the user, or symbolic links owned by anyone under the user's home directory.
+Finally, after deleting all contents owned by the user only empty directories
+will be removed.
+If any additional cleanup work is required, this is left to the adminstrator.
+.El
+.Pp
+Mail spool files and crontabs are always removed when an account is deleted as these
+are unconditionally attached to the user name.
+Jobs queued for processing by
+.Ar at
+are also removed if the user's uid is unique (not also used by another account on the
+system).
+.Pp
+The
+.Ar 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
+with the password field replaced with a
+.Ql \&* .
+Class, account and password expiration fields will be blank or zero zero unless the user
+running
+.Nm pw
+has root priviledges, as the secure password file where these reside is not accessible
+to non-root users.
+If the
+.Ql Fl p
+switch is used, then
+.Nm pw
+outputs the account details in a more human readable form.
+The
+.Ql Fl a
+switch lists all users currently on file.
+.Pp
+.Sh GROUP OPTIONS
+The
+.Ql Fl C Ar config
+and
+.Ql Fl q
+options (explained at the start of the previous section) are available with the
+.Ar groupadd
+and
+.Ar groupmod
+commands.
+Other common options to all group-related commands are:
+.Bl -tag -width "-n name"
+.It Fl n Ar name
+Specifies the group name.
+.It Fl g Ar gid
+Specifies the group numeric id.
+.Pp
+As with the account name and id fields, yo uwill usually only need to supply one of
+these, as the group name implies the uid and vice versa.
+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.
+.El
+.Pp
+.Ar groupadd
+also has a
+.Ql Fl o
+option that allows allocation of an existing group id to new group.
+The default action is to reject an attempt to add a group, and this option overrides
+the check for duplicate group ids.
+There is rarely any need to duplicate a group id.
+.Pp
+The
+.Ar groupmod
+command adds one additonal switch:
+.Pp
+.Bl -tag -width "-l name"
+.It Fl l Ar name
+This option allows changing of an existing group name to
+.Ql \&name .
+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
+are the same as for
+.Ar usershow ,
+with the
+.Ql Fl g Ar gid
+replacing
+.Ql Fl u Ar uid
+to specify the group id.
+.Pp
+.Sh NOTES
+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.
+.Sh FILES
+.Bl -tag -width /etc/master.passwd.new -compact
+.It Pa /etc/master.passwd
+The user database
+.It Pa /etc/passwd 
+A Version 7 format password file
+.It Pa /etc/group
+The group database
+.It Pa /etc/master.passwd.new
+Temporary copy of the master password file
+.It Pa /etc/passwd.new
+Temporary copy of the Version 7 password file
+.It Pa /etc/group.new
+Temporary copy of the group file
+.It Pa /etc/pw.conf
+Pw default options file
+.El
+.Sh SEE ALSO
+.Xr pw.conf 5 ,
+.Xr passwd 1 ,
+.Xr chpass 1 ,
+.Xr passwd 5 ,
+.Xr group 5 ,
+.Xr pwd_mkdb 8 ,
+.Xr vipw 5
+.Sh HISTORY
+.Nm pw
+was written to mimick many of the options used in the Linux
+.Em shadow
+suite, but is modified for passwd and group fields specific to
+the BSD 4.4 operating system.
+