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 February 8, 2019 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. 614When 615.Fl D 616is used, the 617.Ar days 618argument is interpreted differently. 619It must be numeric and represents the number of days after creation 620that the account expires. 621A value of 0 suppresses automatic calculation of the expiry date. 622.It Fl g Ar group 623Set the default group for new users. 624If a blank group is specified using 625.Fl g Ar \&"" , 626then new users will be allocated their own private primary group 627with the same name as their login name. 628If a group is supplied, either its name or uid may be given as an argument. 629.It Fl G Ar grouplist 630Set the default groups in which new users are granted membership. 631This is a separate set of groups from the primary group. 632Avoid nominating the same group as both primary and extra groups. 633In other words, these extra groups determine membership in groups 634.Em other than 635the primary group. 636.Ar grouplist 637is a comma-separated list of group names or ids, and are always 638stored in 639.Pa /etc/pw.conf 640by their symbolic names. 641.It Fl L Ar class 642This option sets the default login class for new users. 643.It Fl k Ar dir 644Set the default 645.Em skeleton 646directory, 647from which prototype shell and other initialization files are copied when 648.Nm 649creates a user's home directory. 650See description of 651.Fl k 652for naming conventions of these files. 653.It Xo 654.Fl u Ar min , Ns Ar max , 655.Fl i Ar min , Ns Ar max 656.Xc 657Set the minimum and maximum user and group ids allocated for new 658accounts and groups created by 659.Nm . 660The default values for each is 1000 minimum and 32000 maximum. 661.Ar min 662and 663.Ar max 664are both numbers, where max must be greater than min, 665and both must be between 0 and 32767. 666In general, 667user and group ids less than 100 are reserved for use by the system, 668and numbers greater than 32000 may also be reserved for special purposes 669.Pq used by some system daemons . 670.It Fl w Ar method 671The 672.Fl w 673option selects the default method used to set passwords for newly created user 674accounts. 675.Ar method 676is one of: 677.Pp 678.Bl -tag -width random -offset indent -compact 679.It no 680disable login on newly created accounts 681.It yes 682force the password to be the account name 683.It none 684force a blank password 685.It random 686generate a random password 687.El 688.Pp 689The 690.Ql \&random 691or 692.Ql \&no 693methods are the most secure; in the former case, 694.Nm 695generates a password and prints it to stdout, 696which is suitable when users are issued passwords rather than being allowed 697to select their own 698.Pq possibly poorly chosen 699password. 700The 701.Ql \&no 702method requires that the superuser use 703.Xr passwd 1 704to render the account accessible with a password. 705.It Fl y Ar path 706This sets the pathname of the database used by 707.Tn NIS 708if you are not sharing 709the information from 710.Pa /etc/master.passwd 711directly with 712.Tn NIS . 713You should only set this option for 714.Tn NIS 715servers. 716.El 717.Pp 718The 719.Ar userdel 720command has three distinct options. 721The 722.Fl n Ar name 723and 724.Fl u Ar uid 725options have already been covered above. 726The additional option is: 727.Bl -tag -width "-G grouplist" 728.It Fl r 729This tells 730.Nm 731to remove the user's home directory and all of its contents. 732The 733.Nm 734utility errs on the side of caution when removing files from the system. 735Firstly, 736it will not do so if the uid of the account being removed is also used by 737another account on the system, and the 'home' directory 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 any additional cleanup work is required, this is left to the administrator. 745.El 746.Pp 747Mail spool files and crontabs are always removed when an account is deleted as 748these are unconditionally attached to the user name. 749Jobs queued for processing by 750.Ar at 751are also removed if the user's uid is unique and not also used by another 752account on the system. 753.Pp 754The 755.Ar usermod 756command adds one additional option: 757.Bl -tag -width "-G grouplist" 758.It Fl l Ar newname 759This option allows changing of an existing account name to 760.Ql \&newname . 761The new name must not already exist, and any attempt to duplicate an 762existing account name will be rejected. 763.El 764.Pp 765The 766.Ar usershow 767command allows viewing of an account in one of two formats. 768By default, the format is identical to the format used in 769.Pa /etc/master.passwd 770with the password field replaced with a 771.Ql \&* . 772If the 773.Fl P 774option is used, then 775.Nm 776outputs the account details in a more human readable form. 777If the 778.Fl 7 779option is used, the account details are shown in v7 format. 780The 781.Fl a 782option lists all users currently on file. 783Using 784.Fl F 785forces 786.Nm 787to print the details of an account even if it does not exist. 788.Pp 789The command 790.Ar usernext 791returns the next available user and group ids separated by a colon. 792This is normally of interest only to interactive scripts or front-ends 793that use 794.Nm . 795.Sh GROUP OPTIONS 796The 797.Fl C 798and 799.Fl q 800options (explained at the start of the previous section) are available 801with the group manipulation commands. 802Other common options to all group-related commands are: 803.Bl -tag -width "-m newmembers" 804.It Oo Fl n Oc Ar name 805Required unless 806.Fl g Ar gid 807is given. 808Specify the group name. 809In the case of 810.Ar groupmod 811can be a gid. 812.It Fl g Ar gid 813Required if 814.Ar name 815is not given. 816Specify the group numeric id. 817In the case of 818.Ar groupmod 819if paired with 820.Ar name , 821changes the numeric id of the named group. 822.Pp 823As with the account name and id fields, you will usually only need 824to supply one of these, as the group name implies the uid and vice 825versa. 826You will only need to use both when setting a specific group id 827against a new group or when changing the uid of an existing group. 828.It Fl M Ar memberlist 829This option provides an alternative way to add existing users to a 830new group (in groupadd) or replace an existing membership list (in 831groupmod). 832.Ar memberlist 833is a comma separated list of valid and existing user names or uids. 834.It Fl m Ar newmembers 835Similar to 836.Fl M , 837this option allows the 838.Em addition 839of existing users to a group without replacing the existing list of 840members. 841Login names or user ids may be used, and duplicate users are 842silently eliminated. 843.It Fl d Ar oldmembers 844Similar to 845.Fl M , 846this option allows the 847.Em deletion 848of existing users from a group without replacing the existing list of 849members. 850Login names or user ids may be used, and duplicate users are 851silently eliminated. 852.El 853.Pp 854.Ar groupadd 855also has a 856.Fl o 857option that allows allocation of an existing group id to a new group. 858The default action is to reject an attempt to add a group, 859and this option overrides the check for duplicate group ids. 860There is rarely any need to duplicate a group id. 861.Pp 862The 863.Ar groupmod 864command adds one additional option: 865.Bl -tag -width "-m newmembers" 866.It Fl l Ar newname 867This option allows changing of an existing group name to 868.Ql \&newname . 869The new name must not already exist, 870and any attempt to duplicate an existing group 871name will be rejected. 872.El 873.Pp 874Options for 875.Ar groupshow 876are the same as for 877.Ar usershow , 878with the 879.Fl g Ar gid 880replacing 881.Fl u Ar uid 882to specify the group id. 883The 884.Fl 7 885option does not apply to the 886.Ar groupshow 887command. 888.Pp 889The command 890.Ar groupnext 891returns the next available group id on standard output. 892.Sh USER LOCKING 893The 894.Nm 895utility 896supports a simple password locking mechanism for users; it works by 897prepending the string 898.Ql *LOCKED* 899to the beginning of the password field in 900.Pa master.passwd 901to prevent successful authentication. 902.Pp 903The 904.Ar lock 905and 906.Ar unlock 907commands take a user name or uid of the account to lock or unlock, 908respectively. 909The 910.Fl V , 911.Fl C , 912and 913.Fl q 914options as described above are accepted by these commands. 915.Sh NOTES 916For a summary of options available with each command, you can use 917.Dl pw [command] help 918For example, 919.Dl pw useradd help 920lists all available options for the useradd operation. 921.Pp 922The 923.Nm 924utility allows 8-bit characters in the passwd GECOS field (user's full name, 925office, work and home phone number subfields), but disallows them in 926user login and group names. 927Use 8-bit characters with caution, as connection to the Internet will 928require that your mail transport program supports 8BITMIME, and will 929convert headers containing 8-bit characters to 7-bit quoted-printable 930format. 931.Xr sendmail 8 932does support this. 933Use of 8-bit characters in the GECOS field should be used in 934conjunction with the user's default locale and character set 935and should not be implemented without their use. 936Using 8-bit characters may also affect other 937programs that transmit the contents of the GECOS field over the 938Internet, such as 939.Xr fingerd 8 , 940and a small number of TCP/IP clients, such as IRC, where full names 941specified in the passwd file may be used by default. 942.Pp 943The 944.Nm 945utility writes a log to the 946.Pa /var/log/userlog 947file when actions such as user or group additions or deletions occur. 948The location of this logfile can be changed in 949.Xr pw.conf 5 . 950.Sh FILES 951.Bl -tag -width /etc/master.passwd.new -compact 952.It Pa /etc/master.passwd 953The user database 954.It Pa /etc/passwd 955A Version 7 format password file 956.It Pa /etc/login.conf 957The user capabilities database 958.It Pa /etc/group 959The group database 960.It Pa /etc/pw.conf 961Pw default options file 962.It Pa /var/log/userlog 963User/group modification logfile 964.El 965.Sh EXAMPLES 966Add new user Glurmo Smith (gsmith). 967A gsmith login group is created if not already present. 968The login shell is set to 969.Xr csh 1 . 970A new home directory at 971.Pa /home/gsmith 972is created if it does not already exist. 973Finally, a random password is generated and displayed: 974.Bd -literal -offset indent 975pw useradd -n gsmith -c "Glurmo Smith" -s /bin/csh -m -w random 976.Ed 977.Pp 978Delete the gsmith user and their home directory, including contents. 979.Bd -literal -offset indent 980pw userdel -n gsmith -r 981.Ed 982.Pp 983Add the existing user jsmith to the wheel group, 984in addition to the other groups jsmith is already a member of. 985.Bd -literal -offset indent 986pw groupmod wheel -m jsmith 987.Ed 988.Sh EXIT STATUS 989The 990.Nm 991utility returns EXIT_SUCCESS on successful operation, otherwise 992.Nm 993returns one of the 994following exit codes defined by 995.Xr sysexits 3 996as follows: 997.Bl -tag -width xxxx 998.It EX_USAGE 999.Bl -bullet -compact 1000.It 1001Command line syntax errors (invalid keyword, unknown option). 1002.El 1003.It EX_NOPERM 1004.Bl -bullet -compact 1005.It 1006Attempting to run one of the update modes as non-root. 1007.El 1008.It EX_OSERR 1009.Bl -bullet -compact 1010.It 1011Memory allocation error. 1012.It 1013Read error from password file descriptor. 1014.El 1015.It EX_DATAERR 1016.Bl -bullet -compact 1017.It 1018Bad or invalid data provided or missing on the command line or 1019via the password file descriptor. 1020.It 1021Attempted to remove, rename root account or change its uid. 1022.El 1023.It EX_OSFILE 1024.Bl -bullet -compact 1025.It 1026Skeleton directory is invalid or does not exist. 1027.It 1028Base home directory is invalid or does not exist. 1029.It 1030Invalid or non-existent shell specified. 1031.El 1032.It EX_NOUSER 1033.Bl -bullet -compact 1034.It 1035User, user id, group or group id specified does not exist. 1036.It 1037User or group recorded, added, or modified unexpectedly disappeared. 1038.El 1039.It EX_SOFTWARE 1040.Bl -bullet -compact 1041.It 1042No more group or user ids available within specified range. 1043.El 1044.It EX_IOERR 1045.Bl -bullet -compact 1046.It 1047Unable to rewrite configuration file. 1048.It 1049Error updating group or user database files. 1050.It 1051Update error for passwd or group database files. 1052.El 1053.It EX_CONFIG 1054.Bl -bullet -compact 1055.It 1056No base home directory configured. 1057.El 1058.El 1059.Sh SEE ALSO 1060.Xr chpass 1 , 1061.Xr passwd 1 , 1062.Xr umask 2 , 1063.Xr group 5 , 1064.Xr login.conf 5 , 1065.Xr passwd 5 , 1066.Xr pw.conf 5 , 1067.Xr pwd_mkdb 8 , 1068.Xr vipw 8 1069.Sh HISTORY 1070The 1071.Nm 1072utility was written to mimic many of the options used in the SYSV 1073.Em shadow 1074support suite, but is modified for passwd and group fields specific to 1075the 1076.Bx 4.4 1077operating system, and combines all of the major elements 1078into a single command. 1079