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