Skip to content

docs: Document that systemd-confext and sysext are unsupported #2436

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

Open
mohan-shash wants to merge 1 commit into
base: main
Choose a base branch
from
+30 −0
Open

docs: Document that systemd-confext and sysext are unsupported #2436

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
30 changes: 30 additions & 0 deletions docs/src/filesystem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,36 @@ view of `/etc`. This should generally be considered an internal implementation d
of bootc/ostree. Do *not* explicitly put files into this location, it can create
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.

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.

A key reason is that bootc systems commonly use composefs for the root filesystem,
and may also enable [transient root](#enabling-transient-root) and/or
[transient `/etc`](#enabling-transient-etc). Each of these features uses overlayfs
stacking. The Linux kernel limits filesystem stacking depth
(`FILESYSTEM_MAX_STACK_DEPTH = 2`), so combining composefs with transient `/etc`
already consumes the available depth. Adding confext or sysext overlays on top
of that is likely to fail.

For these reasons, transient `/etc` and systemd-confext should be treated as
mutually exclusive today.

@HarshwardhanPatil07 HarshwardhanPatil07 Sep 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This reason made me more sense if we could have

"transient /etc and systemd-confext should be treated as mutually exclusive today." line above the line

A key reason is that bootc systems commonly use

as a beginner who read this first time, this is what came in my mind

Suggested change
mutually exclusive today.
For these reasons, transient `/etc` and systemd-confext should be treated as
mutually exclusive today.
A key reason is that bootc systems commonly use composefs for the root filesystem,
and may also enable [transient root](#enabling-transient-root) and/or
[transient `/etc`](#enabling-transient-etc). Each of these features uses overlayfs
stacking. The Linux kernel limits filesystem stacking depth
(`FILESYSTEM_MAX_STACK_DEPTH = 2`), so combining composefs with transient `/etc`
already consumes the available depth. Adding confext or sysext overlays on top
of that is likely to fail.


For per-host configuration, use the patterns described in
[Building images: Configuration](building/guidance.md#configuration) instead:
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`.

For more on the design rationale, see
[Relationship with systemd "particles"](relationship-particles.md).

## `/var`

Content in `/var` persists by default; it is however supported to make it or subdirectories
Expand Down