useradd(ADM)

useradd, userdel, usermod -- add, delete, or change a user account

Syntax

/etc/useradd [-c comment] [-d directory] [-g group] [-G group1,group2,...]
[-M] [-m] [-s shell] [-u uid [-o]] [-x "extendedOptionString"] [-X optionsFile]
[hostname:]user

/etc/userdel [-x "extendedOptionString"] [-X optionsFile] [hostname:]user

/etc/usermod -D [-g group_name] [-s shell] [-x "extendedOptionString"]
[-X optionsFile]

/etc/usermod [-c comment] [-d directory [-m]] [-g group]
[-G group1,group2,...] [-l newname] [-s shell] [-u uid [-o]]
[-x " extendedOptionString"] [-X optionsFile] [hostname:]user

Description

With no options specified useradd creates a user account on the local system.

Users can be created in one of three locations:

the local system
a specified remote system on which the invoking user has equivalence (via a .rhost file) and the auth authorization
an NIS server if the machine is an NIS client, copy server, or slave server and the user has established equivalence (via a .rhost file) with the NIS server machine

If a user account already exists locally when an NIS version of that account is created, the local account is removed from the system. If an NIS version of an account already exists when a local version is created, the remote account is not deleted. If you wish to delete the remote account, you must do so before adding the local account of the same name.

userdel deletes the specified user account from the User Account and Group Account databases. userdel is only valid when the Low or Traditional security profiles are configured (or the SECLUID kernel parameter is set to zero). Otherwise, accounts should be retired rather than removed, as described in ``Removing or retiring a user account'' in Administering users and groups.

usermod modifies one or more of the attributes associated with the specified account.

A user name has a limit of 8 lowercase letters or numbers, but must not begin with a number. In addition, user names cannot include colons (:) (aside from the hostname:user syntax used to create a remote account) or newlines.

For distributed accounts, only the user name, comment, password, login shell, home directory, login group, group membership, password, and lock status are valid across the network. For example, you cannot set the maximum number of failed login attempts for a distributed user on a remote system (it only takes effect on the master server).

When adding users to a group that is both local and distributed, users will be placed in the local group. To add users to a distributed group, use groupmod(ADM).

Options

The following options are supported by useradd and usermod:

-c comment: Specify a text string of no more than 512 characters. Must not contain colons (:) or newlines.
-d directory: Specify the new home directory of the user. If the home directory is being changed, the contents of the previous home directory are only modified if -m is specified. Directory names must not contain colons (:) or newlines and must not begin with a period. If the path specifies an existing file that is not a directory, then the -M option must also be specified.
-g group: Specify the primary group membership of a new user in the User Account database and may define the account as a member of the specified group in the Group Account database. The value can be the GID or the group name. If numeric, the group need not yet exist in the Group Account database.
-G groups: Specify a set of existing group names or GIDs, from the Group Account database, contained in a comma-separated character string. This defines the additional groups that a user can access via the sg(C) utility. Duplicates are ignored. An error is displayed for each member of groups that does not exist in the group database.
-M: Allows creation of an account with an existing file specified as a home directory. Must be used with the -d option. This is typically done to provide increased security for logins used by applications (such as Samba) that do not need home directories.
-m: Create the user home directory if it does not already exist. If the directory already exists, it must be accessible by the user. The home directory is populated with the proper shell environment files found in /usr/lib/mkuser. A mailbox file is created and greetings mail is sent to the user. When used on the usermod command line, -m should not be used without -d.
-o: When used in conjunction with -u, allow the use of a UID already assigned to another account. This option is only valid when the Low or Traditional security profiles are configured (specifically, REUSEUID=TRUE must be present in /etc/default/login).
-s shell: Specify the full pathname of the program that will be used as the user's initial shell program. The shell path must not contain colons (:) or newlines.
-u uid: Specify the user ID of the new user. It must be a positive integer less than 60000. The minimum and maxiumum values are defined in /etc/default/accounts.

The following options are supported by usermod only:

-D: Operate on system defaults instead of an individual user account.
-l newname: Specify the new name of the user to be modified. This option is only valid when the Low or Traditional security profiles are configured (specifically, REUSEUID=TRUE must be present in /etc/default/login).

The following options are supported by useradd, userdel, and usermod:

-x "extendedOptionString": Specify extended account parameters in the form of attribute-value pairs. See the ``Extended options and option files'' section.
-X optionsFile: Specify the file from which a set of account attributes are to be taken.

Extended options and option files

Extended options use the following syntax:

{ attribute value }

Attributes that are associated with a set of values should use nested braces to enclose the values:

{ attribute { value value } }

When used on the command line, the outermost braces ({ }) must be enclosed in double-quotes (") to prevent intrepretation by the shell. Values containing spaces should be further enclosed in single quotes (').

NOTE: Extended options other than distributed and administrativeLockApplied are not valid for distributed accounts. The remaining parameters can be set on the master server, but they will only have effect on the server.

Option files use the same syntax (without the double-quotes).

Certain account status attributes (such as last successful login time and location) are not listed here, but can be queried with userls(ADM).

The following attributes are available (unless noted otherwise, each is valid with or without the -D option):

administrativeLockApplied: When set to 1, the account is locked and prevents a user from logging in. A value of 0 unlocks the account.
auditFlags: A set of flags which indicate which classes of audit event will be collected. The control mask lists the classes of audit records for which the user has non-default behavior. The audit disposition mask lists the classes of audit record for which the user is always audited. When an audit class appears in the control mask and not in the disposition mask it means that the user is never audited for that class. Event values are Default=0, On=1, Off=2.
auditMask: A list of the auditable events for the user's audit mask. See auditevents(M) for a list of valid events to specify with auditMask.
auths: The set of subsystem authorizations available: mem, terminal, lp, backup, auth, audit, cron, root, sysadmin, passwd, audittrail, backup_create, restore, queryspace, printqueue, printerstat, su, shutdown.
authsAvailable: The available subsystem authorizations on the system. This parameter is only valid with the -D option.
baseHome: Default absolute pathname of parent directory of user's home directory. The home directory itself has the same name as the user. This parameter is only valid with the -D option.
distributed: If this attribute is set to 1, then the account is distributed via NIS. If 0, it is not distributed. (NIS must be configured for accounts to be distributed.)
groups: The list of supplemental groups associated with a user.
integrityRequired: Indicates that inconsistencies between the TCB and System V account databases should result in a lockout that prevents users from logging in until the problem is corrected. This parameter is only valid with the -D option.
lastSuccessfulLogoutTime: The time at which a user last logged off the system.
lastSuccessfulLogoutTty: The device from which an account last successfully logged out.
loginGroup: The login group associated with an account.
maxLoginAttempts: The maximum number of consecutive unsuccessful login attempts allowed before an account is locked.
maxSuggestUid: The largest numeric identifier assigned to a new user by default. This parameter is only valid with the -D option.
maxUid: The largest numeric identifier that can be assigned to a user. This parameter is only valid with the -D option.
minSuggestUid: The smallest numeric identifier assigned to a new user by default. This parameter is only valid with the -D option.
minUid: The smallest numeric identifier that can be assigned to a user. This parameter is only valid with the -D option.
mode: The permission bits associated with a home directory.
nextUid: The next available pw_uid in the range of minUid to maxUid. This parameter is only valid with the -D option.
nice: The scheduling priority of user processes (established by login). See nice(C) for more information.
owner: The account name of a user who is held responsible for use of the account. This is only valid for accounts of type pseudo and root.
passwdCheckedForObviousness: If this attribute is set to 1, then a password is verified using the configured password checking. If the password is found to be invalid, it is rejected.
passwdChooseOwn: If this attribute is set to 1, then a user is allowed to choose a password. If set to 0, then a password is supplied by the password generator (or the administrator).
passwdExpirationTime: The interval of time, in days, since a password was last changed until the authentication process requires that a new password be chosen.
passwdGeneratedLength: The length of passwords produced by the password generator.
passwdLifetime: The interval of time, in days, since a password was last changed before the account is locked.
passwdMinChangeTime: The minimum interval of time, in days, which must pass between password changes.
passwdNullAllowed: If this attribute is set to 1, the authentication process does not prompt the user for a password if the password attribute is currently set to NULL. If the attribute is set to 0, then the user is prompted for a password during authentication regardless of the current value of the password attribute. Note that other attributes may still prevent the user from gaining access to an account.
passwdRunGenerator: If this attribute is set to 1, a password can be generated by the user. If set to 0, the user must create their own password.
passwdSignificantSegments: The number of characters (divided by 8) considered significant in password comparisons. For example, if passwdSignificantSegments was set to 1, then 8 characters would be significant, so login would match an entered password of abcd1234 with a stored password of abcd12345. The range is 1 to 10. This parameter is only valid with the -D option.
passwdUser: The account name of a user who may change the password of the account without needing subsystem authorization.
privs: The set of initial kernel privileges set by login. The privileges are: suspendaudit, configaudit, writeaudit, execsuid, setguid, chown.
pw_dir: The home directory of an account.
pw_gid: The group number associated with an account.
pw_shell: The login shell of a user.
pw_uid: The numeric identifier for an account. This parameter is not valid with the -D option.
tcbDatabaseIsMaster: Indicates that values from the Protected Password database and the System default database are used in preference to the value of attributes duplicated in /etc/passwd, /etc/shadow and various /etc/default files when a discrepancy is detected. This parameter is only valid with the -D option.
userType: The user type classification (a non-functional label). The values are: root, operator, sso, administrator, pseudo, general, retired. Normal user accounts are assigned the type general, and system accounts the type pseudo. The label retired is used only for accounts that have been retired.

Exit values

Upon completion, these utilities exit with one of the following values:

0: The action was successful.
>0: An error occurred.

Examples

The following command creates a distributed user account, mavrac, with a UID of 1600, a login group of type41, and a login shell of csh:

useradd -u 1600 -s /bin/csh -g type41 -x "{distributed 1}" mavrac

This command creates a remote user, nathanb, on a remote machine obie:

useradd nathanb:obie

This command changes the maximum number of failed login attempts for user mavrac to eight:

usermod -x "{maxLoginAttempts 8}" mavrac

This command changes the set of default authorizations for users who have not been assigned individual values:

usermod -D -x "{auths {mem lp cron} }"

Notes

The length of shell and home pathnames is limited by the maximum path length supported by the filesystem on which the shell and home directory reside. This is determined by .pathconf(S-osr5)

There is no limit to the comment entry length other than that an /etc/passwd file entry must not exceed 1024 characters in total length.

Files

/etc/passwd: password file
/etc/group: group file
/tcb/files/auth/?/: Protected Password database
/etc/auth/?/: Subsystem Authorizations database
/etc/default/accounts: user/group account creation defaults

Standards conformance

useradd is conformant with AT&T SVID Issue 2.