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 .Bk -words
  38 .Op Fl CENhq
  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 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 .Ek
  49 .Sh DESCRIPTION
  50 The
  51 .Nm adduser
  52 program 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. 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 Ds -compact
  63 .It Sy username
  64 Login name.
  65 The user name is restricted to whatever
  66 .Xr pw 8
  67 will accept. Generally this means it
  68 may contain only lowercase characters or digits.
  69 Maximum length
  70 is 16 characters.
  71 The reasons for this limit are "Historical".
  72 Given that people have traditionally wanted to break this
  73 limit for aesthetic reasons, it's never been of great importance to break
  74 such a basic fundamental parameter in UNIX.
  75 You can change
  76 .Dv UT_NAMESIZE
  77 in
  78 .Pa /usr/include/utmp.h
  79 and recompile the
  80 world; people have done this and it works, but you will have problems
  81 with any precompiled programs, or source that assumes the 8-character
  82 name limit and NIS.
  83 The NIS protocol mandates an 8-character username.
  84 If you need a longer login name for e-mail addresses,
  85 you can define an alias in
  86 .Pa /etc/mail/aliases .
  87 .It Sy full name
  88 This is typically known as the gecos field and usually contains
  89 the user's full name. Additionally, it may contain a comma separated
  90 list of values such as office number and work and home phones. If the
  91 name contains an amperstand it will be replaced by the capitalized
  92 login name when displayed by other programs.
  93 The
  94 .Ql Pa \&:
  95 character is not allowed.
  96 .It Sy shell
  97 Only valid shells from the shell database (/etc/shells) are allowed. In
  98 addition, only the base name of the shell is necessary, not the full path.
  99 .It Sy uid
 100 Automatically generated or your choice. It must be less than 32000.
 101 .It Sy gid/login group
 102 Automatically generated or your choice. It must be less than 32000.
 103 .It Sy password
 104 You may choose an empty password, disable the password, use a
 105 randomly generated password or specify your own plaintext password,
 106 which will be encrypted before being stored in the user database.
 107 .El
 108 .Sh UNIQUE GROUPS
 109 Perhaps you're missing what
 110 .Em can
 111 be done with this scheme that falls apart
 112 with most other schemes.
 113 With each user in his/her own group the user can
 114 safely run with a umask of 002 instead of the usual 022
 115 and create files in their home directory
 116 without worrying about others being able to change them.
 117 .Pp
 118 For a shared area you create a separate uid/gid (like cvs or ncvs on freefall),
 119 you place each person that should be able to access this area into that new
 120 group.
 121 .Pp
 122 This model of uid/gid administration allows far greater flexibility than lumping
 123 users into groups and having to muck with the umask when working in a shared
 124 area.
 125 .Pp
 126 I have been using this model for almost 10 years and found that it works
 127 for most situations, and has never gotten in the way.  (Rod Grimes)
 128 .Sh CONFIGURATION
 129 The
 130 .Nm
 131 utility reads its configuration information from
 132 .Ar /etc/adduser.conf .
 133 If this file does not exist it will use predefined defaults. While
 134 this file may be edited by hand the safer option is to use the
 135 .Op Fl C
 136 command line argument. With this argument
 137 .Nm
 138 will start interactive input, save the answers to its prompts in
 139 .Ar /etc/adduser.conf ,
 140 and promptly exit without modifying the user
 141 database. Options specified on the command line will take precedence over
 142 any values saved in this file.
 143 .Sh OPTIONS
 144 .Bl -tag -width Ds
 145 .It Fl C
 146 Create new configuration file and exit. This option is mutually exclusive
 147 with the
 148 .Op Fl f
 149 option.
 150 .It Fl d Ar partition
 151 Home partition. Default partition, under which all user directories
 152 will be located.
 153 .It Fl E
 154 Disable the account. This option will lock the account by prepending
 155 the string *LOCKED* to the password field. The account may be unlocked
 156 by the super-user with the
 157 .Xr pw 8
 158 command:
 159 .Pp
 160 .Dl "pw unlock [name|uid]"
 161 .It Fl f Ar file
 162 Get the list of accounts to create from
 163 .Ar file .
 164 If
 165 .Ar file
 166 is '`-'', then get the list from standard input. If this option
 167 is specified
 168 .Nm
 169 will operate in batch mode and will not seek any user input. If an
 170 error is encountered while processing an account it will write a
 171 message to standard error and move to the next account. The format
 172 of the input file is described below.
 173 .It Fl G Ar groups
 174 Additional group(s). By default the user name is used as the login group.
 175 This option allows the user to specify additional groups to add users to.
 176 .It Fl h
 177 Print a summary of options and exit.
 178 .It Fl k Ar directory
 179 Copy files from
 180 .Ar directory
 181 into the home
 182 directory of new users,
 183 .Ql Pa dot.foo
 184 will be renamed to
 185 .Ql Pa .foo .
 186 .It Fl L Ar login_class
 187 Set default login class.
 188 .It Fl m Ar file
 189 Send new users a welcome message from
 190 .Ar file .
 191 Specifying a value of
 192 .Ar no
 193 for
 194 .Ar file
 195 causes no message to be sent to new users. Please note that the message
 196 file can reference the internal variables of the
 197 .Nm
 198 script.
 199 .It Fl N
 200 Do not read the default configuration file.
 201 .It Fl q
 202 Minimal user feedback. In particular, the random password will not be echoed to
 203 standard output.
 204 .It Fl s Ar shell
 205 Default shell for new users. The
 206 .Ar shell
 207 argument must be the base name of the shell , NOT the full path.
 208 It must exist in
 209 .Ar /etc/shells
 210 to be considered a valid shell.
 211 .It Fl u Ar uid
 212 Use uid's from
 213 .Ar uid
 214 on up.
 215 .It Fl w Ar type
 216 Password type. The
 217 .Nm
 218 utility allows the user to specify what type of password to create.
 219 The
 220 .Ar type
 221 argument may have one of the following values:
 222 .Bl -tag -width ".Dv random"
 223 .It Dv no
 224 Disable the password. Instead of an encrypted string the passowrd field
 225 will contain a single '`*'' character.
 226 The user may not login until the super-user
 227 manually enables the password.
 228 .It Dv none
 229 Use an empty string as the password.
 230 .It Dv yes
 231 Use a user supplied string as the password. In interactive mode
 232 the user will be prompted for the password. In batch mode, the
 233 last (10th) field in the line is assumed to be the password.
 234 .It Dv random
 235 Generate a random string and use it as a password. The password will
 236 be echoed to standard output. In addition it will be available for
 237 inclusion in the message file in the
 238 .Ar randompass
 239 environment variable.
 240 .El
 241 .Sh FORMAT
 242 .Bl -tag -width Ds -compact
 243 When the
 244 .Op Fl f
 245 option is used the account information must be stored in a specific
 246 format. All empty lines or lines beginning with a
 247 .Ql Pa #
 248 will be ignored. All other lines must contain ten colon (:) separated
 249 fields as described below. Command line options do not take precedence
 250 over values in the fields. Only the password field may contain a
 251 .Ql Pa :
 252 character as part of the string.
 253 .Pp
 254 .Dl "name:uid:gid:class:change:expire:gecos:home_dir:shell:password"
 255 .Bl -tag -width ".Dv password"
 256 .It Dv name
 257 Login name. This field may not be empty.
 258 .It Dv uid
 259 Numeric login user id. If this field is left empty it will be automatically
 260 generated.
 261 .It Dv gid
 262 Numeric primary group id. If this field is left empty a group with the
 263 same name as the user name will be created and its gid will be used
 264 instead.
 265 .It Dv class
 266 Login class. This field may be left empty.
 267 .It Dv change
 268 Password ageing.
 269 This field denotes the password change date for the account. The format of this
 270 field is the same as the format of the
 271 .Op Fl p
 272 argument to
 273 .Xr pw 8 .
 274 It may be 'dd-mmm-yy[yy]', where 'dd' is for the day, 'mmm' is for the month
 275 in numeric or alphabetical format: '10 or Oct', and 'yy[yy]' is the four or two digit year.
 276 To denote a time relative to the current date the format
 277 is: '+n[mhdwoy]', where 'n' denotes a number, followed by the Minutes, Hours,
 278 Days, Weeks, Months or Years after which the password must be changed.
 279 This field may be left empty to turn it off.
 280 .It Dv expire
 281 Account expiration. This field denotes the expiry date of the account. The account may
 282 not be used after the specified date. The format of this field is the same as that
 283 for password ageing. This field may be left empty to turn it off.
 284 .It Dv gecos
 285 Full name and other extra information about the user.
 286 .It Dv home_dir
 287 Home directory. If this field is left empty it will be automatically
 288 created by appending the username to the home partition.
 289 .It Dv shell
 290 Login Shell. This field should contain the full path to a valid login shell.
 291 .It Dv password
 292 User password. This field should contain a plaintext string, which will
 293 be encrypted before being placed in the user database. If the password type is 'yes'
 294 and this field is empty it is assumed the account will have any empty password. If
 295 the password type is 'random' and this field is NOT empty its contents will be used
 296 as a password. This field will be ignored if the
 297 .Op Fl p
 298 flag is used with a
 299 .Ar no
 300 or
 301 .Ar none
 302 argument. Be carefull not to terminate this field with a closing ':' because it will
 303 be treated as part of the password.
 304 .El
 305 .Sh FILES
 306 .Bl -tag -width /etc/master.passwdxx -compact
 307 .It Pa /etc/master.passwd
 308 user database
 309 .It Pa /etc/group
 310 group database
 311 .It Pa /etc/shells
 312 shell database
 313 .It Pa /etc/login.conf
 314 login classes database
 315 .It Pa /etc/adduser.conf
 316 configuration file for adduser
 317 .It Pa /etc/adduser.message
 318 message file for adduser
 319 .It Pa /usr/share/skel
 320 skeletal login directory
 321 .It Pa /var/log/adduser
 322 logfile for adduser
 323 .El
 324 .Sh SEE ALSO
 325 .Xr chpass 1 ,
 326 .Xr passwd 1 ,
 327 .Xr aliases 5 ,
 328 .Xr group 5 ,
 329 .Xr login.conf 5 ,
 330 .Xr passwd 5 ,
 331 .Xr shells 5 ,
 332 .Xr pw 8 ,
 333 .Xr pwd_mkdb 8 ,
 334 .Xr rmuser 8 ,
 335 .Xr vipw 8 ,
 336 .Xr yp 8
 337 .Sh HISTORY
 338 The
 339 .Nm
 340 command appeared in
 341 .Fx 2.1 .
 342 .Sh AUTHORS
 343 This manual page and the original script, in perl, was written by
 344 .An Wolfram Schneider <wosch@FreeBSD.org>. The replacement script, written as a Bourne
 345 shell script with some enhancements, and the man page modification that
 346 came with it were done by
 347 .An Mike Makonnen <mtm@identd.net> .
 348 .Sh BUGS
 349 In order for
 350 .Nm
 351 to correctly expand variables such as $username and $randompass in the message sent
 352 to new users it must let the shell evaluate each line of the message file. This means
 353 that shell commands can also be embedded in the message file. The
 354 .Nm
 355 utility attemps to mitigate the possibility of an attacker using this feature by
 356 refusing to evaluate the file if it is not owned and writeable only by the root user.
 357 In addition, shell special characters and operators will have to be escaped when
 358 used in the message file.
 359 .Pp
 360 Also, password ageing and account expiry times are currently setable only in batch mode.
 361 The user should be able to set them in interactive mode as well.