useradd(1M)useradd(1M)NAMEuseradd - 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]
alternate_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 appropri‐
ate 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)) com‐
mand 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 speci‐
fied 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 overridden
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 cau‐
tion. 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 inactivity 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_home‐
dir_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_owner‐
ship 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 direc‐
tory and the
files/directories below it.
The command defines the new login name, specified as a string of print‐
able 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 verifying
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 per‐
missions 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 ALSOpasswd(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 CONFORMANCEuseradd(1M)
