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