mirror of
https://github.com/ostreedev/ostree.git
synced 2024-12-22 17:35:55 +03:00
92b1a27202
In the OSTree model, executables go in `/usr`, state in `/var` and configuration in `/etc`. Software that lives in `/opt` however messes this up because it often mixes code *and* state, making it harder to manage. More generally, it's sometimes useful to have the OSTree commit contain code under a certain path, but still allow that path to be writable by software and the sysadmin at runtime (`/usr/local` is another instance). Add the concept of state overlays. A state overlay is an overlayfs mount whose upper directory, which contains unmanaged state, is carried forward on top of a lower directory, containing OSTree-managed files. In the example of `/usr/local`, OSTree commits can ship content there, all while allowing users to e.g. add scripts in `/usr/local/bin` when booted into that commit. Some reconciliation logic is executed whenever the base is updated so that newer files in the base are never shadowed by a copied up version in the upper directory. This matches RPM semantics when upgrading packages whose files may have been modified. For ease of integration, this is exposed as a systemd template unit which any downstream distro/user can enable. The instance name is the mountpath in escaped systemd path notation (e.g. `ostree-state-overlay@usr-local.service`). See discussions in https://github.com/ostreedev/ostree/issues/3113 for more details.
108 lines
3.8 KiB
XML
108 lines
3.8 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">
|
|
|
|
<!--
|
|
Copyright 2023 Red Hat Inc.
|
|
|
|
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, write to the
|
|
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
Boston, MA 02111-1307, USA.
|
|
-->
|
|
|
|
<refentry id="ostree-state-overlay@.service">
|
|
|
|
<refentryinfo>
|
|
<title>ostree-state-overlay</title>
|
|
<productname>ostree</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Jonathan</firstname>
|
|
<surname>Lebon</surname>
|
|
<email>jonathan@jlebon.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>ostree-state-overlay</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ostree-state-overlay@.service</refname>
|
|
<refpurpose>Set up state overlays</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<para><filename>ostree-state-overlay@.service</filename></para>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Experimental</title>
|
|
<para>
|
|
<emphasis role="bold">Note this feature is currently considered
|
|
experimental.</emphasis> It may not work correctly and some of its
|
|
semantics may be subject to change. Positive or negative feedback are both
|
|
welcome and may be provided at
|
|
<ulink url="https://github.com/ostreedev/ostree/discussions"/>. If using
|
|
the feature via rpm-ostree, feedback may also be provided at
|
|
<ulink url="https://github.com/coreos/rpm-ostree/issues/233"/>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
In some cases, it's useful to be able to have a directory as part of the
|
|
OSTree commit yet still have this directory be writable client-side. One
|
|
example is software that ships in <filename>/opt</filename>.
|
|
<filename>/opt</filename> is its own vendor-namespaced alternate file
|
|
hierarchy which may contain both code and state. With state overlays, it's
|
|
possible to have the code part baked in the OSTree, but still allowing the
|
|
directory to be writable so that state can be kept there.
|
|
</para>
|
|
|
|
<para>
|
|
Since it's writable, nothing prevents sufficiently privileged code to
|
|
modify or delete content that comes from the OSTree commit. This is in
|
|
sharp contrast with content in <filename>/usr</filename>, and more
|
|
closely matches a package manager-based distro.
|
|
</para>
|
|
|
|
<para>
|
|
Crucially, this state is automatically rebased during upgrades (or more
|
|
generally, anytime a different OSTree commit is booted). The semantics
|
|
of the rebase are as follows: any state file or directory that modified
|
|
OSTree content is deleted, otherwise it is kept and merged onto the new
|
|
base content (using overlayfs). This mostly matches the semantics of a
|
|
package manager.
|
|
</para>
|
|
|
|
<para>
|
|
To enable this feature, simply instantiate the unit template, using the
|
|
target path (in escaped systemd path notation) as the instance name. For
|
|
example, to enable it on <filename>/opt</filename>:
|
|
</para>
|
|
|
|
<literallayout>
|
|
$ systemctl enable --now ostree-state-overlay@opt.service
|
|
</literallayout>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|