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