Add concept of state overlays

Makefile-boot.am

@@ -42,6 +42,7 @@ systemdsystemunit_DATA = src/boot/ostree-prepare-root.service \
 	src/boot/ostree-finalize-staged.service \
 	src/boot/ostree-finalize-staged.path \
 	src/boot/ostree-finalize-staged-hold.service \
+	src/boot/ostree-state-overlay@.service \
 	$(NULL)
 systemdtmpfilesdir = $(prefix)/lib/tmpfiles.d
 dist_systemdtmpfiles_DATA = src/boot/ostree-tmpfiles.conf
@@ -72,6 +73,7 @@ EXTRA_DIST += src/boot/dracut/module-setup.sh \
 	src/boot/ostree-remount.service \
 	src/boot/ostree-finalize-staged.service \
 	src/boot/ostree-finalize-staged-hold.service \
+	src/boot/ostree-state-overlay@.service \
 	src/boot/grub2/grub2-15_ostree \
 	src/boot/grub2/ostree-grub-generator \
 	$(NULL)

Makefile-man.am

@@ -49,13 +49,17 @@ endif
 
 man5_files = ostree.repo.5 ostree.repo-config.5
 
+man8_files = ostree-state-overlay@.service.8
+
 man1_MANS = $(addprefix man/,$(man1_files))
 man5_MANS = $(addprefix man/,$(man5_files))
+man8_MANS = $(addprefix man/,$(man8_files))
 
 manhtml_files = \
 	man/html/index.html \
 	$(addprefix man/html/,$(man1_files:.1=.html)) \
 	$(addprefix man/html/,$(man5_files:.5=.html)) \
+	$(addprefix man/html/,$(man8_files:.8=.html)) \
 	$(NULL)
 
 if ENABLE_MAN_HTML
@@ -65,7 +69,7 @@ noinst_DATA += $(manhtml_files)
 manhtml: $(manhtml_files)
 endif
 
-EXTRA_DIST += man/index.xml $(man1_MANS:.1=.xml) $(man5_MANS:.5=.xml)
+EXTRA_DIST += man/index.xml $(man1_MANS:.1=.xml) $(man5_MANS:.5=.xml) $(man8_MANS:.8=.xml)
 
 XSLT_MAN_STYLESHEET = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
 XSLT_HTML_STYLESHEET = man/html.xsl
@@ -87,13 +91,17 @@ XSLTPROC_MAN = $(XSLTPROC) $(XSLTPROC_FLAGS)
 %.5: %.xml
 	$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_MAN_STYLESHEET) $<
 
+%.8: %.xml
+	$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_MAN_STYLESHEET) $<
+
 man/html/%.html: man/%.xml
 	@mkdir -p man/html
 	$(AM_V_GEN) $(XSLTPROC_MAN) --output $@ $(XSLT_HTML_STYLESHEET) $<
 
 CLEANFILES += \
 	$(man1_MANS) \
 	$(man5_MANS) \
+	$(man8_MANS) \
 	$(manhtml_files) \
 	$(NULL)
 

Makefile-ostree.am

@@ -85,6 +85,7 @@ ostree_SOURCES += \
 	src/ostree/ot-admin-builtin-post-copy.c \
 	src/ostree/ot-admin-builtin-upgrade.c \
 	src/ostree/ot-admin-builtin-unlock.c \
+	src/ostree/ot-admin-builtin-state-overlay.c \
 	src/ostree/ot-admin-builtins.h \
 	src/ostree/ot-admin-instutil-builtin-selinux-ensure-labeled.c \
 	src/ostree/ot-admin-instutil-builtin-set-kargs.c \

man/ostree-state-overlay@.service.xml

@@ -0,0 +1,107 @@
+<?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>

src/boot/ostree-state-overlay@.service

@@ -0,0 +1,36 @@
+# Copyright (C) 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, see <https://www.gnu.org/licenses/>.
+
+[Unit]
+Description=OSTree State Overlay On /%I
+Documentation=man:ostree(1)
+DefaultDependencies=no
+ConditionKernelCommandLine=ostree
+# run after /var is setup since that's where the upperdir is stored
+# and after boot.mount so we can load the sysroot
+After=var.mount boot.mount
+# but before local-fs.target, which we consider ourselves a part of
+Before=local-fs.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/bin/ostree admin state-overlay %i /%I
+StandardInput=null
+StandardOutput=journal
+StandardError=journal+console
+
+[Install]
+WantedBy=local-fs.target