Translations: English - Português (Brasil)

Contents

  1. Basics and History
    1. How passwords are stored
  2. These tools do we have in Debian
    1. adduser
    2. src:shadow
    3. systemd
    4. non-traditional methods of user account management
      1. LDAP
      2. Active Directory
      3. NIS
  3. Creating Users
    1. Choosing a user or group name
      1. Debian
        1. general restrictions
        2. system accounts
        3. regular user accounts
  4. Valid User Names
  5. Auxiliary packages that interact with users and groups
    1. base-passwd
    2. dpkg
    3. systemd-sysusers
    4. libc
    5. pam
    6. Debian Policy
  6. Links

Basics and History

In a Unix OS (and in many other other non-unix OS), a user of a computer is required to authenticate themselves so that the OS may track (or account) their use of the computer. This account can be further traced back to the person themselves when the OS is audited. User account names serve as unique identifiers for users who interact with the system.

The entities in Unix and Unix-like systems like GNU/Linux and Debian are called users (more exactly, user accounts) and groups. Users and Groups do have alphanumeric names and are mapped in system software to numeric IDs (commonly called user id, uid and group id, gid). The Linux kernel does not have a notion of the alphanumeric names and handles numeric IDs only. The "database" holding this information is traditionally in text files like /etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow. See passwd(5) and the associated other manual pages for detailed documentation of the format.

It might be important to note that the documentation does not say how long a user name is supposed to be and what kind of encoding is being used. There are technical limits though:

While other Operating Systems like the BSDs may compile the text file user database into databases of some sort, Debian and most other GNU/Linux based Operating Systems use the text files directly.

How passwords are stored

Traditionally, /etc/passwd held the passwords associated with users and groups directly. A salted hash of the password replaced the plain text passwords pretty quickly. The regular passwd file must be readable for everybody or it would not be possible for tools like ls to display the alphanumeric names of file and directory owners. As brute forcing of hashes became possible, the password hashes were moved to a dedicated file, /etc/shadow, that could be restricted to be only readable for privileged processes.

Having passwords directly in /etc/passwd is still configurable, but has not been in wide use at least since the mid 1990ies. It is recommended to leave the respective setting at its default, keeping passwords in /etc/shadow, owned by root:shadow, with an access mode of 0640.

These tools do we have in Debian

adduser

The Debian-specific tools to add and remove an account are adduser and deluser from the adduser package. These tools act as a front-end to the low level tools and have intelligence to honor Debian specialties. They are configurable so that you can adapt them to your local policies and needs. They offer different operation modes for local user accounts (for use by the local administrator) and for system accounts (mainly for use by package maintainers to create package-related accounts during package installation, but of course also freely usable for the local administrator).

adduser is maintained on Salsa as a Debian native package.

Most Debian derivatives and pure blends also use Debian's adduser and deluser. Other Operating Systems might have their own implementations, probably even using the same names, but a different syntax.

adduser is configurable about what makes a valid system or non-system (regular) user name, but it relies on src:shadow to create the actual account. And src:shadow has become more restrictive in its rules in late 2024, and is not configurable. Hence, adduser's configurability does not make much sense any more.

src:shadow

Most of the low level tools used to manage user accounts and passwords that directly interface with the user database come from the passwd package:

Since the source package for passwd is called shadow without building a binary package of that name for historical reasons, the source package is frequently refered to as src:shadow to avoid confusion.

These tools have the reputation of being rather low-level, but have evolved to being nearly as full-featured as adduser. They are likely to exist and work on non-Debian systems as well, albeit maybe with a different feature set due to the long history of this package.

src:shadow has an Upstream that is not associated with Debian. The Debian packages are maintained on Salsa as well.

src:shadow in Debian is patched to cater for Debian's special needs and policies. There is an effort going on to reduce the amount of such patches beginning with the Trixie/Debian 13 development cycle.

src:shadow is somewhat authoritative in defining what is valid user/group name. It is designed to have rather limited configurability and is being used in other Operating Systems. Debian has limited influence on those upstream decisions.

systemd

systemd interfaces with the user database by way of systemd-sysusers which is a declarative way of creating system accounts and systemd-homed which introduces a new way to handle user's home directories. Other parts of systemd do also interact with the user database.

systemd has its own view on what consists a valid user name, which is stricter than our method in some regards, and more relaxed in others. See below for a link to systemd's relevant documentation.

non-traditional methods of user account management

If you use non-traditional methods of user account management, you need different tools that might get covered here eventually. Volunteering to write those chapters would be greatly appreciated.

LDAP

insert text here

Active Directory

insert text here

NIS

NIS is understood to be going away. Some packages have already removed their NIS features. This might be caused by lack of maintenance, so you might be willing to offer assistance if you want to keep NIS in Debian.

Creating Users

Elaborate about the difference between adduser, useradd and declarative approaches.

Choosing a user or group name

The choice of user and group name can range from practical and straightforward to unconventional and bizarre. Numerous independent and sometimes contradicting conventions to choose user names exist. Security also plays a role here since strange characters in user name might lead to security vulnerabilities.

The PRECIS Framework (Preparation, Enforcement, and Comparison of Internationalized Strings in Application Protocols) is documented in some RFCs listed below and gives important advice and guidelines how to handle user names. Adduser at least hast not given much attention to this until lately.

Debian

Debian formally has two types of accounts and account names: system accounts and non-system (regular) user accounts. This distinctions mainly are different ranges of numeric UIDs/GIDs and in different regexes being applied to allow/disallow characters in account and group names.

general restrictions

Some restrictions should be applied to all kinds of user and group names for technical and security reasons. For example, the colon is used in /etc/passwd as a field separator and the specs don't contain any language about escaping, so it is widely accepted that a user name should not contain colons. Some tools reading /etc/passwd consider the backslash an escape character, others do not. Additionally, the user name is usually used as part of the path to the home directory and should thus not contain characters that might be problematic in file names, such as slashes.

For security reasons, characters that might be used for code injection in various scripts (interpunction, whitespace) should also be avoided because of course user names are processed in various ways in scripts and programs written in a wide variety of programming languages.

Characters that might confuse (or control) output devices are another bad idea in a user name. This includes the classical control characters such as line feed, carriage return, or form feed, but also Unicode control characters such as combining characters and/or right-to-left control characters.

To avoid confusion with numeric UIDs, user names that consist entirely of digits are problematic. Starting with a hyphen might confuse user names with command line options, and also with negative numbers.

That being said, some corner cases create conflicts, for example some site might want to use e-mail addresses (containing @) as user names, while in Windows/Samba installations Dollar Signs and Backslashes are common in user names. Dots in user names commonly separate first and last names, but are for example problematic in shell scripts (mainly in chown, which changed its syntax from user.group to user:group for this reason).

Whitespace inside user names is technically possible even in PRECIS, but this will make thousands of shell scripts break.

In Debian (and most other Linux distributions), user names are case sensitive.

Length of user names is also an issue.

Creating user names containing Unicode characters like ä or ꭥ is possible in Debian 12. However, no normalization is done on such user names which will lead to unintended behavior and possible security risks.

Some additional basic sanity restrictions should be adopted and enforced. None of the suggestions from PRECIS and/or the systemd project are fully suited for Debian though, so we need to do our own definition.

It makes sense to at least disallow:

Upstream src:shadow applies this restrictive ruleset:

It makes sense to use the same rules for group names.

system accounts

System accounts are the accounts that are in the default user database as delivered and maintained automatically by base-passwd, and those created on package installation from the maintainer scripts.

adduser restricts system accounts rather severely. System account names must start with a lower case letter or an underscore, followed by lower case letters, digits, underscores, and dashes. There is a maximum length of 32 characters.

A local administrator might change the sets of accepted characters, but changing to a more restrictive character set might cause installation of packages to fail. There is only minimal testing for these cases; administrators who decide to break their systems that way are entitled to keep all pieces. In addition, configuring adduser to accept strange characters will probably only result in the underlying useradd rejecting the user name.

Policy suggests that account names belonging to a package are prefixed with an underscore to avoid name space collisions. Older packages may use other methods to avoid this, such as prefixing Debian-. Existing packages do not need to change to the new convention. There is currently no discussion in Debian to change this. It is widely believed that the current state of policy and code is a good and practical solution.

regular user accounts

Regular (non-system) user accounts are those that might be associated with real life persons, functions or roles and are under the control of the local Admin.

adduser does impose less strict restrictions on those by default and can be configured to accept user names to the discretion of the local Administrator. useradd's restrictions still do apply.

adduser's behavior can be influenced by the --allow-bad-names option which weakens the user name check and the --allow-all-names option that just passes the selected user name to useradd, leaving the decision whether to accept the name or not to useradd. It is currently unclear whether this is a good idea.

Valid User Names

This chapter is supposed to cover what Debian considers a valid user name and will include information about what we expect to work and what we know to not work. It will somehow find a way between documenting the current state of affairs and where we want to go. Sadly, this is still work to be done.

In Debian, it looks like the user name in /etc/passwd is naively UTF-8 encoded. It is therefore possible to create accounts with a unicode user name. Some unicode characters might be longer than one byte in the encoded form and therefore reduce the possible length of the user name (whose limits are to be considered in bytes, not in characters). However, no canonicalization is done to those user names which causes multiple issues outlined below.

There is a noticeable specification gap, and the current behavior was empirically determined. Tools might change behavior in the future.

In November 2024, there was a discussion about this topic on debian-devel which also got some coverage in Linux Weekly News. The main result of this discussion was that the adduser maintainer stepping back from his idea to officially allow UTF-8 in user names, shadow considerably tightening up its restrictions of user names, with adduser following suit.

There is a Proposed Internet Standard (RFC 8265) that states that a user name should only contain of the characters listed in the ?IdentifierClass (RFC 8264 Section 4.2) should be allowed. adduser will most probably change its default operation mode to this, if it's possible in a regular expression.

The ?IdentifierClass according to RFC 8264 is:

We need to discuss:

It is currently unclear how to destill this into a perl regexp and what test cases should be applied.

Auxiliary packages that interact with users and groups

This chapter contains a list of (source) packages that are affecting this page, user accounts, groups, and are affected the other way round. Maintainers of those packages, please mark your package in italics if you are aware of this Wiki page and in bold if you are willing to participate with maintaining those docs and adapt your package accordingly. If you have a page for your package on this Wiki, kindly link here.

base-passwd

base-passwd contains the canonical master copies of the user database files (/etc/passwd and /etc/group), containing the Debian-allocated user and group IDs.

dpkg

While dpkg currently does not interface with the user database, the maintainers do plan doing so in some future. See Teams/Dpkg/Spec/SysUser for details.

systemd-sysusers

systemd offers a declarative way to create system accounts at run time.

libc

libc contains various library routines that interface with the user database, allowing to map user and group names to users and groups.

pam

pam plays a lot of roles here as well. Please consider dumping your knowledge here.

Debian Policy

The Debian Policy Manual contains in its Chapter 9.2 some information about user and group names. Since it only covers the packaging side and deliberately leaves things open for discussion and further definition, this page exists.

Links

CategorySystemSecurity | CategorySystemAdministration