| blob | f87c545a12951dade7d8ac66eb4c8e1b418a6cd9 |
1 '\" te
2 .\" Copyright (c) 2013 Gary Mills
3 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
4 .\" Copyright 1989 AT&T
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH USERADD 1M "Apr 16, 2013"
9 .SH NAME
10 useradd \- administer a new user login on the system
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBuseradd\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
15 [\fB-b\fR \fIbase_dir\fR] [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR]
16 [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [,\fIgroup\fR]...]
17 [\fB-K\fR \fIkey=value\fR] [\fB-m\fR [\fB-z|-Z\fR] [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
18 [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
19 [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIlogin\fR
20 .fi
22 .LP
23 .nf
24 \fBuseradd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
25 [\fB-b\fR \fIbase_dir\fR] [\fB-s\fR \fIshell\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-e\fR \fIexpire\fR]
26 [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
27 [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
28 .fi
30 .SH DESCRIPTION
31 .LP
32 \fBuseradd\fR adds a new user to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
33 and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
34 assign authorizations and profiles to the user. The \fB-R\fR option assigns
35 roles to a user. The \fB-p\fR option associates a project with a user. The
36 \fB-K\fR option adds a \fIkey=value\fR pair to \fB/etc/user_attr\fR for the
37 user. Multiple \fIkey=value\fR pairs may be added with multiple \fB-K\fR
38 options.
39 .sp
40 .LP
41 \fBuseradd\fR also creates supplementary group memberships for the user
42 (\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the user
43 if requested. The new login remains locked until the \fBpasswd\fR(1) command is
44 executed.
45 .sp
46 .LP
47 Specifying \fBuseradd\fR \fB-D\fR with the \fB-s\fR, \fB-k\fR,\fB-g\fR,
48 \fB-b\fR, \fB-f\fR, \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or
49 \fB-K\fR option (or any combination of these options) sets the default values
50 for the respective fields. See the \fB-D\fR option, below. Subsequent
51 \fBuseradd\fR commands without the \fB-D\fR option use these arguments.
52 .sp
53 .LP
54 The system file entries created with this command have a limit of 2048
55 characters per line. Specifying long arguments to several options can exceed
56 this limit.
57 .sp
58 .LP
59 \fBuseradd\fR requires that usernames be in the format described in
60 \fBpasswd\fR(4). A warning message is displayed if these restrictions are not
61 met. See \fBpasswd\fR(4) for the requirements for usernames.
62 .LP
63 To change the action of \fBuseradd\fR when the traditional login name
64 length limit of eight characters is exceeded, edit the file
65 \fB/etc/default/useradd\fR by removing the \fB#\fR (pound sign) before the
66 appropriate \fBEXCEED_TRAD=\fR entry, and adding it before the others.
67 .SH OPTIONS
68 .LP
69 The following options are supported:
70 .sp
71 .ne 2
72 .na
73 \fB\fB-A\fR \fIauthorization\fR\fR
74 .ad
75 .sp .6
76 .RS 4n
77 One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
78 a user or role who has \fBgrant\fR rights to the authorization can assign it to
79 an account.
80 .RE
82 .sp
83 .ne 2
84 .na
85 \fB\fB-b\fR \fIbase_dir\fR\fR
86 .ad
87 .sp .6
88 .RS 4n
89 The base directory for new login home directories (see the \fB-d\fR option
90 below. When a new user account is being created, \fIbase_dir\fR must already
91 exist unless the \fB-m\fR option or the \fB-d\fR option is also specified.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fB-c\fR \fIcomment\fR\fR
98 .ad
99 .sp .6
100 .RS 4n
101 Any text string. It is generally a short description of the login, and is
102 currently used as the field for the user's full name. This information is
103 stored in the user's \fB/etc/passwd\fR entry.
104 .RE
106 .sp
107 .ne 2
108 .na
109 \fB\fB-d\fR \fIdir\fR\fR
110 .ad
111 .sp .6
112 .RS 4n
113 The home directory of the new user. It defaults to
114 \fIbase_dir\fR/\fIaccount_name\fR, where \fIbase_dir\fR is the base directory
115 for new login home directories and \fIaccount_name\fR is the new login name.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fB-D\fR\fR
122 .ad
123 .sp .6
124 .RS 4n
125 Display the default values for \fBgroup\fR, \fBbase_dir\fR, \fBskel_dir\fR,
126 \fBshell\fR, \fBinactive\fR, \fBexpire\fR, \fBproj\fR, \fBprojname\fR and
127 \fBkey=value\fR pairs. When used with the \fB-g\fR, \fB-b\fR, \fB-f\fR,
128 \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or \fB-K\fR options, the
129 \fB-D\fR option sets the default values for the specified fields. The default
130 values are:
131 .sp
132 .ne 2
133 .na
134 \fBgroup\fR
135 .ad
136 .sp .6
137 .RS 4n
138 \fBother\fR (\fBGID\fR of 1)
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fBbase_dir\fR
145 .ad
146 .sp .6
147 .RS 4n
148 \fB/home\fR
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fBskel_dir\fR
155 .ad
156 .sp .6
157 .RS 4n
158 \fB/etc/skel\fR
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fBshell\fR
165 .ad
166 .sp .6
167 .RS 4n
168 \fB/bin/sh\fR
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fBinactive\fR
175 .ad
176 .sp .6
177 .RS 4n
178 \fB0\fR
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fBexpire\fR
185 .ad
186 .sp .6
187 .RS 4n
188 null
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fBauths\fR
195 .ad
196 .sp .6
197 .RS 4n
198 null
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fBprofiles\fR
205 .ad
206 .sp .6
207 .RS 4n
208 null
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fBproj\fR
215 .ad
216 .sp .6
217 .RS 4n
218 \fB3\fR
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fBprojname\fR
225 .ad
226 .sp .6
227 .RS 4n
228 \fBdefault\fR
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fBkey=value (pairs defined in \fBuser_attr\fR(4)\fR
235 .ad
236 .sp .6
237 .RS 4n
238 not present
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fBroles\fR
245 .ad
246 .sp .6
247 .RS 4n
248 null
249 .RE
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fB-e\fR \fIexpire\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Specify the expiration date for a login. After this date, no user will be able
261 to access this login. The expire option argument is a date entered using one of
262 the date formats included in the template file \fB/etc/datemsk\fR. See
263 \fBgetdate\fR(3C).
264 .sp
265 If the date format that you choose includes spaces, it must be quoted. For
266 example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
267 (\fB" "\fR) defeats the status of the expired date. This option is useful for
268 creating temporary logins.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fB-f\fR \fIinactive\fR\fR
275 .ad
276 .sp .6
277 .RS 4n
278 The maximum number of days allowed between uses of a login ID before that
279 \fBID\fR is declared invalid. Normal values are positive integers. A value of
280 \fB0\fR defeats the status.
281 .RE
283 .sp
284 .ne 2
285 .na
286 \fB\fB-g\fR \fIgroup\fR\fR
287 .ad
288 .sp .6
289 .RS 4n
290 An existing group's integer \fBID\fR or character-string name. Without the
291 \fB-D\fR option, it defines the new user's primary group membership and
292 defaults to the default group. You can reset this default value by invoking
293 \fBuseradd\fR \fB-D\fR \fB-g\fR \fIgroup\fR. GIDs 0-99 are reserved for
294 allocation by the Solaris Operating System.
295 .RE
297 .sp
298 .ne 2
299 .na
300 \fB\fB-G\fR \fIgroup\fR\fR
301 .ad
302 .sp .6
303 .RS 4n
304 An existing group's integer \fBID\fR or character-string name. It defines the
305 new user's supplementary group membership. Duplicates between \fIgroup\fR with
306 the \fB-g\fR and \fB-G\fR options are ignored. No more than \fBNGROUPS_MAX\fR
307 groups can be specified. GIDs 0-99 are reserved for allocation by the Solaris
308 Operating System.
309 .RE
311 .sp
312 .ne 2
313 .na
314 \fB\fB-K\fR \fIkey=value\fR\fR
315 .ad
316 .sp .6
317 .RS 4n
318 A \fIkey=value\fR pair to add to the user's attributes. Multiple \fB-K\fR
319 options may be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
320 option with the appropriate key may be used instead of the specific implied key
321 options (\fB-A\fR, \fB-P\fR, \fB-R\fR, \fB-p\fR). See \fBuser_attr\fR(4) for a
322 list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
323 option. Keys may not be repeated.
324 .RE
326 .sp
327 .ne 2
328 .na
329 \fB\fB-k\fR \fIskel_dir\fR\fR
330 .ad
331 .sp .6
332 .RS 4n
333 A directory that contains skeleton information (such as \fB\&.profile\fR) that
334 can be copied into a new user's home directory. This directory must already
335 exist. The system provides the \fB/etc/skel\fR directory that can be used for
336 this purpose.
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fB-m\fR\fR [\fB-z|-Z\fR]
343 .ad
344 .sp .6
345 .RS 4n
346 Create the new user's home directory if it does not already exist. If the
347 directory already exists, it must have read, write, and execute permissions by
348 \fIgroup\fR, where \fIgroup\fR is the user's primary group.
349 .sp
350 If the parent directory of the user's home directory is located on a separate
351 \fBZFS\fR file system and the \fB/etc/default/useradd\fR file contains the
352 parameter \fBMANAGE_ZFS\fR set to the value \fBYES\fR, a new \fBZFS\fR
353 file system will be created for the user.
354 .sp
355 If the \fB-z\fR option is specified, \fBuseradd\fR will always try to create
356 a new file system for the home directory.
357 .sp
358 If the \fB-Z\fR option is specified, a new file system will never be created.
359 .RE
361 .sp
362 .ne 2
363 .na
364 \fB\fB-o\fR\fR
365 .ad
366 .sp .6
367 .RS 4n
368 This option allows a \fBUID\fR to be duplicated (non-unique).
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fB\fB-P\fR \fIprofile\fR\fR
375 .ad
376 .sp .6
377 .RS 4n
378 One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fB\fB-p\fR \fIprojname\fR\fR
385 .ad
386 .sp .6
387 .RS 4n
388 Name of the project with which the added user is associated. See the
389 \fIprojname\fR field as defined in \fBproject\fR(4).
390 .RE
392 .sp
393 .ne 2
394 .na
395 \fB\fB-R\fR \fIrole\fR\fR
396 .ad
397 .sp .6
398 .RS 4n
399 One or more comma-separated execution profiles defined in \fBuser_attr\fR(4).
400 Roles cannot be assigned to other roles.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fB-s\fR \fIshell\fR\fR
407 .ad
408 .sp .6
409 .RS 4n
410 Full pathname of the program used as the user's shell on login. It defaults to
411 an empty field causing the system to use \fB/bin/sh\fR as the default. The
412 value of \fIshell\fR must be a valid executable file.
413 .RE
415 .sp
416 .ne 2
417 .na
418 \fB\fB-u\fR \fIuid\fR\fR
419 .ad
420 .sp .6
421 .RS 4n
422 The \fBUID\fR of the new user. This \fBUID\fR must be a non-negative decimal
423 integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
424 defaults to the next available (unique) number above the highest number
425 currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
426 the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
427 reserved for allocation by the Solaris Operating System.
428 .RE
430 .SH FILES
431 .LP
432 \fB/etc/default/useradd\fR
433 .sp
434 .LP
435 \fB/etc/datemsk\fR
436 .sp
437 .LP
438 \fB/etc/passwd\fR
439 .sp
440 .LP
441 \fB/etc/shadow\fR
442 .sp
443 .LP
444 \fB/etc/group\fR
445 .sp
446 .LP
447 \fB/etc/skel\fR
448 .sp
449 .LP
450 \fB/usr/include/limits.h\fR
451 .sp
452 .LP
453 \fB/etc/user_attr\fR
454 .SH ATTRIBUTES
455 .LP
456 See \fBattributes\fR(5) for descriptions of the following attributes:
457 .sp
459 .sp
460 .TS
461 box;
462 c | c
463 l | l .
464 ATTRIBUTE TYPE ATTRIBUTE VALUE
465 _
466 Interface Stability Committed
467 .TE
469 .SH SEE ALSO
470 .LP
471 \fBpasswd\fR(1), \fBprofiles\fR(1), \fBroles\fR(1), \fBusers\fR(1B),
472 \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBgrpck\fR(1M),
473 \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M), \fBusermod\fR(1M),
474 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4), \fBprof_attr\fR(4),
475 \fBproject\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBzfs\fR(1M)
476 .SH DIAGNOSTICS
477 .LP
478 In case of an error, \fBuseradd\fR prints an error message and exits with a
479 non-zero status.
480 .sp
481 .LP
482 The following indicates that \fBlogin\fR specified is already in use:
483 .sp
484 .in +2
485 .nf
486 UX: useradd: ERROR: login is already in use. Choose another.
487 .fi
488 .in -2
489 .sp
491 .sp
492 .LP
493 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
494 is not unique:
495 .sp
496 .in +2
497 .nf
498 UX: useradd: ERROR: uid \fIuid\fR is already in use. Choose another.
499 .fi
500 .in -2
501 .sp
503 .sp
504 .LP
505 The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
506 is already in use:
507 .sp
508 .in +2
509 .nf
510 UX: useradd: ERROR: group \fIgroup\fR does not exist. Choose another.
511 .fi
512 .in -2
513 .sp
515 .sp
516 .LP
517 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
518 is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
519 .sp
520 .in +2
521 .nf
522 UX: useradd: WARNING: uid \fIuid\fR is reserved.
523 .fi
524 .in -2
525 .sp
527 .sp
528 .LP
529 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
530 exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
531 .sp
532 .in +2
533 .nf
534 UX: useradd: ERROR: uid \fIuid\fR is too big. Choose another.
535 .fi
536 .in -2
537 .sp
539 .sp
540 .LP
541 The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
542 do not exist:
543 .sp
544 .in +2
545 .nf
546 UX: useradd: ERROR: Cannot update system files - login cannot be created.
547 .fi
548 .in -2
549 .sp
551 .SH NOTES
552 .LP
553 The \fBuseradd\fR utility adds definitions to only the local \fB/etc/group\fR,
554 \fBetc/passwd\fR, \fB/etc/passwd\fR, \fB/etc/shadow\fR, \fB/etc/project\fR, and
555 \fB/etc/user_attr\fR files. If a network name service such as \fBNIS\fR or
556 \fBNIS+\fR is being used to supplement the local \fB/etc/passwd\fR file with
557 additional entries, \fBuseradd\fR cannot change information supplied by the
558 network name service. However \fBuseradd\fR will verify the uniqueness of the
559 user name (or role) and user id and the existence of any group names specified
560 against the external name service.