usermod(1M)

usermod -- modify a user's login information on the system

Synopsis

usermod [-u uid [-U] [-o]] [-g group] [-G group[[,group] ...]] [-d dir [-m]] [-s shell] [-c comment] [-l new_logname] [-f inactive] [-e expire] [-p passgen] [-a [operator1] event [,...]] login

Description

Invoking usermod modifies a user entry in the Identification and Authentication (I&A) data files. The system file entries created with this command have a limit of 512 characters per line. Specifying long arguments to several options may result in exceeding this limit.

NOTE: This command must be invoked with the -U option to change the UID on directories and files owned by the user whose UID is being changed; otherwise, the system administrator must make such changes.

The following options are available:

-u uid: New user identification number (UID). It must be a non-negative decimal integer below MAXUID as defined in sys/param.h. This option is ignored if the login is administered by the Network Information Service (NIS).
-o: This option allows the specified 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).
-U: This option examines a list of pathnames specified in /etc/default/usermod. Any files or directories in the specified path list that are owned by the old UID will have their ownership changed to be that of the new UID. The path list typically includes the user's home directory and mail file. This option will also disable a crontab file under the old UID, and re-enable it under the new UID. The -u option must also be specified when this option is used.
-g group: An existing group's integer ID or character-string name. It redefines the user's primary group membership. This option is ignored if the login is 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 becomes the new supplementary group membership for the user, replacing any existing supplementary group list 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 login is administered by the Network Information Service (NIS).
-d dir: The new home directory of the user. This field is limited to 256 characters.
-m: Move the user's home directory to the new directory specified with the -d option. If the directory already exists, the specified login must have access to it.
-s shell: Full pathname of the program that is used as the user's shell on login. This field is limited to 256 characters. 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 field is limited to 128 printable characters. This information is stored in the user's /etc/passwd entry.
-l new_logname: 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.
-f inactive: The maximum number of days allowed between uses of a login ID before that login ID is declared invalid. Normal values are positive integers. A value of 0 turns off inactive checking.
-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''. A value of ``""'' turns off expiration checking.
-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. If passgen is neither a NULL string nor a printable ASCII character, a diagnostic message is printed.
-a [operator] event: Set the user's audit mask based on the event(s) specified. An operator can be specified (as + to add or - to delete) or not specified (to replace). 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 printable characters that specifies the existing login name of a user. It must exist and may not contain a colon (:), or a newline (\n).

If login is preceded by a ``+'' or ``-'' character, the changes will be applied to the login administered by the Network Information Service, not a local user. In this case, the -u, -g, and -G options, if specified are silently ignored. Instead, values for the user ID and group ID are taken from the NIS database.

Files

/etc/group
/etc/passwd
/etc/security/ia/audit (if the Auditing Utilities are installed)
/etc/security/ia/index
/etc/security/ia/master
/etc/shadow

Diagnostics

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

The command syntax was invalid.
An invalid argument was provided to an option.
The uid given with the -u option is already in use.
The login to be modified does not exist or group does not exist.
The login to be modified is in use.
The new_logname is already in use.
Cannot update the /etc/group file. Other update requests will be implemented.
Insufficient space to move the home directory (-m option). Other update requests will be implemented.
Unable to complete the move of the home directory to the new home directory.
Invalid options -h, -v system service not installed.
Invalid option -a, system service not installed.
Invalid audit event type or class specified.

References

crontab(1), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), passwd(1), useradd(1M), userdel(1M), userls(1M), users(1bsd)