Linux usermod Command

Modify User Account Properties and Settings

Command Overview

usermod modifies existing user account properties on a Linux system. It can change user attributes such as home directory, shell, group memberships, account expiration, password settings, and user ID. This command requires root privileges and is essential for managing user accounts after they've been created.

Common Modification Tasks

Task	Option	Example
Change login name	-l	usermod -l newname oldname
Change home directory	-d	usermod -d /new/home username
Change default shell	-s	usermod -s /bin/bash username
Add to groups	-aG	usermod -aG group1,group2 username
Lock account	-L	usermod -L username
Unlock account	-U	usermod -U username
Set expiration date	-e	usermod -e 2025-12-31 username

Important: Always be careful when modifying user accounts, especially system accounts. Changes to UID, GID, or home directory can affect file ownership and permissions system-wide.

Example 1: Add User to Additional Groups

sudo usermod -aG sudo,docker jsmith

# No output on success # Verify the change: $ groups jsmith jsmith : jsmith sudo docker

Explanation:

Adds user jsmith to the sudo and docker groups without removing existing group memberships.

-a flag: Append mode - adds to groups without removing current ones
-G flag: Specifies supplementary groups
CRITICAL: Always use -a with -G to avoid removing user from other groups
Multiple groups: Comma-separated list (no spaces)
Use case: Grant sudo access or add to service groups like docker, www-data

Warning: Using -G without -a will remove the user from all groups not listed in the command! Always use -aG together.

Example 2: Change User's Default Shell

sudo usermod -s /bin/zsh jsmith

# Verify the change: $ grep jsmith /etc/passwd jsmith:x:1001:1001:John Smith:/home/jsmith:/bin/zsh

Explanation:

Changes jsmith's default login shell to zsh.

-s option: Sets the user's login shell
Shell path: Must be a valid shell listed in /etc/shells
Takes effect: On next login (doesn't affect current sessions)
Common shells: /bin/bash, /bin/zsh, /bin/fish, /bin/dash
Use case: User preferences, security restrictions

Tip: View available shells with cat /etc/shells. Setting shell to /sbin/nologin or /bin/false prevents interactive login while allowing services to run.

Example 3: Change Home Directory and Move Contents

sudo usermod -d /new/home/jsmith -m jsmith

# Files are moved automatically with -m option # Verify: $ grep jsmith /etc/passwd | cut -d: -f6 /new/home/jsmith

Explanation:

Changes home directory and moves all contents to the new location.

-d option: Specifies new home directory path
-m option: Moves contents from old to new directory
Without -m: Directory changes but files don't move
Permissions: Ownership and permissions are preserved
Use case: Reorganizing filesystem, moving to larger partition

Note: The user should not be logged in when moving their home directory. Active processes may cause issues or incomplete moves.

Example 4: Lock a User Account

sudo usermod -L jsmith

# Check locked status: $ sudo passwd -S jsmith jsmith L 11/11/2025 0 99999 7 -1 # Or check /etc/shadow (password starts with !) $ sudo grep jsmith /etc/shadow jsmith:!$6$randomsalt...

Explanation:

Locks the user account by disabling password authentication.

-L option: Locks the account (Lock)
How it works: Adds ! prefix to encrypted password in /etc/shadow
SSH keys: User can still login with SSH keys if configured
Status check: passwd -S username shows 'L' for locked
Use case: Temporarily disable account, suspended users, security incidents

Security Note: Locking an account doesn't kill active sessions or prevent SSH key authentication. For complete lockout, also expire the account and consider killing active sessions.

Example 5: Unlock a User Account

sudo usermod -U jsmith

# Verify: $ sudo passwd -S jsmith jsmith P 11/11/2025 0 99999 7 -1 # 'P' indicates password is set (unlocked)

Explanation:

Unlocks a previously locked user account.

-U option: Unlocks the account (Unlock)
How it works: Removes ! prefix from password in /etc/shadow
Prerequisite: Account must have had a password before being locked
Status 'P': Indicates account has a valid password
Use case: Restore access after temporary suspension

Example 6: Set Account Expiration Date

sudo usermod -e 2025-12-31 contractor1

# Verify expiration: $ sudo chage -l contractor1 | grep "Account expires" Account expires : Dec 31, 2025

Explanation:

Sets an expiration date for a user account (useful for temporary access).

-e option: Sets account expiration date (format: YYYY-MM-DD)
After expiration: Account cannot login even with correct password
Empty value: usermod -e "" username removes expiration
Check status: Use chage -l username
Use case: Contractors, temporary employees, student accounts

Tip: Combine with password expiration settings using chage for comprehensive account lifecycle management.

Example 7: Change User's Login Name

sudo usermod -l jdoe jsmith

# Verify: $ id jdoe uid=1001(jdoe) gid=1001(jsmith) groups=1001(jsmith),27(sudo) # Note: Primary group name doesn't change automatically $ sudo groupmod -n jdoe jsmith

Explanation:

Changes the username from jsmith to jdoe.

-l option: Changes login name (new name first, old name second)
Home directory: Path doesn't change automatically (use -d -m if needed)
Primary group: Group name remains the same, rename separately if desired
Processes: User must be logged out (no active processes)
Mail/cron: May need manual updates for username references

Important: Username change doesn't automatically update home directory path, group name, or file ownership. These require separate commands.

Example 8: Change User ID (UID)

sudo usermod -u 2001 jsmith

# Verify: $ id jsmith uid=2001(jsmith) gid=1001(jsmith) groups=1001(jsmith) # Update file ownership: $ sudo find / -user 1001 -exec chown -h 2001 {} \; 2>/dev/null

Explanation:

Changes the user's UID from 1001 to 2001.

-u option: Sets new UID
File ownership: Doesn't automatically update - must use find/chown
Active sessions: User should be logged out
UID conflicts: New UID must not be in use by another user
Use case: Resolving UID conflicts, standardizing UIDs across systems

Critical: After changing UID, all files owned by the old UID will show as numeric ID instead of username. You must update file ownership with find and chown commands.

Example 9: Change Primary Group

sudo usermod -g developers jsmith

# Verify: $ id jsmith uid=1001(jsmith) gid=1050(developers) groups=1050(developers),27(sudo),999(docker)

Explanation:

Changes jsmith's primary group to developers.

-g option: Changes primary group (lowercase g)
Primary vs supplementary: Every user has one primary group, can have many supplementary
New files: Will be owned by new primary group by default
Existing files: Ownership doesn't change automatically
Use case: Project assignments, department changes

Note: The difference between -g (primary group) and -G (supplementary groups) is crucial. Primary group affects default ownership of new files.

Example 10: Comprehensive User Account Modification

sudo usermod -c "John Smith - Engineering Team" \ -d /home/engineering/jsmith \ -m \ -s /bin/bash \ -aG docker,sudo,engineering \ -e 2026-12-31 \ jsmith

# Verify all changes: $ grep jsmith /etc/passwd jsmith:x:1001:1001:John Smith - Engineering Team:/home/engineering/jsmith:/bin/bash $ groups jsmith jsmith : jsmith docker sudo engineering $ sudo chage -l jsmith | grep expires Account expires : Dec 31, 2026

Explanation:

Makes multiple modifications to a user account in a single command.

-c option: Updates comment field (GECOS - usually full name)
-d and -m: Moves home directory to new location
-s: Sets shell to bash
-aG: Adds to multiple supplementary groups
-e: Sets account expiration
Efficiency: Single command vs multiple separate commands

Best Practice: When making multiple changes, combine them in one usermod command to reduce system calls and maintain consistency.

Additional Information

Common usermod Options

-l LOGIN - Change login name
-u UID - Change user ID
-g GROUP - Change primary group
-G GROUPS - Set supplementary groups (use with -a to append)
-a - Append to groups (always use with -G)
-d HOME_DIR - Change home directory
-m - Move home directory contents (use with -d)
-s SHELL - Change login shell
-c COMMENT - Change GECOS/comment field
-e EXPIRE_DATE - Set account expiration (YYYY-MM-DD)
-f INACTIVE - Set password inactive days after expiration
-L - Lock account
-U - Unlock account
-p PASSWORD - Set encrypted password (not recommended - use passwd instead)

Related Commands

useradd - Create new user accounts
userdel - Delete user accounts
passwd - Change user passwords
chage - Change password aging information
groups - Display group memberships
id - Display user and group IDs
groupmod - Modify group definitions
chown - Change file ownership
chsh - Change login shell (user-accessible)
chfn - Change finger information (GECOS field)

Important Files Modified

/etc/passwd - User account information /etc/shadow - Encrypted passwords and account expiration /etc/group - Group membership information /etc/gshadow - Secure group information /home/* - User home directories (with -d -m)

Best Practices

Always verify user is not logged in before making critical changes (UID, username, home directory)
Use -aG together to add groups without removing existing ones
Test changes in development environment for critical accounts
Document all usermod changes for audit trail
After UID changes, update file ownership system-wide
Use account expiration for temporary access instead of manual deletion
Lock accounts rather than delete when preserving data is important
Backup /etc/passwd and /etc/group before mass modifications

Common Use Cases

Onboarding: Add new employees to appropriate groups
Role changes: Update groups and home directories for promotions/transfers
Contractors: Set expiration dates for temporary access
Security incidents: Lock accounts pending investigation
System migration: Standardize UIDs across multiple systems
Service accounts: Set shell to /sbin/nologin to prevent interactive login
Offboarding: Lock or expire accounts for departed employees

Troubleshooting

# Check if user is logged in $ who | grep username $ ps -u username # View current user settings $ id username $ finger username $ sudo chage -l username # Check group memberships $ groups username $ getent group groupname # Verify password status $ sudo passwd -S username # Check for locked files (user logged in) $ sudo lsof -u username

Security Considerations

UID 0 restricted: Never assign UID 0 to regular users (root privilege)
Shell restrictions: Use /sbin/nologin for service accounts
Group permissions: Review implications before adding users to privileged groups (sudo, wheel, docker)
Home directory: Ensure proper permissions (typically 750 or 700)
Account locks: Remember SSH keys bypass password locks
Audit trail: Log all usermod commands for security compliance
System accounts: Be extra careful with UIDs < 1000 (system accounts)

Example: Safe Account Suspension

# Complete account lockdown sudo usermod -L -e 1 -s /sbin/nologin username # Kill active sessions sudo pkill -u username # Verify lock sudo passwd -S username # Should show 'L' (locked)

Example: Update All Files After UID Change

# Change UID sudo usermod -u 2001 username # Update all files owned by old UID (1001) sudo find / -user 1001 -exec chown -h 2001 {} \; 2>/dev/null # Or more efficient with -uid: sudo find / -uid 1001 -exec chown -h 2001 {} \; 2>/dev/null # For specific partitions only: sudo find /home /var -uid 1001 -exec chown -h 2001 {} \;

Example: Contractor Account Setup

# Create with 90-day expiration sudo usermod -e $(date -d "+90 days" +%Y-%m-%d) contractor1 \ -c "Contractor - Project Alpha - Ends $(date -d '+90 days' +%Y-%m-%d)" \ -aG projectalpha # Set password to expire in 5 days (force change) sudo chage -M 5 contractor1

Critical Safety Tip: Always backup user account files before mass modifications:

sudo cp /etc/passwd /etc/passwd.backup.$(date +%Y%m%d) sudo cp /etc/shadow /etc/shadow.backup.$(date +%Y%m%d) sudo cp /etc/group /etc/group.backup.$(date +%Y%m%d)

Pro Tip: Create a script to standardize common usermod operations:

#!/bin/bash # add_to_dev_team.sh USER=$1 sudo usermod -aG developers,docker,git $USER sudo usermod -c "$(getent passwd $USER | cut -d: -f5) - Development Team" $USER echo "Added $USER to development team groups"