usermod(1M)usermod(1M)NAMEusermod - modify a user login on the system
SYNOPSIS
uid group] groupgroup]...] dir shell] comment] inactive] new_logname]
expire] encrypted_password] alternate_password_file] login
DESCRIPTION
The command modifies a user login on the system by changing the appro‐
priate login related files.
The command requires the login argument. login is the login name,
specified as a string of printable characters. It may not contain a
colon or a newline
Refer to usergroupname(5) to understand the functionality changes with
the Numeric User Group Name feature.
New Behavior
If the primary group of a user is modified, then the user name is not
added to the primary group entry in file. However, if option is speci‐
fied the user is added to the corresponding supplemental group.
Options
The command supports the following options:
Specify the UID for the user. uid must be a non-negative
decimal integer less than as it is defined in
the header file.
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 redefines the primary group mem‐
bership of the login.
Specify the integer group
ID or character string name of an existing
group. This redefines the supplemental group
memberships of the login. Duplicates within
group with the and options are ignored.
Specify the new home directory of the login.
It defaults to base_dir/login, where login is
the login and base_dir is the base directory
for new login home directories.
Move the user's home directory to the directory specified with
the
option. The operation cannot be performed if
the user's home directory is the root direc‐
tory or if the user's home directory is speci‐
fied in the configuration file. See user‐
mod(4). If the home directory exists, the
directory must have read and execute permis‐
sion by group, where group is the primary
group of the login. This condition can be
overridden using the option.
Inherit an existing home directory, regardless of its current
access
permissions. Typically use this option to
inherit orphaned directories, that is, direc‐
tories 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 caution. The permissions will
be same as that of newly created home direc‐
tory.
Specify the full pathname of the login shell.
The value of shell must be a valid executable
file.
Specify the comment field present in the
entry of this login. This can be any text
string. A short description of the login is
suggested for this field.
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 new login name for the user.
It consists of a string of printable charac‐
ters that does not contain a colon or a new‐
line
Specify the date on which this login can no longer be used.
After the expire date occurs, no user will be
able to access this login. This option is
used to create temporary logins. expire,
which is a date, may be typed in any desired
format, except a Julian date. For example, a
date may be entered as either of the follow‐
ing:
A value of (two single quotes) or (two double
quotes) results in no expiration date.
Specify the encrypted password for the user.
Before using the option, obtain the encrypted
password by using or (see crypt(3C) or
crypt2(3C)).
Force the changes, even if the login is currently in use.
Indicate that modifications are to be 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.
The and options are supported only if are in use. For details refer to
pwconv(1M).
In the event where a directory is shared by users of the same group and
the owner of that directory is modified, then the ownership of that
directory is propagated to the next user who is sharing that directory.
The new owner is determined by looking at the order in which the users
sharing this directory are added to the file. If there is only one
user remaining then the directory is brought back to unshared mode by
resetting the permissions to from
If a directory is shared by users, then one cannot change the primary
group of any of these users unless the home directory of that user is
also changed.
NIS
The command is aware of NIS user and group entries. Only local users
and groups may be modified with this 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 veri‐
fying the uniqueness of the new UID or new user name, which may result
in the following error messages:
(return value 6) if the user specified is an NIS user (see passwd(4)).
Also, 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 option if either the source or the target
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 login to be modified or the group specified with the option
does not exist.
The login to be modified is in use.
new_logname
is not unique.
Cannot modify the
file. The other parts of the update request will be per‐
formed.
There is insufficient space to move the home directory (with the
option). The other parts of the update request will be
performed.
Unable to complete the move of the home directory to the
new home directory.
Unable to open
file, or file is non-existent.
file or
file busy. Another command may be modifying the file.
Cannot modify the entry in the
file.
Out of memory.
Invalid template file.
Exceeding permissible limit of maximum members in a group.
The file is not modified.
EXAMPLES
Change primary group to
Change user ID to and change the login name to
WARNINGS
A directory can be shared between the users belonging to the same
group. If the home directory is in unshared mode and a new user is
allocated to that directory, then it will be put into 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 and permissions for the group. Otherwise, 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.
While modifying the user login, the username is not added to the pri‐
mary group entry in the file. If a supplemental group is specified,
the user is added to the supplemental group. If the size of a group
entry in file exceeds limit, a new entry of the same group is created
and a warning message is issued. See limits(5) for the value of
FILES
Shadow password file
System password file
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), useradd(1M), userdel(1M), crypt(3C),
crypt2(3C), group(4), shadow(4), usermod(4), limits(5), usergroup‐
name(5).
STANDARDS CONFORMANCEusermod(1M)
