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