From f8097a4d90bc588746190b3cd7c64155ec4493c5 Mon Sep 17 00:00:00 2001 From: Peter Siegel Date: Fri, 30 Oct 2026 00:40:52 +0100 Subject: [PATCH] docs: Document persisting the pull secret with a transient /etc Document linking /run/ostree/auth.json to a pull secret in /var with a tmpfiles.d entry. Also fix the search order in ostree-container-auth(5), which listed /etc before /run. Assisted-by: AI Signed-off-by: Peter Siegel --- .../ostree-ext/man/ostree-container-auth.md | 4 ++-- docs/src/building/bootc-secrets.7.md | 21 +++++++++++++++++-- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/crates/ostree-ext/man/ostree-container-auth.md b/crates/ostree-ext/man/ostree-container-auth.md index 234f499595..73fd7f46ad 100644 --- a/crates/ostree-ext/man/ostree-container-auth.md +++ b/crates/ostree-ext/man/ostree-container-auth.md @@ -8,8 +8,8 @@ ostree-container-auth description of the registry authentication file The OSTree container stack uses the same file formats as **containers-auth(5)** but not the same locations. -When running as uid 0 (root), the tooling uses `/etc/ostree/auth.json` first, then looks -in `/run/ostree/auth.json`, and finally checks `/usr/lib/ostree/auth.json`. +When running as uid 0 (root), the tooling uses `/run/ostree/auth.json` first, then looks +in `/etc/ostree/auth.json`, and finally checks `/usr/lib/ostree/auth.json`. For any other uid, the file paths used are in `${XDG_RUNTIME_DIR}/ostree/auth.json`. In the future, it is likely that a path that is supported for both "system podman" diff --git a/docs/src/building/bootc-secrets.7.md b/docs/src/building/bootc-secrets.7.md index b220d5100f..1e0b330cfa 100644 --- a/docs/src/building/bootc-secrets.7.md +++ b/docs/src/building/bootc-secrets.7.md @@ -2,8 +2,9 @@ # Secrets (e.g. container pull secrets) To have `bootc` fetch updates from registry which requires authentication, -you must include a pull secret in one of `/etc/ostree/auth.json`, -`/run/ostree/auth.json` or `/usr/lib/ostree/auth.json`. +you must include a pull secret in one of `/run/ostree/auth.json`, +`/etc/ostree/auth.json` or `/usr/lib/ostree/auth.json`. They are checked +in this order. The path to the authentication file differs from that used by e.g. `podman` by default as some of the file paths used @@ -43,6 +44,22 @@ as suggested by [this document](https://docs.aws.amazon.com/AmazonECR/latest/use You can also use the machine-local persistent location `/etc/ostree/auth.json` via this method. +## Persisting the pull secret with a transient /etc + +If `/etc` is transient (see `bootc-setup-root-conf(5)`), changes to +`/etc/ostree/auth.json` will be lost on reboot. Instead, keep the pull +secret in `/var` and include a `tmpfiles.d` entry in the image that links +it into `/run/ostree/auth.json`, e.g.: + +``` +# /usr/lib/tmpfiles.d/bootc-auth.conf +d /var/lib/ostree 0700 root root - +L /run/ostree/auth.json - - - - /var/lib/ostree/auth.json +``` + +Then log in with `--authfile /var/lib/ostree/auth.json`. Note that this +pull secret will take precedence over one included in the image. + ## Using a credential helper In order to use a credential helper as configured in `registries.conf`