NAME

       ostree-prepare-root - Change the view of a mounted root filesystem to an ostree deployment

SYNOPSIS

       ostree prepare-root {TARGET}

DESCRIPTION

       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".

CONFIGURATION

       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.readonly
           A 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.transient
           A 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.transient
           A 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.enabled
           This can be yes, no.  maybe or signed. The default is maybe. 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. If
           set to maybe, then composefs is used if supported.

       composefs.keypath
           Path 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.

SYSTEMD

       As mentioned above, this tool comes with a systemd unit file ostree-prepare-root.service
       and it is primarily expected to be invoked this way.

COMPOSEFS

       The default for ostree is to create a plain hardlinked filesystem tree. composefs support
       is currently experimental; see the upstream doc/composefs.md for more information on using
       it.