Skip to main content
Engineering LibreTexts

02-B.6: Users: Create, Modify, and Delete (cont'd)

  • Page ID
  • The useradd Command

    The useradd command is used to create user accounts and configure basic settings. The basic usage of useradd is quite simple: A user can be added just by providing their username.


    useradd [ OPTIONS ] USER_LOGIN

    Command Options

    Options Meaning
    -b, --base-dir BASE_DIR The default base directory for the system if -d HOME_DIR is not specified. BASE_DIR is concatenated with the account name to define the home directory. If the -m option is not used, BASE_DIR must exist.
    If this option is not specified, useradd will use the base directory specified by the HOME variable in /etc/default/useradd, or /home by default.
    -c, --comment COMMENT Any text string. It is generally a short description of the login, and is currently used as the field for the user's full name.
    -d, --home HOME_DIR The new user will be created using HOME_DIR as the value for the user's login directory. The default is to append the LOGIN name to BASE_DIR and use that as the login directory name. The directory HOME_DIR does not have to exist but will not be created if it is missing.
    -D, --defaults See below, the subsection "Changing the default values."
    -e, --expiredate EXPIRE_DATE The date on which the user account will be disabled. The date is specified in the format YYYY-MM-DD.
    -s, --shell SHELL The name of the user's login shell. The default is to leave this field blank, which causes the system to select the default login shell specified by the SHELL variable in /etc/default/useradd, or an empty string by default.

    As an example, to add a new user, pbmac, the following command is used:

    $ sudo useradd pbmac

    In this example, the useradd command creates an account called pbmac. A group with the same name is also created, and the user pbmac is placed in this new group and is the primary group for this user. There are other parameters, such as language and shell, that are applied according to defaults and values set in the configuration files /etc/default/useradd and /etc/login.defs. This is generally sufficient for a single, personal system or a small, one-server business environment.

    While the two files above govern the behavior of useradd, user information is stored in other files found in the /etc directory.

    File Description Fields (bold—set by useradd)
    /etc/passwd Stores user account details username:unused:uid:gid:comment:homedir:shell
    /etc/shadow Stores user account security details username:password:lastchange:minimum:maximum:warn:inactive:expire:unused
    /etc/group Stores group details


    The useradd command line allows customization for times when an administrator needs finer control, such as to specify a user's ID number.

    (Starting in this next section, the getent command produces output in a specific format. We will talk more about this when we discuss the password command.)

    User and Group ID Numbers

    By default, useradd tries to use the same number for the user ID (UID) and primary group ID (GID), however, this is NOT guaranteed. Although it's not necessary for the UID and GID to match, it's easier for administrators to manage them when they do. (ATTENTION - memorize UID and GID, these are important acronyms for Linux admins)

    Suppose we add another account, this time for santiago. Comparing the two users, pbmac and santiago, shows that both users and their respective primary groups were created by using the getent command.

    $ getent passwd pbmac santiago
    $ getent group pbmac santiago

    Unfortunately, neither users' UID nor primary GID match. This is because the default behavior is to assign the next available UID to the user and then attempt to assign the same number to the primary group. However, if that number is already used, the next available GID is assigned to the group. To understand what happened, we can assume that a group with GID 1001 already exists - we can enter a command to confirm:

    $ getent group 1001

    The group book with the ID 1001 has caused the GIDs to be off by one. This is an example where a system administrator would need to take more control of the user-creation process. To resolve this issue, you must first determine the next available user and group ID that will match. The commands getent group and getent passwd will be helpful in determining the next available number. This number can be passed with the -u argument.

    $ sudo useradd -u 1004 maida
    $ getent passwd maida; getent group maida

    "Intro to the Linux useradd command" by Alan Formy-Duval, is licensed under CC BY-SA 4.0

    • Was this article helpful?