← Full reference

useradd and usermod

Creating and changing users and groups — useradd, usermod, groupadd, passwd, chage, userdel

Users and groups are stored in text files: /etc/passwd, /etc/shadow and /etc/group. You don't need to edit them by hand — that's what useradd, usermod, groupadd, passwd and their relatives are for. All changes require root.

Syntax

useradd [options] name       # create a user
usermod [options] name       # change an existing one
userdel [-r] name            # delete
groupadd [options] group     # create a group
groupmod [options] group     # change a group
groupdel group               # delete a group
gpasswd -a|-d name group     # add to a group / remove from a group
passwd [options] [name]      # password and its state
chage [options] name         # password and account expiry

File formats

FileFields separated by :
/etc/passwdname:x:UID:GID:comment:home_directory:shell — x means the password is in /etc/shadow
/etc/shadowname:hash:last_change:min:max:warning:inactive:expires: — dates in days since 1970; ! or * instead of a hash — password login is impossible
/etc/groupgroup:x:GID:member1,member2 — only supplementary members are listed here

It's easier to read them via getent passwd name, getent group group and id name.

useradd

OptionWhat it does
-mcreate the home directory and copy /etc/skel into it
-Mdon't create a home directory
-d /pathpath to the home directory (/home/name by default)
-k directorytake the home directory template from somewhere other than /etc/skel (with -m)
-s /bin/bashlogin shell; /usr/sbin/nologin — forbid login
-u 1500UID; -o — allow a non-unique UID
-g groupprimary group (must exist)
-G group1,group2supplementary groups
-U / -Ncreate a personal group named after the user (default on Ubuntu) / don't, use the group from useradd -D
-rsystem account: UID below 1000, no home directory
-c 'text'comment (usually the full name)
-e 2030-12-31date after which the account is disabled
-p 'hash'a ready-made password hash (not the password itself)
-Dshow the defaults; -D -s /bin/bash — change them

usermod

OptionWhat it does
-aG group1,group2add to supplementary groups
-G group1,group2replace the whole list of supplementary groups
-g groupchange the primary group
-s shellchange the login shell
-d /new -mchange the home directory and move its contents
-l new_namerename the user (the directory isn't renamed)
-u UIDchange the UID; the user's files in the home directory get the new UID, others don't (find them with find / -uid OLD)
-c 'text'change the comment
-L / -Ulock / unlock the password
-e 2030-12-31 / -e ''account expiry date / remove the date

Groups

CommandWhat it does
groupadd devscreate a group; -g 1500 — with a given GID, -r — a system group
groupmod -n new oldrename a group; -g GID — change the GID
groupdel devsdelete a group (not allowed if it's someone's primary group)
gpasswd -a alice devs / gpasswd -d alice devsadd to a group / remove from a group
gpasswd -M alice,bob devsset the whole member list

passwd and chage

CommandWhat it does
passwd nameset a password interactively; without a name — your own
passwd -S namestatus: name, P/L/NP (has a password / locked / no password), change date, min, max, warning, inactivity
passwd -l / -ulock / unlock the password
passwd -ddelete the password — login without a password
passwd -eforce a password change at next login
passwd -n 1 -x 90 -w 7min and max password age, how many days in advance to warn
echo 'name:password' | chpasswdset a password non-interactively; chpasswd -e — accepts a ready-made hash
chage -l nameshow all expiry settings in readable form
chage -M 90 -E 2030-12-31 namemax password age / account expiry date
chage -d 0 namesame as passwd -e

Deletion

CommandWhat it does
userdel namedelete the account, the files stay
userdel -r namedelete together with the home directory and mail spool
userdel -f namedelete even if the user is currently logged in

Examples

# a regular user: home directory, bash, sudo group
useradd -m -s /bin/bash -c 'Alice Smith' -G sudo alice

# a service account: no login and no home directory in /home
useradd -r -s /usr/sbin/nologin -d /srv/app -M appsvc

# a group and adding an existing user to it
groupadd devs
usermod -aG devs alice
gpasswd -d alice devs          # remove from the group

# set a password non-interactively (from a script)
echo 'alice:S3cret-pass' | chpasswd

# a temporary account: disabled at the end of the year, password change at login
useradd -m -e 2030-12-31 contractor
chage -d 0 contractor

# forbid login without deleting the user
usermod -L -s /usr/sbin/nologin alice

# check the result
id alice
getent passwd alice
getent group devs
passwd -S alice
chage -l alice

# run a command as the user
su - alice -c 'id; pwd'

# delete the user together with the home directory
userdel -r alice

Pitfalls

  • usermod -G without -a replaces the group list. usermod -G devs alice kicks alice out of sudo and all other supplementary groups. You almost always need -aG.
  • Without -m the home directory isn't created. On Ubuntu, useradd alice records /home/alice in /etc/passwd, but the directory won't exist. The default shell is /bin/sh, not bash. The convenient wrapper adduser does all of this itself, but asks questions interactively.
  • New groups are visible only in a new session. The user's already running shell won't know about usermod -aG — they need to log in again (or su - name).
  • The primary group isn't visible in /etc/group. The member list there contains only supplementary members. id name gives the full picture.
  • A new user without a password is locked (! in /etc/shadow, status L). Password login is impossible, but root can get in via su - name. And usermod -U refuses to unlock — set a password first.
  • -p expects a hash, not a password. useradd -p secret stores the string secret as the hash, and you can't log in with it. openssl passwd -6 gives a hash, but chpasswd is simpler.
  • passwd -d allows login with no password at all. To lock, you need -l. Note that -l doesn't prevent login with an SSH key — to forbid login completely, change the shell to nologin or set an expiry date.
  • userdel without -r leaves the home directory. Its files will belong to a "bare" UID that may be given to the next user created.
  • usermod -d new -m gives an error if the old directory doesn't exist, but changes the path in /etc/passwd anyway.
  • useradd -o -u 0 creates a second root under another name. Don't do this — it's a classic backdoor.

See also

sudo · id · su · chage · getent · chown · chmod · umask