useradd(1M) useradd(1M)
NAME
useradd - add a new user login to the system
SYNOPSIS
uid group] groupgroup]...] dir] shell] comment] skel_dir]] inactive] expire] update_homedir_ownership] encrypted_password] template] alter-
nate_password_file] login
group] base_dir] inactive] expire] update_homedir_ownership] skel_dir] shell] comment] allow_dup_uids] template]
DESCRIPTION
The command creates a user login on the system by adding the appropriate entry to the file and any security files, modifying the file as
necessary, creating a home directory, and copying the appropriate default files into the home directory depending on the command line
options. The new login remains locked until the (see passwd(1)) command is invoked.
Refer to usergroupname(5) to understand the functionality changes with the Numeric User Group Name feature.
New Behavior
The login will not be added to the primary group entry in the file, even if the primary group is specified in the command line. However,
the login is added to the corresponding supplemental group in the file.
Options
The command supports the following options:
Specify the UID for the new user. uid must be a non-negative decimal integer less than as defined in the header file. uid
defaults to the next available unique number above the maximum currently assigned number. UIDs from 0-99 are
reserved.
Allow the UID to be non-unique (that is, a duplicate).
Specify the integer group
ID or character string name of an existing group. This defines the primary group membership of the new login. The
default for this option can be reset by invoking the command.
Specify the integer group
ID or character string name of an existing group. This defines the supplemental group memberships of the new login.
Multiple groups may be specified as a comma separated list. Duplicates within group with the and options are
ignored.
Specify the home directory of the new login.
It defaults to base_dir/login, where login is the new login and base_dir is the base directory for new login home
directories.
To specify directory creation, you must use the option.
Specify the full pathname of the new login shell.
The default is an empty field, which causes the system to use as the login shell. The value of shell must be a valid
executable file.
Specify the comment field present in the
entry for this login. This can be any text string. A short description of the new login is suggested for this
field.
Create the home directory for the new login if it does not exist. If the home directory exists, the directory must have
read and execute permission by group, where group is the primary group of the new login. This condition can be over-
ridden using the option. The option must be used to create a home directory.
Inherit an existing home directory, regardless of its current access
permissions. Typically use this option to inherit orphaned directories, that is, directories that are not owned by
any active user of the system. Note that using the option will impact shared home directories; hence use the option
with caution. The permissions will be same as that of a newly created home directory.
Specify the skeleton directory that contains information that
can be copied to the new login's home directory. This skeleton directory must exist. The system provides a skeleton
directory, that can be used for this purpose.
Specify the maximum number of days of continuous
inactivity of the login before the account is locked. For the valid values of inactive refer to description of inac-
tivity field in shadow(4).
Specify the date on which this account is no longer valid.
After the expire date occurs, no user will be able to access this account. This option is used to create temporary
logins. expire, which is a date, may be typed in any format, except a Julian date. For example, a date may be
entered in either of the following formats:
A value of (two single quotes) or (two double quotes) results in no expiration date.
Specify the initial encrypted password for the user.
Before using the option, obtain the encrypted password by using or (see crypt(3C) or crypt2(3C)).
Specify that the changes are being made to the alternate
password file of NIS specified by the option. The following options edit the password file and should not be used
with the option:
Specify the path of the alternate password file of NIS.
The option is used with the option.
Manage the defaults for various options.
When is invoked with this option only, the default values for group, base_dir, skel_dir, shell, inactive, expire,
comment, update_homedir_ownership, create_homedir, and allow_dup_uids are displayed. Invoking with this option and
other allowed options sets the default values for those options listed in
Specify the template to be used when loading the defaults
for options not specified for command. Any file of the form can be specified as a template file. When used with the
specified attributes are updated to the template file. It is recommended to use and and at least one other allowed
option listed in the to create the template.
Specify the default base directory for the system.
If is not specified, base_dir is concatenated with the new login name (login) to define the path of the new home
directory.
Specify whether duplicate UIDs should be allowed
by default. The value for allow_dup_uids is either or
Allow usage of duplicate UIDs by default.
Disallow usage of duplicate UIDs by default.
By default, will not recursively update the ownership of the home directory for the new user if the directory exists and is not a
shared home directory. This behavior of can be changed using the option. When used with the option, the option will
set the default behavior. The update_homedir_ownership argument is either or
will recursively update the ownership of the home directory and the
files/directories below it to the new user, if the directory already exists and is not a shared home directory.
will not update the ownership of the home directory and the
files/directories below it.
The command defines the new login name, specified as a string of printable characters. login can not contain a colon or a newline
The and options are supported only if are in use. For details refer to pwconv(1M).
NIS
The command is aware of NIS user and group entries. Only local users and groups may be modified with the command. Attempts to modify an
NIS user or group will result in an error. NIS users and groups must be administered from the NIS server. NIS users are checked when ver-
ifying uniqueness of the new UID or new user name, which may result in the following error messages:
(return value 9), or the error
(return value 4) even though the user or UID is not present in the local file. The error
(return value 10) is returned if an NIS group is specified with either the option or the option (see group(4)).
NFS
Errors may occur with the or options if the indicated directory is within an NFS mounted file system that does not allow root privileges
across the NFS mount, and the directory or files within the directory do not have sufficient permissions.
RETURN VALUE
exits with one of the following values:
Successful completion.
Invalid command syntax.
Invalid argument supplied to an option.
uid is not unique (when is not used).
The group specified with the option does not exist.
login
is not unique.
Cannot modify the
file. The login was added to the file, but not to the file.
Unable to create the home directory (while using the
option) or unable to complete the copy of skel_dir to the new home directory.
Unable to open
file or file, or file is non-existent.
or or file busy. Another command may be modifying the file.
Cannot add the entry into the
file.
Out of memory.
Invalid template file.
Exceeding permissible limit of maximum members in a group.
The file is not modified.
Cannot modify the specified template.
The file is either missing or not in a sane state.
EXAMPLES
Add the user to the system with all of the default attributes.
Add the user to the system with a UID of and a primary group of
List the defaults for the primary group, base directory, inactivity timeout, and skeleton directory.
Change the default primary group to
WARNINGS
A directory can be shared between the users belonging to the same group. If the home directory is in the unshared mode and a new user is
allocated to that directory then it will be put into the shared mode by setting the permissions of that directory to (includes the write
permissions to the group as well). Also, the directory which will be shared should have read and execute permissions for the group. Other-
wise, will report an error.
Because many users may try to write the file simultaneously, a password locking mechanism was devised. If this password locking fails
after subsequent retrying, terminates.
A group entry in the file can have maximum of bytes. See limits(5) for the value of If a user is added to a group that has reached limit,
another entry of the same group is created to which the new user is added. A warning message is also issued.
FILES
Shadow Password file
System Password file
Skeleton directory
System group file
Lock file used when updating password file
SEE ALSO
passwd(1), users(1), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), pwconv(1M), userdel(1M), usermod(1M), crypt(3C), crypt2(3C),
group(4), shadow(4), limits(5), usergroupname(5).
STANDARDS CONFORMANCE
useradd(1M)