-
Notifications
You must be signed in to change notification settings - Fork 290
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3120 from jlebon/pr/state-overlays
Add concept of state overlays
- Loading branch information
Showing
10 changed files
with
589 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.