How To Use Linux USERADD Command [With Examples]

By Leonard Cucos •  Updated: 12/06/21 •  12 min read

The Linux useradd command is one of the most elementary things you need to master to become a Linux and UNIX system administrator. 

In this guide, I will walk you step-by-step on how to use the useradd command in Linux, how useradd works, and which files and directors are involved in the user creation process.

Think of the useradd command being similar to what an HR manager does when a new employee is hired. Specifically, she or he makes sure the new staff has its name and all the relevant information registered in the company’s database so that in the future it can have proper access to the company’s resources.

In the same way, you as a system administrator use the Linux useradd command to add new users to a system. The useradd command has a dedicated syntax and a set of options [flags] that can be used to define how a user is created. Let’s discuss that first.

Linux useradd command

The Linux useradd utility can be used only with root privileges to create new users and typically has the following syntax on a Linux system:

useradd [options] USERNAME

Where: 

[options] = a set of arguments available for the useradd command

USERNAME = the actual user name assigned to the account.

The useradd command provides a number of options to specify how a new user is created. The following table provides a summary of all options [flags and arguments] available for useradd as well as the explanation for each.

FlagArgumentExplenation
–badnamesInstruct useradd to not check for bad names
-b–base-dir BASE_DIRSpecify the base directory for the home directory of the new account
–btrfs-subvolume-homeInstruct useradd to use BTRFS subvolume [if available] for home directory 
-c–comment  COMMENTSpecify the GECOS field [a field of each record in the /etc/passwd file] of the new account
-d–home-dir HOME_DIRSpecify the home directory of the new account
-D–defaultsChange or print the default useradd configuration for the login user
-e–expiredate EXPIRE_DATESet the expiration date of the new account
-f–inactiuve INACTIVESet password inactivity period of the new account
-g–gid GROUPSpecify the ID or the name of the primary group of the new account
-G–groups GROUPSSpecify the additionally groups the new account should be part of
-h–helpShow the Linux useradd help page
-k–skel SKEL_DIRInstructs useradd to use a specified skeleton directory
-K–key KEY=VALUEInstructs useradd to override /etc/login.defs default configuration
-l–no-log-initInstructs useradd not to add the new account to the faillog and lastlog database
-m–create-homeInstructs useradd to create the home directory for the specified user
-M–no-create-homeInstructs useradd to not create the home directory for the specified user
-N–no-user-groupInstructs useradd to not create a new group with the same name as the user
-o–non-uniqueAllows useradd to create users with non-unique [duplicate] UID
-p–password PASSWORDSpecify the password for the specified account
-r–systemInstruct useradd to create a system account
-R–root CHROOT_DIRSpecify the chroot directory for the specified account
-P–prefix PREFIX_DIRSpecify the prefix directory respectively the location of the /etc/* files
-s–shell SHELLSpecify the login shell for the new user
-u–uid UIDSpecify the user ID for the new user
-U–user-groupInstructs useradd to create a group with the same name as the user
-z–selinux-user SEUSERInstructs useradd to use a specified SEUSER for the SELinux user mapping.

NOTE: use only the flag or the argument in the useradd command and not both.

Before we move to understand what really happens in our system when we create a user with the Linux useradd command let’s have a look at a few practical examples.

Linux useradd Examples

The examples below use “john” as the name for the new user. Feel free to replace “john” with any name you like. Don’t worry, once you finish practicing the examples below, I will show you how to completely remove “john” from your system.

1. Create a new user without any home directory

sudo useradd -M john

This command will create the user “john” without giving it any home folder.

2. Create a new user and give it a home directory in /home folder

sudo useradd -m john

This will create the user “john,” create its home folder at /home/john, and copy the files from /etc/skel directory into john’s home folder.

3. Create a new user and give it a custom home directory

sudo useradd -m -d /opt/john john

This command will create the user “john,” create its home folder at /opt/john, and populate it with the files from /etc/skel directory. 

4. Create a new user with a custom user ID (UID).

sudo useradd -u 2222 john

This command will create the user “john” and give it the user ID “2222.” To check if the custom ID was allocated to your new user, use the id -u command in the terminal as follows:

id -u john

5. Create a new user with a custom group ID (GID)

sudo useradd -g 2222 john

This command will create the user “john” and the user group ID “2222.” To check the new user group ID use the id -gn command as shown in the previous example.

id -gn john

6.  Create a new user with a short description or comment.

sudo useradd -c “This account belongs to John Smith” john

This command will create the “john” user and add a custom comment to it. To view the description for “john” use the following command:

sudo cat /etc/passwd | grep john

7. Create a user account with a specific expiry date 

sudo useradd -e 2022-01-01 john

This command will create the user “john” account with an expiration date of 1st of January 2022. To view the expiration date for “john” account use the following command:

sudo chage -l john

8. Create a system user

sudo useradd -r john

This command will create the system user “john.” Take note that system users have no expiry date specified in /etc/shadow and the numeric ID associated with the system users are picked from a range specified in the /etc/login.defs file. 

9. Set a password to a new user. 

sudo passwd john

This command will prompt you to assign a password to the “john” user. You should have already created the user “john” using any of the steps above before running the passwd command.

10. Completely remove a user from the system.

userdel -Z -r -f john

Where:

-Z remove SELinux user mapping. 

-r remove user account and its home directory and mail spool.

-f force remove any user files.

The above command will forcefully delete the user “john” and all its associated files, directories, and mail spool from the system.

Now that we went through some of the most common Linux useradd command applications, let’s have a look at what really happens in the system every time we create or modify a user.

User Configuration Files in Linux

A number of configuration files and directories are involved in the user creation process in Linux. Here is a representation of the process flow and files with their respective paths involved.

Linux useradd configuration files. Source: nudesystems.com

You may have noticed that the /etc/skel and /home/userid directories are marked in red in the above diagram. This is because they may or may not be involved in the process of creating a new user depending on the user configuration. It is also important to note that depending on how your Linux distribution handles the user creation process, these directories may have different names or simply not exist.

The /etc/login.defs file

The /etc/login.defs configuration file contains directives for use in various shadow password suite commands and is usually created on most Linux distributions. The shadow password suite is a term associated with commands designed to handle account credentials [e.g., useradd, userdel, and passwd]. 

For instance, it can define how long the password should be, what type of characters should include or how long until the password expires. 

The /etc/login.defs contains a lot of commented lines containing instructions for each parameter. Here is how the /etc/login.defs file for my normal user looks after removing all the comments using the grep command below.

grep -v ^$ /etc/login.defs | grep -v ^\#
Linux useradd login.defs file. Source: nudesystems.com

In the table below, I included some of the most important directives in the /etc/login.defs file from a Linux administrator perspective.

DirectiveExplanation
UIDUser Identification number associated with a user account in Linux.
UID_MIN and UID_MAXIndicates the lowest and highest UID allowed for user accounts. The UID_MIN can vary, on some Linux systems being 500 and other 1000.
SYS_UID_MIN and SYS_UID_MAXIndicates the lowest and highest SYS_UID allowed for system accounts. The system accounts are in charge of running daemons (services) or performing system-related tasks.
PASS_MIN_LENGTHSets the minimum number of characters for the user password
PASS_MAX_DAYSSets the password expiration date [number of days] until a user is asked to change its password.
PASS_MIN_DAYSSets a limit [in days] between two password change events.
PASS_WARN_AGESets the number of days for the password change user warning prior to the password expiration.
EMCRYPT_METHODSets the method used by the system to encrypt [hash] account passwords.
CREATE_HOMEAllows for user account home directory to be created. The default setting is no.

You can edit the /etc/login.defs file with vi or any other editor of your choice as a root user:

sudo vi /etc/login.defs 

The /etc/default/useradd File

The /etc/default/useradd configuration file is typically shorter than the previous one and contains additional directives for the user account creation process. The /etc/default/useradd can be visualized using the cat or unseradd -D commands and usually looks like this:

Linux useradd file. Source: nudesystems.com

The table below comprises some of the most important directives in the /etc/default/useradd file:

DirectiveExplanation
HOMEThe base directory location for user account directories
INACTIVEDefines the number of days until the account will be deactivated if the password is not changed once expired.
SKELDefines the skeleton directory
SHELLThe default shell application for the user account is typically set to /bin/bash or /bin/sh depending on the Linux distribution. All the processes related to your terminal are run in this folder.

The /etc/skel/ Directory

The “skel” name stands for “skeleton” and is also referred to as the “hold files.” This directory contains all the files that will be copied into the home directory of every new user created on the system.

On Fedora Workstation, here is how the /etc/skel directory looks like. Take note that all the files contained in this directory are hidden by default. Use the following command to list all the hidden files in this directory:

ls -la /etc/skel
Linux useradd skel directory. Source: nudesystems.com

So far we covered the main files involved in the user creation process. Let’s now quickly look into the files and directories that are created or modified during this process.

The /etc/passwd File

The main purpose of the /etc/passwd file is to store the information for all accounts in the system. Each line in this file is dedicated to one account. Therefore, when a new account is created in the system, a new line is generated in this file. 

Here is how /etc/passwd file looks like on a Fedora system. Use the following command to view the passwd file on your system:

cat /etc/passwd
Linux useradd passwd file. Source: nudesystems.com

There are seven fields in total for each account record (line) in this file and each field is separated by a colon “:” The following table summarizes and explains each field.

FieldExplanation
1The username associated with the account (e.g., nudesystems or john in the above example).
2The password field where “x” indicates the password is stored in the /etc/shadow file.
3The user identification number (UID) associated with each account (e.g., 1000 and 1001 in the above example).
4The user identification group (GID) associated with each account.
5The comment field traditionally reserved for the user’s full name. 
6The home directory of the user.
7The default shell of the user. 

You would think that a file called passwd contains passwords right? Well, as you can see, it doesn’t. The passwords are stored in a different file which is discussed next. 

The /etc/shadow File

This file contains all the user’s password information for the users in the system. This file gets modified each time a new user is added to the system, even if no password was allocated to the user yet. 

All user passwords are encrypted using the Data Encryption Standard [DES] so you’re out of luck if hope that you can see a root password in plain text here. 

Here is how the /etc/shadow file looks on my system. For security reasons, I blurred a section of the encrypted root password. 

sudo cat /etc/shadow
Linux useradd shadow file. Source: nudesystems.com

As in the previous example, each record contains a total of nine fields separated by a “:” Table below gives a summary and explanation for each field. 

FieldExplanation
1The username associated with the account (e.g., root in the above example). This is the only field shared with the /etc/passwd file.
2The hashed account password. 
3The date when the password was changed last time is displayed in POSIX time format. 
4The number of days between password change is required.
5The password expiration date is expressed in days left until password change is required. 
6The number of days for password change warning before the password expiration date.
7The number of days the account gets deactivated if the account password is not renewed after expiration.
8The date for account expiration in POSIX time format.
9The “special flag” field reserved for future use. 

The last  /etc/group is another file that is involved each time a user is created. However, groups and usergroup in Linux are matters that require their own article.

Wrapping Up

There you go. Everything you need to know about useradd command in Linux: what happens when a new user is created with useradd, which files are created and modified, where and how the user IDs, group IDs, and passwords are stored, etc.

It is important to know that the useradd command is part of a larger ecosystem of Linux commands (e.g., usermod, usergroup, userdel, etc.)

I hope you found this tutorial useful. If so, take a moment and share it around.

Stay safe!

Leonard Cucos

Leonard Cucos is an engineer with over 20 years of IT/Telco experience managing large UNIX/Linux-based server infrastructures, IP and Optics core networks, Information Security [red/blue], Data Science, and FinTech.