useradd(1M)

useradd -- administer a new user login on the system

Synopsis

useradd [-u uid [-o] [-i]] [-g group] [-G group[[,group] . . .]]
[-d dir] [-s shell] [-c comment] [-m [-k skel_dir]] [-f inactive]
[-e expire] [-p passgen] [-a event[, . . .]] login

Description

Invoking useradd generally adds a new user entry to the Identification and Authentication (I&A) data files. The only exception is for Network Information Service (NIS) users. It also creates supplementary group memberships for the user (-G option) and creates the home directory (-m option) for the user if requested. The new login is locked until the passwd(1) command is executed.

As installed, defaults for the various parameters are listed in the file /etc/default/useradd. The defaults for the options below that offer defaults can be changed via the defadm command.

The system file entries created with this command have a limit of 512 characters per line. Specifying long arguments to several options may exceed this limit.

The following options are available:

-u uid: The user identification number (UID). This UID must be a non-negative decimal integer below MAXUID as defined in sys/param.h. The UID defaults to the next available (unique) non-aged UID greater than 99. This option is ignored if the new login will be administered by the Network Information Service (NIS).
-o: This option allows a UID to be duplicated (non-unique). Because the security of the system in general, and the integrity of the audit trail and accounting information in particular, depends on every UID being uniquely associated with a specific individual, use of this option is discouraged (in order to maintain user accountability).
-i: Allow a UID currently being aged to be used.
-g group: An existing group's integer ID or character-string name. This option defines the new user's primary group membership and defaults to the default group in /etc/default/useradd. This option is ignored if the new login will be administered by the Network Information Service (NIS).
-G group[[,group] . . .]: One or more comma-separated list elements, each an existing group's integer ID or character string name. This list defines the supplementary group membership for the user. Duplicates are ignored. The list specified must be less than NGROUPS_MAX in length, as the number of supplementary groups for a user, plus the base group, may never exceed NGROUPS_MAX. This option is ignored if the new login will be administered by the Network Information Service (NIS).
-d dir: The home directory of the new user. This field is limited to 256 characters. It defaults to HOMEDIR/login, where HOMEDIR is the base directory for new login home directories and login is the new login.
-s shell: Full pathname of the program used as the user's shell on login. This field is limited to 256 characters. It defaults to an empty field causing the system to use /usr/bin/ksh as the default. The value of shell must be a valid executable file.
-c comment: Any text string. It is generally a short description of the login, and is currently used as the field for the user's full name. This information is stored in the user's /etc/passwd entry. This field is limited to 128 printable characters.
-m: Create the new user's home directory if it doesn't already exist. If the directory already exists, the user being added must have access permissions to the directory.
-k skel_dir: Copy the contents of the directory skel_dir into the new user's home directory, instead of the contents of the default skeleton directory, /etc/skel. The skel_dir directory must exist. The default skeleton directory contains a standard .profile file, and can contain other directories and files that define the user's environment. An administrator-defined skel_dir might contain the same types of files and directories, customized for a special purpose.
-f inactive: The maximum number of days allowed between uses of a login before that login is declared invalid. Normal values are positive integers.
-e expire: The date on which a login can no longer be used; after this date, no user will be able to access this login. (This option is useful for creating temporary logins.) You may type the value of the argument expire (which is a date) in any format you like (except a Julian date). For example, you may enter 10/6/90 or October 6, 1990.
-p passgen: Indicates that the FLAG field in /etc/shadow is to be set to the specified value. This field is referenced by the passwd command to determine if a password generator is in effect for this user. The FORCED_PASS entry in /etc/default/useradd is checked if the -p option is not explicitly specified to determine the value for the entry in /etc/shadow. If FORCED_PASS does not exist in /etc/default/useradd there will be no value in the /etc/shadow entry. If the value of FORCED_PASS is 1, then the entry in /etc/shadow is set to 1. If passgen is neither a null string nor a printable ASCII character, a diagnostic message is printed.
-a event: A comma-separated list of event types or classes that make up the user's audit mask. There is no default user audit mask in the system as delivered, but you can define a default in the file /etc/default/useradd using the defadm command. This option is valid only if the Auditing Utilities are installed. (To find out which packages are installed on your system, run the pkginfo command.)
login: A string of characters (restricted to the set of alphanumeric characters, the period (.), underscore (_), plus (+), and minus (-) characters) that specifies the new login name of the user. It must not begin with a capital letter.

Note that many of the defaults for the above parameters can be changed through the defadm command, which administers the /etc/default/useradd file. These defaults apply to local users only. The Network Information Service (NIS) database controls defaults for NIS users. You must specify options on the command line to override NIS defaults.

Network information service logins

If login is preceded by a ``+'' character, (for example, ``+chris''), the login definition will be administered by the Network Information Service (NIS). The default values will be drawn from the NIS database rather than from /etc/defaults/useradd. Values for the -u, -g and -G options will be silently ignored if these options are specified. Instead, the values for user ID and group ID will be taken from the NIS database. See passwd(4) for more information. Note that when adding a NIS user, login must exist in the NIS database. For example, to add login ``chris'' as an NIS user, ``chris'' must already exist in the NIS database. You would then invoke useradd with a login of ``+chris'', to distinguish that you wish to add ``chris'' as an NIS user, not a local user.

Files

/etc/default/useradd
/etc/group
/etc/passwd
/etc/security/ia/ageduid
/etc/security/ia/audit: (if the Auditing Utilities are installed)
/etc/security/ia/index
/etc/security/ia/master
/etc/shadow
/etc/skel

Diagnostics

The useradd command exits with a return code of 0 upon successful completion. In case of errors, the following messages may be displayed:

The command line syntax was invalid.
An invalid argument was provided with an option.
The uid specified with the -u option is already in use and the -o option was not specified.
The group specified with the -g option does not exist.
The specified login is not unique.
Cannot update /etc/group. The login was added to the /etc/passwd file but not to the /etc/group file.
Unable to create the home directory (with the -m option) or unable to complete the copy of skel_dir to the home directory.
uid not aged sufficiently. Choose another.
An invalid option -a was specified; system service not installed.
An invalid audit event type or class event was specified.

References

defadm(1M), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), passwd(1), passwd(4), userdel(1M), userls(1M), usermod(1M), users(1bsd)