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       -b, --base-dir BASE_DIR
29           The default base directory for the system if -dHOME_DIR is not
30           specified.  BASE_DIR is concatenated with the account name to
31           define the home directory. The BASE_DIR must exist otherwise the
32           home directory cannot be created.
33
34           If this option is not specified, useradd will use the base
35           directory specified by the HOME variable in /etc/default/useradd,
36           or /home by default.
37
38       -c, --comment COMMENT
39           Any text string. It is generally a short description of the login,
40           and is currently used as the field for the user's full name.
41
42       -d, --home-dir HOME_DIR
43           The new user will be created using HOME_DIR as the value for the
44           user's login directory. The default is to append the LOGIN name to
45           BASE_DIR and use that as the login directory name.
46
47       -D, --defaults
48           See below, the subsection "Changing the default values".
49
50       -e, --expiredate EXPIRE_DATE
51           The date on which the user account will be disabled. The date is
52           specified in the format YYYY-MM-DD.
53
54           If not specified, useradd will use the default expiry date
55           specified by the EXPIRE variable in /etc/default/useradd, or an
56           empty string (no expiry) by default.
57
58       -f, --inactive INACTIVE
59           The number of days after a password expires until the account is
60           permanently disabled. A value of 0 disables the account as soon as
61           the password has expired, and a value of -1 disables the feature.
62
63           If not specified, useradd will use the default inactivity period
64           specified by the INACTIVE variable in /etc/default/useradd, or -1
65           by default.
66
67       -g, --gid GROUP
68           The group name or number of the user's initial login group. The
69           group name must exist. A group number must refer to an already
70           existing group.
71
72           If not specified, the behavior of useradd will depend on the
73           USERGROUPS_ENAB variable in /etc/login.defs. If this variable is
74           set to yes (or -U/--user-group is specified on the command line), a
75           group will be created for the user, with the same name as her
76           loginname. If the variable is set to no (or -N/--no-user-group is
77           specified on the command line), useradd will set the primary group
78           of the new user to the value specified by the GROUP variable in
79           /etc/default/useradd, or 100 by default.
80
81       -G, --groups GROUP1[,GROUP2,...[,GROUPN]]]
82           A list of supplementary groups which the user is also a member of.
83           Each group is separated from the next by a comma, with no
84           intervening whitespace. The groups are subject to the same
85           restrictions as the group given with the -g option. The default is
86           for the user to belong only to the initial group.
87
88       -h, --help
89           Display help message and exit.
90
91       -k, --skel SKEL_DIR
92           The skeleton directory, which contains files and directories to be
93           copied in the user's home directory, when the home directory is
94           created by useradd.
95
96           This option is only valid if the -m (or --create-home) option is
97           specified.
98
99           If this option is not set, the skeleton directory is defined by the
100           SKEL variable in /etc/default/useradd or, by default, /etc/skel.
101
102           If possible, the ACLs and extended attributes are copied.
103
104       -K, --key KEY=VALUE
105           Overrides /etc/login.defs defaults (UID_MIN, UID_MAX, UMASK,
106           PASS_MAX_DAYS and others).
107
108           Example: -K PASS_MAX_DAYS=-1 can be used when creating system
109           account to turn off password ageing, even though system account has
110           no password at all. Multiple -K options can be specified, e.g.: -K
111           UID_MIN=100-K UID_MAX=499
112
113       -l, --no-log-init
114           Do not add the user to the lastlog and faillog databases.
115
116           By default, the user's entries in the lastlog and faillog databases
117           are resetted to avoid reusing the entry from a previously deleted
118           user.
119
120       -m, --create-home
121           Create the user's home directory if it does not exist. The files
122           and directories contained in the skeleton directory (which can be
123           defined with the -k option) will be copied to the home directory.
124
125           By default, if this option is not specified and CREATE_HOME is not
126           enabled, no home directories are created.
127
128           The directory where the user's home directory is created must exist
129           and have proper SELinux context and permissions. Otherwise the
130           user's home directory cannot be created or accessed.
131
132       -M, --no-create-home
133           Do not create the user's home directory, even if the system wide
134           setting from /etc/login.defs (CREATE_HOME) is set to yes.
135
136       -N, --no-user-group
137           Do not create a group with the same name as the user, but add the
138           user to the group specified by the -g option or by the GROUP
139           variable in /etc/default/useradd.
140
141           The default behavior (if the -g, -N, and -U options are not
142           specified) is defined by the USERGROUPS_ENAB variable in
143           /etc/login.defs.
144
145       -o, --non-unique
146           Allow the creation of a user account with a duplicate (non-unique)
147           UID.
148
149           This option is only valid in combination with the -u option.
150
151       -p, --password PASSWORD
152           The encrypted password, as returned by crypt(3). The default is to
153           disable the password.
154
155           Note: This option is not recommended because the password (or
156           encrypted password) will be visible by users listing the processes.
157
158           You should make sure the password respects the system's password
159           policy.
160
161       -r, --system
162           Create a system account.
163
164           System users will be created with no aging information in
165           /etc/shadow, and their numeric identifiers are chosen in the
166           SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, instead
167           of UID_MIN-UID_MAX (and their GID counterparts for the creation of
168           groups).
169
170           Note that useradd will not create a home directory for such an
171           user, regardless of the default setting in /etc/login.defs
172           (CREATE_HOME). You have to specify the -m options if you want a
173           home directory for a system account to be created.
174
175       -R, --root CHROOT_DIR
176           Apply changes in the CHROOT_DIR directory and use the configuration
177           files from the CHROOT_DIR directory.
178
179       -s, --shell SHELL
180           The name of the user's login shell. The default is to leave this
181           field blank, which causes the system to select the default login
182           shell specified by the SHELL variable in /etc/default/useradd, or
183           an empty string by default.
184
185       -u, --uid UID
186           The numerical value of the user's ID. This value must be unique,
187           unless the -o option is used. The value must be non-negative. The
188           default is to use the smallest ID value greater than or equal to
189           UID_MIN and greater than every other user.
190
191           See also the -r option and the UID_MAX description.
192
193       -U, --user-group
194           Create a group with the same name as the user, and add the user to
195           this group.
196
197           The default behavior (if the -g, -N, and -U options are not
198           specified) is defined by the USERGROUPS_ENAB variable in
199           /etc/login.defs.
200
201       -Z, --selinux-user SEUSER
202           The SELinux user for the user's login. The default is to leave this
203           field blank, which causes the system to select the default SELinux
204           user.
205
206   Changing the default values
207       When invoked with only the -D option, useradd will display the current
208       default values. When invoked with -D plus other options, useradd will
209       update the default values for the specified options. Valid
210       default-changing options are:
211
212       -b, --base-dir BASE_DIR
213           The path prefix for a new user's home directory. The user's name
214           will be affixed to the end of BASE_DIR to form the new user's home
215           directory name, if the -d option is not used when creating a new
216           account.
217
218           This option sets the HOME variable in /etc/default/useradd.
219
220       -e, --expiredate EXPIRE_DATE
221           The date on which the user account is disabled.
222
223           This option sets the EXPIRE variable in /etc/default/useradd.
224
225       -f, --inactive INACTIVE
226           The number of days after a password has expired before the account
227           will be disabled.
228
229           This option sets the INACTIVE variable in /etc/default/useradd.
230
231       -g, --gid GROUP
232           The group name or ID for a new user's initial group (when the
233           -N/--no-user-group is used or when the USERGROUPS_ENAB variable is
234           set to no in /etc/login.defs). The named group must exist, and a
235           numerical group ID must have an existing entry.
236
237           This option sets the GROUP variable in /etc/default/useradd.
238
239       -s, --shell SHELL
240           The name of a new user's login shell.
241
242           This option sets the SHELL variable in /etc/default/useradd.
243

NOTES

245       The system administrator is responsible for placing the default user
246       files in the /etc/skel/ directory (or any other skeleton directory
247       specified in /etc/default/useradd or on the command line).
248

CAVEATS

250       You may not add a user to a NIS or LDAP group. This must be performed
251       on the corresponding server.
252
253       Similarly, if the username already exists in an external user database
254       such as NIS or LDAP, useradd will deny the user account creation
255       request.
256
257       Usernames may contain only lower and upper case letters, digits,
258       underscores, or dashes. They can end with a dollar sign. Dashes are not
259       allowed at the beginning of the username. Fully numeric usernames and
260       usernames . or .. are also disallowed. It is not recommended to use
261       usernames beginning with . character as their home directories will be
262       hidden in the ls output. In regular expression terms:
263       [a-zA-Z0-9_.][a-zA-Z0-9_.-]*[$]?
264
265       Usernames may only be up to 32 characters long.
266

CONFIGURATION

268       The following configuration variables in /etc/login.defs change the
269       behavior of this tool:
270
271       CREATE_HOME (boolean)
272           Indicate if a home directory should be created by default for new
273           users.
274
275           This setting does not apply to system users, and can be overridden
276           on the command line.
277
278       GID_MAX (number), GID_MIN (number)
279           Range of group IDs used for the creation of regular groups by
280           useradd, groupadd, or newusers.
281
282           The default value for GID_MIN (resp.  GID_MAX) is 1000 (resp.
283           60000).
284
285       MAIL_DIR (string)
286           The mail spool directory. This is needed to manipulate the mailbox
287           when its corresponding user account is modified or deleted. If not
288           specified, a compile-time default is used.
289
290       MAIL_FILE (string)
291           Defines the location of the users mail spool files relatively to
292           their home directory.
293
294       The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and
295       userdel to create, move, or delete the user's mail spool.
296
297       If MAIL_CHECK_ENAB is set to yes, they are also used to define the MAIL
298       environment variable.
299
300       MAX_MEMBERS_PER_GROUP (number)
301           Maximum members per group entry. When the maximum is reached, a new
302           group entry (line) is started in /etc/group (with the same name,
303           same password, and same GID).
304
305           The default value is 0, meaning that there are no limits in the
306           number of members in a group.
307
308           This feature (split group) permits to limit the length of lines in
309           the group file. This is useful to make sure that lines for NIS
310           groups are not larger than 1024 characters.
311
312           If you need to enforce such limit, you can use 25.
313
314           Note: split groups may not be supported by all tools (even in the
315           Shadow toolsuite). You should not use this variable unless you
316           really need it.
317
318       PASS_MAX_DAYS (number)
319           The maximum number of days a password may be used. If the password
320           is older than this, a password change will be forced. If not
321           specified, -1 will be assumed (which disables the restriction).
322
323       PASS_MIN_DAYS (number)
324           The minimum number of days allowed between password changes. Any
325           password changes attempted sooner than this will be rejected. If
326           not specified, -1 will be assumed (which disables the restriction).
327
328       PASS_WARN_AGE (number)
329           The number of days warning given before a password expires. A zero
330           means warning is given only upon the day of expiration, a negative
331           value means no warning is given. If not specified, no warning will
332           be provided.
333
334       SYS_GID_MAX (number), SYS_GID_MIN (number)
335           Range of group IDs used for the creation of system groups by
336           useradd, groupadd, or newusers.
337
338           The default value for SYS_GID_MIN (resp.  SYS_GID_MAX) is 101
339           (resp.  GID_MIN-1).
340
341       SYS_UID_MAX (number), SYS_UID_MIN (number)
342           Range of user IDs used for the creation of system users by useradd
343           or newusers.
344
345           The default value for SYS_UID_MIN (resp.  SYS_UID_MAX) is 101
346           (resp.  UID_MIN-1).
347
348       UID_MAX (number), UID_MIN (number)
349           Range of user IDs used for the creation of regular users by useradd
350           or newusers.
351
352           The default value for UID_MIN (resp.  UID_MAX) is 1000 (resp.
353           60000).
354
355       UMASK (number)
356           The file mode creation mask is initialized to this value. If not
357           specified, the mask will be initialized to 022.
358
359           useradd and newusers use this mask to set the mode of the home
360           directory they create
361
362           It is also used by login to define users' initial umask. Note that
363           this mask can be overridden by the user's GECOS line (if
364           QUOTAS_ENAB is set) or by the specification of a limit with the K
365           identifier in limits(5).
366
367       USERGROUPS_ENAB (boolean)
368           Enable setting of the umask group bits to be the same as owner bits
369           (examples: 022 -> 002, 077 -> 007) for non-root users, if the uid
370           is the same as gid, and username is the same as the primary group
371           name.
372
373           If set to yes, userdel will remove the user's group if it contains
374           no more members, and useradd will create by default a group with
375           the name of the user.
376

FILES

378       /etc/passwd
379           User account information.
380
381       /etc/shadow
382           Secure user account information.
383
384       /etc/group
385           Group account information.
386
387       /etc/gshadow
388           Secure group account information.
389
390       /etc/default/useradd
391           Default values for account creation.
392
393       /etc/skel/
394           Directory containing default files.
395
396       /etc/login.defs
397           Shadow password suite configuration.
398

EXIT VALUES

400       The useradd command exits with the following values:
401
402       0
403           success
404
405       1
406           can't update password file
407
408       2
409           invalid command syntax
410
411       3
412           invalid argument to option
413
414       4
415           UID already in use (and no -o)
416
417       6
418           specified group doesn't exist
419
420       9
421           username already in use
422
423       10
424           can't update group file
425
426       12
427           can't create home directory
428
429       14
430           can't update SELinux user mapping
431

SEE ALSO

433       chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8),
434       groupmod(8), login.defs(5), newusers(8), userdel(8), usermod(8).
435
436
437
438shadow-utils 4.1.5.1              03/14/2019                        USERADD(8)
Impressum