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: src/usr.sbin/adduser/adduser.8,v 1.55 2004/06/06 17:55:55 mtm Exp $
  28 .\" $DragonFly: src/usr.sbin/adduser/adduser.8,v 1.4 2007/05/17 08:19:03 swildner Exp $
  29 .\"
  30 .Dd March 30, 2004
  31 .Dt ADDUSER 8
  32 .Os
  33 .Sh NAME
  34 .Nm adduser
  35 .Nd command for adding new users
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl CDENShq
  39 .Op Fl G Ar groups
  40 .Op Fl L Ar login_class
  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.
  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 and 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 (like cvs or ncvs on freefall),
 131 you place each person that should be able to access this area into that new
 132 group.
 133 .Pp
 134 This model of UID/GID administration allows far greater flexibility than lumping
 135 users into groups and having to muck with the umask when working in a shared
 136 area.
 137 .Pp
 138 I have been using this model for almost 10 years and found that it works
 139 for most situations, and has never gotten in the way.
 140 (Rod Grimes)
 141 .Sh CONFIGURATION
 142 The
 143 .Nm
 144 utility reads its configuration information from
 145 .Pa /etc/adduser.conf .
 146 If this file does not exist, it will use predefined defaults.
 147 While this file may be edited by hand,
 148 the safer option is to use the
 149 .Fl C
 150 command line argument.
 151 With this argument,
 152 .Nm
 153 will start interactive input, save the answers to its prompts in
 154 .Pa /etc/adduser.conf ,
 155 and promptly exit without modifying the user
 156 database.
 157 Options specified on the command line will take precedence over
 158 any values saved in this file.
 159 .Sh OPTIONS
 160 .Bl -tag -width indent
 161 .It Fl C
 162 Create new configuration file and exit.
 163 This option is mutually exclusive with the
 164 .Fl f
 165 option.
 166 .It Fl d Ar partition
 167 Home partition.
 168 Default partition, under which all user directories
 169 will be located.
 170 The
 171 .Pa /nonexistent
 172 partition is considered special.
 173 The
 174 .Nm
 175 script will not create and populate a home directory by that name.
 176 Otherwise,
 177 by default it attempts to create a home directory.
 178 .It Fl D
 179 Do not attempt to create the home directory.
 180 .It Fl E
 181 Disable the account.
 182 This option will lock the account by prepending the string
 183 .Dq Li *LOCKED*
 184 to the password field.
 185 The account may be unlocked
 186 by the super-user with the
 187 .Xr pw 8
 188 command:
 189 .Pp
 190 .D1 Nm pw Cm unlock Op Ar name | uid
 191 .It Fl f Ar file
 192 Get the list of accounts to create from
 193 .Ar file .
 194 If
 195 .Ar file
 196 is
 197 .Dq Fl ,
 198 then get the list from standard input.
 199 If this option is specified,
 200 .Nm
 201 will operate in batch mode and will not seek any user input.
 202 If an error is encountered while processing an account, it will write a
 203 message to standard error and move to the next account.
 204 The format
 205 of the input file is described below.
 206 .It Fl g Ar login_group
 207 Normally,
 208 if no login group is specified,
 209 it is assumed to be the same as the username.
 210 This option makes
 211 .Ar login_group
 212 the default.
 213 .It Fl G Ar groups
 214 Additional groups.
 215 This option allows the user to specify additional groups to add users to.
 216 The user is a member of these groups in addition to their login group.
 217 .It Fl h
 218 Print a summary of options and exit.
 219 .It Fl k Ar directory
 220 Copy files from
 221 .Ar directory
 222 into the home
 223 directory of new users;
 224 .Pa dot.foo
 225 will be renamed to
 226 .Pa .foo .
 227 .It Fl L Ar login_class
 228 Set default login class.
 229 .It Fl m Ar file
 230 Send new users a welcome message from
 231 .Ar file .
 232 Specifying a value of
 233 .Cm no
 234 for
 235 .Ar file
 236 causes no message to be sent to new users.
 237 Please note that the message
 238 file can reference the internal variables of the
 239 .Nm
 240 script.
 241 .It Fl N
 242 Do not read the default configuration file.
 243 .It Fl q
 244 Minimal user feedback.
 245 In particular, the random password will not be echoed to
 246 standard output.
 247 .It Fl s Ar shell
 248 Default shell for new users.
 249 The
 250 .Ar shell
 251 argument may be the base name of the shell or the full path.
 252 Unless the
 253 .Fl S
 254 argument is supplied the shell must exist in
 255 .Pa /etc/shells
 256 or be the special shell
 257 .Em nologin
 258 to be considered a valid shell.
 259 .It Fl S
 260 The existence or validity of the specified shell will not be checked.
 261 .It Fl u Ar uid
 262 Use UIDs from
 263 .Ar uid
 264 on up.
 265 .It Fl w Ar type
 266 Password type.
 267 The
 268 .Nm
 269 utility allows the user to specify what type of password to create.
 270 The
 271 .Ar type
 272 argument may have one of the following values:
 273 .Bl -tag -width ".Cm random"
 274 .It Cm no
 275 Disable the password.
 276 Instead of an encrypted string, the password field will contain a single
 277 .Ql *
 278 character.
 279 The user may not log in until the super-user
 280 manually enables the password.
 281 .It Cm none
 282 Use an empty string as the password.
 283 .It Cm yes
 284 Use a user-supplied string as the password.
 285 In interactive mode,
 286 the user will be prompted for the password.
 287 In batch mode, the
 288 last (10th) field in the line is assumed to be the password.
 289 .It Cm random
 290 Generate a random string and use it as a password.
 291 The password will be echoed to standard output.
 292 In addition, it will be available for inclusion in the message file in the
 293 .Va randompass
 294 variable.
 295 .El
 296 .El
 297 .Sh FORMAT
 298 When the
 299 .Fl f
 300 option is used, the account information must be stored in a specific
 301 format.
 302 All empty lines or lines beginning with a
 303 .Ql #
 304 will be ignored.
 305 All other lines must contain ten colon
 306 .Pq Ql \&:
 307 separated fields as described below.
 308 Command line options do not take precedence
 309 over values in the fields.
 310 Only the password field may contain a
 311 .Ql \&:
 312 character as part of the string.
 313 .Pp
 314 .Sm off
 315 .D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password
 316 .Sm on
 317 .Bl -tag -width ".Ar password"
 318 .It Ar name
 319 Login name.
 320 This field may not be empty.
 321 .It Ar uid
 322 Numeric login user ID.
 323 If this field is left empty, it will be automatically generated.
 324 .It Ar gid
 325 Numeric primary group ID.
 326 If this field is left empty, a group with the
 327 same name as the user name will be created and its GID will be used
 328 instead.
 329 .It Ar class
 330 Login class.
 331 This field may be left empty.
 332 .It Ar change
 333 Password ageing.
 334 This field denotes the password change date for the account.
 335 The format of this field is the same as the format of the
 336 .Fl p
 337 argument to
 338 .Xr pw 8 .
 339 It may be
 340 .Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy ,
 341 where
 342 .Ar dd
 343 is for the day,
 344 .Ar mmm
 345 is for the month in numeric or alphabetical format:
 346 .Dq Li 10
 347 or
 348 .Dq Li Oct ,
 349 and
 350 .Ar yy Ns Op Ar yy
 351 is the four or two digit year.
 352 To denote a time relative to the current date the format is:
 353 .No + Ns Ar n Ns Op Ar mhdwoy ,
 354 where
 355 .Ar n
 356 denotes a number, followed by the minutes, hours, days, weeks,
 357 months or years after which the password must be changed.
 358 This field may be left empty to turn it off.
 359 .It Ar expire
 360 Account expiration.
 361 This field denotes the expiry date of the account.
 362 The account may not be used after the specified date.
 363 The format of this field is the same as that for password ageing.
 364 This field may be left empty to turn it off.
 365 .It Ar gecos
 366 Full name and other extra information about the user.
 367 .It Ar home_dir
 368 Home directory.
 369 If this field is left empty, it will be automatically
 370 created by appending the username to the home partition.
 371 The
 372 .Pa /nonexistent
 373 home directory is considered special and
 374 is understood to mean that no home directory is to be
 375 created for the user.
 376 .It Ar shell
 377 Login shell.
 378 This field should contain either the base name or
 379 the full path to a valid login shell.
 380 .It Ar password
 381 User password.
 382 This field should contain a plaintext string, which will
 383 be encrypted before being placed in the user database.
 384 If the password type is
 385 .Cm yes
 386 and this field is empty, it is assumed the account will have an empty password.
 387 If the password type is
 388 .Cm random
 389 and this field is
 390 .Em not
 391 empty, its contents will be used
 392 as a password.
 393 This field will be ignored if the
 394 .Fl p
 395 option is used with a
 396 .Cm no
 397 or
 398 .Cm none
 399 argument.
 400 Be careful not to terminate this field with a closing
 401 .Ql \&:
 402 because it will be treated as part of the password.
 403 .El
 404 .Sh FILES
 405 .Bl -tag -width ".Pa /etc/adduser.message" -compact
 406 .It Pa /etc/master.passwd
 407 user database
 408 .It Pa /etc/group
 409 group database
 410 .It Pa /etc/shells
 411 shell database
 412 .It Pa /etc/login.conf
 413 login classes database
 414 .It Pa /etc/adduser.conf
 415 configuration file for
 416 .Nm
 417 .It Pa /etc/adduser.message
 418 message file for
 419 .Nm
 420 .It Pa /usr/share/skel
 421 skeletal login directory
 422 .It Pa /var/log/adduser
 423 logfile for
 424 .Nm
 425 .El
 426 .Sh SEE ALSO
 427 .Xr chpass 1 ,
 428 .Xr passwd 1 ,
 429 .Xr adduser.conf 5 ,
 430 .Xr aliases 5 ,
 431 .Xr group 5 ,
 432 .Xr login.conf 5 ,
 433 .Xr passwd 5 ,
 434 .Xr shells 5 ,
 435 .Xr pw 8 ,
 436 .Xr pwd_mkdb 8 ,
 437 .Xr rmuser 8 ,
 438 .Xr vipw 8 ,
 439 .Xr yp 8
 440 .Sh HISTORY
 441 The
 442 .Nm
 443 command appeared in
 444 .Fx 2.1 .
 445 .Sh AUTHORS
 446 .An -nosplit
 447 This manual page and the original script, in Perl, was written by
 448 .An Wolfram Schneider Aq wosch@FreeBSD.org .
 449 The replacement script, written as a Bourne
 450 shell script with some enhancements, and the man page modification that
 451 came with it were done by
 452 .An Mike Makonnen Aq mtm@identd.net .
 453 .Sh BUGS
 454 In order for
 455 .Nm
 456 to correctly expand variables such as
 457 .Va $username
 458 and
 459 .Va $randompass
 460 in the message sent to new users, it must let the shell evaluate
 461 each line of the message file.
 462 This means that shell commands can also be embedded in the message file.
 463 The
 464 .Nm
 465 utility attempts to mitigate the possibility of an attacker using this
 466 feature by refusing to evaluate the file if it is not owned and writeable
 467 only by the root user.
 468 In addition, shell special characters and operators will have to be
 469 escaped when used in the message file.
 470 .Pp
 471 Also, password ageing and account expiry times are currently settable
 472 only in batch mode or when specified in
 473 .Pa /etc/adduser.conf .
 474 The user should be able to set them in interactive mode as well.