1USERADD(8) System Management Commands USERADD(8)
2
6 useradd - create a new user or update default new user information
7
9 useradd [options] LOGIN
10 useradd -D
12 useradd -D [options]
14
16 When invoked without the -D option, the useradd command creates a new
17 user account using the values specified on the command line plus the
18 default values from the system. Depending on command line options, the
19 useradd command will update system files and may also create the new
20 user's home directory and copy initial files.
21 By default, a group will also be created for the new user (see -g, -N,
23 -U, and USERGROUPS_ENAB).
24
26 The options which apply to the useradd command are:
27 --badname
29 Allow names that do not conform to standards.
30 -b, --base-dir BASE_DIR
32 The default base directory for the system if -d HOME_DIR is not
33 specified. BASE_DIR is concatenated with the account name to
34 define the home directory. If the -m option is not used, BASE_DIR
35 must exist.
36 If this option is not specified, useradd will use the base
38 directory specified by the HOME variable in /etc/default/useradd,
39 or /home by default.
40 -c, --comment COMMENT
42 Any text string. It is generally a short description of the login,
43 and is currently used as the field for the user's full name.
44 -d, --home-dir HOME_DIR
46 The new user will be created using HOME_DIR as the value for the
47 user's login directory. The default is to append the LOGIN name to
48 BASE_DIR and use that as the login directory name. If the directory
49 HOME_DIR does not exist, then it will be created unless the -M
50 option is specified.
51 -D, --defaults
53 See below, the subsection "Changing the default values".
54 -e, --expiredate EXPIRE_DATE
56 The date on which the user account will be disabled. The date is
57 specified in the format YYYY-MM-DD.
58 If not specified, useradd will use the default expiry date
60 specified by the EXPIRE variable in /etc/default/useradd, or an
61 empty string (no expiry) by default.
62 -f, --inactive INACTIVE
64 The number of days after a password expires until the account is
65 permanently disabled. A value of 0 disables the account as soon as
66 the password has expired, and a value of -1 disables the feature.
67 If not specified, useradd will use the default inactivity period
69 specified by the INACTIVE variable in /etc/default/useradd, or -1
70 by default.
71 -g, --gid GROUP
73 The group name or number of the user's initial login group. The
74 group name must exist. A group number must refer to an already
75 existing group.
76 If not specified, the behavior of useradd will depend on the
78 USERGROUPS_ENAB variable in /etc/login.defs. If this variable is
79 set to yes (or -U/--user-group is specified on the command line), a
80 group will be created for the user, with the same name as her
81 loginname. If the variable is set to no (or -N/--no-user-group is
82 specified on the command line), useradd will set the primary group
83 of the new user to the value specified by the GROUP variable in
84 /etc/default/useradd, or 100 by default.
85 -G, --groups GROUP1[,GROUP2,...[,GROUPN]]]
87 A list of supplementary groups which the user is also a member of.
88 Each group is separated from the next by a comma, with no
89 intervening whitespace. The groups are subject to the same
90 restrictions as the group given with the -g option. The default is
91 for the user to belong only to the initial group.
92 -h, --help
94 Display help message and exit.
95 -k, --skel SKEL_DIR
97 The skeleton directory, which contains files and directories to be
98 copied in the user's home directory, when the home directory is
99 created by useradd.
100 This option is only valid if the -m (or --create-home) option is
102 specified.
103 If this option is not set, the skeleton directory is defined by the
105 SKEL variable in /etc/default/useradd or, by default, /etc/skel.
106 If possible, the ACLs and extended attributes are copied.
108 -K, --key KEY=VALUE
110 Overrides /etc/login.defs defaults (UID_MIN, UID_MAX, UMASK,
111 PASS_MAX_DAYS and others).
112 Example: -K PASS_MAX_DAYS=-1 can be used when creating system
114 account to turn off password aging, even though system account has
115 no password at all. Multiple -K options can be specified, e.g.:
116 -K UID_MIN=100 -K UID_MAX=499
117 -l, --no-log-init
119 Do not add the user to the lastlog and faillog databases.
120 By default, the user's entries in the lastlog and faillog databases
122 are reset to avoid reusing the entry from a previously deleted
123 user.
124 If this option is not specified, useradd will also consult the
126 variable LOG_INIT in the /etc/default/useradd if set to no the user
127 will not be added to the lastlog and faillog databases.
128 -m, --create-home
130 Create the user's home directory if it does not exist. The files
131 and directories contained in the skeleton directory (which can be
132 defined with the -k option) will be copied to the home directory.
133 By default, if this option is not specified and CREATE_HOME is not
135 enabled, no home directories are created.
136 The directory where the user's home directory is created must exist
138 and have proper SELinux context and permissions. Otherwise the
139 user's home directory cannot be created or accessed.
140 -M, --no-create-home
142 Do no create the user's home directory, even if the system wide
143 setting from /etc/login.defs (CREATE_HOME) is set to yes.
144 -N, --no-user-group
146 Do not create a group with the same name as the user, but add the
147 user to the group specified by the -g option or by the GROUP
148 variable in /etc/default/useradd.
149 The default behavior (if the -g, -N, and -U options are not
151 specified) is defined by the USERGROUPS_ENAB variable in
152 /etc/login.defs.
153 -o, --non-unique
155 Allow the creation of a user account with a duplicate (non-unique)
156 UID.
157 This option is only valid in combination with the -u option.
159 -p, --password PASSWORD
161 The encrypted password, as returned by crypt(3). The default is to
162 disable the password.
163 Note: This option is not recommended because the password (or
165 encrypted password) will be visible by users listing the processes.
166 You should make sure the password respects the system's password
168 policy.
169 -r, --system
171 Create a system account.
172 System users will be created with no aging information in
174 /etc/shadow, and their numeric identifiers are chosen in the
175 SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, instead
176 of UID_MIN-UID_MAX (and their GID counterparts for the creation of
177 groups).
178 Note that useradd will not create a home directory for such a user,
180 regardless of the default setting in /etc/login.defs (CREATE_HOME).
181 You have to specify the -m options if you want a home directory for
182 a system account to be created.
183 -R, --root CHROOT_DIR
185 Apply changes in the CHROOT_DIR directory and use the configuration
186 files from the CHROOT_DIR directory.
187 -P, --prefix PREFIX_DIR
189 Apply changes in the PREFIX_DIR directory and use the configuration
190 files from the PREFIX_DIR directory. This option does not chroot
191 and is intended for preparing a cross-compilation target. Some
192 limitations: NIS and LDAP users/groups are not verified. PAM
193 authentication is using the host files. No SELINUX support.
194 -s, --shell SHELL
196 The name of the user's login shell. The default is to leave this
197 field blank, which causes the system to select the default login
198 shell specified by the SHELL variable in /etc/default/useradd, or
199 an empty string by default.
200 -u, --uid UID
202 The numerical value of the user's ID. This value must be unique,
203 unless the -o option is used. The value must be non-negative. The
204 default is to use the smallest ID value greater than or equal to
205 UID_MIN and greater than every other user.
206 See also the -r option and the UID_MAX description.
208 -U, --user-group
210 Create a group with the same name as the user, and add the user to
211 this group.
212 The default behavior (if the -g, -N, and -U options are not
214 specified) is defined by the USERGROUPS_ENAB variable in
215 /etc/login.defs.
216 -Z, --selinux-user SEUSER
218 The SELinux user for the user's login. The default is to leave this
219 field blank, which causes the system to select the default SELinux
220 user.
221 Changing the default values
223 When invoked with only the -D option, useradd will display the current
224 default values. When invoked with -D plus other options, useradd will
225 update the default values for the specified options. Valid
226 default-changing options are:
227 -b, --base-dir BASE_DIR
229 The path prefix for a new user's home directory. The user's name
230 will be affixed to the end of BASE_DIR to form the new user's home
231 directory name, if the -d option is not used when creating a new
232 account.
233 This option sets the HOME variable in /etc/default/useradd.
235 -e, --expiredate EXPIRE_DATE
237 The date on which the user account is disabled.
238 This option sets the EXPIRE variable in /etc/default/useradd.
240 -f, --inactive INACTIVE
242 The number of days after a password has expired before the account
243 will be disabled.
244 This option sets the INACTIVE variable in /etc/default/useradd.
246 -g, --gid GROUP
248 The group name or ID for a new user's initial group (when the
249 -N/--no-user-group is used or when the USERGROUPS_ENAB variable is
250 set to no in /etc/login.defs). The named group must exist, and a
251 numerical group ID must have an existing entry.
252 This option sets the GROUP variable in /etc/default/useradd.
254 -s, --shell SHELL
256 The name of a new user's login shell.
257 This option sets the SHELL variable in /etc/default/useradd.
259
261 The system administrator is responsible for placing the default user
262 files in the /etc/skel/ directory (or any other skeleton directory
263 specified in /etc/default/useradd or on the command line).
264
266 You may not add a user to a NIS or LDAP group. This must be performed
267 on the corresponding server.
268 Similarly, if the username already exists in an external user database
270 such as NIS or LDAP, useradd will deny the user account creation
271 request.
272 Usernames may contain only lower and upper case letters, digits,
274 underscores, or dashes. They can end with a dollar sign. Dashes are not
275 allowed at the beginning of the username. Fully numeric usernames and
276 usernames . or .. are also disallowed. It is not recommended to use
277 usernames beginning with . character as their home directories will be
278 hidden in the ls output.
279 Usernames may only be up to 32 characters long.
281
283 The following configuration variables in /etc/login.defs change the
284 behavior of this tool:
285 CREATE_HOME (boolean)
287 Indicate if a home directory should be created by default for new
288 users.
289 This setting does not apply to system users, and can be overridden
291 on the command line.
292 GID_MAX (number), GID_MIN (number)
294 Range of group IDs used for the creation of regular groups by
295 useradd, groupadd, or newusers.
296 The default value for GID_MIN (resp. GID_MAX) is 1000 (resp.
298 60000).
299 HOME_MODE (number)
301 The mode for new home directories. If not specified, the UMASK is
302 used to create the mode.
303 useradd and newusers use this to set the mode of the home directory
305 they create.
306 LASTLOG_UID_MAX (number)
308 Highest user ID number for which the lastlog entries should be
309 updated. As higher user IDs are usually tracked by remote user
310 identity and authentication services there is no need to create a
311 huge sparse lastlog file for them.
312 No LASTLOG_UID_MAX option present in the configuration means that
314 there is no user ID limit for writing lastlog entries.
315 MAIL_DIR (string)
317 The mail spool directory. This is needed to manipulate the mailbox
318 when its corresponding user account is modified or deleted. If not
319 specified, a compile-time default is used. The parameter
320 CREATE_MAIL_SPOOL in /etc/default/useradd determines whether the
321 mail spool should be created.
322 MAIL_FILE (string)
324 Defines the location of the users mail spool files relatively to
325 their home directory.
326 The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and
328 userdel to create, move, or delete the user's mail spool.
329 If MAIL_CHECK_ENAB is set to yes, they are also used to define the MAIL
331 environment variable.
332 MAX_MEMBERS_PER_GROUP (number)
334 Maximum members per group entry. When the maximum is reached, a new
335 group entry (line) is started in /etc/group (with the same name,
336 same password, and same GID).
337 The default value is 0, meaning that there are no limits in the
339 number of members in a group.
340 This feature (split group) permits to limit the length of lines in
342 the group file. This is useful to make sure that lines for NIS
343 groups are not larger than 1024 characters.
344 If you need to enforce such limit, you can use 25.
346 Note: split groups may not be supported by all tools (even in the
348 Shadow toolsuite). You should not use this variable unless you
349 really need it.
350 PASS_MAX_DAYS (number)
352 The maximum number of days a password may be used. If the password
353 is older than this, a password change will be forced. If not
354 specified, -1 will be assumed (which disables the restriction).
355 PASS_MIN_DAYS (number)
357 The minimum number of days allowed between password changes. Any
358 password changes attempted sooner than this will be rejected. If
359 not specified, 0 will be assumed (which disables the restriction).
360 PASS_WARN_AGE (number)
362 The number of days warning given before a password expires. A zero
363 means warning is given only upon the day of expiration, a negative
364 value means no warning is given. If not specified, no warning will
365 be provided.
366 SUB_GID_MIN (number), SUB_GID_MAX (number), SUB_GID_COUNT (number)
368 If /etc/subuid exists, the commands useradd and newusers (unless
369 the user already have subordinate group IDs) allocate SUB_GID_COUNT
370 unused group IDs from the range SUB_GID_MIN to SUB_GID_MAX for each
371 new user.
372 The default values for SUB_GID_MIN, SUB_GID_MAX, SUB_GID_COUNT are
374 respectively 100000, 600100000 and 65536.
375 SUB_UID_MIN (number), SUB_UID_MAX (number), SUB_UID_COUNT (number)
377 If /etc/subuid exists, the commands useradd and newusers (unless
378 the user already have subordinate user IDs) allocate SUB_UID_COUNT
379 unused user IDs from the range SUB_UID_MIN to SUB_UID_MAX for each
380 new user.
381 The default values for SUB_UID_MIN, SUB_UID_MAX, SUB_UID_COUNT are
383 respectively 100000, 600100000 and 65536.
384 SYS_GID_MAX (number), SYS_GID_MIN (number)
386 Range of group IDs used for the creation of system groups by
387 useradd, groupadd, or newusers.
388 The default value for SYS_GID_MIN (resp. SYS_GID_MAX) is 101
390 (resp. GID_MIN-1).
391 SYS_UID_MAX (number), SYS_UID_MIN (number)
393 Range of user IDs used for the creation of system users by useradd
394 or newusers.
395 The default value for SYS_UID_MIN (resp. SYS_UID_MAX) is 101
397 (resp. UID_MIN-1).
398 UID_MAX (number), UID_MIN (number)
400 Range of user IDs used for the creation of regular users by useradd
401 or newusers.
402 The default value for UID_MIN (resp. UID_MAX) is 1000 (resp.
404 60000).
405 UMASK (number)
407 The file mode creation mask is initialized to this value. If not
408 specified, the mask will be initialized to 022.
409 useradd and newusers use this mask to set the mode of the home
411 directory they create if HOME_MODE is not set.
412 It is also used by login to define users' initial umask. Note that
414 this mask can be overridden by the user's GECOS line (if
415 QUOTAS_ENAB is set) or by the specification of a limit with the K
416 identifier in limits(5).
417 USERGROUPS_ENAB (boolean)
419 Enable setting of the umask group bits to be the same as owner bits
420 (examples: 022 -> 002, 077 -> 007) for non-root users, if the uid
421 is the same as gid, and username is the same as the primary group
422 name.
423 If set to yes, userdel will remove the user's group if it contains
425 no more members, and useradd will create by default a group with
426 the name of the user.
427
429 /etc/passwd
430 User account information.
431 /etc/shadow
433 Secure user account information.
434 /etc/group
436 Group account information.
437 /etc/gshadow
439 Secure group account information.
440 /etc/default/useradd
442 Default values for account creation.
443 /etc/shadow-maint/useradd-pre.d/*, /etc/shadow-maint/useradd-post.d/*
445 Run-part files to execute during user addition. The environment
446 variable ACTION will be populated with useradd and SUBJECT with the
447 username. useradd-pre.d will be executed prior to any user
448 addition. useradd-post.d will execute after user addition. If a
449 script exits non-zero then execution will terminate.
450 /etc/skel/
452 Directory containing default files.
453 /etc/subgid
455 Per user subordinate group IDs.
456 /etc/subuid
458 Per user subordinate user IDs.
459 /etc/login.defs
461 Shadow password suite configuration.
462
464 The useradd command exits with the following values:
465 0
467 success
468 1
470 can't update password file
471 2
473 invalid command syntax
474 3
476 invalid argument to option
477 4
479 UID already in use (and no -o)
480 6
482 specified group doesn't exist
483 9
485 username already in use
486 10
488 can't update group file
489 12
491 can't create home directory
492 14
494 can't update SELinux user mapping
495
497 chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8),
498 groupmod(8), login.defs(5), newusers(8), subgid(5), subuid(5),
499 userdel(8), usermod(8).
500shadow-utils 4.11.1 02/10/2022 USERADD(8)