adduser/adduser.8

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