Linux useradd command

On Unix-like operating systems, the useradd command creates a new user or sets the default information for new users.

This page covers the Linux version of useradd.

Description

useradd is a low-level utility for adding users to a system. In general, the more friendly adduser should be used instead.

Your operating system may come with a slightly different version of useradd; check your documentation before using it to create new accounts. This documentation refers to some options frequently used on Debian-based variants of Linux, but is representative of useradd's general use.

When invoked without the -D option, the useradd command creates a new user account using the values specified on the command line plus the default values from the system. Depending on command line options, the useradd command updates system files and may also create the new user's home directory and copy initial files.

By default, a group is also created for the new user (see the -g, -N, -U options, and the USERGROUPS_ENAB variable, below).

Syntax

useradd [options] LOGIN

useradd -D

useradd -D [options]

Options

Changing new user default values

When invoked with only the -D option, useradd displays the current default values. When invoked with -D plus other options, useradd updates the default values for the specified options.

Valid default-changing options are:

Notes

The system administrator is responsible for placing the default user files in the /etc/skel/ directory (or any other skeleton directory specified in /etc/default/useradd or on the command line).

Caveats

You may not add a user to a NIS or LDAP group. This must be performed on the corresponding server.

Similarly, if the username already exists in an external user database such as NIS or LDAP, useradd will deny the user account creation request.

It is usually recommended to only use usernames that begin with a lowercase letter or an underscore, followed by lowercase letters, digits, underscores, or dashes. They can end with a dollar sign. The regular expression describes a valid username is:

[a-z_][a-z0-9_-]*[$]?

The only constraints are that usernames must neither start with a dash ('-') nor plus ('+') nor tilde ('~') nor contain a colon (':'), a comma (','), or a whitespace (space: ' ', end of line: '\n', tab: '\t', etc.). Note that using a slash ('/') may break the default algorithm for the definition of the user's home directory.

Usernames may only be up to 32 characters long.

Configuration

The following configuration variables in /etc/login.defs change the behavior of this tool:

The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and userdel to create, move, or delete the user's mail spool.

Files

Exit status

useradd exits with the following status, depending on what occurred:

Examples

useradd -D

Displays the defaults for new users. Output resembles the following:

GROUP=1001
HOME=/home
INACTIVE=-1
EXPIRE=
SHELL=/bin/bash
SKEL=/etc/skel
CREATE_MAIL_SPOOL=no

useradd newperson

Creates newperson as a new user. Once the new user is added, you would need to use the passwd command to assign a password to the account.

Once a user is created, you can modify any of the user settings, such as the user's home directory, using the usermod command.

Related commands

groupadd — Add a group to the system.
passwd — Change a user's password.
userdel — Remove a user from the system.
usermod — Modify a user's account.