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 .\" $FreeBSD$
  28 .\"
  29 .Dd June 7, 2006
  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
  49 The
  50 .Nm
  51 utility is a shell script, implemented around the
  52 .Xr pw 8
  53 command, for adding new users.
  54 It creates passwd/group entries, a home directory,
  55 copies dotfiles and sends the new user a welcome message.
  56 It supports two modes of operation.
  57 It may be used interactively
  58 at the command line to add one user at a time, or it may be directed
  59 to get the list of new users from a file and operate in batch mode
  60 without requiring any user interaction.
  61 .Sh RESTRICTIONS
  62 .Bl -tag -width indent
  63 .It username
  64 Login name.
  65 The user name is restricted to whatever
  66 .Xr pw 8
  67 will accept.
  68 Generally this means it
  69 may contain only lowercase characters or digits but cannot begin with
  70 .Sq Fl
  71 character.
  72 Maximum length
  73 is 16 characters.
  74 The reasons for this limit are historical.
  75 Given that people have traditionally wanted to break this
  76 limit for aesthetic reasons, it has never been of great importance to break
  77 such a basic fundamental parameter in
  78 .Ux .
  79 You can change
  80 .Dv UT_NAMESIZE
  81 in
  82 .In utmp.h
  83 and recompile the
  84 world; people have done this and it works, but you will have problems
  85 with any precompiled programs, or source that assumes the 8-character
  86 name limit, such as NIS.
  87 The NIS protocol mandates an 8-character username.
  88 If you need a longer login name for e-mail addresses,
  89 you can define an alias in
  90 .Pa /etc/mail/aliases .
  91 .It "full name"
  92 This is typically known as the gecos field and usually contains
  93 the user's full name.
  94 Additionally, it may contain a comma separated
  95 list of values such as office number and work and home phones.
  96 If the
  97 name contains an ampersand it will be replaced by the capitalized
  98 login name when displayed by other programs.
  99 The
 100 .Ql \&:
 101 character is not allowed.
 102 .It shell
 103 Unless the
 104 .Fl S
 105 argument is supplied only valid shells from the shell database
 106 .Pq Pa /etc/shells
 107 are allowed.
 108 In addition,
 109 either the base name or the full path of the shell may be supplied.
 110 .It UID
 111 Automatically generated or your choice.
 112 It must be less than 32000.
 113 .It "GID/login group"
 114 Automatically generated or your choice.
 115 It must be less than 32000.
 116 .It password
 117 You may choose an empty password, disable the password, use a
 118 randomly generated password or specify your own plaintext password,
 119 which will be encrypted before being stored in the user database.
 120 .El
 121 .Sh UNIQUE GROUPS
 122 Perhaps you are missing what
 123 .Em can
 124 be done with this scheme that falls apart
 125 with most other schemes.
 126 With each user in their own group,
 127 they can safely run with a umask of 002 instead of the usual 022
 128 and create files in their home directory
 129 without worrying about others being able to change them.
 130 .Pp
 131 For a shared area you create a separate UID/GID (like cvs or ncvs on freefall),
 132 you place each person that should be able to access this area into that new
 133 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 Normaly,
 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 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 N
 243 Do not read the default configuration file.
 244 .It Fl q
 245 Minimal user feedback.
 246 In particular, the random password will not be echoed to
 247 standard output.
 248 .It Fl s Ar shell
 249 Default shell for new users.
 250 The
 251 .Ar shell
 252 argument may be the base name of the shell or the full path.
 253 Unless the
 254 .Fl S
 255 argument is supplied the shell must exist in
 256 .Pa /etc/shells
 257 or be the special shell
 258 .Em nologin
 259 to be considered a valid shell.
 260 .It Fl S
 261 The existence or validity of the specified shell will not be checked.
 262 .It Fl u Ar uid
 263 Use UIDs from
 264 .Ar uid
 265 on up.
 266 .It Fl w Ar type
 267 Password type.
 268 The
 269 .Nm
 270 utility allows the user to specify what type of password to create.
 271 The
 272 .Ar type
 273 argument may have one of the following values:
 274 .Bl -tag -width ".Cm random"
 275 .It Cm no
 276 Disable the password.
 277 Instead of an encrypted string, the password field will contain a single
 278 .Ql *
 279 character.
 280 The user may not log in until the super-user
 281 manually enables the password.
 282 .It Cm none
 283 Use an empty string as the password.
 284 .It Cm yes
 285 Use a user-supplied string as the password.
 286 In interactive mode,
 287 the user will be prompted for the password.
 288 In batch mode, the
 289 last (10th) field in the line is assumed to be the password.
 290 .It Cm random
 291 Generate a random string and use it as a password.
 292 The password will be echoed to standard output.
 293 In addition, it will be available for inclusion in the message file in the
 294 .Va randompass
 295 variable.
 296 .El
 297 .El
 298 .Sh FORMAT
 299 When the
 300 .Fl f
 301 option is used, the account information must be stored in a specific
 302 format.
 303 All empty lines or lines beginning with a
 304 .Ql #
 305 will be ignored.
 306 All other lines must contain ten colon
 307 .Pq Ql \&:
 308 separated fields as described below.
 309 Command line options do not take precedence
 310 over values in the fields.
 311 Only the password field may contain a
 312 .Ql \&:
 313 character as part of the string.
 314 .Pp
 315 .Sm off
 316 .D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password
 317 .Sm on
 318 .Bl -tag -width ".Ar password"
 319 .It Ar name
 320 Login name.
 321 This field may not be empty.
 322 .It Ar uid
 323 Numeric login user ID.
 324 If this field is left empty, it will be automatically generated.
 325 .It Ar gid
 326 Numeric primary group ID.
 327 If this field is left empty, a group with the
 328 same name as the user name will be created and its GID will be used
 329 instead.
 330 .It Ar class
 331 Login class.
 332 This field may be left empty.
 333 .It Ar change
 334 Password ageing.
 335 This field denotes the password change date for the account.
 336 The format of this field is the same as the format of the
 337 .Fl p
 338 argument to
 339 .Xr pw 8 .
 340 It may be
 341 .Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy ,
 342 where
 343 .Ar dd
 344 is for the day,
 345 .Ar mmm
 346 is for the month in numeric or alphabetical format:
 347 .Dq Li 10
 348 or
 349 .Dq Li Oct ,
 350 and
 351 .Ar yy Ns Op Ar yy
 352 is the four or two digit year.
 353 To denote a time relative to the current date the format is:
 354 .No + Ns Ar n Ns Op Ar mhdwoy ,
 355 where
 356 .Ar n
 357 denotes a number, followed by the minutes, hours, days, weeks,
 358 months or years after which the password must be changed.
 359 This field may be left empty to turn it off.
 360 .It Ar expire
 361 Account expiration.
 362 This field denotes the expiry date of the account.
 363 The account may not be used after the specified date.
 364 The format of this field is the same as that for password ageing.
 365 This field may be left empty to turn it off.
 366 .It Ar gecos
 367 Full name and other extra information about the user.
 368 .It Ar home_dir
 369 Home directory.
 370 If this field is left empty, it will be automatically
 371 created by appending the username to the home partition.
 372 The
 373 .Pa /nonexistent
 374 home directory is considered special and
 375 is understood to mean that no home directory is to be
 376 created for the user.
 377 .It Ar shell
 378 Login shell.
 379 This field should contain either the base name or
 380 the full path to a valid login shell.
 381 .It Ar password
 382 User password.
 383 This field should contain a plaintext string, which will
 384 be encrypted before being placed in the user database.
 385 If the password type is
 386 .Cm yes
 387 and this field is empty, it is assumed the account will have an empty password.
 388 If the password type is
 389 .Cm random
 390 and this field is
 391 .Em not
 392 empty, its contents will be used
 393 as a password.
 394 This field will be ignored if the
 395 .Fl p
 396 option is used with a
 397 .Cm no
 398 or
 399 .Cm none
 400 argument.
 401 Be careful not to terminate this field with a closing
 402 .Ql \&:
 403 because it will be treated as part of the password.
 404 .El
 405 .Sh FILES
 406 .Bl -tag -width ".Pa /etc/adduser.message" -compact
 407 .It Pa /etc/master.passwd
 408 user database
 409 .It Pa /etc/group
 410 group database
 411 .It Pa /etc/shells
 412 shell database
 413 .It Pa /etc/login.conf
 414 login classes database
 415 .It Pa /etc/adduser.conf
 416 configuration file for
 417 .Nm
 418 .It Pa /etc/adduser.message
 419 message file for
 420 .Nm
 421 .It Pa /usr/share/skel
 422 skeletal login directory
 423 .It Pa /var/log/adduser
 424 logfile for
 425 .Nm
 426 .El
 427 .Sh SEE ALSO
 428 .Xr chpass 1 ,
 429 .Xr passwd 1 ,
 430 .Xr adduser.conf 5 ,
 431 .Xr aliases 5 ,
 432 .Xr group 5 ,
 433 .Xr login.conf 5 ,
 434 .Xr passwd 5 ,
 435 .Xr shells 5 ,
 436 .Xr adding_user 8 ,
 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 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 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 writeable
 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 setable
 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.