Usermod Command in Linux – Options + Examples

User accounts have attributes such as group, user information, home directory, login shell, UID, expiry date. For an existing user in Linux, if you wish to change those attributes, you need usermod command.

In this tutorial, we learn how to use usermod command in Linux.

Prerequisites

• Any Linux system
• A user with sudo access or root account
• Basic knowledge of Linux command line
• An existing user account

What is the usermod command?

The Linux usermod command is a command-line tool that is used to modify the properties of a user in a Linux system. It can modify user account attributes such as group, user information, home directory, login shell, UID, expiry date.

In Linux systems, information about user accounts is typically recorded in the /etc/passwd, /etc/group, /etc/login.defs, /etc/gshadow and /etc/shadow configuration files. Once you execute the usermod command, the command modifies the user account information in the specified files.

Basic Syntax

usermod command takes the following syntax:

usermod [ options ] USER

The usermod command is a privileged command, only the root user or sudo users can successfully run execute the command.

Usermod options

Here are some of the commonly used usermod command options:

Options	Description
-a	Adds a user to a secondary group. Typically used with the -G option.
-d	Modifies the user’s new home directory
-e	Sets expiry date and specifies the date which the user account will be disabled. The expiry date is set in the YYYY-MM-DD format.
-g	Sets the GID group ID of the user
-G	Specifies the new GROUP that the user will be added.
-l	Changes the login name of the user
-L	Locks the user’s password
-m	Transfers the content of user’s home directory to a new directory
-m	Specifies user’s new login shell.
-u	Sets the new numerical value of the user’s UID
-U	It unlocks a user’s password

Usermod command Examples

Now let us check how to use usermod command with a few practical examples.

Add a user to a group

Perhaps the most widely used function of the usermod command is adding a user to a group. When a user account is created, the user by default is added to the primary group. The primary group will have the same name as the user. Any other group is called the secondary group. A user can belong to only one primary group and one or more secondary groups.

To add an existing user to a secondary group use the -a ( append ) and -G ( group ) options.

Syntax:

usermod -a -G GROUP USER

To add a user to multiple groups, simply list the groups after the -G option separated by a comma with no whitespaces in between.

Syntax:

usermod -a -G GROUP1, GROUP2  USER

The following command add the user named jack to the secondary group named developers:

usermod -a -G developers jack 

Note: To create a group you can use groupadd command.

You can verify by checking the following command:

groups jack

The primary group is listed first after the username and the secondary group name comes next.

You may also use the same command to add a user to sudo group, just replace group name with sudo:

usermod -aG sudo jack

You can see from the output, the user jack now belongs to two secondary groups: the developers group and the sudo group.

To add ‘jack’ to multiple groups e.g developers and testers( these already exist in our Linux system ) , run the command:

usermod  -aG developers,testers  jack

Change Primary group of the user

Rarely we may need to change the primary group of the user. To change the primary group of a user, use the -g option followed by the group name and the user.

Syntax:

usermod -g GROUP USER

For example to change the primary group of the user named jack to administrators, type:

usermod -g administrators jack

Change user default shell

The login shell is the shell that a user drops into once they log in to the Linux system. Typically, the default shell is set to bash.

To check which shell you are using, run the command:

echo $SHELL

The output /bin/sh confirms that we are using the bash shell.

To change a user default login shell, use the -s option followed by the full path of the shell and username.

Syntax:

usermod -s SHELL USER

For example, to change the shell to zsh for the user jack, type:

usermod -s /usr/bin/zsh jack

Change user name

Although not a common operation, you may need to rename an existing user account to your preferred name. For this, we can change the user login name. The home directory still remains the same with the name of the old username.

To change the user login name, use the -l option.

Syntax:

usermod -l NEW_USERNAME EXISTING_USER

For example, to rename the user account named called jack to mike, type:

usermod -l mike  jack 

You can verify by checking /etc/passwd file and filtering the user using the grep command. However, the home directory name still remains the same.

The discrepancy between the login name and the login home directory has the tendency to cause confusion. For this reason, it is recommended to change the home directory of the user which we shall look at shortly.

Change user home directory

To change a user's home directory, use the -d option followed by the full path of the user home directory and username.

Syntax:

usermod -d HOME_DIR USER

To change the home directory for the user named mike to /home/mikedata, type:

usermod -d /home/mikedata mike

By default, the command doesn't transfer the contents of the previous home folder to your new home directory. To migrate the contents of the user home directory, use the -m option followed by the user account name.

Syntax:

usermod -d HOME_DIR -m USER

Change User UID

When a new user is created, the Linux system assigns them a unique user identifier known as the UID (Unique Identifier). The UID is what the system uses to reference users on a Linux system. To change the user's numerical UID, invoke the -u option followed by the UID and the name of the user.

Syntax:

usermod -u UID USER

For example to change a UID of the user name mike from 1003 to 1010 , type:

usermod -u 1010 mike

For the files owned by the user and located in the user's home directory, the UID will apply. The same holds true for the user’s mailbox file. However, ownership of the user files has to be manually changed.

Change User information

The usermod command also allows you to change the value of the user's comment field (/etc/passwd file) using the -c option.

For example to change the comment filed value to Test user for the user mike, type:

usermod -c "Test user" mike

You can verify by checking the /etc/passwd file by using the following command:

cat /etc/passwd | grep -i mike

Lock and unlock a user account

You can use usermod or chage command to lock or unlock user accounts in Linux.

Using usermod, to lock user account use the -L option. In the following command, we are locking the account belonging to user mike:

usermod -L mike

When a user account is locked,  the encrypted user password in the /etc/shadow file is preceded by an exclamation mark. This renders the user's password inactive, effectively disabling the user's ability to log in using password authentication. However, the user can still access the system, using other authentication methods such as SSH key-pair authentication.

To effectively lock out the user, you also need to disable all the authentication methods and configure the account expiry date to 1.

usermod -L -e 1 mike

To unlock a locked user account, use the -U option. This removes the exclamation mark from the user's encrypted password. Therefore, to unlock user account named mike, type:

usermod -U mike

Once the user account is unlocked, the user can log in using the same password.

Set user expiry date

A user's expiry date refers to the day that the account will be disabled. As the password expires, effectively user won't be able to log in.

Syntax:

usermod -e DATE USER

The expiry date is specified using the YYYY-MM-DD format.

Setting an expiry date effectively disables the user from logging in once the expiry date is reached. The following example disables a user called mike on 2022-04-10:

usermod -e "2022-04-10" mike

Users' expiration date is stored in the /etc/shadow file.

To undo this, set an empty expiry date with double quotation marks with nothing in between.

usermod -e " " mike

To get a better view of the user's expiry date, use the following chage -l command:

chage -l mike

Conclusion

In this tutorial, we learned how to use usermod command to modify user account settings. We can perform a wide range of user account management tasks using this command.