1OSTREE PREPARE-ROOT(1) ostree prepare-root OSTREE PREPARE-ROOT(1)
2
6 ostree-prepare-root - Change the view of a mounted root filesystem to
7 an ostree deployment
8
10 ostree prepare-root {TARGET}
11
13 At its core, ostree operates on an existing mounted filesystem. Tooling
14 such as ostree admin deploy will create a new directory that can be
15 used as a bootable target. This tool is designed to run in an initramfs
16 and set up "remapping" mounts as a view into that filesystem.
17 As of more recently, this tool also has optional support for composefs,
19 which creates a distinct mount point layered on top of the underlying
20 filesystem.
21 The most common pattern today is to use systemd in an initramfs. The
23 systemd unit shipped upstream is ordered in this way:
24 After=sysroot.mount and Before=initrd-root-fs.target
25 When it runs, the mounted filesystem at the provided TARGET (usually
27 /sysroot) will be changed such that what appears at /sysroot is
28 actually the "deployment root" - i.e. a particular versioned
29 subdirectory. What was formerly the "physical root" i.e. the real root
30 of the filesystem will appear as /sysroot/sysroot.
31 For /var, by default a bind mount is created from the deployment root
33 to /sysroot/var.
34 A read-only bind mount is created over /sysroot/usr. The immutable bit
36 is set on the deployment root, so this provides basic protection for
37 filesystem mutation. If the sysroot.readonly option is enabled, instead
38 a writable bind mount for /sysroot/etc, and everything else is mounted
39 read-only.
40 Finally, when higher level tooling such as systemd performs a
42 switch-root operation, what was /sysroot becomes / and after the
43 transition into the real root, the system will be booted into the
44 "deployment", which is a versioned immutable filesystem tree. The
45 ostree tooling running in the real root thereafter performs further
46 changes by operating on /sysroot which is now the "physical root".
47
49 The /usr/lib/ostree/prepare-root.conf (or
50 /etc/ostree/prepare-root.conf) config file is parsed by
51 ostree-prepare-root. This file must be present in the initramfs. The
52 default dracut module will copy it from the real root if present.
53 sysroot.readonly
55 A boolean value; the default is false. If this is set to true, then
56 the /sysroot mount point is mounted read-only.
57 etc.transient
59 A boolean value; the default is false. If this is set to true, then
60 the /etc mount point is mounted transiently i.e. a non-persistent
61 location.
62 composefs.enabled
64 This can be yes, no. maybe or signed. The default is maybe. If set
65 to yes or signed, then composefs is always used, and the boot fails
66 if it is not available. Additionally if set to signed, boot will
67 fail if the image cannot be validated by a public key. If set to
68 maybe, then composefs is used if supported.
69 composefs.keypath
71 Path to a file with Ed25519 public keys in the initramfs, used if
72 composefs.enabled is set to signed. The default value for this is
73 /etc/ostree/initramfs-root-binding.key. For a valid signed boot the
74 target OSTree commit must be signed by at least one public key in
75 this file, and the commitfs digest listed in the commit must match
76 the target composefs image.
77
79 As mentioned above, this tool comes with a systemd unit file
80 ostree-prepare-root.service and it is primarily expected to be invoked
81 this way.
82
84 The default for ostree is to create a plain hardlinked filesystem tree.
85 composefs support is currently experimental; see the upstream
86 doc/composefs.md for more information on using it.
87OSTree OSTREE PREPARE-ROOT(1)