1OSTREE PREPARE-ROOT(1)        ostree prepare-root       OSTREE PREPARE-ROOT(1)
2
3
4

NAME

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

SYNOPSIS

10       ostree prepare-root {TARGET}
11

DESCRIPTION

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
18       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
22       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
26       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
32       For /var, by default a bind mount is created from the deployment root
33       to /sysroot/var.
34
35       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
41       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

CONFIGURATION

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
54       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
58       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
63       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
70       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

SYSTEMD

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

COMPOSEFS

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.
87
88
89
90OSTree                                                  OSTREE PREPARE-ROOT(1)
Impressum