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