From a0f7b3c7898c0d77b2e95d5314b4cc9bfbb13f00 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 8 Dec 2023 13:58:42 -0500 Subject: [PATCH 1/2] man: Document `root.transient` This one warrants some explanation. --- man/ostree-prepare-root.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml index 53aad8cdd9..9117c340bd 100644 --- a/man/ostree-prepare-root.xml +++ b/man/ostree-prepare-root.xml @@ -117,6 +117,24 @@ License along with this library. If not, see . etc.transient A boolean value; the default is false. If this is set to true, then the /etc mount point is mounted transiently i.e. a non-persistent location. + + root.transient + A boolean value; the default is false. + If this is set to true, then the / filesystem will be a writable overlayfs, + with the upper directory being a hidden directory (in the underlying system root filesystem) that will persist across reboots by default. + However, changes will be discarded on OS updates! + + + Enabling this option can be very useful for cases such as packages (dpkg/rpm/etc) that write content into /opt, + particularly where they expect the target to be writable at runtime. To make that work, ensure that your /opt + directory is *not* a symlink to /var/opt, but is just an empty directory. + + + Note the /usr mount point remains read-only by default. This option is independent of etc.transient and sysroot.readonly; + it is supported for example to have root.transient=true but etc.transient=false in which case changes to /etc continue + to persist across updates, with the default OSTree 3-way merge applied. + + composefs.enabled This can be yes, no. maybe or From 8f4beb4a7fd49f8161597c62322a606d29b8f77e Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 8 Dec 2023 14:01:13 -0500 Subject: [PATCH 2/2] docs: Add `var.md` This one overlaps a bit with some other sections...the docs need a bigger rework, but this is better than we had before. --- docs/adapting-existing.md | 4 +++ docs/var.md | 60 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 docs/var.md diff --git a/docs/adapting-existing.md b/docs/adapting-existing.md index 62c9a99c3b..12df966f2b 100644 --- a/docs/adapting-existing.md +++ b/docs/adapting-existing.md @@ -69,6 +69,10 @@ d /var/mnt 0755 root root - d /run/media 0755 root root - ``` +However, as of OSTree 2023.9 there is support for a `root.transient` +model, which can increase compatibility in some scenarios. For more +information, see `man ostree-prepare-root.conf`. + Particularly note here the double indirection of `/home`. By default, each deployment will share the global toplevel `/home` directory on the physical root filesystem. It is then up to higher levels of diff --git a/docs/var.md b/docs/var.md new file mode 100644 index 0000000000..6ab52cc7d6 --- /dev/null +++ b/docs/var.md @@ -0,0 +1,60 @@ +--- +nav_order: 6 +--- + +# OSTree and /var handling + +{: .no_toc } + +1. TOC +{:toc} + +As of OSTree 2023.8, the `/usr/lib/tmpfiles.d/ostree-tmpfiles.conf` file gained this snippet: + +```text +# Automatically propagate all /var content from /usr/share/factory/var; +# the ostree-container stack is being changed to do this, and we want to +# encourage ostree use cases in general to follow this pattern. +C+! /var - - - - - +``` + +This is inert by default. However, there is a pending change in the ostree-container stack which will move all files in `/var` from fetched container images into `/usr/share/factory/var`. And other projects in the ostree ecosystem are now recommended do this by default. + +Together, this will have the semantic that on OS updates, on the next boot (early in boot), any new files/directories will be copied. For more information on this, see [`man tmpfiles.d`](https://man7.org/linux/man-pages/man5/tmpfiles.d.5.html). + +However, `tmpfiles.d` is not a package system: + +## Pitfalls + +- Large amounts of data will slow down firstboot while the content is copied (though reflinks are used if available) +- Any files which already exist will *not* be updated. +- Any files which are deleted in the new version will not be deleted on existing systems. + +## Examples + +### Apache default content in `/var/www/html` + +The `tmpfiles.d` model may work OK for use cases that wants to treat this content as locally mutable state. But in general, such static content would much better live in `/usr` - or even better, in an application container. + +### User home directories and databases + +The semantics here are likely OK for the use case of "default users". + +### debs/RPMs which drop files into `/opt` (i.e. `/var/opt`) + +The default OSTree "strict" layout has `/opt` be a symlink to `/var/opt`. +However, `tmpfiles.d` is not a package system, and so over time these will slowly +break because changes in the package will not be reflected on disk. + +For situations like this, it's recommended to enable the `root.transient = true` option for `ostree-prepare-root.conf` +and change your build system to make `/opt` a plain directory. + +### `/var/lib/containers` + +Pulling container images into OSTree commits like this would be a bad idea; similar problems as RPM content. + +### dnf `/var/lib/dnf/history.sqlite` + +For $reasons dnf has its own database for state distinct from the RPM database, which on rpm-ostree systems is in `/usr/share/rpm` (under the read-only bind mount, managed by OS updates). + +In an image/container-oriented flow, we don't really care about this database which mainly holds things like "was this package user installed". This data could move to `/usr`.