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