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