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 June 14, 2015 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 additional group memberships for an account. 424.Ar grouplist 425is a comma, space or tab-separated list of group names or group numbers. 426The user's name is added to the group lists in 427.Pa /etc/group , 428and 429removed from any groups not specified in 430.Ar grouplist . 431Note: a user should not be added to their primary group with 432.Ar grouplist . 433Also, group membership changes do not take effect for current user login 434sessions, requiring the user to reconnect to be affected by the changes. 435.It Fl L Ar class 436This option sets the login class for the user being created. 437See 438.Xr login.conf 5 439and 440.Xr passwd 5 441for more information on user login classes. 442.It Fl m 443This option instructs 444.Nm 445to attempt to create the user's home directory. 446While primarily useful when adding a new account with 447.Ar useradd , 448this may also be of use when moving an existing user's home directory elsewhere 449on the file system. 450The new home directory is populated with the contents of the 451.Ar skeleton 452directory, which typically contains a set of shell configuration files that the 453user may personalize to taste. 454Files in this directory are usually named 455.Pa dot . Ns Aq Ar config 456where the 457.Pa dot 458prefix will be stripped. 459When 460.Fl m 461is used on an account with 462.Ar usermod , 463existing configuration files in the user's home directory are 464.Em not 465overwritten from the skeleton files. 466.Pp 467When a user's home directory is created, 468it will by default be a subdirectory of the 469.Ar basehome 470directory as specified by the 471.Fl b 472option (see below), bearing the name of the new account. 473This can be overridden by the 474.Fl d 475option on the command line, if desired. 476.It Fl M Ar mode 477Create the user's home directory with the specified 478.Ar mode , 479modified by the current 480.Xr umask 2 . 481If omitted, it is derived from the parent process' 482.Xr umask 2 . 483This option is only useful in combination with the 484.Fl m 485flag. 486.It Fl k Ar dir 487Set the 488.Ar skeleton 489directory, from which basic startup and configuration files are copied when 490the user's home directory is created. 491This option only has meaning when used with the 492.Fl d 493or 494.Fl m 495flags. 496.It Fl s Ar shell 497Set or changes the user's login shell to 498.Ar shell . 499If the path to the shell program is omitted, 500.Nm 501searches the 502.Ar shellpath 503specified in 504.Pa /etc/pw.conf 505and fills it in as appropriate. 506Note that unless you have a specific reason to do so, you should avoid 507specifying the path - this will allow 508.Nm 509to validate that the program exists and is executable. 510Specifying a full path (or supplying a blank "" shell) avoids this check 511and allows for such entries as 512.Pa /nonexistent 513that should be set for accounts not intended for interactive login. 514.It Fl h Ar fd 515This option provides a special interface by which interactive scripts can 516set an account password using 517.Nm . 518Because the command line and environment are fundamentally insecure mechanisms 519by which programs can accept information, 520.Nm 521will only allow setting of account and group passwords via a file descriptor 522(usually a pipe between an interactive script and the program). 523.Ar sh , 524.Ar bash , 525.Ar ksh 526and 527.Ar perl 528all possess mechanisms by which this can be done. 529Alternatively, 530.Nm 531will prompt for the user's password if 532.Fl h Ar 0 533is given, nominating 534.Em stdin 535as the file descriptor on which to read the password. 536Note that this password will be read only once and is intended 537for use by a script rather than for interactive use. 538If you wish to have new password confirmation along the lines of 539.Xr passwd 1 , 540this must be implemented as part of an interactive script that calls 541.Nm . 542.Pp 543If a value of 544.Ql \&- 545is given as the argument 546.Ar fd , 547then the password will be set to 548.Ql \&* , 549rendering the account inaccessible via password-based login. 550.It Fl H Ar fd 551Read an encrypted password string from the specified file descriptor. 552This is like 553.Fl h , 554but the password should be supplied already encrypted in a form 555suitable for writing directly to the password database. 556.El 557.Pp 558It is possible to use 559.Ar useradd 560to create a new account that duplicates an existing user id. 561While this is normally considered an error and will be rejected, the 562.Fl o 563option overrides the check for duplicates and allows the duplication of 564the user id. 565This may be useful if you allow the same user to login under 566different contexts (different group allocations, different home 567directory, different shell) while providing basically the same 568permissions for access to the user's files in each account. 569.Pp 570The 571.Ar useradd 572command also has the ability to set new user and group defaults by using the 573.Fl D 574option. 575Instead of adding a new user, 576.Nm 577writes a new set of defaults to its configuration file, 578.Pa /etc/pw.conf . 579When using the 580.Fl D 581option, you must not use either 582.Fl n Ar name 583or 584.Fl u Ar uid 585or an error will result. 586Use of 587.Fl D 588changes the meaning of several command line switches in the 589.Ar useradd 590command. 591These are: 592.Bl -tag -width "-G grouplist" 593.It Fl D 594Set default values in 595.Pa /etc/pw.conf 596configuration file, or a different named configuration file if the 597.Fl C Ar config 598option is used. 599.It Fl b Ar dir 600Set the root directory in which user home directories are created. 601The default value for this is 602.Pa /home , 603but it may be set elsewhere as desired. 604.It Fl e Ar days 605Set the default account expiration period in days. 606When 607.Fl D 608is used, the 609.Ar days 610argument is interpreted differently. 611It must be numeric and represents the number of days after creation 612that the account expires. 613A value of 0 suppresses automatic calculation of the expiry date. 614.It Fl p Ar days 615Set the default password expiration period in days. 616.It Fl g Ar group 617Set the default group for new users. 618If a blank group is specified using 619.Fl g Ar \&"" , 620then new users will be allocated their own private primary group 621with the same name as their login name. 622If a group is supplied, either its name or uid may be given as an argument. 623.It Fl G Ar grouplist 624Set the default groups in which new users are granted membership. 625This is a separate set of groups from the primary group. 626Avoid nominating the same group as both primary and extra groups. 627In other words, these extra groups determine membership in groups 628.Em other than 629the primary group. 630.Ar grouplist 631is a comma-separated list of group names or ids, and are always 632stored in 633.Pa /etc/pw.conf 634by their symbolic names. 635.It Fl L Ar class 636This option sets the default login class for new users. 637.It Fl k Ar dir 638Set the default 639.Em skeleton 640directory, 641from which prototype shell and other initialization files are copied when 642.Nm 643creates a user's home directory. 644See description of 645.Fl k 646for naming conventions of these files. 647.It Xo 648.Fl u Ar min , Ns Ar max , 649.Fl i Ar min , Ns Ar max 650.Xc 651Set the minimum and maximum user and group ids allocated for new 652accounts and groups created by 653.Nm . 654The default values for each is 1000 minimum and 32000 maximum. 655.Ar min 656and 657.Ar max 658are both numbers, where max must be greater than min, 659and both must be between 0 and 32767. 660In general, 661user and group ids less than 100 are reserved for use by the system, 662and numbers greater than 32000 may also be reserved for special purposes 663.Pq used by some system daemons . 664.It Fl w Ar method 665The 666.Fl w 667option selects the default method used to set passwords for newly created user 668accounts. 669.Ar method 670is one of: 671.Pp 672.Bl -tag -width random -offset indent -compact 673.It no 674disable login on newly created accounts 675.It yes 676force the password to be the account name 677.It none 678force a blank password 679.It random 680generate a random password 681.El 682.Pp 683The 684.Ql \&random 685or 686.Ql \&no 687methods are the most secure; in the former case, 688.Nm 689generates a password and prints it to stdout, 690which is suitable when users are issued passwords rather than being allowed 691to select their own 692.Pq possibly poorly chosen 693password. 694The 695.Ql \&no 696method requires that the superuser use 697.Xr passwd 1 698to render the account accessible with a password. 699.It Fl y Ar path 700This sets the pathname of the database used by 701.Tn NIS 702if you are not sharing 703the information from 704.Pa /etc/master.passwd 705directly with 706.Tn NIS . 707You should only set this option for 708.Tn NIS 709servers. 710.El 711.Pp 712The 713.Ar userdel 714command has three distinct options. 715The 716.Fl n Ar name 717and 718.Fl u Ar uid 719options have already been covered above. 720The additional option is: 721.Bl -tag -width "-G grouplist" 722.It Fl r 723This tells 724.Nm 725to remove the user's home directory and all of its contents. 726The 727.Nm 728utility errs on the side of caution when removing files from the system. 729Firstly, 730it will not do so if the uid of the account being removed is also used by 731another account on the system, and the 'home' directory in the password file is 732a valid path that commences with the character 733.Ql \&/ . 734Secondly, it will only remove files and directories that are actually owned by 735the user, or symbolic links owned by anyone under the user's home directory. 736Finally, after deleting all contents owned by the user only empty directories 737will be removed. 738If any additional cleanup work is required, this is left to the administrator. 739.El 740.Pp 741Mail spool files and crontabs are always removed when an account is deleted as 742these are unconditionally attached to the user name. 743Jobs queued for processing by 744.Ar at 745are also removed if the user's uid is unique and not also used by another 746account on the system. 747.Pp 748The 749.Ar usermod 750command adds one additional option: 751.Bl -tag -width "-G grouplist" 752.It Fl l Ar newname 753This option allows changing of an existing account name to 754.Ql \&newname . 755The new name must not already exist, and any attempt to duplicate an 756existing account name will be rejected. 757.El 758.Pp 759The 760.Ar usershow 761command allows viewing of an account in one of two formats. 762By default, the format is identical to the format used in 763.Pa /etc/master.passwd 764with the password field replaced with a 765.Ql \&* . 766If the 767.Fl P 768option is used, then 769.Nm 770outputs the account details in a more human readable form. 771If the 772.Fl 7 773option is used, the account details are shown in v7 format. 774The 775.Fl a 776option lists all users currently on file. 777Using 778.Fl F 779forces 780.Nm 781to print the details of an account even if it does not exist. 782.Pp 783The command 784.Ar usernext 785returns the next available user and group ids separated by a colon. 786This is normally of interest only to interactive scripts or front-ends 787that use 788.Nm . 789.Sh GROUP OPTIONS 790The 791.Fl C 792and 793.Fl q 794options (explained at the start of the previous section) are available 795with the group manipulation commands. 796Other common options to all group-related commands are: 797.Bl -tag -width "-m newmembers" 798.It Oo Fl n Oc Ar name 799Required unless 800.Fl g Ar gid 801is given. 802Specify the group name. 803In the case of 804.Ar groupmod 805can be a gid. 806.It Fl g Ar gid 807Required if 808.Ar name 809is not given. 810Specify the group numeric id. 811In the case of 812.Ar groupmod 813if paired with 814.Ar name , 815changes the numeric id of the named group. 816.Pp 817As with the account name and id fields, you will usually only need 818to supply one of these, as the group name implies the uid and vice 819versa. 820You will only need to use both when setting a specific group id 821against a new group or when changing the uid of an existing group. 822.It Fl M Ar memberlist 823This option provides an alternative way to add existing users to a 824new group (in groupadd) or replace an existing membership list (in 825groupmod). 826.Ar memberlist 827is a comma separated list of valid and existing user names or uids. 828.It Fl m Ar newmembers 829Similar to 830.Fl M , 831this option allows the 832.Em addition 833of existing users to a group without replacing the existing list of 834members. 835Login names or user ids may be used, and duplicate users are 836silently eliminated. 837.It Fl d Ar oldmembers 838Similar to 839.Fl M , 840this option allows the 841.Em deletion 842of existing users from a group without replacing the existing list of 843members. 844Login names or user ids may be used, and duplicate users are 845silently eliminated. 846.El 847.Pp 848.Ar groupadd 849also has a 850.Fl o 851option that allows allocation of an existing group id to a new group. 852The default action is to reject an attempt to add a group, 853and this option overrides the check for duplicate group ids. 854There is rarely any need to duplicate a group id. 855.Pp 856The 857.Ar groupmod 858command adds one additional option: 859.Bl -tag -width "-m newmembers" 860.It Fl l Ar newname 861This option allows changing of an existing group name to 862.Ql \&newname . 863The new name must not already exist, 864and any attempt to duplicate an existing group 865name will be rejected. 866.El 867.Pp 868Options for 869.Ar groupshow 870are the same as for 871.Ar usershow , 872with the 873.Fl g Ar gid 874replacing 875.Fl u Ar uid 876to specify the group id. 877The 878.Fl 7 879option does not apply to the 880.Ar groupshow 881command. 882.Pp 883The command 884.Ar groupnext 885returns the next available group id on standard output. 886.Sh USER LOCKING 887The 888.Nm 889utility 890supports a simple password locking mechanism for users; it works by 891prepending the string 892.Ql *LOCKED* 893to the beginning of the password field in 894.Pa master.passwd 895to prevent successful authentication. 896.Pp 897The 898.Ar lock 899and 900.Ar unlock 901commands take a user name or uid of the account to lock or unlock, 902respectively. 903The 904.Fl V , 905.Fl C , 906and 907.Fl q 908options as described above are accepted by these commands. 909.Sh NOTES 910For a summary of options available with each command, you can use 911.Dl pw [command] help 912For example, 913.Dl pw useradd help 914lists all available options for the useradd operation. 915.Pp 916The 917.Nm 918utility allows 8-bit characters in the passwd GECOS field (user's full name, 919office, work and home phone number subfields), but disallows them in 920user login and group names. 921Use 8-bit characters with caution, as connection to the Internet will 922require that your mail transport program supports 8BITMIME, and will 923convert headers containing 8-bit characters to 7-bit quoted-printable 924format. 925.Xr sendmail 8 926does support this. 927Use of 8-bit characters in the GECOS field should be used in 928conjunction with the user's default locale and character set 929and should not be implemented without their use. 930Using 8-bit characters may also affect other 931programs that transmit the contents of the GECOS field over the 932Internet, such as 933.Xr fingerd 8 , 934and a small number of TCP/IP clients, such as IRC, where full names 935specified in the passwd file may be used by default. 936.Pp 937The 938.Nm 939utility writes a log to the 940.Pa /var/log/userlog 941file when actions such as user or group additions or deletions occur. 942The location of this logfile can be changed in 943.Xr pw.conf 5 . 944.Sh FILES 945.Bl -tag -width /etc/master.passwd.new -compact 946.It Pa /etc/master.passwd 947The user database 948.It Pa /etc/passwd 949A Version 7 format password file 950.It Pa /etc/login.conf 951The user capabilities database 952.It Pa /etc/group 953The group database 954.It Pa /etc/pw.conf 955Pw default options file 956.It Pa /var/log/userlog 957User/group modification logfile 958.El 959.Sh EXIT STATUS 960The 961.Nm 962utility returns EXIT_SUCCESS on successful operation, otherwise 963.Nm 964returns one of the 965following exit codes defined by 966.Xr sysexits 3 967as follows: 968.Bl -tag -width xxxx 969.It EX_USAGE 970.Bl -bullet -compact 971.It 972Command line syntax errors (invalid keyword, unknown option). 973.El 974.It EX_NOPERM 975.Bl -bullet -compact 976.It 977Attempting to run one of the update modes as non-root. 978.El 979.It EX_OSERR 980.Bl -bullet -compact 981.It 982Memory allocation error. 983.It 984Read error from password file descriptor. 985.El 986.It EX_DATAERR 987.Bl -bullet -compact 988.It 989Bad or invalid data provided or missing on the command line or 990via the password file descriptor. 991.It 992Attempted to remove, rename root account or change its uid. 993.El 994.It EX_OSFILE 995.Bl -bullet -compact 996.It 997Skeleton directory is invalid or does not exist. 998.It 999Base home directory is invalid or does not exist. 1000.It 1001Invalid or non-existent shell specified. 1002.El 1003.It EX_NOUSER 1004.Bl -bullet -compact 1005.It 1006User, user id, group or group id specified does not exist. 1007.It 1008User or group recorded, added, or modified unexpectedly disappeared. 1009.El 1010.It EX_SOFTWARE 1011.Bl -bullet -compact 1012.It 1013No more group or user ids available within specified range. 1014.El 1015.It EX_IOERR 1016.Bl -bullet -compact 1017.It 1018Unable to rewrite configuration file. 1019.It 1020Error updating group or user database files. 1021.It 1022Update error for passwd or group database files. 1023.El 1024.It EX_CONFIG 1025.Bl -bullet -compact 1026.It 1027No base home directory configured. 1028.El 1029.El 1030.Sh SEE ALSO 1031.Xr chpass 1 , 1032.Xr passwd 1 , 1033.Xr umask 2 , 1034.Xr group 5 , 1035.Xr login.conf 5 , 1036.Xr passwd 5 , 1037.Xr pw.conf 5 , 1038.Xr pwd_mkdb 8 , 1039.Xr vipw 8 1040.Sh HISTORY 1041The 1042.Nm 1043utility was written to mimic many of the options used in the SYSV 1044.Em shadow 1045support suite, but is modified for passwd and group fields specific to 1046the 1047.Bx 4.4 1048operating system, and combines all of the major elements 1049into a single command. 1050