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