Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > U


HP-UX 11i Version 3: February 2007

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index


usermod — modify a user login on the system


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


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.


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.


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.


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.


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:

July 13, 1993 7/13/93

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)).


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 -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.


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:

login x does not exist

(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)).


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.


usermod exits with one of the following values:


Successful completion.


Invalid command syntax.


Invalid argument supplied to an option.


uid is not unique (when -o is not used).


The login to be modified or the group specified with the -g option does not exist.


The login to be modified is in use.


new_logname is not unique.


Cannot modify the /etc/group file. The other parts of the update request will be performed.


There is insufficient space to move the home directory (with the -m 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 /etc/ptmp file, or /etc/passwd file is non-existent.


/etc/passwd file or /etc/ptmp file busy. Another command may be modifying the /etc/passwd file.


Cannot modify the entry in the /etc/passwd file.


Out of memory.


Invalid template file.


Exceeding permissible limit of maximum members in a group. The /etc/group file is not modified.


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


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.



Shadow password file


System password file


System group file


Lock file used when updating password file


usermod: SVID3

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.