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