1USERADD(8)                System Management Commands                USERADD(8)
2
3
4

NAME

6       useradd - create a new user or update default new user information
7

SYNOPSIS

9       useradd [options] LOGIN
10
11       useradd -D
12
13       useradd -D [options]
14

DESCRIPTION

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
22       By default, a group will also be created for the new user (see -g, -N,
23       -U, and USERGROUPS_ENAB).
24

OPTIONS

26       The options which apply to the useradd command are:
27
28       --badname
29           Allow names that do not conform to standards.
30
31       -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.
35
36           If this option is not specified, useradd will use the base
37           directory specified by the HOME variable in /etc/default/useradd,
38           or /home by default.
39
40       -c, --comment COMMENT
41           Any text string. It is generally a short description of the
42           account, and is currently used as the field for the user's full
43           name.
44
45       -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
52       -D, --defaults
53           See below, the subsection "Changing the default values".
54
55       -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
59           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
63       -f, --inactive INACTIVE
64           defines the number of days after the password exceeded its maximum
65           age where the user is expected to replace this password. The value
66           is stored in the shadow password file. An input of 0 will disable
67           an expired password with no delay. An input of -1 will blank the
68           respective field in the shadow password file. See shadow(5)for more
69           information.
70
71           If not specified, useradd will use the default inactivity period
72           specified by the INACTIVE variable in /etc/default/useradd, or -1
73           by default.
74
75       -F, --add-subids-for-system
76           Update /etc/subuid and /etc/subgid even when creating a system
77           account with -r option.
78
79       -g, --gid GROUP
80           The name or the number of the user's primary group. The group name
81           must exist. A group number must refer to an already existing group.
82
83           If not specified, the behavior of useradd will depend on the
84           USERGROUPS_ENAB variable in /etc/login.defs. If this variable is
85           set to yes (or -U/--user-group is specified on the command line), a
86           group will be created for the user, with the same name as her
87           loginname. If the variable is set to no (or -N/--no-user-group is
88           specified on the command line), useradd will set the primary group
89           of the new user to the value specified by the GROUP variable in
90           /etc/default/useradd, or 1000 by default.
91
92       -G, --groups GROUP1[,GROUP2,...[,GROUPN]]]
93           A list of supplementary groups which the user is also a member of.
94           Each group is separated from the next by a comma, with no
95           intervening whitespace. The groups are subject to the same
96           restrictions as the group given with the -g option. The default is
97           for the user to belong only to the initial group.
98
99       -h, --help
100           Display help message and exit.
101
102       -k, --skel SKEL_DIR
103           The skeleton directory, which contains files and directories to be
104           copied in the user's home directory, when the home directory is
105           created by useradd.
106
107           This option is only valid if the -m (or --create-home) option is
108           specified.
109
110           If this option is not set, the skeleton directory is defined by the
111           SKEL variable in /etc/default/useradd or, by default, /etc/skel.
112
113           If possible, the ACLs and extended attributes are copied.
114
115       -K, --key KEY=VALUE
116           Overrides /etc/login.defs defaults (UID_MIN, UID_MAX, UMASK,
117           PASS_MAX_DAYS and others).
118
119           Example: -K PASS_MAX_DAYS =-1 can be used when creating an account
120           to turn off password aging. Multiple -K options can be specified,
121           e.g.: -K UID_MIN =100 -K  UID_MAX=499
122
123       -l, --no-log-init
124           Do not add the user to the lastlog and faillog databases.
125
126           By default, the user's entries in the lastlog and faillog databases
127           are reset to avoid reusing the entry from a previously deleted
128           user.
129
130           If this option is not specified, useradd will also consult the
131           variable LOG_INIT in the /etc/default/useradd if set to no the user
132           will not be added to the lastlog and faillog databases.
133
134       -m, --create-home
135           Create the user's home directory if it does not exist. The files
136           and directories contained in the skeleton directory (which can be
137           defined with the -k option) will be copied to the home directory.
138
139           By default, if this option is not specified and CREATE_HOME is not
140           enabled, no home directories are created.
141
142           The directory where the user's home directory is created must exist
143           and have proper SELinux context and permissions. Otherwise the
144           user's home directory cannot be created or accessed.
145
146       -M, --no-create-home
147           Do not create the user's home directory, even if the system wide
148           setting from /etc/login.defs (CREATE_HOME) is set to yes.
149
150       -N, --no-user-group
151           Do not create a group with the same name as the user, but add the
152           user to the group specified by the -g option or by the GROUP
153           variable in /etc/default/useradd.
154
155           The default behavior (if the -g, -N, and -U options are not
156           specified) is defined by the USERGROUPS_ENAB variable in
157           /etc/login.defs.
158
159       -o, --non-unique
160           allows the creation of an account with an already existing UID.
161
162           This option is only valid in combination with the -u option. As a
163           user identity serves as key to map between users on one hand and
164           permissions, file ownerships and other aspects that determine the
165           system's behavior on the other hand, more than one login name will
166           access the account of the given UID.
167
168       -p, --password PASSWORD
169           defines an initial password for the account. PASSWORD is expected
170           to be encrypted, as returned by crypt (3). Within a shell script,
171           this option allows to create efficiently batches of users.
172
173           Without this option, the new account will be locked and with no
174           password defined, i.e. a single exclamation mark in the respective
175           field of /etc/shadow. This is a state where the user won't be able
176           to access the account or to define a password himself.
177
178           Note:Avoid this option on the command line because the password (or
179           encrypted password) will be visible by users listing the processes.
180
181           You should make sure the password respects the system's password
182           policy.
183
184       -r, --system
185           Create a system account.
186
187           System users will be created with no aging information in
188           /etc/shadow, and their numeric identifiers are chosen in the
189           SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, instead
190           of UID_MIN-UID_MAX (and their GID counterparts for the creation of
191           groups).
192
193           Note that useradd will not create a home directory for such a user,
194           regardless of the default setting in /etc/login.defs (CREATE_HOME).
195           You have to specify the -m options if you want a home directory for
196           a system account to be created.
197
198           Note that this option will not update /etc/subuid and /etc/subgid.
199           You have to specify the -F options if you want to update the files
200           for a system account to be created.
201
202       -R, --root CHROOT_DIR
203           Apply changes in the CHROOT_DIR directory and use the configuration
204           files from the CHROOT_DIR directory. Only absolute paths are
205           supported.
206
207       -P, --prefix PREFIX_DIR
208           Apply changes to configuration files under the root filesystem
209           found under the directory PREFIX_DIR. This option does not chroot
210           and is intended for preparing a cross-compilation target. Some
211           limitations: NIS and LDAP users/groups are not verified. PAM
212           authentication is using the host files. No SELINUX support.
213
214       -s, --shell SHELL
215           sets the path to the user's login shell. Without this option, the
216           system will use the SHELL variable specified in
217           /etc/default/useradd, or, if that is as well not set, the field for
218           the login shell in /etc/passwd remains empty.
219
220       -u, --uid UID
221           The numerical value of the user's ID. This value must be unique,
222           unless the -o option is used. The value must be non-negative. The
223           default is to use the smallest ID value greater than or equal to
224           UID_MIN and greater than every other user.
225
226           See also the -r option and the UID_MAX description.
227
228       -U, --user-group
229           Create a group with the same name as the user, and add the user to
230           this group.
231
232           The default behavior (if the -g, -N, and -U options are not
233           specified) is defined by the USERGROUPS_ENAB variable in
234           /etc/login.defs.
235
236       -Z, --selinux-user SEUSER
237           defines the SELinux user for the new account. Without this option,
238           a SELinux uses the default user. Note that the shadow system
239           doesn't store the selinux-user, it uses semanage(8) for that.
240
241   Changing the default values
242       When invoked with only the -D option, useradd will display the current
243       default values. When invoked with -D plus other options, useradd will
244       update the default values for the specified options. Valid
245       default-changing options are:
246
247       -b, --base-dir BASE_DIR
248           sets the path prefix for a new user's home directory. The user's
249           name will be affixed to the end of BASE_DIR to form the new user's
250           home directory name, if the -d option is not used when creating a
251           new account.
252
253           This option sets the HOME variable in /etc/default/useradd.
254
255       -e, --expiredate EXPIRE_DATE
256           sets the date on which newly created user accounts are disabled.
257
258           This option sets the EXPIRE variable in /etc/default/useradd.
259
260       -f, --inactive INACTIVE
261           defines the number of days after the password exceeded its maximum
262           age where the user is expected to replace this password. See
263           shadow(5)for more information.
264
265           This option sets the INACTIVE variable in /etc/default/useradd.
266
267       -g, --gid GROUP
268           sets the default primary group for newly created users, accepting
269           group names or a numerical group ID. The named group must exist,
270           and the GID must have an existing entry.
271
272           This option sets the GROUP variable in /etc/default/useradd.
273
274       -s, --shell SHELL
275           defines the default login shell for new users.
276
277           This option sets the SHELL variable in /etc/default/useradd.
278

NOTES

280       The system administrator is responsible for placing the default user
281       files in the /etc/skel/ directory (or any other skeleton directory
282       specified in /etc/default/useradd or on the command line).
283

CAVEATS

285       You may not add a user to a NIS or LDAP group. This must be performed
286       on the corresponding server.
287
288       Similarly, if the username already exists in an external user database
289       such as NIS or LDAP, useradd will deny the user account creation
290       request.
291
292       Usernames may contain only lower and upper case letters, digits,
293       underscores, or dashes. They can end with a dollar sign. Dashes are not
294       allowed at the beginning of the username. Fully numeric usernames and
295       usernames . or .. are also disallowed. It is not recommended to use
296       usernames beginning with . character as their home directories will be
297       hidden in the ls output.
298
299       Usernames may only be up to 32 characters long.
300

CONFIGURATION

302       The following configuration variables in /etc/login.defs change the
303       behavior of this tool:
304
305       CREATE_HOME (boolean)
306           Indicate if a home directory should be created by default for new
307           users.
308
309           This setting does not apply to system users, and can be overridden
310           on the command line.
311
312       GID_MAX (number), GID_MIN (number)
313           Range of group IDs used for the creation of regular groups by
314           useradd, groupadd, or newusers.
315
316           The default value for GID_MIN (resp.  GID_MAX) is 1000 (resp.
317           60000).
318
319       HOME_MODE (number)
320           The mode for new home directories. If not specified, the UMASK is
321           used to create the mode.
322
323           useradd and newusers use this to set the mode of the home directory
324           they create.
325
326       LASTLOG_UID_MAX (number)
327           Highest user ID number for which the lastlog entries should be
328           updated. As higher user IDs are usually tracked by remote user
329           identity and authentication services there is no need to create a
330           huge sparse lastlog file for them.
331
332           No LASTLOG_UID_MAX option present in the configuration means that
333           there is no user ID limit for writing lastlog entries.
334
335       MAIL_DIR (string)
336           The mail spool directory. This is needed to manipulate the mailbox
337           when its corresponding user account is modified or deleted. If not
338           specified, a compile-time default is used. The parameter
339           CREATE_MAIL_SPOOL in /etc/default/useradd determines whether the
340           mail spool should be created.
341
342       MAIL_FILE (string)
343           Defines the location of the users mail spool files relatively to
344           their home directory.
345
346       The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and
347       userdel to create, move, or delete the user's mail spool.
348
349       If MAIL_CHECK_ENAB is set to yes, they are also used to define the MAIL
350       environment variable.
351
352       MAX_MEMBERS_PER_GROUP (number)
353           Maximum members per group entry. When the maximum is reached, a new
354           group entry (line) is started in /etc/group (with the same name,
355           same password, and same GID).
356
357           The default value is 0, meaning that there are no limits in the
358           number of members in a group.
359
360           This feature (split group) permits to limit the length of lines in
361           the group file. This is useful to make sure that lines for NIS
362           groups are not larger than 1024 characters.
363
364           If you need to enforce such limit, you can use 25.
365
366           Note: split groups may not be supported by all tools (even in the
367           Shadow toolsuite). You should not use this variable unless you
368           really need it.
369
370       PASS_MAX_DAYS (number)
371           The maximum number of days a password may be used. If the password
372           is older than this, a password change will be forced. If not
373           specified, -1 will be assumed (which disables the restriction).
374
375       PASS_MIN_DAYS (number)
376           The minimum number of days allowed between password changes. Any
377           password changes attempted sooner than this will be rejected. If
378           not specified, 0 will be assumed (which disables the restriction).
379
380       PASS_WARN_AGE (number)
381           The number of days warning given before a password expires. A zero
382           means warning is given only upon the day of expiration, a negative
383           value means no warning is given. If not specified, no warning will
384           be provided.
385
386       SUB_GID_MIN (number), SUB_GID_MAX (number), SUB_GID_COUNT (number)
387           If /etc/subuid exists, the commands useradd and newusers (unless
388           the user already have subordinate group IDs) allocate SUB_GID_COUNT
389           unused group IDs from the range SUB_GID_MIN to SUB_GID_MAX for each
390           new user.
391
392           The default values for SUB_GID_MIN, SUB_GID_MAX, SUB_GID_COUNT are
393           respectively 100000, 600100000 and 65536.
394
395       SUB_UID_MIN (number), SUB_UID_MAX (number), SUB_UID_COUNT (number)
396           If /etc/subuid exists, the commands useradd and newusers (unless
397           the user already have subordinate user IDs) allocate SUB_UID_COUNT
398           unused user IDs from the range SUB_UID_MIN to SUB_UID_MAX for each
399           new user.
400
401           The default values for SUB_UID_MIN, SUB_UID_MAX, SUB_UID_COUNT are
402           respectively 100000, 600100000 and 65536.
403
404       SYS_GID_MAX (number), SYS_GID_MIN (number)
405           Range of group IDs used for the creation of system groups by
406           useradd, groupadd, or newusers.
407
408           The default value for SYS_GID_MIN (resp.  SYS_GID_MAX) is 101
409           (resp.  GID_MIN-1).
410
411       SYS_UID_MAX (number), SYS_UID_MIN (number)
412           Range of user IDs used for the creation of system users by useradd
413           or newusers.
414
415           The default value for SYS_UID_MIN (resp.  SYS_UID_MAX) is 101
416           (resp.  UID_MIN-1).
417
418       UID_MAX (number), UID_MIN (number)
419           Range of user IDs used for the creation of regular users by useradd
420           or newusers.
421
422           The default value for UID_MIN (resp.  UID_MAX) is 1000 (resp.
423           60000).
424
425       UMASK (number)
426           The file mode creation mask is initialized to this value. If not
427           specified, the mask will be initialized to 022.
428
429           useradd and newusers use this mask to set the mode of the home
430           directory they create if HOME_MODE is not set.
431
432           It is also used by login to define users' initial umask. Note that
433           this mask can be overridden by the user's GECOS line (if
434           QUOTAS_ENAB is set) or by the specification of a limit with the K
435           identifier in limits(5).
436
437       USERGROUPS_ENAB (boolean)
438           Enable setting of the umask group bits to be the same as owner bits
439           (examples: 022 -> 002, 077 -> 007) for non-root users, if the uid
440           is the same as gid, and username is the same as the primary group
441           name.
442
443           If set to yes, userdel will remove the user's group if it contains
444           no more members, and useradd will create by default a group with
445           the name of the user.
446

FILES

448       /etc/passwd
449           User account information.
450
451       /etc/shadow
452           Secure user account information.
453
454       /etc/group
455           Group account information.
456
457       /etc/gshadow
458           Secure group account information.
459
460       /etc/default/useradd
461           Default values for account creation.
462
463       /etc/shadow-maint/useradd-pre.d/*, /etc/shadow-maint/useradd-post.d/*
464           Run-part files to execute during user addition. The environment
465           variable ACTION will be populated with useradd and SUBJECT with the
466           username.  useradd-pre.d will be executed prior to any user
467           addition.  useradd-post.d will execute after user addition. If a
468           script exits non-zero then execution will terminate.
469
470       /etc/skel/
471           Directory containing default files.
472
473       /etc/subgid
474           Per user subordinate group IDs.
475
476       /etc/subuid
477           Per user subordinate user IDs.
478
479       /etc/login.defs
480           Shadow password suite configuration.
481

EXIT VALUES

483       The useradd command exits with the following values:
484
485       0
486           success
487
488       1
489           can't update password file
490
491       2
492           invalid command syntax
493
494       3
495           invalid argument to option
496
497       4
498           UID already in use (and no -o)
499
500       6
501           specified group doesn't exist
502
503       9
504           username or group name already in use
505
506       10
507           can't update group file
508
509       12
510           can't create home directory
511
512       14
513           can't update SELinux user mapping
514

SEE ALSO

516       chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8),
517       groupmod(8), login.defs(5), newusers(8), subgid(5), subuid(5),
518       userdel(8), usermod(8).
519
520
521
522shadow-utils 4.13                 03/06/2023                        USERADD(8)
Impressum