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