Userborn

Declaratively bear (manage) Linux users and groups.

Features

• Create system (UID < 1000) and normal (UID >= 1000) users.
• Update user (password, description (gecos), home directory, shell) and group (members) information.
• Prohibit UID/GID re-use.
• Simple JSON config format with a JSON Schema.
• Create per-user groups if no explicit primary group is provided.
• Warn about insecure password hashing schemes.
• Manage /etc/subuid and /etc/subgid for rootless containers.

Getting Started

NixOS

Userborn is available in Nixpkgs. To enable it:

services.userborn.enable = true;

Other Distros

While Userborn finds its origin in NixOS, it has been designed to work on any distro. However, there are currently no ready-to-use integrations for other distros. If you're interested in adding one, please reach out to me!

Nondestructivity

• Never deletes a user or group, only disables them when they are not present in the config anymore.
• Never changes the UID of an existing user or the GID of an existing group.
• Never removes a subordinate UID/GID range from /etc/sub{u,g}id for an owner that no longer requests one, so the range cannot be reassigned to a different owner.
• The file mode, uid, and gid of the /etc/{group,passwd,shadow} files is never changed. If the files already exist before Userborn runs for the first time it will retain these values.

This prohibits UID/GID re-use which is a security issue. The danger of UID/GID re-use is best illustrated by an example. Imagine the following scenario:

• A new user with the UID 1000 is created. The user creates all sorts of files owned by them (via their UID).
• This user is deleted, their UID is freed up.
• A new user (with a different username) is created and gets allocated a new UID. The allocation algorithm doesn't know that previously a user with the UID 1000 existed so it allocates UID 1000 to the new user.
• This user can now access files from a previously existing user because their UIDs are the same.

Limitations to Nondestructivity

• Userborn can handle comments in the password database files but it will silently discard them.
• Userborn will sort the password database files by GID/UID. This influences only the representation inside the text files but doesn't change the way group/user resolution works.
• Userborn will discard entries in the shadow database that are not present in the passwd database. It will warn about these inconsistent entries.

Mutable Users

Userborn support mutable users. This feature allows you to manage some users via Userborn and manage other users imperatively with tools like useradd, usermod, etc.

When the mutable user feature is enabled by setting USERBORN_MUTABLE_USERS = true, only users and groups that were already in the previous config are disabled and drained. All other users/groups remain enabled.

Userborn will still "re-take" control of users/groups that were imperatively created and later added to the Userborn config. For example:

• You imperatively create a user with useradd called normalo.
• Userborn will keep it enabled as long as the user is not in the Userborn config.
• You now add a config for the user normalo to your Userborn config setting a different password.
• On the next invocation, Userborn will update the password of the user normalo and take full ownership of the entire user.
• When you now remove the user from the config, Userborn will disable the user on the next invocation.

Subordinate UID/GID Ranges

Userborn writes /etc/subuid and /etc/subgid so that tools like newuidmap/newgidmap (used by rootless Podman, Docker, and similar) work out of the box.

Per user you can either:

• list explicit ranges via subUidRanges / subGidRanges, which are written verbatim, or
• set autoSubIdRange: true to have Userborn allocate a single 65536-wide range at or above 100000 that does not overlap any other owner's ranges.

Auto-allocated ranges are stable: once written they are read back from /etc/sub{u,g}id on subsequent runs and never moved, even if other ranges change around them. As with UIDs, entries for owners that disappear from the config are kept so the range cannot be reused by a different owner.

If the resulting set of ranges overlaps across distinct owners (which can only happen via explicit configuration or pre-existing on-disk state), Userborn refuses to write /etc/sub{u,g}id and exits with an error. The other databases (passwd, group, shadow) are still written.

Configuration

You can configure Userborn during runtime via the provided config file and via environment variables.

Config

The config file is specified in a provided JSON schema which you can use to see available options and to validate your config.

Environment Variables

• USERBORN_MUTABLE_USERS: Set this to the string true if you want to enable mutable users.
• USERBORN_PREVIOUS_CONFIG: Set this to the path of the previous Userborn config. This is necessary when you enable mutable users. Otherwise, this variable is ignored. It is your responsibility to update this on each change of the Userborn config.

Building Userborn

Runtime dependencies:

• libxcrypt

Build-Time Parameters

You can configure Userborn via compile-time environment variables:

• USERBORN_NO_LOGIN_DEFAULT_PATH: Set this to the default path of the nologin binary in your distro or system. If this is not set, the value /run/current-system/sw/bin/nologin is used which will only make sense on NixOS.

Comparison With Other Tools for Declarative User Management

systemd-sysusers

Userborn follows the same spirit as systemd-sysusers and indeed can be viewed as an adaptation of sysusers to a more specialized system where the service takes full ownership of the user database (i.e. also changes certain fields of entries).

Userborn has two key differences from systemd-sysusers:

1. Does not only create system users (UID < 1000) but also normal users. In the systemd world, "normal" users wouldn't have an entry in /etc/{group,passwd,shadow}. Userborn, however affords them one of these entries, not because the systemd way is wrong or bad but because this way is easier and fully backwards compatible.
2. Takes full ownership of the password database and thus also (destructively) changes user entries. For example, it can change passwords, home directories, default shell, etc. Please see the Nondestructivity section for details of what Userborn can change and what it will never change.

NixOS update-users-groups.pl

Userborn:

1. Doesn't use perl.
2. Runs as a systemd service, not as an activation script.
3. Doesn't rely on a hidden database to track state over the lifetime of a system.
4. Supports mounting /etc via an (immutable, read-only) overlay.

Limitations

• Currently doesn't support group passwords (and thus also doesn't support /etc/gshadow).