Working with groups

In an atomic system, user group management has its own peculiarities. This page describes how the group mechanism works in ALT Atomic and how to add a user to the necessary groups.

How users and groups work in an atomic system

In a classic system, all users and groups are stored in /etc/passwd and /etc/group. In an atomic system based on bootc, the /etc directory is partially persistent (keeps between updates the files that were changed), and /usr is immutable (replaced entirely when the image is updated).

This creates a problem: when a system user appears in the new image (for example, a package adds a user for its service), it does not automatically get into the persistent /etc/passwd.

NSS altfiles

To solve this problem, the NSS altfiles module is used. It splits storage into two sources:

• /lib/passwd and /lib/group — system users and groups from the image (immutable, updated with the image)
• /etc/passwd and /etc/group — local users and groups (persistent, created on a specific machine)

For any user or group request (for example, getent group docker), the system first searches in /etc, then in /lib. Thus, system accounts are always up-to-date from the image, while local users persist between updates.

The altfiles configuration is done via /etc/nsswitch.conf:

passwd:     files altfiles systemd
shadow:     tcb files systemd
group:      files [SUCCESS=merge] altfiles [SUCCESS=merge] systemd role

APM automatically configures altfiles during the build of any image when the following conditions are met: atomic system, the libnss-altfiles package is present.

Adding users to groups

APM provides the sync-groups command, which adds users to specified groups based on YAML configs.

Configuration

Configs are read from two directories:

• /usr/share/apm/grpconf.d/ — configs from the image (added during build)
• /etc/apm/grpconf.d/ — user configs (can be added on a specific machine)

Config format (files .yaml or .yml):

sync:
  groups:
    - docker
    - libvirt
    - audio
    - video
  users:
    - dm
    - testuser

• groups — list of groups to which users should be added
• users — list of user selectors (optional)

If users is not specified, APM will automatically add all users from the wheel group with UID in the range 1000-60000.

User selectors

Each element of the users list is a selector of one of three types, with exactly one key specified in the element:

Selector	Example	Who it selects
name	- dm or - name: dm	user with this name
exact UID	- uid: 1000	users with this UID
UID range	- uid_range: {min: 1000, max: 60000}	all users with UID in the range (inclusive boundaries)

A string (- dm) is a shorthand for - name: dm; both forms are equivalent.

For uid_range, both boundaries can be omitted: by default min: 1000, max: 60000.

There can be any number of selectors, including several ranges — the final list of users is the union of all selectors without duplicates:

sync:
  groups:
    - docker
  users:
    - alice                # by name
    - uid: 1005            # by exact UID
    - uid_range:           # local users
        min: 1000
        max: 1999
    - uid_range:
        min: 50000
        max: 55000

Selectors only choose actually existing users from /etc/passwd and /lib/passwd — a range does not "create" anyone, and a non-existent name or UID is silently skipped. If no selector selected anyone (for example, on the first boot, when the user has not yet been created), the config is skipped entirely — the next run of sync-groups will catch up.

Typical scenarios

Assign groups to all local users:

sync:
  groups: [docker, audio, video]
  users:
    - uid_range:
        min: 1000
        max: 60000

Give the wheel group only to the first user (the first system administrator):

sync:
  groups: [wheel]
  users:
    - uid: 1000

Applying

Group synchronization:

apm system image sync-groups

The command:

1. Reads all .yaml/.yml files from /usr/share/apm/grpconf.d/ and /etc/apm/grpconf.d/
2. Resolves the users selectors of each config into a list of existing users
3. Adds users to groups, fixing the GID if it differs from the image
4. The operation is idempotent — repeated runs will not break anything

Configs are applied sequentially: if a group is mentioned in several files, it will get the union of users from all of them. A syntax error in any of the files aborts the synchronization entirely.

Automatic run

At system boot, sync-groups is automatically executed via the systemd service sync-users.service. This guarantees that after an image update, users will be in the correct groups.

Adding a user config

If you need to add a user to a group not covered by the image configs:

1. Create the file /etc/apm/grpconf.d/my-groups.yaml:

sync:
  groups:
    - docker
    - wireshark

2. Apply the changes:

apm system image sync-groups

Configs from /etc/apm/grpconf.d/ survive image updates, so your settings will be preserved.