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 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. 167The 168.Pa /nonexistent 169partition is considered special. 170The 171.Nm 172script will not create and populate a home directory by that name. 173Otherwise, 174by default it attempts to create a home directory. 175.It Fl D 176Do not attempt to create the home directory. 177.It Fl E 178Disable the account. 179This option will lock the account by prepending the string 180.Dq Li *LOCKED* 181to the password field. 182The account may be unlocked 183by the super-user with the 184.Xr pw 8 185command: 186.Pp 187.D1 Nm pw Cm unlock Op Ar name | uid 188.It Fl f Ar file 189Get the list of accounts to create from 190.Ar file . 191If 192.Ar file 193is 194.Dq Fl , 195then get the list from standard input. 196If this option is specified, 197.Nm 198will operate in batch mode and will not seek any user input. 199If an error is encountered while processing an account, it will write a 200message to standard error and move to the next account. 201The format 202of the input file is described below. 203.It Fl g Ar login_group 204Normaly, 205if no login group is specified, 206it is assumed to be the same as the username. 207This option makes 208.Ar login_group 209the default. 210.It Fl G Ar groups 211Additional groups. 212This option allows the user to specify additional groups to add users to. 213The user is a member of these groups in addition to their login group. 214.It Fl h 215Print a summary of options and exit. 216.It Fl k Ar directory 217Copy files from 218.Ar directory 219into the home 220directory of new users; 221.Pa dot.foo 222will be renamed to 223.Pa .foo . 224.It Fl L Ar login_class 225Set default login class. 226.It Fl m Ar file 227Send new users a welcome message from 228.Ar file . 229Specifying a value of 230.Cm no 231for 232.Ar file 233causes no message to be sent to new users. 234Please note that the message 235file can reference the internal variables of the 236.Nm 237script. 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 must be the base name of the shell, 249.Em not 250the full path. 251It 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 the full path to a valid login shell. 376.It Ar password 377User password. 378This field should contain a plaintext string, which will 379be encrypted before being placed in the user database. 380If the password type is 381.Cm yes 382and this field is empty, it is assumed the account will have an empty password. 383If the password type is 384.Cm random 385and this field is 386.Em not 387empty, its contents will be used 388as a password. 389This field will be ignored if the 390.Fl p 391option is used with a 392.Cm no 393or 394.Cm none 395argument. 396Be careful not to terminate this field with a closing 397.Ql \&: 398because it will be treated as part of the password. 399.El 400.Sh FILES 401.Bl -tag -width ".Pa /etc/adduser.message" -compact 402.It Pa /etc/master.passwd 403user database 404.It Pa /etc/group 405group database 406.It Pa /etc/shells 407shell database 408.It Pa /etc/login.conf 409login classes database 410.It Pa /etc/adduser.conf 411configuration file for 412.Nm 413.It Pa /etc/adduser.message 414message file for 415.Nm 416.It Pa /usr/share/skel 417skeletal login directory 418.It Pa /var/log/adduser 419logfile for 420.Nm 421.El 422.Sh SEE ALSO 423.Xr chpass 1 , 424.Xr passwd 1 , 425.Xr adduser.conf 5 , 426.Xr aliases 5 , 427.Xr group 5 , 428.Xr login.conf 5 , 429.Xr passwd 5 , 430.Xr shells 5 , 431.Xr pw 8 , 432.Xr pwd_mkdb 8 , 433.Xr rmuser 8 , 434.Xr vipw 8 , 435.Xr yp 8 436.Sh HISTORY 437The 438.Nm 439command appeared in 440.Fx 2.1 . 441.Sh AUTHORS 442.An -nosplit 443This manual page and the original script, in Perl, was written by 444.An Wolfram Schneider Aq wosch@FreeBSD.org . 445The replacement script, written as a Bourne 446shell script with some enhancements, and the man page modification that 447came with it were done by 448.An Mike Makonnen Aq mtm@identd.net . 449.Sh BUGS 450In order for 451.Nm 452to correctly expand variables such as 453.Va $username 454and 455.Va $randompass 456in the message sent to new users, it must let the shell evaluate 457each line of the message file. 458This means that shell commands can also be embedded in the message file. 459The 460.Nm 461utility attempts to mitigate the possibility of an attacker using this 462feature by refusing to evaluate the file if it is not owned and writeable 463only by the root user. 464In addition, shell special characters and operators will have to be 465escaped when used in the message file. 466.Pp 467Also, password ageing and account expiry times are currently setable 468only in batch mode or when specified in 469.Pa /etc/adduser.conf . 470The user should be able to set them in interactive mode as well. 471