adduser/adduser.8

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