ostree-prepare-root — Change the view of a mounted root filesystem to an ostree deployment
ostree prepare-root {TARGET}
At its core, ostree operates on an existing mounted filesystem. Tooling such
as ostree admin deploy will create a new directory that can be
used as a bootable target. This tool is designed to run in an initramfs and
set up "remapping" mounts as a view into that filesystem.
As of more recently, this tool also has optional support for composefs, which creates a distinct mount point layered on top of the underlying filesystem.
The most common pattern today is to use systemd in an initramfs. The systemd
unit shipped upstream is ordered in this way:
After=sysroot.mount and Before=initrd-root-fs.target
When it runs, the mounted filesystem at the provided TARGET (usually /sysroot)
will be changed such that what appears at /sysroot is actually the
"deployment root" - i.e. a particular versioned subdirectory. What was formerly the
"physical root" i.e. the real root of the filesystem will appear as /sysroot/sysroot.
For /var, by default a bind mount is created from the deployment root to /sysroot/var.
A read-only bind mount is created over /sysroot/usr. The immutable bit (see chattr(1)) is set on the deployment
root, so this provides basic protection for filesystem mutation. If the sysroot.readonly
option is enabled, then /sysroot/sysroot is mounted read-only to provide further protection and a writable bind mount for
/sysroot/etc is created.
Finally, when higher level tooling such as systemd performs a switch-root operation, what
was /sysroot becomes / and after the transition into
the real root, the system will be booted into the "deployment", which is a versioned immutable
filesystem tree. The ostree tooling running in the real root thereafter performs further changes
by operating on /sysroot which is now the "physical root".
The /usr/lib/ostree/prepare-root.conf (or /etc/ostree/prepare-root.conf) config file is parsed by ostree-prepare-root. This file must
be present in the initramfs. The default dracut module will copy it from the real root if present.
sysroot.readonlyA boolean value; the default is false unless composefs is enabled. If this is set to true, then the /sysroot mount point is mounted read-only.
etc.transientA boolean value; the default is false. If this is set to true, then the /etc mount point is mounted transiently i.e. a non-persistent location.
root.transientA boolean value; the default is false.
If this is set to true, then the / filesystem will be a writable overlayfs,
with the upper directory being a hidden directory (in the underlying system root filesystem) that will persist across reboots by default.
However, changes will be discarded on OS updates!
Enabling this option can be very useful for cases such as packages (dpkg/rpm/etc) that write content into /opt,
particularly where they expect the target to be writable at runtime. To make that work, ensure that your /opt
directory is *not* a symlink to /var/opt, but is just an empty directory.
Note the /usr mount point remains read-only by default. This option is independent of etc.transient and sysroot.readonly;
it is supported for example to have root.transient=true but etc.transient=false in which case changes to /etc continue
to persist across updates, with the default OSTree 3-way merge applied.
composefs.enabledThis can be yes, no, maybe,
or signed. The default is no. If set to yes or
signed, then composefs is always used, and the boot fails if it is not
available. Additionally if set to signed, boot will fail if the image cannot be
validated by a public key. Setting this to maybe is currently equivalent to no.
composefs.keypathPath to a file with Ed25519 public keys in the initramfs, used if
composefs.enabled is set to signed. The default value for this is
/etc/ostree/initramfs-root-binding.key. For a valid signed boot the target OSTree
commit must be signed by at least one public key in this file, and the commitfs digest listed in the
commit must match the target composefs image.
The following kernel commandline parameters are also parsed:
ostree.prepare-root.composefsThis accepts the same values as composefs.enabled above, and overrides the config file (if present).
For example, specifying ostree.prepare-root.composefs=0 will disable composefs, even if it is enabled by default in the initrd config.