xref: /freebsd/usr.sbin/pw/pw.8 (revision a90b9d0159070121c221b966469c3e36d912bf82)
1.\" Copyright (C) 1996
2.\" David L. Nugent.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY DAVID L. NUGENT AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL DAVID L. NUGENT OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd November 28, 2022
26.Dt PW 8
27.Os
28.Sh NAME
29.Nm pw
30.Nd create, remove, modify & display system users and groups
31.Sh SYNOPSIS
32.Nm
33.Op Fl R Ar rootdir
34.Op Fl V Ar etcdir
35.Cm useradd
36.Oo Fl n Oc Ar name
37.Op Fl mNoPq
38.Op Fl C Ar config
39.Op Fl c Ar comment
40.Op Fl d Ar homedir
41.Op Fl e Ar accexpdate
42.Op Fl G Ar grouplist
43.Op Fl g Ar group
44.Op Fl H Ar fd
45.Op Fl h Ar fd
46.Op Fl k Ar skeldir
47.Op Fl L Ar class
48.Op Fl M Ar mode
49.Op Fl p Ar passexpdate
50.Op Fl s Ar shell
51.Op Fl u Ar uid
52.Op Fl w Ar passmethod
53.Op Fl Y Op Fl y Ar nispasswd
54.Nm
55.Op Fl R Ar rootdir
56.Op Fl V Ar etcdir
57.Cm useradd
58.Fl D
59.Op Fl q
60.Op Fl b Ar basehome
61.Op Fl C Ar config
62.Op Fl e Ar accexpdays
63.Op Fl G Ar grouplist
64.Op Fl g Ar group
65.Op Fl i Ar mingid , Ns Ar maxgid
66.Op Fl k Ar skeldir
67.Op Fl M Ar mode
68.Op Fl p Ar passexpdays
69.Op Fl s Ar shell
70.Op Fl u Ar minuid , Ns Ar maxuid
71.Op Fl w Ar passmethod
72.Op Fl Y Op Fl y Ar nispasswd
73.Nm
74.Op Fl R Ar rootdir
75.Op Fl V Ar etcdir
76.Cm userdel
77.Oo Fl n Oc Ar name Ns | Ns Oo Fl u Oc Ar uid
78.Op Fl r
79.Op Fl Y Op Fl y Ar nispasswd
80.Nm
81.Op Fl R Ar rootdir
82.Op Fl V Ar etcdir
83.Cm usermod
84.Oo Fl n Oc Ar name Ns | Ns Ar uid Oo Fl u Ar newuid Oc | Fl u Ar uid
85.Op Fl mNPq
86.Op Fl C Ar config
87.Op Fl c Ar comment
88.Op Fl d Ar homedir
89.Op Fl e Ar accexpdate
90.Op Fl k Ar skeldir
91.Op Fl G Ar grouplist
92.Op Fl g Ar group
93.Op Fl H Ar fd
94.Op Fl h Ar fd
95.Op Fl L Ar class
96.Op Fl l Ar newname
97.Op Fl M Ar mode
98.Op Fl p Ar passexpdate
99.Op Fl s Ar shell
100.Op Fl w Ar passmethod
101.Op Fl Y Op Fl y Ar nispasswd
102.Nm
103.Op Fl R Ar rootdir
104.Op Fl V Ar etcdir
105.Cm usershow
106.Oo Fl n Oc Ar name Ns | Ns Oo Fl u Oc Ar uid
107.Op Fl 7aFP
108.Nm
109.Op Fl R Ar rootdir
110.Op Fl V Ar etcdir
111.Cm usernext
112.Op Fl q
113.Op Fl C Ar config
114.Nm
115.Op Fl R Ar rootdir
116.Op Fl V Ar etcdir
117.Cm groupadd
118.Oo Fl n Oc Ar name
119.Op Fl oNPqY
120.Op Fl C Ar config
121.Op Fl g Ar gid
122.Op Fl H Ar fd
123.Op Fl h Ar fd
124.Op Fl M Ar members
125.Nm
126.Op Fl R Ar rootdir
127.Op Fl V Ar etcdir
128.Cm groupdel
129.Oo Fl n Oc Ar name Ns | Ns Oo Fl g Oc Ar gid
130.Op Fl Y
131.Nm
132.Op Fl R Ar rootdir
133.Op Fl V Ar etcdir
134.Cm groupmod
135.Oo Fl n Oc Ar name Ns | Ns Ar gid Oo Fl g Ar newgid Oc | Fl g Ar gid
136.Op Fl NPqY
137.Op Fl C Ar config
138.Op Fl d Ar oldmembers
139.Op Fl H Ar fd
140.Op Fl h Ar fd
141.Op Fl l Ar newname
142.Op Fl M Ar members
143.Op Fl m Ar newmembers
144.Nm
145.Op Fl R Ar rootdir
146.Op Fl V Ar etcdir
147.Cm groupshow
148.Oo Fl n Oc Ar name Ns | Ns Oo Fl g Oc Ar gid
149.Op Fl aFP
150.Nm
151.Op Fl R Ar rootdir
152.Op Fl V Ar etcdir
153.Cm groupnext
154.Op Fl C Ar config
155.Op Fl q
156.Nm
157.Op Fl R Ar rootdir
158.Op Fl V Ar etcdir
159.Cm lock
160.Oo Fl n Oc Ar name Ns | Ns Oo Fl u Oc Ar uid
161.Op Fl q
162.Op Fl C Ar config
163.Nm
164.Op Fl R Ar rootdir
165.Op Fl V Ar etcdir
166.Cm unlock
167.Oo Fl n Oc Ar name Ns | Ns Oo Fl u Oc Ar uid
168.Op Fl q
169.Op Fl C Ar config
170.Sh DESCRIPTION
171The
172.Nm
173utility is a command-line based editor for the system
174.Ar user
175and
176.Ar group
177files, allowing the superuser an easy to use and standardized way of adding,
178modifying and removing users and groups.
179Note that
180.Nm
181only operates on the local user and group files.
182.Tn NIS
183users and groups must be
184maintained on the
185.Tn NIS
186server.
187The
188.Nm
189utility handles updating the
190.Xr passwd 5 ,
191.Xr master.passwd 5 ,
192.Xr group 5
193and the secure and insecure
194password database files, and must be run as root.
195.Pp
196The first one or two keywords provided to
197.Nm
198on the command line provide the context for the remainder of the arguments.
199The keywords
200.Cm user
201and
202.Cm group
203may be combined with
204.Cm add ,
205.Cm del ,
206.Cm mod ,
207.Cm show ,
208or
209.Cm next
210in any order.
211(For example,
212.Cm showuser ,
213.Cm usershow ,
214.Cm show user ,
215and
216.Cm user show
217all mean the same thing.)
218This flexibility is useful for interactive scripts calling
219.Nm
220for user and group database manipulation.
221Following these keywords,
222the user or group name or numeric id may be optionally specified as an
223alternative to using the
224.Fl n Ar name ,
225.Fl u Ar uid ,
226.Fl g Ar gid
227options.
228.Pp
229The following flags are common to most or all modes of operation:
230.Bl -tag -width "-G grouplist"
231.It Fl R Ar rootdir
232Specifies an alternate root directory within which
233.Nm
234will operate.
235Any paths specified will be relative to
236.Va rootdir .
237.It Fl V Ar etcdir
238Set an alternate location for the password, group, and configuration files.
239Can be used to maintain a user/group database in an alternate location.
240If this switch is specified, the system
241.Pa /etc/pw.conf
242will not be sourced for default configuration data,
243but the file
244.Pa pw.conf
245in the specified directory will be used instead
246.Pq or none, if it does not exist .
247The
248.Fl C
249flag may be used to override this behaviour.
250As an exception to the general rule where options must follow the operation
251type, the
252.Fl V
253flag must be used on the command line before the operation keyword.
254.It Fl C Ar config
255By default,
256.Nm
257reads the file
258.Pa /etc/pw.conf
259to obtain policy information on how new user accounts and groups are to be created.
260The
261.Fl C
262option specifies a different configuration file.
263While most of the contents of the configuration file may be overridden via
264command-line options, it may be more convenient to keep standard information in a
265configuration file.
266.It Fl q
267Use of this option causes
268.Nm
269to suppress error messages,
270which may be useful in interactive environments where it
271is preferable to interpret status codes returned by
272.Nm
273rather than messing up a carefully formatted display.
274.It Fl N
275This option is available in
276.Cm add
277and
278.Cm modify
279operations, and tells
280.Nm
281to output the result of the operation without updating the user or group
282databases.
283You may use the
284.Fl P
285option to switch between standard passwd and readable formats.
286.It Fl Y
287Using this option with any of the update modes causes
288.Nm
289to run
290.Xr make 1
291after changing to the directory
292.Pa /var/yp .
293This is intended to allow automatic updating of
294.Tn NIS
295database files.
296If separate passwd and group files are being used by
297.Tn NIS ,
298then use the
299.Fl y Ar nispasswd
300option to specify the location of the
301.Tn NIS
302passwd database so that
303.Nm
304will concurrently update it with the system password
305databases.
306.El
307.Sh USER OPTIONS
308The following options apply to the
309.Cm useradd
310and
311.Cm usermod
312commands:
313.Bl -tag -width "-G grouplist"
314.It Oo Fl n Oc Ar name
315Required unless
316.Fl u Ar uid
317is given.
318Specify the user/account name.
319In the case of
320.Cm usermod
321can be a
322.Ar uid .
323.It Fl u Ar uid
324Required if
325.Ar name
326is not given.
327Specify the user/account numeric id.
328In the case of
329.Cm usermod
330if paired with
331.Ar name ,
332changes the numeric id of the named user/account.
333.Pp
334Usually, only one of these options is required,
335as the account name will imply the uid, or vice versa.
336However, there are times when both are needed.
337For example, when changing the uid of an existing user with
338.Cm usermod ,
339or overriding the default uid when creating a new account with
340.Cm useradd .
341To automatically allocate the uid to a new user with
342.Cm useradd ,
343then do
344.Em not
345use the
346.Fl u
347option.
348Either the account or userid can also be provided immediately after the
349.Cm useradd ,
350.Cm userdel ,
351.Cm usermod ,
352or
353.Cm usershow
354keywords on the command line without using the
355.Fl n
356or
357.Fl u
358options.
359.El
360.Bl -tag -width "-G grouplist"
361.It Fl c Ar comment
362This field sets the contents of the passwd GECOS field,
363which normally contains up to four comma-separated fields containing the
364user's full name, office or location,
365and work and home phone numbers.
366These sub-fields are used by convention only, however, and are optional.
367If this field is to contain spaces,
368the comment must be enclosed in double quotes
369.Ql \&" .
370Avoid using commas in this field as these are used as sub-field separators,
371and the colon
372.Ql \&:
373character also cannot be used as this is the field separator for the passwd
374file itself.
375.It Fl d Ar homedir
376This option sets the account's home directory.
377Normally,
378this is only used if the home directory is to be different from the
379default determined from
380.Pa /etc/pw.conf
381- normally
382.Pa /home
383with the account name as a subdirectory.
384.It Fl e Ar accexpdate
385Set the account's expiration date.
386Format of the date is either a UNIX time in decimal, or a date in
387.Ql dd-mmm-yy[yy]
388format, where dd is the day,
389mmm is the month, either in numeric or alphabetic format
390('Jan', 'Feb', etc) and year is either a two or four digit year.
391This option also accepts a relative date in the form
392.Ql \&+n[mhdwoy]
393where
394.Ql \&n
395is a decimal,
396octal (leading 0) or hexadecimal (leading 0x) digit followed by the
397number of Minutes, Hours, Days, Weeks, Months or Years from the current date at
398which the expiration date is to be set.
399.It Fl p Ar passexpdate
400Set the account's password expiration date.
401This field is similar to the account expiration date option, except that it
402applies to forced password changes.
403This is set in the same manner as the
404.Fl e
405option.
406.It Fl g Ar group
407Set the account's primary group to the given group.
408.Ar group
409may be defined by either its name or group number.
410.It Fl G Ar grouplist
411Set secondary group memberships for an account.
412.Ar grouplist
413is a comma, space, or tab-separated list of group names or group numbers.
414The user is added to the groups specified in
415.Ar grouplist ,
416and removed from all groups not specified.
417The current login session is not affected by group membership changes,
418which only take effect when the user reconnects.
419Note: do not add a user to their primary group with
420.Ar grouplist .
421.It Fl L Ar class
422This option sets the login class for the user being created.
423See
424.Xr login.conf 5
425and
426.Xr passwd 5
427for more information on user login classes.
428.It Fl m
429This option instructs
430.Nm
431to attempt to create the user's home directory.
432While primarily useful when adding a new account with
433.Cm useradd ,
434this may also be of use when moving an existing user's home directory elsewhere
435on the file system.
436The new home directory is populated with the contents of the
437.Ar skeleton
438directory, which typically contains a set of shell configuration files that the
439user may personalize to taste.
440Files in this directory are usually named
441.Pa dot . Ns Aq Ar config
442where the
443.Pa dot
444prefix will be stripped.
445When
446.Fl m
447is used on an account with
448.Cm usermod ,
449existing configuration files in the user's home directory are
450.Em not
451overwritten from the skeleton files.
452.Pp
453When a user's home directory is created,
454it will by default be a subdirectory of the
455.Ar basehome
456directory as specified by the
457.Fl b
458option, bearing the name of the new account.
459This can be overridden by the
460.Fl d
461option on the command line, if desired.
462.It Fl M Ar mode
463Create the user's home directory with the specified
464.Ar mode ,
465modified by the current
466.Xr umask 2 .
467If omitted, it is derived from the parent process'
468.Xr umask 2 .
469This option is only useful in combination with the
470.Fl m
471flag.
472.It Fl k Ar skeldir
473Set the
474.Ar skeleton
475directory, from which basic startup and configuration files are copied when
476the user's home directory is created.
477This option only has meaning when used with the
478.Fl d
479or
480.Fl m
481flags.
482.It Fl s Ar shell
483Set or changes the user's login shell to
484.Ar shell .
485If the path to the shell program is omitted,
486.Nm
487searches the
488.Ar shellpath
489specified in
490.Pa /etc/pw.conf
491and fills it in as appropriate.
492Note that unless you have a specific reason to do so, you should avoid
493specifying the path - this will allow
494.Nm
495to validate that the program exists and is executable.
496Specifying a full path (or supplying a blank "" shell) avoids this check
497and allows for such entries as
498.Pa /nonexistent
499that should be set for accounts not intended for interactive login.
500.It Fl h Ar fd
501This option provides a special interface by which interactive scripts can
502set an account password using
503.Nm .
504Because the command line and environment are fundamentally insecure mechanisms
505by which programs can accept information,
506.Nm
507will only allow setting of account and group passwords via a file descriptor
508(usually a pipe between an interactive script and the program).
509.Ar sh ,
510.Ar bash ,
511.Ar ksh
512and
513.Ar perl
514all possess mechanisms by which this can be done.
515Alternatively,
516.Nm
517will prompt for the user's password if
518.Fl h Ar 0
519is given, nominating
520.Em stdin
521as the file descriptor on which to read the password.
522Note that this password will be read only once and is intended
523for use by a script rather than for interactive use.
524If you wish to have new password confirmation along the lines of
525.Xr passwd 1 ,
526this must be implemented as part of an interactive script that calls
527.Nm .
528.Pp
529If a value of
530.Ql \&-
531is given as the argument
532.Ar fd ,
533then the password will be set to
534.Ql \&* ,
535rendering the account inaccessible via password-based login.
536.It Fl H Ar fd
537Read an encrypted password string from the specified file descriptor.
538This is like
539.Fl h ,
540but the password should be supplied already encrypted in a form
541suitable for writing directly to the password database.
542See
543.Xr openssl-passwd 1
544and
545.Xr crypt 3
546for more details about generating an encrypted password hash.
547.El
548.Pp
549It is possible to use
550.Cm useradd
551to create a new account that duplicates an existing user id.
552While this is normally considered an error and will be rejected, the
553.Fl o
554option overrides the check for duplicates and allows the duplication of
555the user id.
556This may be useful if you allow the same user to login under
557different contexts (different group allocations, different home
558directory, different shell) while providing basically the same
559permissions for access to the user's files in each account.
560.Pp
561The
562.Cm useradd
563command also has the ability to set new user and group defaults by using the
564.Fl D
565option.
566Instead of adding a new user,
567.Nm
568writes a new set of defaults to its configuration file,
569.Pa /etc/pw.conf .
570When using the
571.Fl D
572option, you must not use either
573.Fl n Ar name
574or
575.Fl u Ar uid
576or an error will result.
577Use of
578.Fl D
579changes the meaning of several command line switches in the
580.Ar useradd
581command.
582These are:
583.Bl -tag -width "-G grouplist"
584.It Fl D
585Set default values in
586.Pa /etc/pw.conf
587configuration file, or a different named configuration file if the
588.Fl C Ar config
589option is used.
590.It Fl b Ar basehome
591Set the root directory in which user home directories are created.
592The default value for this is
593.Pa /home ,
594but it may be set elsewhere as desired.
595.It Fl e Ar accexpdays
596Set the default account expiration period in days.
597When
598.Fl D
599is used, the
600.Ar accexpdays
601argument is interpreted differently.
602It must be numeric and represents the number of days after creation
603that the account expires.
604A value of 0 suppresses automatic calculation of the expiry date.
605.It Fl p Ar passexpdays
606Set the default password expiration period in days.
607When
608.Fl D
609is used, the
610.Ar passexpdays
611argument is interpreted differently.
612It must be numeric and represents the number of days after creation
613that the account expires.
614A value of 0 suppresses automatic calculation of the expiry date.
615.It Fl g Ar group
616Set the default group for new users.
617If a blank group is specified using
618.Fl g Ar \&"" ,
619then new users will be allocated their own private primary group
620with the same name as their login name.
621If a group is supplied, either its name or uid may be given as an argument.
622.It Fl G Ar grouplist
623Set the default groups in which new users are granted membership.
624This is a separate set of groups from the primary group.
625Avoid nominating the same group as both primary and extra groups.
626In other words, these extra groups determine membership in groups
627.Em other than
628the primary group.
629.Ar grouplist
630is a comma-separated list of group names or ids, and are always
631stored in
632.Pa /etc/pw.conf
633by their symbolic names.
634.It Fl L Ar class
635This option sets the default login class for new users.
636.It Fl k Ar skeldir
637Set the default
638.Em skeleton
639directory,
640from which prototype shell and other initialization files are copied when
641.Nm
642creates a user's home directory.
643See description of
644.Fl k
645for naming conventions of these files.
646.It Xo
647.Fl u Ar minuid Ns Cm \&, Ns Ar maxuid ,
648.Fl i Ar mingid Ns Cm \&, Ns Ar maxgid
649.Xc
650Set the minimum and maximum user and group ids allocated for new
651accounts and groups created by
652.Nm .
653The default values for each is 1000 minimum and 32000 maximum.
654.Ar minuid
655and
656.Ar maxuid
657are both numbers, where max must be greater than min,
658and both must be between 0 and 32767
659.Po the same applies to
660.Ar mingid
661and
662.Ar maxgid
663.Pc .
664In general,
665user and group ids less than 100 are reserved for use by the system,
666and numbers greater than 32000 may also be reserved for special purposes
667.Pq used by some system daemons .
668.It Fl w Ar passmethod
669The
670.Fl w
671option selects the default method used to set passwords for newly created user
672accounts.
673.Ar passmethod
674is one of:
675.Pp
676.Bl -tag -width random -offset indent -compact
677.It Cm no
678disable login on newly created accounts
679.It Cm yes
680force the password to be the account name
681.It Cm none
682force a blank password
683.It Cm random
684generate a random password
685.El
686.Pp
687The
688.Cm random
689or
690.Cm no
691methods are the most secure; in the former case,
692.Nm
693generates a password and prints it to stdout,
694which is suitable when users are issued passwords rather than being allowed
695to select their own
696.Pq possibly poorly chosen
697password.
698The
699.Cm no
700method requires that the superuser use
701.Xr passwd 1
702to render the account accessible with a password.
703.It Fl y Ar path
704This sets the pathname of the database used by
705.Tn NIS
706if you are not sharing
707the information from
708.Pa /etc/master.passwd
709directly with
710.Tn NIS .
711You should only set this option for
712.Tn NIS
713servers.
714.El
715.Pp
716The
717.Cm userdel
718command has three distinct options.
719The
720.Fl n Ar name
721and
722.Fl u Ar uid
723options have already been covered above.
724The additional option is:
725.Bl -tag -width "-G grouplist"
726.It Fl r
727This tells
728.Nm
729to remove the user's home directory and all of its contents.
730The
731.Nm
732utility errs on the side of caution when removing files from the system.
733Firstly,
734it will not do so if the uid of the account being removed is also used by
735another account on the system, and the
736.Dq home
737directory in the password file is
738a valid path that commences with the character
739.Ql \&/ .
740Secondly, it will only remove files and directories that are actually owned by
741the user, or symbolic links owned by anyone under the user's home directory.
742Finally, after deleting all contents owned by the user only empty directories
743will be removed.
744If the home directory is a ZFS dataset and has been emptied,
745the dataset will be destroyed.
746ZFS datasets within the home directory and snapshots are not handled.
747If any additional cleanup work is required, this is left to the administrator.
748.El
749.Pp
750Mail spool files and
751.Xr crontab 5
752files are always removed when an account is deleted as
753these are unconditionally attached to the user name.
754Jobs queued for processing by
755.Xr at 1
756are also removed if the user's uid is unique and not also used by another
757account on the system.
758.Pp
759The
760.Cm usermod
761command adds one additional option:
762.Bl -tag -width "-G grouplist"
763.It Fl l Ar newname
764This option allows changing of an existing account name to
765.Ar newname .
766The new name must not already exist, and any attempt to duplicate an
767existing account name will be rejected.
768.El
769.Pp
770The
771.Cm usershow
772command allows viewing of an account in one of two formats.
773By default, the format is identical to the format used in
774.Pa /etc/master.passwd
775with the password field replaced with a
776.Ql \&* .
777If the
778.Fl P
779option is used, then
780.Nm
781outputs the account details in a more human readable form.
782If the
783.Fl 7
784option is used, the account details are shown in v7 format.
785The
786.Fl a
787option lists all users currently on file.
788Using
789.Fl F
790forces
791.Nm
792to print the details of an account even if it does not exist.
793.Pp
794The command
795.Cm usernext
796returns the next available user and group ids separated by a colon.
797This is normally of interest only to interactive scripts or front-ends
798that use
799.Nm .
800.Sh GROUP OPTIONS
801The
802.Fl C
803and
804.Fl q
805options (explained at the start of the previous section) are available
806with the group manipulation commands.
807Other common options to all group-related commands are:
808.Bl -tag -width "-m newmembers"
809.It Oo Fl n Oc Ar name
810Required unless
811.Fl g Ar gid
812is given.
813Specify the group name.
814In the case of
815.Cm groupmod
816can be a gid.
817.It Fl g Ar gid
818Required if
819.Ar name
820is not given.
821Specify the group numeric id.
822In the case of
823.Cm groupmod
824if paired with
825.Ar name ,
826changes the numeric id of the named group.
827.Pp
828As with the account name and id fields, you will usually only need
829to supply one of these, as the group name implies the uid and vice
830versa.
831You will only need to use both when setting a specific group id
832against a new group or when changing the uid of an existing group.
833.It Fl M Ar memberlist
834This option provides an alternative way to add existing users to a
835new group
836.Pq in Cm groupadd
837or replace an existing membership list
838.Pq in Cm groupmod .
839.Ar memberlist
840is a comma separated list of valid and existing user names or uids.
841.It Fl m Ar newmembers
842Similar to
843.Fl M ,
844this option allows the
845.Em addition
846of existing users to a group without replacing the existing list of
847members.
848Login names or user ids may be used, and duplicate users are
849silently eliminated.
850.It Fl d Ar oldmembers
851Similar to
852.Fl M ,
853this option allows the
854.Em deletion
855of existing users from a group without replacing the existing list of
856members.
857Login names or user ids may be used, and duplicate users are
858silently eliminated.
859.El
860.Pp
861.Cm groupadd
862also has a
863.Fl o
864option that allows allocation of an existing group id to a new group.
865The default action is to reject an attempt to add a group,
866and this option overrides the check for duplicate group ids.
867There is rarely any need to duplicate a group id.
868.Pp
869The
870.Cm groupmod
871command adds one additional option:
872.Bl -tag -width "-m newmembers"
873.It Fl l Ar newname
874This option allows changing of an existing group name to
875.Ar newname .
876The new name must not already exist,
877and any attempt to duplicate an existing group
878name will be rejected.
879.El
880.Pp
881Options for
882.Cm groupshow
883are the same as for
884.Cm usershow ,
885with the
886.Fl g Ar gid
887replacing
888.Fl u Ar uid
889to specify the group id.
890The
891.Fl 7
892option does not apply to the
893.Cm groupshow
894command.
895.Pp
896The command
897.Cm groupnext
898returns the next available group id on standard output.
899.Sh USER LOCKING
900The
901.Nm
902utility
903supports a simple password locking mechanism for users; it works by
904prepending the string
905.Ql *LOCKED*
906to the beginning of the password field in
907.Xr master.passwd 5
908to prevent successful authentication.
909.Pp
910The
911.Cm lock
912and
913.Cm unlock
914commands take a user name or uid of the account to lock or unlock,
915respectively.
916The
917.Fl V ,
918.Fl C ,
919and
920.Fl q
921options as described above are accepted by these commands.
922.Sh NOTES
923For a summary of options available with each command, you can use
924.Dl pw [command] help
925For example,
926.Dl pw useradd help
927lists all available options for the
928.Cm useradd
929operation.
930.Pp
931The
932.Nm
933utility allows 8-bit characters in the passwd GECOS field (user's full name,
934office, work and home phone number subfields), but disallows them in
935user login and group names.
936Use 8-bit characters with caution, as connection to the Internet will
937require that your mail transport program supports 8BITMIME, and will
938convert headers containing 8-bit characters to 7-bit quoted-printable
939format.
940.Xr sendmail 8
941does support this.
942Use of 8-bit characters in the GECOS field should be used in
943conjunction with the user's default locale and character set
944and should not be implemented without their use.
945Using 8-bit characters may also affect other
946programs that transmit the contents of the GECOS field over the
947Internet, such as
948.Xr fingerd 8 ,
949and a small number of TCP/IP clients, such as IRC, where full names
950specified in the passwd file may be used by default.
951.Pp
952The
953.Nm
954utility writes a log to the
955.Pa /var/log/userlog
956file when actions such as user or group additions or deletions occur.
957The location of this logfile can be changed in
958.Xr pw.conf 5 .
959.Sh FILES
960.Bl -tag -width /etc/master.passwd.new -compact
961.It Pa /etc/master.passwd
962The user database
963.It Pa /etc/passwd
964A Version 7 format password file
965.It Pa /etc/login.conf
966The user capabilities database
967.It Pa /etc/group
968The group database
969.It Pa /etc/pw.conf
970Pw default options file
971.It Pa /var/log/userlog
972User/group modification logfile
973.El
974.Sh EXAMPLES
975Add new user Glurmo Smith (gsmith).
976A gsmith login group is created if not already present.
977The login shell is set to
978.Xr csh 1 .
979A new home directory at
980.Pa /home/gsmith
981is created if it does not already exist.
982Finally, a random password is generated and displayed:
983.Bd -literal -offset indent
984pw useradd -n gsmith -c "Glurmo Smith" -s csh -m -w random
985.Ed
986.Pp
987Delete the gsmith user and their home directory, including contents.
988.Bd -literal -offset indent
989pw userdel -n gsmith -r
990.Ed
991.Pp
992Add the existing user jsmith to the wheel group,
993in addition to the other groups jsmith is already a member of.
994.Bd -literal -offset indent
995pw groupmod wheel -m jsmith
996.Ed
997.Pp
998Generate random password and show it in both plain text and
999encrypted form not modifying any database.
1000.Bd -literal -offset indent
1001pw usermod nobody -Nw random
1002.Ed
1003.Sh EXIT STATUS
1004The
1005.Nm
1006utility returns EXIT_SUCCESS on successful operation, otherwise
1007.Nm
1008returns one of the
1009following exit codes defined by
1010.Xr sysexits 3
1011as follows:
1012.Bl -tag -width xxxx
1013.It EX_USAGE
1014.Bl -bullet -compact
1015.It
1016Command line syntax errors (invalid keyword, unknown option).
1017.El
1018.It EX_NOPERM
1019.Bl -bullet -compact
1020.It
1021Attempting to run one of the update modes as non-root.
1022.El
1023.It EX_OSERR
1024.Bl -bullet -compact
1025.It
1026Memory allocation error.
1027.It
1028Read error from password file descriptor.
1029.El
1030.It EX_DATAERR
1031.Bl -bullet -compact
1032.It
1033Bad or invalid data provided or missing on the command line or
1034via the password file descriptor.
1035.It
1036Attempted to remove, rename root account or change its uid.
1037.El
1038.It EX_OSFILE
1039.Bl -bullet -compact
1040.It
1041Skeleton directory is invalid or does not exist.
1042.It
1043Base home directory is invalid or does not exist.
1044.It
1045Invalid or non-existent shell specified.
1046.El
1047.It EX_NOUSER
1048.Bl -bullet -compact
1049.It
1050User, user id, group or group id specified does not exist.
1051.It
1052User or group recorded, added, or modified unexpectedly disappeared.
1053.El
1054.It EX_SOFTWARE
1055.Bl -bullet -compact
1056.It
1057No more group or user ids available within specified range.
1058.El
1059.It EX_IOERR
1060.Bl -bullet -compact
1061.It
1062Unable to rewrite configuration file.
1063.It
1064Error updating group or user database files.
1065.It
1066Update error for passwd or group database files.
1067.El
1068.It EX_CONFIG
1069.Bl -bullet -compact
1070.It
1071No base home directory configured.
1072.El
1073.El
1074.Sh SEE ALSO
1075.Xr chpass 1 ,
1076.Xr passwd 1 ,
1077.Xr umask 2 ,
1078.Xr group 5 ,
1079.Xr login.conf 5 ,
1080.Xr passwd 5 ,
1081.Xr pw.conf 5 ,
1082.Xr pwd_mkdb 8 ,
1083.Xr vipw 8 ,
1084.Xr zfs 8
1085.Sh HISTORY
1086The
1087.Nm
1088utility was written to mimic many of the options used in the SYSV
1089.Em shadow
1090support suite, but is modified for passwd and group fields specific to
1091the
1092.Bx 4.4
1093operating system, and combines all of the major elements
1094into a single command.
1095