ADDUSER(8)

📦
version 3.157ubuntu2 · 6 versions
, in ubuntu stonking

✨ ADDUSER(8) — System Manager's Manual ✨

okay so bestie, welcome to adduser and addgroup, the two icons of this manual page 💅 they live in section 8 of the System Manager's Manual and they are literally about to make your whole user-and-group situation cute and correct.

🎀 NAME 🎀

adduser, addgroup — add or manipulate users or groups 🫶

🌸 SYNOPSIS 🌸

adduser [--add-extra-groups] [--allow-all-names] [--allow-bad-names]
        [--comment comment] [--conf file] [--debug] [--disabled-login]
        [--disabled-password] [--encrypt-home] [--firstgid id]
        [--firstuid id] [--force-home] [--gid id] [--home dir]
        [--ingroup group] [--lastgid id] [--lastuid id]
        [--no-create-home] [--no-copy-skel] [--shell shell] [--quiet]
        [--uid id] [--verbose] [--stdoutmsglevel prio]
        [--stderrmsglevel prio] [--logmsglevel prio] user

adduser --system [--comment comment] [--conf file] [--debug] [--gid id]
        [--group] [--home dir] [--ingroup group] [--no-create-home]
        [--no-copy-skel] [--shell shell] [--uid id] [--quiet]
        [--verbose] [--stdoutmsglevel prio] [--stderrmsglevel prio]
        [--logmsglevel prio] user

adduser --unlock [--system] user

adduser --group [--conf file] [--debug] [--firstgid id] [--gid ID]
        [--lastgid id] [--quiet] [--verbose] [--stdoutmsglevel prio]
        [--stderrmsglevel prio] [--logmsglevel prio] group

addgroup [--conf file] [--debug] [--firstgid id] [--gid ID]
         [--lastgid id] [--quiet] [--verbose] [--stdoutmsglevel prio]
         [--stderrmsglevel prio] [--logmsglevel prio] group

addgroup --system [--gid id] [--conf file] [--quiet] [--verbose]
         [--stdoutmsglevel prio] [--stderrmsglevel prio]
         [--logmsglevel prio] group

adduser [--conf file] [--debug] [--quiet] [--verbose]
        [--stdoutmsglevel prio] [--stderrmsglevel prio]
        [--logmsglevel prio] user group

adduser --help

adduser --version

like, that's a lot of brackets, but every single one of them is important, so don't get overwhelmed bestie 🌈

🌟 DESCRIPTION 🌟

so adduser and addgroup add users and groups to the system, following whatever you tell them on the command line plus the configuration info chilling in /etc/adduser.conf. They're the more Debian-specific front ends to the useradd, groupadd and usermod programs — those ones are the more distribution-agnostic girlies. By default, adduser and addgroup pick UID and GID values that conform to Debian policy 👑, create a home directory with skeletal configuration, run a custom script, and have other features. main character behavior, honestly.

adduser and addgroup are meant to be a policy layer, which makes it easier for package maintainers and local administrators to create local system accounts the way Debian expects them to be created — taking the burden off you to adapt to Debian policy's probably-changing specifications. adduser --system takes special attention on needing just a single call in the package maintainer scripts, no conditional wrappers, no error suppression, no other scaffolding. it's giving one-shot, no notes ✨

adduser honors the distinction between dynamically allocated system users and groups and dynamically allocated user accounts that's documented in Debian Policy, Chapter 9.2.2.

for the full list and explanations of all the options, go look at the OPTIONS section 👀

adduser and addgroup can be run in one of five modes:

💫 Add a regular (non-system) user 💫

If you call it with one non-option argument and without the --system or --group options, adduser will add a regular user — meaning a dynamically allocated user account in the sense of Debian Policy. In adduser this is commonly called a non-system user.

If adduser is called with the --unlock option, it will search for an existing account and make sure it's unlocked. If the user is not found, adduser will return an error 😭. See Unlock an account below for more details.

adduser will choose the first available UID from the range specified by FIRST_UID and LAST_UID in the configuration file. That range can be overridden with the --firstuid and --lastuid options. And finally, the UID can be set fully manually with the --uid option 💅

By default, each user is given a corresponding group with the same name. This is commonly called Usergroups, and it lets group-writable directories be easily maintained by placing the appropriate users in the new group, setting the set-group-ID bit in the directory, and making sure all users use a umask of 002.

For a usergroup, adduser will choose the first available GID from the range specified by FIRST_GID and LAST_GID in the configuration file. The range may be overridden with the --firstgid and --lastgid options. And finally, the GID can be set fully manually with the --gid option.

The interaction between USERS_GID, USERS_GROUP, and USERGROUPS is explained in detail in adduser.conf(5) — go read it, it's tea 🍓

The new user's primary group can also be overridden from the command line with the --gid or --ingroup options, to set the group by id or name, respectively. Also, users can be added to one or more supplemental groups defined as EXTRA_GROUPS, either by setting ADD_EXTRA_GROUPS to 1 in the configuration file, or by passing --add-extra-groups on the command line.

adduser will copy files from /etc/skel into the home directory and prompt for the comment field and a password, if those functions haven't been turned off / overridden from the command line.

UID, comment, home directory and shell might be pre-determined with the UID_POOL and GID_POOL option, documented in adduser.conf(5).

To set up an encrypted home directory for the new user, add the --encrypt-home option. For more info, refer to the -b option of ecryptfs-setup-private(1) 🔐

🧚 Add a system user 🧚

If you call it with one non-option argument and the --system option, adduser will add a dynamically allocated system user, often abbreviated as system user in the context of the adduser package.

If the user already exists and is a system account, then adduser will make sure the account is unlocked and return successfully. See Unlock a user account below.

adduser will choose the first available UID from the range specified by FIRST_SYSTEM_UID and LAST_SYSTEM_UID in the configuration file. This can be overridden with the --uid option.

By default, system users are assigned nogroup as primary group. To assign an already existing group as primary group, use the --gid or --ingroup options. If the --group option is given and the identically named group does not already exist, it is created with the same ID.

If no home directory is specified, the default home directory for a new system user is /nonexistent. This directory should never exist on any Debian system, and adduser will never create it automatically 🚫

okay so here's a genuinely important one, pay attention bestie: if a home directory is specified with the --home option, and the directory already exists (like, if the package ships with files in that directory), adduser silently does not set the owner of the directory to the newly created user. Setting the owner might override a decision of the local admin, and reporting the fact would break adduser's silence during package installation. If you use adduser --home in your package's maintainer scripts, you might want to issue an explicit recursive chown for the home directory after the call to adduser. 💀 no cap.

Unless a shell is explicitly set with the --shell option, the new system user will have the shell set to /usr/sbin/nologin. adduser --system does not set a password for the new account. It is an error if adduser --system is called for an account that has a password. Skeletal configuration files are not copied.

Other options will behave as for the creation of a regular user. The files referenced by UID_POOL and GID_POOL are also honored.

🔓 Unlock a user account 🔓

If it's called with the --unlock option, adduser will unlock an existing, previously locked account. If found, the user's password will be re-enabled, and expiry restrictions will be removed. Any previous expiry settings will have to be added manually after unlocking the account — so note that down, bestie 🎀

👑 Add a group 👑

If adduser is called with the --group option and without the --system option, or addgroup is called respectively, a user group will be added.

A dynamically allocated system group, often abbreviated as system group in the context of the adduser package, will be created if adduser --group or addgroup are called with the --system option.

A GID will be chosen from the respective range specified for GIDs in the configuration file (FIRST_GID, LAST_GID, FIRST_SYSTEM_GID, LAST_SYSTEM_GID). To override that mechanism, you can give the GID using the --gid option.

For non-system groups, the range specified in the configuration file may be overridden with the --firstgid and --lastgid options.

The group is created with no members. fresh start, empty group, iconic ✨

🫶 Add an existing user to an existing group 🫶

If it's called with two non-option arguments, adduser will add an existing user to an existing group. that's it, that's the mode 💜

💅 OPTIONS 💅

okay so here's the tea, bestie: different modes of adduser allow different options. So each option below tells you which modes it's valid in. And if an option doesn't list any valid modes? Then it's accepted in all of them. easy!

Also, quick heads up: some options have short versions that exist for historical reasons. They're staying supported, but they've been yeeted from the documentation. So like, migrate to the long version of options, bestie. do it for me. 🫶

  • --add-extra-groups — adds the new user to the extra groups defined in the configuration file's EXTRA_GROUPS setting. The old spelling --add_extra_groups is deprecated and will only be supported in Debian bookworm. Valid modes: adduser, adduser --system. ✨
  • --allow-all-names — allows literally any user- and groupname that the underlying useradd(8) supports. See VALID NAMES below for the deets. Valid modes: adduser, adduser --system, addgroup, addgroup --system. 🌈
  • --allow-bad-names — disables the NAME_REGEX and SYS_NAME_REGEX check of names. Only a weaker check for the validity of the name gets applied. See VALID NAMES below. Valid modes: adduser, adduser --system, addgroup, addgroup --system. 💀
  • --comment comment — sets the comment field for the new entry. If you pass this, adduser won't ask you for that info. This field is also known as the GECOS field, and it holds the info that the finger(1) command uses. This used to be the --gecos option, which is deprecated and will be removed after Debian bookworm. Valid modes: adduser, adduser --system. 👑
  • --conf file — use file instead of /etc/adduser.conf. You can pass multiple --conf options if you're feeling extra. 🎀
  • --debug — synonymous to --stdoutmsglevel=debug. Deprecated. 🙈
  • --disabled-login
  • --disabled-password — do not run passwd(1) to set a password. ngl in most situations logins are still possible though (like, via SSH keys or through PAM) for reasons that are beyond adduser's scope, so don't get it twisted. --disabled-login will additionally set the shell to /usr/sbin/nologin. Valid mode: adduser.
  • --firstuid ID
  • --lastuid ID
  • --firstgid ID
  • --lastgid ID — override the first UID / last UID / first GID / last GID in the range that the uid is chosen from (that's FIRST_UID, LAST_UID, FIRST_GID and LAST_GID, FIRST_SYSTEM_UID, LAST_SYSTEM_UID, FIRST_SYSTEM_GID and LAST_SYSTEM_GID in the configuration file). Heads up though: if a group is created as a usergroup, --firstgid and --lastgid get ignored, because the group just gets the same ID as the user. Valid modes: adduser, adduser --system, and for --firstgid and --lastgid also addgroup. 🦋
  • --force-badname
  • --allow-badname — these are the deprecated forms of --allow-bad-names. They will be removed during the release cycle of Debian 13. don't use them fr fr. 😭
  • --extrausers — uses extra users as the database. 💜
  • --gid GID — when you're creating a group, this sets the group ID number of the new group to GID. When you're creating a user, this sets the primary group ID number of the new user to GID. Valid modes: adduser, adduser --system, addgroup, addgroup --system.
  • --group — using this in adduser --system means the new user should get an identically named group as its primary group. If that identically named group isn't already there, it gets created. If you don't combine it with --system, then a group with the given name is created. (And that latter thing is the default action if the program is invoked as addgroup.) Valid modes: adduser --system, addgroup, addgroup --system. 🌸
  • --help — displays brief instructions. the classic. ✨
  • --home dir — use dir as the user's home directory, rather than the default specified by the configuration file (or /nonexistent if adduser --system is used). If the directory doesn't exist, it gets created. Valid modes: adduser, adduser --system.
  • --ingroup GROUP — when creating a user, this sets the primary group ID number of the new user to the GID of the named group. Unlike with the --gid option, you specify the group here by name rather than by numeric ID number. The group must already exist. Valid modes: adduser, adduser --system. 👯
  • --lastuid ID
  • --lastgid ID — override the last UID / last GID. See --firstuid.
  • --no-create-home — do not create a home directory for the new user. Note that the pathname for the new user's home directory will still be entered in the appropriate field in the /etc/passwd file. Using this option does not imply that this field should be empty — rather, it tells adduser that some other mechanism will be responsible for initializing the new user's home directory. Valid modes: adduser, adduser --system. 🫶
  • --force-home — assume the home directory does already exist and has been taken care of by the local administrator. chown the directory to the newly created user and populate it with the files from /etc/skel without double checking. This lets you put new home directories on an md, lvm, or dm-crypt device. Valid modes: adduser. 🔥
  • --no-copy-skel — do not populate the home directory for the new user with files from /etc/skel. If the home directory is newly created, it will be empty. Valid modes: adduser, adduser --system.
  • --quiet — synonymous to --stdoutmsglevel=warn. Deprecated.
  • --shell shell — use shell as the user's login shell, rather than the default specified by the configuration file (or /usr/sbin/nologin if adduser --system is used). Valid modes: adduser, adduser --system. 🐚
  • --system — normally, adduser creates dynamically allocated user accounts and groups as defined in Debian Policy, Chapter 9.2.2. With this option, adduser creates a dynamically allocated system user and group and changes its mode respectively. Valid modes: adduser, addgroup.
  • --uid ID — force the new userid to be the given number. adduser will fail if the userid is already taken. Valid modes: adduser, adduser --system. 💅
  • --verbose — synonymous to --stdoutmsglevel=info. Deprecated.
  • --stdoutmsglevel prio
  • --stderrmsglevel prio
  • --logmsglevel prio — minimum priority for messages logged to syslog/journal and the console, respectively. Values are trace, debug, info, warn, err, and fatal. Messages with the priority set here or higher get printed to the respective medium. Messages printed to stderr are not repeated on stdout. That lets the local admin control adduser's chattiness on the console and in the log independently — keeping probably confusing info to itself while still leaving helpful info in the log. stdoutmsglevel, stderrmsglevel, and logmsglevel default to warn, warn, info, respectively. 🎚️
  • -v, --version — displays version and copyright information. ⭐

✨ VALID NAMES ✨

so, a lil history lesson for you bestie 🎀: adduser(8) and addgroup(8) historically enforced conformity to IEEE Std 1003.1-2001, which allows only the following characters to appear in group- and usernames: letters, digits, underscores, periods, at signs (@) and dashes. The name may not start with a dash or @. The "$" sign is allowed at the end of usernames to allow typical Samba machine accounts.

The default settings for NAME_REGEX and SYS_NAME_REGEX allow usernames to contain letters and digits, plus dash (-) and underscore (_); the name must begin with a letter (or an underscore for system users).

The least restrictive policy — available by using the --allow-all-names option — simply makes the same checks as useradd(8). Please note that useradd's checks have become quite a bit more restrictive in Debian 13. 😳

Changing the default behavior can be used to create confusing or misleading names; use with caution. ⚠️

📝 LOGGING 📝

adduser uses extensive and configurable logging to tailor its verbosity to the needs of the system administrator. iconic, honestly.

Every message that adduser prints has a priority value assigned by the authors. This priority can not be changed at run time. Available priority values are fatal, error, warn, info, debug, and trace.

If you find that a message has the wrong priority, please file a bug. 🙏

Every time a message is generated, the code decides whether to print the message to standard output, standard error, or syslog. This is mainly and independently controlled by the configuration settings STDOUTMSGLEVEL, STDERRMSGLEVEL, and LOGMSGLEVEL. For testing purposes, these settings can be overridden on the command line.

Only messages with a priority higher or equal to the respective message level are logged to the respective output medium. A message that was written to standard error is not written a second time to standard output. periodt. 💖

💀 EXIT VALUES 💀 (aka the receipts)

Like, when adduser dips out, it tells you why with a number. Here's the whole tea, bestie:

  • 0 — Success! The user or group exists exactly as specified. Two ways this happens: either this call to adduser made it, or it was already chilling on the system as specified before adduser even showed up. And heads up — if you run adduser --system on a user that already exists with the requested or compatible attributes, it'll still hand you a 0. Slay.
  • 11 — The thing adduser was asked to create? Already exists, babe.
  • 12 — The thing adduser or deluser was asked to operate on? Doesn't exist. Nowhere. Gone.
  • 13 — The object adduser or deluser was asked to operate on doesn't have the properties needed to finish the job. Specifically: a user (or group) requested to be created as a system user (group) already exists and is not a system user (group); or a user (group) requested to be created with a certain UID (GID) already exists with a different UID (GID); or a system user (group) requested to be deleted does exist but is not a system user (group). So messy.
  • 21 — That UID (GID) you explicitly demanded for a new user (group)? Already in use, sorry bestie.
  • 22 — No available UID (GID) in the range you asked for. The range said no. 💀
  • 23 — There's no group with the requested GID to be the primary group for the new user.
  • 31 — The chosen name or comment for a new user or group doesn't conform to the naming rules you selected.
  • 32 — The home directory of a new user has to be an absolute path. No shortcuts, literally.
  • 33 — useradd returned exit code 19 "invalid user or group name". Meaning the name you picked doesn't fit useradd's restrictions and adduser simply can't create the user. It's giving blocked.
  • 41 — The group requested for deletion is not empty. Can't delete a group that still has people in it, that's rude.
  • 42 — The user you wanted removed from a group... was never in it to begin with. Awkward. 🙈
  • 43 — You can't remove a user from its primary group, or no primary group was selected for a new user by any method.
  • 51 — Incorrect number or order of command line parameters detected. Check your flags, bestie.
  • 52 — Incompatible options set in the configuration file.
  • 53 — Mutually incompatible command line options detected. These flags cannot sit together, it's giving enemies.
  • 54 — adduser and deluser were invoked as non-root and therefore cannot work. Root privileges are non-negotiable.
  • 55 — deluser will flat-out refuse to delete the root account. Iconic behaviour honestly.
  • 56 — A function was requested that needs more packages installed. Peep the Recommends: and Suggests: of the adduser package.
  • 61 — adduser was aborted for some reason and tried to roll back everything it did during execution. It said "undo, undo, undo".
  • 62 — Internal adduser error. This should not happen. Please try to reproduce the issue and file a bug report. 🐛
  • 71 — Error creating and handling the lock.
  • 72 — Error accessing the configuration file(s).
  • 73 — Error accessing a pool file.
  • 74 — Error reading a pool file, syntax error in file.
  • 75 — Error accessing auxiliary files.
  • 81 — An executable that adduser or deluser needs can't be found. Check your installation and dependencies.
  • 82 — Executing an external command returned some unexpected error.
  • 83 — An external command was terminated with a signal.
  • 84 — A syscall terminated with unexpected error.

Or for many other yet undocumented reasons which get printed to console right then. In that case you might consider bumping up a log level to make adduser more verbose. 🫶

🔒 SECURITY 🔒 (do not play with this)

adduser needs root privileges, and it offers you the --conf command line option to use different configuration files. Do not use sudo(8) or similar tools to give partial privileges to adduser with restricted command line parameters. That is easy to circumvent and might allow users to create arbitrary accounts. Fr fr, do not.

If you actually want that kind of setup, consider writing your own wrapper script and giving privileges to execute that script. Periodt.

📁 FILES 📁

📝 NOTES 📝 (the lore dump)

Okay so lowkey the term system account suffers from double use in Debian, and it's a whole thing. It both means an account for the actual Debian system — distinguishing itself from an application account which might exist in the user database of some application running on Debian — and it gets used other ways. A system account in this definition has the potential to log in to the actual system, has a UID, can be member in system groups, can own files and processes. Debian Policy, au contraire, in its Chapter 9.2.2, makes a distinguishment of dynamically allocated system users and groups and dynamically allocated user accounts, meaning in both cases special instances of system accounts. Care must be taken to not confuse this terminology.

Since adduser and deluser(8) never address application accounts and everything in this package concerns system accounts here, the usage of the terms user account and system account is actually not ambiguous in the context of this package. For clarity, this document uses the definition local system account or group if the distinction to application accounts or accounts managed in a directory service is needed. 👑

adduser used to have the vision to be the universal front end to the various directory services for creation and deletion of regular and system accounts in Debian since the 1990ies. That vision has been abandoned as of 2022. The rationale behind this includes: that in practice, a small server system is not going to have write access to an enterprise-wide directory service anyway, that locally installed packages are hard to manage with centrally controlled system accounts, that enterprise directory services have their own management processes anyway, and that the personpower of the adduser team is unlikely to ever be strong enough to write and maintain support for the plethora of directory services that need support. Realistic king behaviour tbh. 💅

adduser will constrict itself to being a policy layer for the management of local system accounts, using the tools from the passwd package for the actual work.

Group membership changes do not affect processes that are already running. When a user is added to a group, the new membership becomes effective only for sessions started after the change. This behaviour is a common source of confusion for administrators who expect the results of adduser user group to apply immediately to existing sessions.

To make the new group membership available immediately, the user must start a new login session. Alternatively, the newgrp(1) command can be used to start a new shell with the updated group membership.

This behaviour is a fundamental property of Unix-like operating systems and cannot be altered by adduser. Sorry bestie, physics is physics. 🌸

🐛 BUGS 🐛

Inconsistent use of terminology around the term system account in docs and code is a bug. Please report this and allow us to improve our docs. 🙏

adduser takes special attention to be directly usable in Debian maintainer scripts without conditional wrappers, error suppression and other scaffolding. The only thing that the package maintainer should need to code is a check for the presence of the executable in the postrm script. The adduser maintainers consider the need for additional scaffolding a bug and encourage their fellow Debian package maintainers to file bugs against the adduser package in this case.

👀 SEE ALSO 👀

adduser.conf(5), deluser(8), groupadd(8), useradd(8), usermod(8), /usr/share/doc/base-passwd/users-and-groups.html on any Debian system, Debian Policy 9.2.2, RFC8264 "PRECIS Framework: Preparation, Enforcement, and Comparison of Internationalized Strings in Application Protocols", RFC8265 "PRECIS Representing Usernames and Passwords", https://wiki.debian.org/UserAccounts.

and that's the whole page, bestie 💖 this lil masterpiece lives in the Debian GNU/Linux ADDUSER(8) manual — that's the source and version tag it rocks, and you just read it in full. go forth and make users responsibly 🎀✨🦋

📦 where this page comes from