NAME
usermod — modify a user login on the system
SYNOPSIS
usermod
[-u
uid
[-o]]
[-g
group]
[-G
group
[,
group]...]
[-d
dir
[-m
[-i]]]
[-s
shell]
[-c
comment]
[-f
inactive]
[-l
new_logname]
[-e
expire]
[-p
encrypted_password]
[-F]
[-P
-S
alternate_password_file]
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 the 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
Specify the
UID
for the user.
uid
must be a non-negative decimal
integer less than
MAXUID
as it is defined in the
<param.h>
header file.
- -o
Allow the
UID
to be non-unique (that is, a duplicate).
- -g group
Specify the integer group
ID
or character string name of an existing group.
This redefines the primary group membership of the login.
- -G group
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
-g
and
-G
options are ignored.
- -d dir
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.
- -m
Move the user's home directory to the directory specified with the
-d
option.
The operation cannot be performed if the user's home
directory is the root directory or if the user's home directory
is specified in the
/etc/default/usermod
configuration file.
See
usermod(4).
If the home directory exists, the directory must have
read and execute permission by
group,
where
group
is the primary group of the login.
This condition can be overridden using the
-i
option.
- -i
Inherit an existing home directory, regardless of its current access
permissions. Typically use this option to inherit orphaned directories,
that is,
directories that are not owned by any active user of the system.
Note that using the
-i
option will impact shared home directories; hence use
the
-i
option with caution.
The permissions will be same as that of newly created home directory.
- -s shell
Specify the full pathname of the login shell.
The value of
shell
must be a valid executable file.
- -c comment
Specify the comment field present in the
/etc/passwd
entry of this login.
This can be any text string.
A short description of the login is suggested for this field.
- -f inactive
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).
- -l new_logname
Specify 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).
- -e expire
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 following:
A value of
''
(two single quotes) or
""
(two double quotes)
results in no expiration date.
- -p encrypted_password
Specify the encrypted password for the user.
Before using the
-p
option, obtain the encrypted password by using
crypt()
(see
crypt(3C)).
- -F
Force the changes, even if the login is currently in use.
- -P
Indicate that modifications are to be made to the alternate
password file of NIS specified by the
-S
option.
The following options edit the password file and should not be used with the
-P
option:
-m,
-i,
-r,
-k,
-F.
- -S alternate_password_file
Specify the path of the alternate password file of NIS.
The
-P
option is used with the
-S
option.
The
-e
and
-f
options are supported only if
Shadow Passwords
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
/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.
NIS users are checked when verifying 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
Cannot modify /etc/group file, /etc/passwd was modified
(return value 10) is returned if an NIS group is specified with
either the
-g
option or the
-G
option
(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.
- 18
Out of memory.
- 19
Invalid template 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
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
(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.
Otherwise,
usermod
will report an error.
Because many users may try to write the
/etc/passwd
file simultaneously, a password locking mechanism was devised.
If this password 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.
See
limits(5)
for the value of
LINE_MAX.
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
SEE ALSO
passwd(1),
users(1),
groupadd(1M),
groupdel(1M),
groupmod(1M),
logins(1M),
pwconv(1M),
useradd(1M),
userdel(1M),
group(4),
shadow(4),
limits(5),
usermod(4).
STANDARDS CONFORMANCE
usermod: SVID3
Printable version
