systemd-sysusers

Create system users and groups

TLDR

Create users and groups from a specific configuration file

$ systemd-sysusers [path/to/file]

Process configuration files and print what would be done without actually doing anything

$ systemd-sysusers --dry-run [path/to/file]

Print the contents of all configuration files (before each file, its name is printed as a comment)

$ systemd-sysusers --cat-config

Create users based on files listed in the previous command

$ systemd-sysusers

SYNOPSIS

systemd-sysusers [OPTIONS] [PATH...]

-h, --help
    Show a short help message and exit.

--version
    Show a short version string and exit.

--root=PATH
    Operate on an alternate root directory, useful for chroot or container environments.

--config-root=PATH
    Specifies an alternate root for configuration directories (e.g., sysusers.d).

--build-image[=PATH]
    Similar to --root, but also adjusts default paths for building container images.

--defined-only
    Only process users and groups explicitly defined in configuration files, skipping any implicit system defaults.

--uid-min=UID, --uid-max=UID
    Defines the minimum and maximum UIDs for dynamically allocated users.

--gid-min=GID, --gid-max=GID
    Defines the minimum and maximum GIDs for dynamically allocated groups.

--first-system-uid=UID, --last-system-uid=UID
    Defines the range for statically allocated system UIDs.

--first-system-gid=GID, --last-system-gid=GID
    Defines the range for statically allocated system GIDs.

--force
    Force creation of users/groups even if they conflict with existing entries (e.g., UID/GID already taken).

--json=pretty|short|long|json
    Format output as JSON for programmatic parsing.

--dry-run
    Perform a trial run without actually creating or modifying any users or groups.

--verbose
    Print more verbose debug output during operation.

--sync
    Synchronize the database with the configuration files, used by sysusers.target.

DESCRIPTION

systemd-sysusers is a utility that creates system users and groups based on declarative configuration files, typically located in `/usr/lib/sysusers.d/`, `/etc/sysusers.d/`, and `/run/sysusers.d/`. It processes these files, which define users and groups along with their UIDs, GIDs, home directories, and shells, and ensures their existence on the system. This mechanism is an integral part of the systemd ecosystem, providing a robust and standardized way for services and packages to declare their required runtime identities. Unlike traditional user management tools, systemd-sysusers is idempotent, meaning it can be run multiple times safely; it only creates entities that don't already exist. It focuses solely on the creation of system users and groups (often those with low UIDs/GIDs) and does not handle their deletion or general user account management.

CAVEATS

systemd-sysusers is a creation-only tool; it will not delete or modify existing users/groups beyond their initial setup. If an entry is removed from a .sysusers file, the corresponding user or group will not be automatically removed from the system. It is primarily designed for managing system-level identities, not regular user accounts. Using --force should be done with caution, as it can lead to UID/GID conflicts if misused.

CONFIGURATION FILES

Configuration is read from .conf files located in three primary directories, processed in the following order of precedence:

1. /etc/sysusers.d/: For local overrides and custom definitions.
2. /run/sysusers.d/: For volatile runtime definitions.
3. /usr/lib/sysusers.d/: For definitions provided by installed packages.

Files or symlinks ending with .conf.d or containing other suffixes are ignored. Empty files are also ignored.

FILE FORMAT (SYSUSERS.D(5) SYNTAX)

Each line in a .sysusers file defines a user or group. Lines starting with # are comments.

For Users:
u <name> [<id>] [<gid>] [<gecos>] [<home>] [<shell>]

<name>: The user name.
<id>: Optional UID. If omitted, a dynamic UID is allocated from the system range.
<gid>: Optional primary GID. If omitted, it defaults to the UID or a dynamically allocated GID.
<gecos>: Optional GECOS field (full name/comment).
<home>: Optional home directory. Defaults to / if omitted.
<shell>: Optional login shell. Defaults to /sbin/nologin if omitted.

For Groups:
g <name> [<id>] [<members>]

<name>: The group name.
<id>: Optional GID. If omitted, a dynamic GID is allocated from the system range.
<members>: Optional comma-separated list of user names to be added as additional group members.

Dynamic UIDs/GIDs are allocated from ranges like 900-999 by default, but can be configured via command-line options or /etc/systemd/system.conf.d/.

HISTORY

systemd-sysusers was developed as part of the systemd project to provide a declarative and robust method for creating system users and groups required by services. Before its introduction, such tasks often relied on imperative shell scripts in package pre/post-installation stages, which could be less reliable and harder to manage. It aims to standardize user/group setup, enhance security by promoting dedicated identities for services, and simplify dependency management within the systemd ecosystem.