LinuxCommandLibrary

usermod

Modify user account properties

TLDR

Change a username

$ sudo usermod [[-l|--login]] [new_username] [username]
copy

Change a user ID
$ sudo usermod [[-u|--uid]] [id] [username]
copy

Change a user shell
$ sudo usermod [[-s|--shell]] [path/to/shell] [username]
copy

Add a user to supplementary groups (mind the lack of whitespace)
$ sudo usermod [[-aG|--append --groups]] [group1,group2,...] [username]
copy

Change a user home directory
$ sudo usermod [[-m|--move-home]] [[-d|--home]] [path/to/new_home] [username]
copy

Lock an account
$ sudo usermod [[-L|--lock]] [username]
copy

Unlock an account
$ sudo usermod [[-U|--unlock]] [username]
copy

SYNOPSIS

usermod [options] LOGIN

PARAMETERS

-c, --comment COMMENT
    Change the GECOS field (user information).

-d, --home HOME_DIR
    Change the user's home directory. Use with -m to move contents.

-e, --expiredate EXPIRE_DATE
    Set account expiration date (YYYY-MM-DD).

-f, --inactive INACTIVE_DAYS
    Set account inactive after password expiration.

-g, --gid GROUP
    Change the user's primary group ID.

-G, --groups GROUP1[,GROUP2,...]
    Change the user's supplementary group list.

-a, --append
    Append the user to the supplementary group(s) without removing them from the current group list.

-l, --login NEW_LOGIN
    Change the user's login name.

-L, --lock
    Lock the user's account.

-m, --move-home
    Move the content of the current home directory to the new location when used with -d.

-o, --non-unique
    Allow using a non-unique UID.

-p, --password PASSWORD
    Encrypt and set the new password. Note: Use of shadow passwords recommended.

-n, --namestyle STYLE
    Specifies the method used to convert between user and group names and UIDs and GIDs. Available styles are: uid, gid, user, group, name, id, auto.

-r, --remove
    Remove the user's files from the home directory.

-s, --shell SHELL
    Change the user's login shell.

-u, --uid UID
    Change the user's UID.

-U, --unlock
    Unlock the user's account.

-v, --add-subuids COUNT
    Reserve subuids (only for root user, COUNT is the number of subuids).

-w, --add-subgids COUNT
    Reserve subgids (only for root user, COUNT is the number of subgids).

-A, --del-subuids FIRST_ID
    Delete subuids (only for root user, FIRST_ID is the first subuid).

-B, --del-subgids FIRST_ID
    Delete subgids (only for root user, FIRST_ID is the first subgid).

--help
    Display help text and exit.

--version
    Display version information and exit.

DESCRIPTION

The `usermod` command in Linux is used to modify an existing user account. It allows administrators to change various user attributes such as the username, user ID (UID), group memberships, home directory, login shell, and comment field (GECOS).

The command provides a powerful way to manage user accounts and ensure they adhere to security policies and organizational requirements. Proper use of `usermod` requires careful consideration as incorrect modifications can lead to account lockout or system instability. The command requires root privileges to execute successfully, either directly or through sudo.

CAVEATS

Modifying a user's primary group can affect file permissions. Ensure that all processes belonging to the user are stopped before making changes to avoid unexpected behavior. Always back up critical data before making any modifications to user accounts.

EXIT STATUS

The `usermod` command returns 0 if successful, and a non-zero value if an error occurs. Common error conditions include invalid options, insufficient privileges, or attempting to modify a user that doesn't exist.

Check the exit code to ensure the command executed successfully. Some distributions use extended error code. See man page for details.

HISTORY

The `usermod` command has been a standard utility in Unix-like operating systems for many years. Its purpose has remained consistent: to provide a means for administrators to modify user account attributes. Over time, its features have expanded to include options for managing group memberships, home directories, password aging policies, and other security-related settings. The command is a core component of user account management in Linux.

SEE ALSO

useradd(8), userdel(8), groupadd(8), groupmod(8), groupdel(8), passwd(1), chown(1)

Copied to clipboard