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