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