From 87dcc801a25f6f37748ce9462c6c9ffed3046d80 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 12 Feb 2024 11:50:50 -0500
Subject: [PATCH 1/2] ostree-tmpfiles.conf: Drop `var` entry

We are backing away from this semantic, and moving towards
`/var` only being initialized at initial provisioning.
---
 src/boot/ostree-tmpfiles.conf              |  4 ---
 tests/kolainst/destructive/var-tmpfiles.sh | 29 ----------------------
 2 files changed, 33 deletions(-)
 delete mode 100755 tests/kolainst/destructive/var-tmpfiles.sh

diff --git a/src/boot/ostree-tmpfiles.conf b/src/boot/ostree-tmpfiles.conf
index c1b5048037..69c2d3f385 100644
--- a/src/boot/ostree-tmpfiles.conf
+++ b/src/boot/ostree-tmpfiles.conf
@@ -17,7 +17,3 @@
 d /run/ostree 0755 root root -
 # https://github.com/ostreedev/ostree/issues/393
 R! /var/tmp/ostree-unlock-ovl.*
-# Automatically propagate all /var content from /usr/share/factory/var;
-# NOTE: This is now considered a mistake, and will likely be reverted.
-# As of OSTree 2024.3, content from the initial deployment is used.
-C+! /var - - - - -
diff --git a/tests/kolainst/destructive/var-tmpfiles.sh b/tests/kolainst/destructive/var-tmpfiles.sh
deleted file mode 100755
index 3ce9e3590a..0000000000
--- a/tests/kolainst/destructive/var-tmpfiles.sh
+++ /dev/null
@@ -1,29 +0,0 @@
-#!/bin/bash
-set -xeuo pipefail
-
-. ${KOLA_EXT_DATA}/libinsttest.sh
-
-require_writable_sysroot
-prepare_tmpdir
-
-case "${AUTOPKGTEST_REBOOT_MARK:-}" in
-  "")
-    factory_var=rootfs/usr/share/factory/var
-    mkdir -p ${factory_var}
-    cd "${factory_var}"
-    mkdir -p home/someuser
-    echo bashrc > home/someuser/.bashrc
-    chown -R 1000:1000 home/someuser
-    mkdir -m 01777 -p tmp
-    cd -
-    ostree commit -b testlint --no-bindings --selinux-policy-from-base --tree=ref="${host_refspec}" --consume --tree=dir=rootfs
-    ostree admin deploy testlint 2>err.txt
-    assert_not_file_has_content err.txt 'contains content in /var'
-
-    /tmp/autopkgtest-reboot "2"
-    ;;
-  2)
-    assert_file_has_content /home/someuser/.bashrc bashrc
-    ;;
-  *) fatal "Unexpected AUTOPKGTEST_REBOOT_MARK=${AUTOPKGTEST_REBOOT_MARK}" ;;
-esac

From 6df18abee7521d872fe12fe37c030033b2a4e171 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 12 Feb 2024 11:59:39 -0500
Subject: [PATCH 2/2] docs/var: Update for latest

This reorients things here around the latest `VOLUME /var` approach.
---
 docs/var.md | 70 +++++++++++++++++++++++++++++------------------------
 1 file changed, 38 insertions(+), 32 deletions(-)

diff --git a/docs/var.md b/docs/var.md
index 61480d8c7e..625359892d 100644
--- a/docs/var.md
+++ b/docs/var.md
@@ -26,54 +26,43 @@ because this is more resilent.
 
 Even better, use `StateDirectory=` for systemd units.
 
-### ostree container /var
-
-Some earlier versions of the ostree-container stack migrated content in `/var`
-in container images into `/usr/share/factory/var` (per below).  This has
-been reverted, and the semantics defer to the above ostree semantic.
-
-## Previous /var handling via /usr/share/factory/var
+## Pitfalls
 
-As of OSTree 2023.8, the `/usr/lib/tmpfiles.d/ostree-tmpfiles.conf` file gained this snippet:
+On subsequent upgrades, normally `/var` would not be empty anymore
+(as it's typically expected that basics like `/var/tmp` etc. are created,
+ if not also other local state such as `/var/log` etc.).  Hence,
+*no updates* from the commit/container will be applied.
 
-```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 - - - - -
-```
+To be clear then:
 
-This is inert by default.  As of version 0.13 of the ostree-ext project, content in `/var` in fetched container images is moved to `/usr/share/factory/var`.  This is no longer recommended.
+- 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.
 
-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).
+## Examples
 
-However, `tmpfiles.d` is not a package system:
+### debs/RPMs which drop files into `/opt` (i.e. `/var/opt`)
 
-## Pitfalls
+The default OSTree "strict" layout has `/opt` be a symlink to `/var/opt`.
+Including any packaged content that "straddles" `/usr` and `/var` (i.e. `/var/opt`)
+will over time cause drift because changes in the package will not be reflected on disk.
 
-- 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.
+For situations like this, it's strongly recommended to enable either
+`composefs.enabled = true` or the `root.transient = true` option for `ostree-prepare-root.conf`
+and change ensure your commit/container image has `/opt` as a plain directory.  In the former case,
+content in `/opt` will be immutable at runtime, the same as everything else in `/usr`.
+In the latter case content it will be writable but transient.
 
-## Examples
+There's also a currently-experimental [../man/ostree-state-overlay@.service.xml](ostree-state-overlay@.service)
+which can manage stateful writable overlays for individual mounts.
 
 ### 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.
+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.
@@ -83,3 +72,20 @@ Pulling container images into OSTree commits like this would be a bad idea; simi
 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`.
+
+## Previous ostree /var and tmpfiles.d /usr/share/factory/var
+
+From OSTree versions 2023.8 to v2024.3 the `/usr/lib/tmpfiles.d/ostree-tmpfiles.conf` file included 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 - - - - -
+```
+
+Until version 0.13.2 of the ostree-ext project, content in `/var` in fetched container images is moved to `/usr/share/factory/var`, but this no longer happens when targeting ostree v2024.3.
+
+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).
+
+This has been reverted, and the semantics defer to the above ostree semantic.