From 7bcd96904137f447a8d58a8295ea58f26711ab71 Mon Sep 17 00:00:00 2001 From: Joerg Wunsch Date: Mon, 9 Dec 1996 14:05:35 +0000 Subject: 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, --- pw/pw.8 | 648 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 648 insertions(+) create mode 100644 pw/pw.8 (limited to 'pw/pw.8') 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. + -- cgit v1.2.3-56-ge451