useradd
name
: create a new user
or update the new user’s default information
Synopsis
useradd [options] LOGIN useradd -D useradd -D
[options]Description
When invoked without the -D option, the useradd command
creates a new user account using the values specified on the command line plus system defaults. Depending on the command-line options, the useradd command will update the system files and can also create the new user’s home directory and copy the initial files.
By default, a group will also be created for the new user (see –g, –N, –you, and USERGROUPS_ENAB).
Options
The
options that apply to the useradd command are:
–
b, –base-dir, BASE_DIR
The default base directory for the system if -d is not specified HOME_DIR. BASE_DIR concatenates with the account name to define the home directory. If the -m option is not used, BASE_DIR people must exist.
If this option is not specified, useradd will use the base directory specified by the HOME variable in /etc/default/useradd or /home by default.
-c, -comment COMMENT Any text string. It is usually a brief description of the login, and is currently used as the field for the user’s full name. -d, -home HOME_DIR The new user will be created using HOME_DIR as the value for the user’s logon directory. The default is to add the name LOGIN to BASE_DIR and use it as the name of the login directory. The HOME_DIR directory does not have to exist, but it will not be created if it is missing. -D, -defaults See the “Changing Defaults” subsection below. -e, -expiredate EXPIRE_DATE The date on which the user account will be disabled. The date is specified in the format YYYY-MM-DD.
If not specified, useradd will use the default expiration date specified by the EXPIRE variable in /etc/default/useradd, or an empty string (no expiration) by default
. –f, -inactivate INACTIVATE The number of days after a password expires until the account is permanently disabled. A value of 0 disables the account as soon as the password has expired and a value of -1 disables the feature.
If not specified, useradd will use the default idle period specified by the INACTIVE variable in /etc/default/useradd, or -1 by default.
-g, -gid GROUP The name or group number of the user’s initial logon group. The group name must exist. A group number must refer to an existing group.
If not specified, the useradd bahávior will depend on the variable USERGROUPS_ENAB in /etc/login.defs. If this variable is set to yes (or –U/-user-group is specified on the command line), a group is created for the user, with the same name as their loginname. If the variable is set to no (or -N/-no-user-group is specified on the command line), useradd will set the new user’s parent group to the value specified by the GROUP variable in /etc/default/useradd, or 100 by default.
-G, -groups GROUP1[,GROUP2,… [,GROUP]]] A list of supplemental groups of which the user is also a member. Each group is separated from the next by a comma, with no blank spaces in between. Groups are subject to the same restrictions as the group given with the -g option. The default is that the user belongs only to the initial group. -h, –help Show help message and exit. -k, -skel SKEL_DIR The skeleton directory, which contains files and directories to be copied to the user’s home directory, when useradd creates the home directory. This option is
valid only if the -m (or –create-home) option is specified.
If this option is not set, the skeleton directory is defined by the SKEL variable in
/etc/default/useradd or, by default, /etc/skel. –K, -key KEY=VALUE Overrides the default values /etc/login.defs (UID_MIN, UID_MAX, UMASK, PASS_MAX_DAYS, and others).
Example: –K PASS_MAX_DAYS=-1 can be used when creating a system account to disable password expiration, even if the system account has no password. Multiple options can be specified -K, for example: -K UID_MIN=100 -K UID_MAX=499 Note: -K UID_MIN=10,UID_MAX=499
still does not work.
-l, –no-log-init Do not add the user to the lastlog and faillog databases.
By default, user entries in the lastlog and faillog databases are reset to prevent reuse of a previously deleted user’s entry.
-m, –create-home Create the user’s home directory if it does not exist. The files and directories contained in the skeleton directory (which can be defined with the -k option) will be copied to the home directory.
UserAdd will create the home directory unless CREATE_HOME in /etc/login.defs is set to No.
-M Do not create the user’s home directory, even if the system-wide setting of /etc/login.defs (CREATE_HOME) is set to yes. -N, -no-user-group Do not create a group with the same name as the user, but add the user to the group specified by the -g option or by the GROUP variable in /etc/default/useradd.
The default behavior (if the –g, -N, and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.
-or, -non-unique Allows the creation of a user account with a duplicate (non-unique) UID.
This option is only valid in combination with the -o option.
-p, –password PASSWORD The encrypted password, as returned by crypt(3). The default is to disable the password.
Note: This option is not recommended because the password (or encrypted password) will be visible to users who list the processes.
You must ensure that the password respects the system’s password policy.
-r, –system Create a system account.
System users will be created without old information in /etc/shadow, and their numeric identifiers are chosen in the SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, rather than UID_MIN-UID_MAX (and its GID counterparts for group creation).
Note that useradd will not create a home directory for that user, regardless of the default settings in /etc/login.defs (CREATE_HOME). You must specify the -m options if you want a home directory to be created for a system account.
-s, –shell SHELL The name of the user’s logon shell. The default is to leave this field blank, which causes the system to select the default login shell specified by the SHELL variable in /etc/default/useradd, or an empty string by default. -u, -uid UID The numeric value of the user ID. This value must be unique, unless the -o option is used. The value must be non-negative. The default is to use the smallest ID value greater than 999 and larger than any other user. Values between 0 and 999 are typically reserved for system accounts. -U, –user-group Create a group with the same name as the user and add it to this group.
The default behavior (if the –g, -N, and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.
-Z, –selinux-user SEUSER The SELinux user for user login. The default is to leave this field blank, which causes the system to select the default SELinux user.
Changing defaults
When invoked with the -D option alone, useradd will display the current default values. When invoked with -D plus other options, useradd will update the default values for the specified options. Valid default change options are: –
b, –base-dir, BASE_DIR
The path prefix for a new user’s home directory. The user’s name will be placed at the end of BASE_DIR to form the name of the new user’s home directory, if the -d option is not used when creating a new account.
This option sets the HOME variable to /etc/default/useradd.
-e, -expiredate EXPIRE_DATE The date the user account is disabled.
This option sets the EXPIRE variable to /etc/default/useradd.
-f, -inactive INACTIVE The number of days after a password has expired before the account is disabled.
This option sets the INACTIVE variable to /etc/default/useradd.
-g, -gid GROUP The name or group ID for the initial group of a new user (when using -N/-no-user-group or when the USERGROUPS_ENAB variable is set to no in /etc/login.defs. The named group must exist, and a numeric group identifier must have an existing entry.
This option sets the GROUP variable to /etc/default/useradd.
-s, –shell SHELL The name of a new user’s login shell.
This option sets the SHELL variable to /etc/default/useradd.
Notes
The system administrator is responsible for placing the default user files in the /etc/skel/ directory (or any other skeleton directory specified in /etc/default/useradd or on the command line).
Warnings
You cannot add a user to an NIS or LDAP group. This must be done on the appropriate server.
Similarly, if the user
name already exists in an external user database such as NIS or LDAP, useradd will deny the user account creation request
.
Usernames can only be up to 32 characters long
.
Configuration
The following configuration variables in /etc/login.defs change the behavior of this tool:
CREATE_HOME (Boolean)
Indicate whether to create a home directory by default for new users.
These settings do not apply to system users and can be overridden on the command line.
GID_MAX (number), GID_MIN (number) A range of group IDs used for the creation of regular groups by useradd, groupadd, or newusers. MAIL_DIR (string) The mail queue directory. This is required to manipulate the mailbox when its corresponding user account is modified or deleted. If not specified, a compile-time default value is used. MAIL_FILE (string) Defines the location of users’ mail queue files relative to their home directory. The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and userdel to create, move, or delete the user’s mail queue.
If MAIL_CHECK_ENAB is set to yes, they are also used to define the MAIL environment variable.
MAX_MEMBERS_PER_GROUP (number)
Maximum number of members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, password, and same GID).
The default value is 0, which means that there are no limits on the number of members in a group.
This function (split group) allows you to limit the length of the lines in the group file. This is useful to ensure that the lines of NIS groups do not exceed 1024 characters.
If you need to enforce such a limit, you can use 25.
Note: Split groups may not be supported by all tools (including the Shadow toolset). You should not use this variable unless you really need it.
PASS_MAX_DAYS (number) The maximum number of days a password can be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction). PASS_MIN_DAYS (number) The minimum number of days allowed between password changes. Any password changes attempted before this will be rejected. If not specified, -1 will be assumed (which disables the restriction). PASS_WARN_AGE (number) The number of warning days given before a password expires. A zero means that the warning is given only on the day of expiration, a negative value means that no warning is given. If not specified, no warning will be provided. SYS_GID_MAX (number), SYS_GID_MIN (number) A range of group IDs used for creating groups of systems by useradd, groupadd, or newusers. SYS_UID_MAX (number), SYS_UID_MIN (number) The range of user IDs used for the creation of system users by useradd or newusers. UID_MAX (number), UID_MIN (number) Range of user IDs used for the creation of normal users by useradd or newusers. UMASK Number The file mode creation mask is initialized with this value. If not specified, the mask will be initialized to 022.
useradd and newusers use this mask to set the home directory mode they create
It is also used by login to define the initial mask of users. Note that this mask can be overridden by the user’s GECOS line (if QUOTAS_ENAB is set) or by specifying a boundary with the identifier K in boundaries(5).
USERGROUPS_ENAB (Boolean) Enable the mask group bits to be the same as the owner bits (examples: 022 -> 002, 077 -> 007) for non-root users, if the uid is the same as gid and the user name is the same as the parent group name.
If set to yes, userdel will delete the user’s group if it contains no more members, and useradd will default to a group with the user’s name.
/
etc/passwd
files User account information. /etc/shadow Secure user account information. /etc/group Group account information. /etc/gshadow Secure group account information. /etc/default/useradd Default values for account creation. /etc/skel/ Directory containing default files. /etc/login.defs Configuration of the hidden password suite.
Output values
The
useradd command comes out with the following values:
0
OK 1 Unable to update password file 2 invalid command syntax 3 invalid argument for option 4 UID already in use (and without -o) 6 The specified group does not exist 9 Username is already in use 10 Unable to update group file 12 Unable to create home directory 13 Not known You can create mail queue 14 Unable to update SELinux user mapping
See also
chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8),
groupmod(8), login.defs(5), newusers(8), userdel(8), usermod(8).
Referenced by
chpasswd(8), groupmems(8), jk_addjailuser(8), useradd_selinux(8)