1.\" Copyright (c) 1995-1996 Wolfram Schneider <wosch@FreeBSD.org>. Berlin. 2.\" All rights reserved. 3.\" Copyright (c) 2002-2004 Michael Telahun Makonnen <mtm@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/usr.sbin/adduser/adduser.8,v 1.62 2008/03/16 21:36:05 brueffer Exp $ 28.\" 29.Dd September 10, 2019 30.Dt ADDUSER 8 31.Os 32.Sh NAME 33.Nm adduser 34.Nd command for adding new users 35.Sh SYNOPSIS 36.Nm 37.Op Fl CDENShq 38.Op Fl G Ar groups 39.Op Fl L Ar login_class 40.Op Fl M Ar mode 41.Op Fl d Ar partition 42.Op Fl f Ar file 43.Op Fl g Ar login_group 44.Op Fl k Ar dotdir 45.Op Fl m Ar message_file 46.Op Fl s Ar shell 47.Op Fl u Ar uid_start 48.Op Fl w Ar type 49.Sh DESCRIPTION 50The 51.Nm 52utility is a shell script, implemented around the 53.Xr pw 8 54command, for adding new users. 55It creates passwd/group entries, a home directory, 56copies dotfiles and sends the new user a welcome message. 57It supports two modes of operation. 58It may be used interactively 59at the command line to add one user at a time, or it may be directed 60to get the list of new users from a file and operate in batch mode 61without requiring any user interaction. 62.Sh RESTRICTIONS 63.Bl -tag -width indent 64.It username 65Login name. 66The user name is restricted to whatever 67.Xr pw 8 68will accept. 69Generally this means it 70may contain only lowercase characters or digits but cannot begin with the 71.Ql - 72character. 73Maximum length 74is 16 characters. 75The reasons for this limit are historical. 76Given that people have traditionally wanted to break this 77limit for aesthetic reasons, it has never been of great importance to break 78such a basic fundamental parameter in 79.Ux . 80The NIS protocol mandates an 8-character username. 81If you need a longer login name for e-mail addresses, 82you can define an alias in 83.Pa /etc/mail/aliases . 84.It "full name" 85This is typically known as the gecos field and usually contains 86the user's full name. 87Additionally, it may contain a comma separated 88list of values such as office number and work and home phones. 89If the 90name contains an ampersand it will be replaced by the capitalized 91login name when displayed by other programs. 92The 93.Ql \&: 94character is not allowed. 95.It shell 96Unless the 97.Fl S 98argument is supplied only valid shells from the shell database 99.Pq Pa /etc/shells 100are allowed. 101In addition, 102either the base name or the full path of the shell may be supplied. 103.It UID 104Automatically generated or your choice. 105It must be less than 32000. 106.It "GID/login group" 107Automatically generated or your choice. 108It must be less than 32000. 109.It password 110You may choose an empty password, disable the password, use a 111randomly generated password or specify your own plaintext password, 112which will be encrypted before being stored in the user database. 113.El 114.Sh UNIQUE GROUPS 115Perhaps you are missing what 116.Em can 117be done with this scheme that falls apart 118with most other schemes. 119With each user in their own group, 120they can safely run with a umask of 002 instead of the usual 022 121and create files in their home directory 122without worrying about others being able to change them. 123.Pp 124For a shared area you create a separate UID/GID (like cvs or ncvs on freefall), 125you place each person that should be able to access this area into that new 126group. 127.Pp 128This model of UID/GID administration allows far greater flexibility than lumping 129users into groups and having to muck with the umask when working in a shared 130area. 131.Pp 132I have been using this model for almost 10 years and found that it works 133for most situations, and has never gotten in the way. 134(Rod Grimes) 135.Sh CONFIGURATION 136The 137.Nm 138utility reads its configuration information from 139.Pa /etc/adduser.conf . 140If this file does not exist, it will use predefined defaults. 141While this file may be edited by hand, 142the safer option is to use the 143.Fl C 144command line argument. 145With this argument, 146.Nm 147will start interactive input, save the answers to its prompts in 148.Pa /etc/adduser.conf , 149and promptly exit without modifying the user 150database. 151Options specified on the command line will take precedence over 152any values saved in this file. 153.Sh OPTIONS 154.Bl -tag -width indent 155.It Fl C 156Create new configuration file and exit. 157This option is mutually exclusive with the 158.Fl f 159option. 160.It Fl d Ar partition 161Home partition. 162Default partition, under which all user directories 163will be located. 164The 165.Pa /nonexistent 166partition is considered special. 167The 168.Nm 169script will not create and populate a home directory by that name. 170Otherwise, 171by default it attempts to create a home directory. 172.It Fl D 173Do not attempt to create the home directory. 174.It Fl E 175Disable the account. 176This option will lock the account by prepending the string 177.Dq Li *LOCKED* 178to the password field. 179The account may be unlocked 180by the super-user with the 181.Xr pw 8 182command: 183.Pp 184.D1 Nm pw Cm unlock Op Ar name | uid 185.It Fl f Ar file 186Get the list of accounts to create from 187.Ar file . 188If 189.Ar file 190is 191.Dq Fl , 192then get the list from standard input. 193If this option is specified, 194.Nm 195will operate in batch mode and will not seek any user input. 196If an error is encountered while processing an account, it will write a 197message to standard error and move to the next account. 198The format 199of the input file is described below. 200.It Fl g Ar login_group 201Normally, 202if no login group is specified, 203it is assumed to be the same as the username. 204This option makes 205.Ar login_group 206the default. 207.It Fl G Ar groups 208Space-separated list of additional groups. 209This option allows the user to specify additional groups to add users to. 210The user is a member of these groups in addition to their login group. 211.It Fl h 212Print a summary of options and exit. 213.It Fl k Ar directory 214Copy files from 215.Ar directory 216into the home 217directory of new users; 218.Pa dot.foo 219will be renamed to 220.Pa .foo . 221.It Fl L Ar login_class 222Set default login class. 223.It Fl m Ar file 224Send new users a welcome message from 225.Ar file . 226Specifying a value of 227.Cm no 228for 229.Ar file 230causes no message to be sent to new users. 231Please note that the message 232file can reference the internal variables of the 233.Nm 234script. 235.It Fl M Ar mode 236Create the home directory with permissions set to 237.Ar mode . 238.It Fl N 239Do not read the default configuration file. 240.It Fl q 241Minimal user feedback. 242In particular, the random password will not be echoed to 243standard output. 244.It Fl s Ar shell 245Default shell for new users. 246The 247.Ar shell 248argument may be the base name of the shell or the full path. 249Unless the 250.Fl S 251argument is supplied the shell must exist in 252.Pa /etc/shells 253or be the special shell 254.Em nologin 255to be considered a valid shell. 256.It Fl S 257The existence or validity of the specified shell will not be checked. 258.It Fl u Ar uid 259Use UIDs from 260.Ar uid 261on up. 262.It Fl w Ar type 263Password type. 264The 265.Nm 266utility allows the user to specify what type of password to create. 267The 268.Ar type 269argument may have one of the following values: 270.Bl -tag -width ".Cm random" 271.It Cm no 272Disable the password. 273Instead of an encrypted string, the password field will contain a single 274.Ql * 275character. 276The user may not log in until the super-user 277manually enables the password. 278.It Cm none 279Use an empty string as the password. 280.It Cm yes 281Use a user-supplied string as the password. 282In interactive mode, 283the user will be prompted for the password. 284In batch mode, the 285last (10th) field in the line is assumed to be the password. 286.It Cm random 287Generate a random string and use it as a password. 288The password will be echoed to standard output. 289In addition, it will be available for inclusion in the message file in the 290.Va randompass 291variable. 292.El 293.El 294.Sh FORMAT 295When the 296.Fl f 297option is used, the account information must be stored in a specific 298format. 299All empty lines or lines beginning with a 300.Ql # 301will be ignored. 302All other lines must contain ten colon 303.Pq Ql \&: 304separated fields as described below. 305Command line options do not take precedence 306over values in the fields. 307Only the password field may contain a 308.Ql \&: 309character as part of the string. 310.Pp 311.Sm off 312.D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password 313.Sm on 314.Bl -tag -width ".Ar password" 315.It Ar name 316Login name. 317This field may not be empty. 318.It Ar uid 319Numeric login user ID. 320If this field is left empty, it will be automatically generated. 321.It Ar gid 322Numeric primary group ID. 323If this field is left empty, a group with the 324same name as the user name will be created and its GID will be used 325instead. 326.It Ar class 327Login class. 328This field may be left empty. 329.It Ar change 330Password ageing. 331This field denotes the password change date for the account. 332The format of this field is the same as the format of the 333.Fl p 334argument to 335.Xr pw 8 . 336It may be 337.Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy , 338where 339.Ar dd 340is for the day, 341.Ar mmm 342is for the month in numeric or alphabetical format: 343.Dq Li 10 344or 345.Dq Li Oct , 346and 347.Ar yy Ns Op Ar yy 348is the four or two digit year. 349To denote a time relative to the current date the format is: 350.No + Ns Ar n Ns Op Ar mhdwoy , 351where 352.Ar n 353denotes a number, followed by the minutes, hours, days, weeks, 354months or years after which the password must be changed. 355This field may be left empty to turn it off. 356.It Ar expire 357Account expiration. 358This field denotes the expiry date of the account. 359The account may not be used after the specified date. 360The format of this field is the same as that for password ageing. 361This field may be left empty to turn it off. 362.It Ar gecos 363Full name and other extra information about the user. 364.It Ar home_dir 365Home directory. 366If this field is left empty, it will be automatically 367created by appending the username to the home partition. 368The 369.Pa /nonexistent 370home directory is considered special and 371is understood to mean that no home directory is to be 372created for the user. 373.It Ar shell 374Login shell. 375This field should contain either the base name or 376the full path to a valid login shell. 377.It Ar password 378User password. 379This field should contain a plaintext string, which will 380be encrypted before being placed in the user database. 381If the password type is 382.Cm yes 383and this field is empty, it is assumed the account will have an empty password. 384If the password type is 385.Cm random 386and this field is 387.Em not 388empty, its contents will be used 389as a password. 390This field will be ignored if the 391.Fl w 392option is used with a 393.Cm no 394or 395.Cm none 396argument. 397Be careful not to terminate this field with a closing 398.Ql \&: 399because it will be treated as part of the password. 400.El 401.Sh FILES 402.Bl -tag -width ".Pa /etc/adduser.message" -compact 403.It Pa /etc/master.passwd 404user database 405.It Pa /etc/group 406group database 407.It Pa /etc/shells 408shell database 409.It Pa /etc/login.conf 410login classes database 411.It Pa /etc/adduser.conf 412configuration file for 413.Nm 414.It Pa /etc/adduser.message 415message file for 416.Nm 417.It Pa /usr/share/skel 418skeletal login directory 419.It Pa /var/log/adduser 420logfile for 421.Nm 422.El 423.Sh SEE ALSO 424.Xr chpass 1 , 425.Xr passwd 1 , 426.Xr adduser.conf 5 , 427.Xr aliases 5 , 428.Xr group 5 , 429.Xr login.conf 5 , 430.Xr passwd 5 , 431.Xr shells 5 , 432.Xr pw 8 , 433.Xr pwd_mkdb 8 , 434.Xr rmuser 8 , 435.Xr vipw 8 , 436.Xr yp 8 437.Sh HISTORY 438The 439.Nm 440command appeared in 441.Fx 2.1 . 442.Sh AUTHORS 443.An -nosplit 444This manual page and the original script, in Perl, were written by 445.An Wolfram Schneider Aq Mt wosch@FreeBSD.org . 446The replacement script, written as a Bourne 447shell script with some enhancements, and the man page modification that 448came with it were done by 449.An Mike Makonnen Aq Mt mtm@identd.net . 450.Sh BUGS 451In order for 452.Nm 453to correctly expand variables such as 454.Va $username 455and 456.Va $randompass 457in the message sent to new users, it must let the shell evaluate 458each line of the message file. 459This means that shell commands can also be embedded in the message file. 460The 461.Nm 462utility attempts to mitigate the possibility of an attacker using this 463feature by refusing to evaluate the file if it is not owned and writable 464only by the root user. 465In addition, shell special characters and operators will have to be 466escaped when used in the message file. 467.Pp 468Also, password ageing and account expiry times are currently settable 469only in batch mode or when specified in 470.Pa /etc/adduser.conf . 471The user should be able to set them in interactive mode as well. 472