useradd(1M)

NAME

useradd — add a new user login to the system

SYNOPSIS

useradd [-u uid [-o]] [-g group] [-G group [, group]...] [-d dir] [-s shell] [-c comment] [-m [-i] [-k skel_dir]] [-f inactive] [-e expire] [-r update_homedir_ownership] [-p encrypted_password] [-t template] [-P -S alternate_password_file] login

useradd -D [-g group] [-b base_dir] [-f inactive] [-e expire] [-r update_homedir_ownership] [-k skel_dir] [-s shell] [-c comment] [-O allow_dup_uids] [-t template]

DESCRIPTION

The useradd command creates a user login on the system by adding the appropriate entry to the /etc/passwd file and any security files, modifying the /etc/group 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 passwd (see passwd(1)) command is invoked.

New Behavior

The login will not be added to the primary group entry in the /etc/group file, even if the primary group is specified in the command line. However, the login is added to the corresponding supplemental group in the /etc/group file.

Options

The useradd command supports the following options:

-u uid

Specify the UID for the new user. uid must be a non-negative decimal integer less than MAXUID as defined in the <param.h> header file. uid defaults to the next available unique number above the maximum currently assigned number. UIDs from 0-99 are reserved.

-o

Allow the UID to be non-unique (that is, a duplicate).

-g group

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 useradd -D -g group command.

-G group

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 -g and -G options are ignored.

-d dir

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 -m option.

-s shell

Specify the full pathname of the new login shell. The default is an empty field, which causes the system to use /sbin/sh as the login shell. The value of shell must be a valid executable file.

-c comment

Specify the comment field present in the /etc/passwd entry for this login. This can be any text string. A short description of the new login is suggested for this field.

-m

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 -i option. The -m option must be used to create a home directory.

-i

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 -i option will impact shared home directories; hence use the -i option with caution. The permissions will be same as that of a newly created home directory.

-k skel_dir

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, /etc/skel, that can be used for this purpose.

-f inactive

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).

-e expire

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:

July 13, 1993
7/13/93

A value of '' (two single quotes) or "" (two double quotes) results in no expiration date.

-p encrypted_password

Specify the initial encrypted password for the user. Before using the -p option, obtain the encrypted password by using crypt() (see crypt(3C)).

-P

Specify that the changes are being made to the alternate password file of NIS specified by the -S option. The following options edit the password file and should not be used with the -P option:

-m, -i, -r, -k, -D.

-S alternate_password_file

Specify the path of the alternate password file of NIS. The -P option is used with the -S option.

-D

Manage the defaults for various options. When useradd 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 useradd with this option and other allowed options sets the default values for those options listed in SYNOPSIS.

-t template

Specify the template to be used when loading the defaults for options not specified for useradd command. Any file of the form /etc/default/useradd, can be specified as a template file. When used with -D, the specified attributes are updated to the template file.

-b base_dir

Specify the default base directory for the system. If -d dir is not specified, base_dir is concatenated with the new login name (login) to define the path of the new home directory.

-O allow_dup_uids

Specify whether duplicate UIDs should be allowed by default. The value for allow_dup_uids is either yes or no:

yes: Allow usage of duplicate UIDs by default.
no: Disallow usage of duplicate UIDs by default.

-r update_homedir_ownership

By default, useradd 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 useradd can be changed using the -r [yes|no] option. When used with the -D option, the -r option will set the default behavior. The update_homedir_ownership argument is either yes or no:

yes: useradd 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.
no: useradd will not update the ownership of the home directory and the files/directories below it.

The useradd login command defines the new login name, specified as a string of printable characters. login can not contain a colon (:) or a newline (\n).

The -e and -f options are supported only if Shadow Passwords are in use. For details refer to pwconv(1M).

NIS

The useradd command is aware of NIS user and group entries. Only local users and groups may be modified with the useradd 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:

login x not unique

(return value 9), or the error

UID # is not unique (when -o is not used)

(return value 4) even though the user or UID is not present in the local /etc/passwd file. The error

Cannot modify /etc/group file, /etc/passwd was modified

(return value 10) is returned if an NIS group is specified with either the -g option or the -G option (see group(4)).

NFS

Errors may occur with the -m or -k 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

useradd exits with one of the following values:

0: Successful completion.
2: Invalid command syntax.
3: Invalid argument supplied to an option.
4: uid is not unique (when -o is not used).
6: The group specified with the -g option does not exist.
9: login is not unique.
10: Cannot modify the /etc/group file. The login was added to the /etc/passwd file, but not to the /etc/group file.
12: Unable to create the home directory (while using the -m option) or unable to complete the copy of skel_dir to the new home directory.
13: Unable to open /etc/ptmp file or /etc/default file, or /etc/passwd file is non-existent.
14: /etc/passwd, or /etc/ptmp, or /etc/default file busy. Another command may be modifying the /etc/passwd file.
16: Cannot add the entry into the /etc/passwd file.
18: Out of memory.
19: Invalid template file.
54: Exceeding permissible limit of maximum members in a group. The /etc/group file is not modified.

EXAMPLES

Add the user otto to the system with all of the default attributes.

useradd otto 

Add the user otto to the system with a UID of 222 and a primary group of staff.

useradd -u 222 -g staff otto 

List the defaults for the primary group, base directory, inactivity timeout, and skeleton directory.

useradd -D 

Change the default primary group to staff.

useradd -D -g staff 

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 775 (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. Otherwise, useradd will report an error.

Because many users may try to write the /etc/passwd file simultaneously, a password locking mechanism was devised. If this password locking fails after subsequent retrying, useradd terminates.

A group entry in the /etc/group file can have maximum of LINE_MAX bytes. See limits(5) for the value of LINE_MAX. If a user is added to a group that has reached LINE_MAX limit, another entry of the same group is created to which the new user is added. A warning message is also issued.

FILES

/etc/shadow: Shadow Password file
/etc/passwd: System Password file
/etc/skel: Skeleton directory
/etc/group: System group file
/etc/ptmp: Lock file used when updating password file

STANDARDS CONFORMANCE

useradd: SVID3