https://github.com/nikstur/userborn
Declaratively bear (manage) Linux users and groups
https://github.com/nikstur/userborn
declarative groups linux nix nixos users
Last synced: 20 days ago
JSON representation
Declaratively bear (manage) Linux users and groups
- Host: GitHub
- URL: https://github.com/nikstur/userborn
- Owner: nikstur
- License: mit
- Created: 2024-07-22T19:33:25.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-16T16:14:32.000Z (about 1 month ago)
- Last Synced: 2025-04-10T01:06:54.333Z (20 days ago)
- Topics: declarative, groups, linux, nix, nixos, users
- Language: Rust
- Homepage:
- Size: 71.3 KB
- Stars: 76
- Watchers: 2
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - nikstur/userborn - Declaratively bear (manage) Linux users and groups (Rust)
- awesome-starred - nikstur/userborn - Declaratively bear (manage) Linux users and groups (Rust)
README
# 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.
- Create per-user groups if no explicit primary group is provided.
- Warn about insecure password hashing schemes.
### Where does it run?
It is undeniable that Userborn finds it's origin in NixOS. However, Userborn
has been designed to work on any distro. It is effectively distro-agnostic. It
will run on any Linux.
## Getting Started
### NixOS
Userborn is available in Nixpkgs (nixos-unstable). To enable it:
```nix
services.userborn.enable = true;
```
## 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.
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 differnent username) is created and get's 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.
## Configuration
You can configure Userborn during runtime via the provided config file and via
environment variables.
### Environment Variables
- `USERBORN_NO_LOGIN_PATH`: Set this to the path of the `nologin` binary on
your system. This path is used when the user config doesn't specify a
`shell`. If this enviroment variable is set, its value overrides
`USERBORN_NO_LOGIN_DEFAULT_PATH`.
## 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 [Idempotence
section](#Idempotence) 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`).