NAME
usermod — modify a user login on the system
SYNOPSIS
usermod
[-u
uid
[-o]
]
[-g
group]
[-G
group
[,
group...]]
[-d
dir
[-m]
]
[-s
shell]
[-c
comment]
[-f
inactive]
[-l
new_logname]
[-e
expire]
login
DESCRIPTION
The
usermod
command modifies a user login on the
system by changing the appropriate login related files.
The
usermod
command requires the
login
argument.
login
is a new login name, specified as a string of printable characters.
It may not contain a colon
(:)
or a newline
(\n).
New Behavior
If the primary group of a user is modified,
then the user name is not added to the primary group entry in
/etc/group
file. However, if
-G
option is specified the user is added to the corresponding
supplemental group.
Options
The
usermod
command supports the following options:
- -u uid
Specifies the
UID
for the new user.
uid
must be a non-negative decimal
integer less than
MAXUID
as it is defined in the
<param.h>
header file.
- -o
Allows the
UID
to be non-unique (i.e., a duplicate).
- -g group
Specifies the integer group
ID
or character string name of an existing group.
This redefines the primary group membership of the new login.
- -G group
Specifies the integer group
ID
or character string name of an existing group.
This redefines the supplemental group memberships of the new login.
Duplicates within
group
with the
-g
and
-G
options are ignored.
- -d dir
Specifies the new home directory of the 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.
- -m
Move the user's home directory to the directory specified with the
-d
option.
If the home directory exists, the directory must have
read and execute permission by
group,
where
group
is the primary group of the login.
When the Restricted Movement of Home Directories
feature is installed, this operation cannot be
performed if the user's home directory is the root directory
or is specified in the
/etc/default/usermod
configuration file.
Refer to
usermod(4)
for the format of the
/etc/default/usermod
configuration file.
- -s shell
Specifies the full path name of the login shell.
The value of
shell
must be a valid executable file.
- -c comment
Specifies the comment field present in the
/etc/passwd
entry of this login.
This can be any text string.
A short description of the new login is suggested for this field.
- -f inactive
Specifies the maximum number of days of continuous
inactivity of the login before the login is
declared invalid.
Normal values are positive integers, while a value of -1
defeats this status.
This option is supported on trusted
system and also on shadow password systems if the
TrustedMigration product is installed.
- -l new_logname
Specifies the new login name for the user.
It consists of a string of printable characters that does not
contain a colon
(:)
or a newline
(\n).
If the TrustedMigration product is installed,
the login name is updated in the user database.
- -e expire
Specifies the date on which this login can no longer be used.
After
expire,
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 following:
A value of
''''
defeats the expired date status.
Unless enhanced security is installed,
the
-e
and
-f
options are not supported and will return an error.
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
775
(i.e., 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.
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
/etc/passwd
file. If there is only one user remaining then the
directory is brought back to unshared mode by resetting the
permissions to
755
from
775.
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
usermod
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.
This command may fail with the error
(return value 6) if the user specified is an
NIS
user (see
passwd(4)).
However,
NIS
users are checked when verifying uniqueness of
the new
UID
or the new user name.
Also, the error
Cannot modify /etc/group file, /etc/passwd was modified
(return value 10) may be returned
if a group specified with either the
-g
option or the
-G
option is an
NIS
group (see
group(4)).
NFS
Errors may occur with the
-m
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
usermod
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
login
to be modified or the
group
specified with the
-g
option does not exist.
- 8
The
login
to be modified is in use.
- 9
new_logname
is not unique.
- 10
Cannot modify the
/etc/group
file.
The other parts of the update request will be performed.
- 11
There is insufficient space to move the home directory (with the
-m
option).
The other parts of the update request will be performed.
- 12
Unable to complete the move of the home directory to the
new home directory.
- 13
Unable to open
/etc/ptmp
file, or
/etc/passwd
file is non-existent.
- 14
/etc/passwd
file or
/etc/ptmp
file busy. Another command may be modifying the
/etc/passwd
file.
- 15
Cannot modify the entry in the
/etc/passwd
file.
- 54
Exceeding permissible limit of maximum members in a group.
The
/etc/group
file is not modified.
EXAMPLES
Change
otto's
primary group to
staff.
Change
otto's
user
ID
to
333
and change the login name to
bob.
usermod -u 333 -l bob otto
WARNINGS
As many users may try to write the
/etc/passwd
file simultaneously, a passwd locking mechanism was devised.
If this locking fails after subsequent retrying,
usermod
terminates.
While modifying the user login, the username is not added to the primary
group entry in the
/etc/group
file. If a supplemental group is specified, the user is added to the
supplemental group. If the size of a group entry in
/etc/group
file exceeds
LINE_MAX
limit, a new entry of the
same group is created and a warning message is issued.
FILES
- /etc/shadow
Shadow Password file
- /etc/passwd
System Password file
- /etc/group
System group file
- /etc/ptmp
Lock file used when updating password file
- /var/adm/userdb
user database
SEE ALSO
passwd(1),
users(1),
groupadd(1M),
groupdel(1M),
groupmod(1M),
logins(1M),
pwconv(1M),
useradd(1M),
userdel(1M),
group(4),
shadow(4),
usermod(4).
STANDARDS CONFORMANCE
usermod: SVID3
