From 752de7fb43a67565bffe0ac9fe6f60b6e53b07aa Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 4 Feb 2025 16:06:34 +0000 Subject: [PATCH] docs/filesystem: Flesh out `etc` a bit more - Mention `ostree admin config-diff` - Note that metadata also counts as a modification Signed-off-by: Colin Walters --- docs/src/filesystem.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md index e414cabc4..15da99249 100644 --- a/docs/src/filesystem.md +++ b/docs/src/filesystem.md @@ -70,7 +70,7 @@ in derived builds. ## `/etc` The `/etc` directory contains mutable persistent state by default; however, -it is suppported to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html), +it is suppported (and encouraged) to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html), see below as well. When in persistent mode, it inherits the OSTree semantics of [performing a 3-way merge](https://ostreedev.github.io/ostree/atomic-upgrades/#assembling-a-new-deployment-directory) @@ -80,6 +80,10 @@ across upgrades. In a nutshell: - The diff between current and previous `/etc` is applied to the new `/etc` - Locally modified files in `/etc` different from the default `/usr/etc` (of the same deployment) will be retained +You can view the state via `ostree admin config-diff`. Note that the "diff" +here is includes metadata (uid, gid, extended attributes), so changing any of those +will also mean that updated files from the image are not applied. + The implementation of this defaults to being executed by `ostree-finalize-staged.service` at shutdown time, before the new bootloader entry is created. @@ -96,6 +100,10 @@ would require external intervention to apply. For more on configuration file best practices, see [Building](building/guidance.md). +To emphasize again, it's recommended to enable `etc.transient` if possible, though +when using that you may need to store some machine-specific state in e.g. the +kernel commandline if applicable. + ### `/usr/etc` The `/usr/etc` tree is generated client side and contains the default container image's