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