useradd Command

Add user accounts to the Linux system

Syntax: useradd [OPTIONS] username

Note: The useradd command requires root privileges to execute. Always use sudo or run as root when adding users to the system.

Description

The useradd command is used to add user accounts to a Linux system. It creates a new user account using the values specified on the command line plus the default values from the system. The new user account will be entered into the system files as needed, the home directory will be created, and initial files copied, depending on the command line options.

Note: useradd is a low-level utility. On Debian-based systems, administrators usually prefer the more user-friendly adduser command, which provides an interactive interface and better defaults.

Common Options

Option	Description
`-c, --comment COMMENT`	Set the user's full name or comment field
`-d, --home-dir HOME_DIR`	Set the user's home directory
`-e, --expiredate EXPIRE_DATE`	Set account expiration date (YYYY-MM-DD)
`-f, --inactive INACTIVE`	Set password inactive days after expiration
`-g, --gid GROUP`	Set the primary group (name or GID)
`-G, --groups GROUPS`	Set supplementary groups (comma-separated)
`-m, --create-home`	Create the user's home directory
`-M, --no-create-home`	Do not create the user's home directory
`-s, --shell SHELL`	Set the user's login shell
`-u, --uid UID`	Set the user ID (UID)
`-r, --system`	Create a system account
`-k, --skel SKEL_DIR`	Set skeleton directory for home directory
`-p, --password PASSWORD`	Set encrypted password
`-D, --defaults`	Display or change default values

Examples

Create a basic user account:

sudo useradd john
# Creates user 'john' with default settings

# Verify the user was created
id john
# Output: uid=1001(john) gid=1001(john) groups=1001(john)

Create user with home directory:

sudo useradd -m jane
# Creates user 'jane' and creates /home/jane

# Check home directory
ls -la /home/jane
# Shows the created home directory with skeleton files

Create user with specific details:

sudo useradd -m -c "Alice Smith" -s /bin/bash alice
# Creates user with:
# - Home directory (-m)
# - Full name "Alice Smith" (-c)
# - Bash shell (-s)

# Verify user details
getent passwd alice
# Output: alice:x:1002:1002:Alice Smith:/home/alice:/bin/bash

Create user with specific UID and GID:

sudo useradd -u 1500 -g users -m bob
# Creates user 'bob' with:
# - UID 1500 (-u)
# - Primary group 'users' (-g)
# - Home directory (-m)

# Verify UID and GID
id bob
# Output: uid=1500(bob) gid=100(users) groups=100(users)

Create user with supplementary groups:

sudo useradd -m -G sudo,docker,www-data charlie
# Creates user 'charlie' with:
# - Home directory (-m)
# - Supplementary groups: sudo, docker, www-data (-G)

# Check group membership
groups charlie
# Output: charlie : charlie sudo docker www-data

Create system user:

sudo useradd -r -s /bin/false -d /var/lib/myapp myapp
# Creates system user 'myapp' with:
# - System account (-r)
# - No shell access (-s /bin/false)
# - Custom home directory (-d)

# System users typically have UID < 1000
id myapp
# Output: uid=999(myapp) gid=999(myapp) groups=999(myapp)

Create user with expiration date:

sudo useradd -m -e 2024-12-31 tempuser
# Creates user that expires on December 31, 2024

# Check expiration date
chage -l tempuser | grep "Account expires"
# Output: Account expires : Dec 31, 2024

Create user with custom home directory:

sudo useradd -m -d /opt/developer dev
# Creates user 'dev' with home directory at /opt/developer

# Verify home directory location
getent passwd dev | cut -d: -f6
# Output: /opt/developer

Setting User Passwords

After creating a user with useradd, you typically need to set a password:

Set password after user creation:

# Create user
sudo useradd -m newuser

# Set password interactively
sudo passwd newuser
# Enter new UNIX password: [type password]
# Retype new UNIX password: [type password]
# passwd: password updated successfully

# Alternative: Set password non-interactively
echo "newuser:mypassword" | sudo chpasswd

Default Values

You can view and modify default values used by useradd:

View default settings:

sudo useradd -D
# Output shows defaults like:
# GROUP=100
# HOME=/home
# INACTIVE=-1
# EXPIRE=
# SHELL=/bin/sh
# SKEL=/etc/skel
# CREATE_MAIL_SPOOL=no

Change default shell:

sudo useradd -D -s /bin/bash
# Changes default shell to bash for new users

# Verify the change
sudo useradd -D | grep SHELL
# Output: SHELL=/bin/bash

Batch User Creation

Create multiple users with script:

#!/bin/bash
# Script to create multiple users

users=("user1" "user2" "user3" "user4")

for user in "${users[@]}"; do
    if ! id "$user" &>/dev/null; then
        sudo useradd -m -s /bin/bash "$user"
        echo "Created user: $user"
        
        # Set temporary password
        echo "$user:temp123" | sudo chpasswd
        
        # Force password change on first login
        sudo chage -d 0 "$user"
    else
        echo "User $user already exists"
    fi
done

Create users from CSV file:

#!/bin/bash
# users.csv format: username,fullname,groups
# john,John Doe,sudo
# jane,Jane Smith,users

while IFS=',' read -r username fullname groups; do
    if [[ ! "$username" =~ ^#.* ]] && [[ -n "$username" ]]; then
        sudo useradd -m -c "$fullname" -G "$groups" "$username"
        echo "Created user: $username ($fullname)"
    fi
done < users.csv

User Account Files

useradd modifies several system files when creating users:

File	Purpose
`/etc/passwd`	User account information
`/etc/shadow`	Encrypted passwords and aging info
`/etc/group`	Group information
`/etc/gshadow`	Secure group information
`/etc/default/useradd`	Default values for useradd
`/etc/skel/`	Skeleton files for new home directories

Advanced Usage

Create user with custom skeleton:

# Create custom skeleton directory
sudo mkdir -p /etc/skel-developer
sudo cp /etc/skel/.* /etc/skel-developer/ 2>/dev/null || true
echo "alias ll='ls -la'" | sudo tee /etc/skel-developer/.bash_aliases

# Create user with custom skeleton
sudo useradd -m -k /etc/skel-developer -s /bin/bash developer

# Verify custom files
ls -la /home/developer/.bash_aliases

Create locked user account:

# Create user without password (locked)
sudo useradd -m -s /bin/bash lockeduser

# Check account status
sudo passwd -S lockeduser
# Output: lockeduser L ... (L = locked)

# Unlock by setting password
sudo passwd lockeduser

Create user for specific service:

# Create service user for web application
sudo useradd -r -d /var/www/myapp -s /bin/false -c "MyApp Service User" myapp

# Set ownership of application directory
sudo mkdir -p /var/www/myapp
sudo chown myapp:myapp /var/www/myapp

# Verify service user
getent passwd myapp

Common Use Cases

Regular users: Creating accounts for people who need system access
Service accounts: Creating users for running specific services or applications
System accounts: Creating accounts for system processes and daemons
Temporary accounts: Creating accounts with expiration dates
Batch creation: Creating multiple users from scripts or data files
Development environments: Setting up user accounts for development teams
Web hosting: Creating accounts for website owners or applications
Database users: Creating system users for database services

Best Practices

Always use -m to create home directories for regular users
Set appropriate shells: /bin/bash for interactive users, /bin/false for service accounts
Use meaningful comments with -c to document user purposes
Set expiration dates for temporary accounts
Use system accounts (-r) for services and applications
Assign users to appropriate supplementary groups
Set strong password policies and force password changes
Document user creation procedures for consistency
Use scripts for batch user creation to ensure consistency
Regularly audit user accounts and remove unused ones

Security Considerations

Never use predictable UIDs for security-sensitive accounts
Set appropriate file permissions on home directories
Use strong passwords and enforce password policies
Limit sudo access and group memberships
Set account expiration dates when appropriate
Monitor user account creation in system logs
Use system accounts for services (no shell access)
Regularly review and audit user accounts

Troubleshooting

Common error: Username already exists

# Check if user exists
id username 2>/dev/null && echo "User exists" || echo "User does not exist"

# If user exists but you need to recreate
sudo userdel username  # Remove user first
sudo useradd -m username  # Then recreate

Common error: UID already in use

# Check what UID is in use
getent passwd | grep ":1001:"

# Use different UID or let system assign automatically
sudo useradd -u 1002 username  # Specify different UID
# or
sudo useradd username  # Let system assign UID

Related Commands: userdel, usermod, chage, groups

Linux Commands