NAME [Toc] [Back]
usermod - modify a user login on the system
SYNOPSIS [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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
Options [Toc] [Back]
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>
-o Allows the UID to be non-unique (i.e., a
-g group Specifies the integer group ID or character
string name of an existing group. This
redefines the primary group membership of the
-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
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
-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
-s shell Specifies the full pathname of the login
shell. The value of shell must be a valid
-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.
-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).
-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
July 13, 1993
A value of '''' defeats the expired date
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.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
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
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
Networking Features [Toc] [Back]
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
login x does not exist
(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 [Toc] [Back]
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 [Toc] [Back]
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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
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
12 Unable to complete the move of the home directory to the new
13 Unable to open /etc/ptmp file, or /etc/passwd file is nonexistent.
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.
EXAMPLES [Toc] [Back]
Change otto's primary group to staff.
usermod -g staff otto
Change otto's user ID to 333 and change the login name to bob.
usermod -u 333 -l bob otto
WARNINGS [Toc] [Back]
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 [Toc] [Back]
/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 [Toc] [Back]
passwd(1), users(1), groupadd(1M), groupdel(1M), groupmod(1M),
logins(1M), useradd(1M), userdel(1M), pwconv(1M), group(4), shadow(4).
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
STANDARDS CONFORMANCE [Toc] [Back]
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003 [ Back ]