Skip to content

docs: Describe systemd-sysext and confext as distribution-dependent #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jmarrero-bot wants to merge 1 commit into from
Closed

docs: Describe systemd-sysext and confext as distribution-dependent #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 16 additions & 12 deletions docs/src/bootc-filesystem.7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,14 +113,15 @@ undefined behavior. There is a check for this in `bootc container lint`.

### systemd-confext and systemd-sysext

[systemd-confext](https://www.freedesktop.org/software/systemd/man/systemd-confext.html)
and [systemd-sysext](https://www.freedesktop.org/software/systemd/man/systemd-sysext.html)
are not currently supported on bootc-managed systems.
The aim of the bootc project is to work together with
[systemd-sysext](https://www.freedesktop.org/software/systemd/man/systemd-sysext.html)
and [systemd-confext](https://www.freedesktop.org/software/systemd/man/systemd-confext.html).
A discussion in [bootc#7](https://github.com/bootc-dev/bootc/issues/7)
explores a more integrated approach.

These tools may be present in the operating system image (for example, because
they ship in the `systemd` package), but bootc has not validated them on deployed
systems. Using them on a bootc host is not recommended. There are two categories
of concern to be aware of.
Support for them today depends mostly on the distribution: the version of
systemd it ships, and distribution-specific technologies such as SELinux.
There are two categories of concern to be aware of.

#### Conflicts with transient overlays

@jmarrero jmarrero Nov 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not keep the heading here when we start talking about the overlay limitations?

@jmarrero-bot jmarrero-bot Nov 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 37ccf9f: the "Conflicts with transient overlays" heading is back, with its original first paragraph, and the intro again ends with "There are two categories of concern to be aware of." One paragraph in that section still differs from upstream: the /etc note (lines 137-142) replaces the nonexistent etc = none with the real [etc] mount options and says when each leaves room for confext.


Expand All @@ -133,9 +134,12 @@ stacking. The Linux kernel limits filesystem stacking depth
(`FILESYSTEM_MAX_STACK_DEPTH = 2`), so combining these features can exhaust the
available depth and cause confext or sysext overlays to fail.

The `/etc` case in particular is expected to become tractable: configuring the
composefs backend with `etc = none` (there is not yet a corresponding ostree
knob) leaves `/etc` free for confext to manage.
For `/etc`, the composefs backend's default `bind` mount puts the deployment's
state directory over `/etc`, even with transient root enabled, so it leaves
room for confext. `[etc] mount = "none"` (which has no ostree equivalent yet)
adds no overlay of its own either, but with transient root `/etc` is then
inside the root overlay. Both are documented with the composefs
[root setup configuration](man/bootc-setup-root-conf.5.md).

#### OS-specific integration concerns

@jmarrero jmarrero Nov 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably not remove this section...

@jmarrero-bot jmarrero-bot Nov 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restored in 37ccf9f: "OS-specific integration concerns" is back word for word. Below it, the per-host configuration paragraph keeps one change, "use … instead" → "see also", because "instead" steers readers away from confext.


Expand All @@ -144,8 +148,8 @@ integration issues (for example, SELinux labeling) that are specific to a
particular OS or distribution. Consult your OS/distribution documentation for
guidance on confext and sysext.

For per-host configuration, use the patterns described in
[Building images: Configuration](building/bootc-building-images.7.md#configuration) instead:
For per-host configuration, see also the patterns described in
[Building images: Configuration](building/bootc-building-images.7.md#configuration):
image-embedded configuration (prefer `/usr` where possible), persistent `/etc`
with day-2 configuration management tools, or machine-local kernel arguments
via `rpm-ostree kargs` or `/usr/lib/bootc/kargs.d`.
Expand Down