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