mirror of
https://github.com/ostreedev/ostree.git
synced 2025-01-09 01:18:35 +03:00
81fa214155
This drops the `ot-composefs` kernel commandline in favour of a `[composefs]` section in the `prepare-rootfs.conf` file. You can set `composefs.enabled` to `signed`, `yes`, `no` or `maybe`, with `maybe` being the default. You can also set `composefs.keypath` (or rely on the default `/etc/ostree/initramfs-root-binding.key`) to point to ed25519 public keys, one of which which the commit must be signed with, or boot fails. The ostree dracut module adds `/etc/ostree/initramfs-root-binding.key` to the initrd if it exists. NOTE: This drop the option to define a digest in the commandline. However, that was currently unused (i.e. ComposefsConfig.expected_digest was never read). Additionally it very hard to actually store the composefs digest in the initrd, as the initrd is typically part of the commit and thus the composefs. It may be possible to handle this, but lets add it back when we know exactly how that will work.
157 lines
7.0 KiB
XML
157 lines
7.0 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
SPDX-License-Identifier: LGPL-2.0+
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library. If not, see <https://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
<refentry id="ostree">
|
|
|
|
<refentryinfo>
|
|
<title>ostree prepare-root</title>
|
|
<productname>OSTree</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Colin</firstname>
|
|
<surname>Walters</surname>
|
|
<email>walters@verbum.org</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>ostree prepare-root</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ostree-prepare-root</refname>
|
|
<refpurpose>Change the view of a mounted root filesystem to an ostree deployment</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>ostree prepare-root</command> <arg choice="req">TARGET</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
At its core, ostree operates on an existing mounted filesystem. Tooling such
|
|
as <literal>ostree admin deploy</literal> 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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The most common pattern today is to use systemd in an initramfs. The systemd
|
|
unit shipped upstream is ordered in this way:
|
|
|
|
<literal>After=sysroot.mount</literal> and <literal>Before=initrd-root-fs.target</literal>
|
|
</para>
|
|
|
|
<para>
|
|
When it runs, the mounted filesystem at the provided <literal>TARGET</literal> (usually <literal>/sysroot</literal>)
|
|
will be changed such that what appears at <literal>/sysroot</literal> 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 <literal>/sysroot/sysroot</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
For <literal>/var</literal>, by default a bind mount is created from the deployment root to <literal>/sysroot/var</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
A read-only bind mount is created over <literal>/sysroot/usr</literal>. The immutable bit is set on the deployment
|
|
root, so this provides basic protection for filesystem mutation. If the <literal>sysroot.readonly</literal>
|
|
option is enabled, instead a writable bind mount for <literal>/sysroot/etc</literal>, and everything else
|
|
is mounted read-only.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, when higher level tooling such as systemd performs a switch-root operation, what
|
|
was <literal>/sysroot</literal> becomes <literal>/</literal> 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 <literal>/sysroot</literal> which is now the "physical root".
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Configuration</title>
|
|
|
|
<para>
|
|
The <literal>/usr/lib/ostree/prepare-root.conf</literal> (or <literal>/etc/ostree/prepare-root.conf</literal>) config file is parsed by <literal>ostree-prepare-root</literal>. This file must
|
|
be present in the initramfs. The default dracut module will copy it from the real root if present.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><varname>sysroot.readonly</varname></term>
|
|
<listitem><para>A boolean value; the default is <literal>false</literal>. If this is set to <literal>true</literal>, then the <literal>/sysroot</literal> mount point is mounted read-only.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>composefs.enabled</varname></term>
|
|
<listitem><para>This can be <literal>yes</literal>, <literal>no</literal>. <literal>maybe</literal> or
|
|
<literal>signed</literal>. The default is <literal>maybe</literal>. If set to <literal>yes</literal> or
|
|
<literal>signed</literal>, then composefs is always used, and the boot fails if it is not
|
|
available. Additionally if set to <literal>signed</literal>, boot will fail if the image cannot be
|
|
validated by a public key. If set to <literal>maybe</literal>, then composefs is used if supported.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>composefs.keypath</varname></term>
|
|
<listitem><para>Path to a file with Ed25519 public keys in the initramfs, used if
|
|
<literal>composefs.enabled</literal> is set to <literal>signed</literal>. The default value for this is
|
|
<literal>/etc/ostree/initramfs-root-binding.key</literal>. 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.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>systemd</title>
|
|
|
|
<para>
|
|
As mentioned above, this tool comes with a systemd unit file <literal>ostree-prepare-root.service</literal>
|
|
and it is primarily expected to be invoked this way.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Composefs</title>
|
|
|
|
<para>
|
|
The default for ostree is to create a plain hardlinked filesystem tree.
|
|
composefs support is currently experimental; see the upstream <literal>doc/composefs.md</literal>
|
|
for more information on using it.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|