SPS · log · files · refs · tags · releases · people · languages · GitHub · commit
219ac4f
Document pkconf and the maintainer audit tools
DistroDeveloperParents
Stat
DESIGN.md | 20 ++++++++++++++++++ PACKAGE-MAINTAINER.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 30 +++++++++++++++++++++++++++ 3 files changed, 107 insertions(+)
Diff
diff --git a/DESIGN.md b/DESIGN.md
index f11d151..14984db 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -332,6 +332,26 @@ The review finds them on the filesystem next to recorded hash paths, which is
why the collision-proofing in `pkin` (`.sps-new`, then a versioned spelling)
keeps review deterministic.
+### Reconciling protected-file updates
+
+`pkconf` is the write side of the same data. It lists the pending packaged
+defaults, diffs them, and applies one of two outcomes per path:
+
+- accepting the packaged default replaces the live file with the `.sps-new`
+ content and removes the sibling. `pkin` already recorded the new package's
+ digest for that path during the upgrade, so the file matches its record
+ again and `pkcheck` reports the package clean;
+- keeping the local file removes the sibling only. The path stays locally
+ modified, and the next upgrade protects it exactly as before.
+
+An interactive `e` key edits a scratch copy in `$VISUAL`/`$EDITOR` and writes
+the result over the live file, which is recorded as a `merge` in history.
+`pkconf` never merges automatically and never rewrites the installed database;
+its only database write is the append-only history line.
+
+Keeping this in a separate command is deliberate. `sget upgrade` finishes and
+reports; it never stops to ask an administrator a question mid-transaction.
+
## Binary package cache
`sget` stores completed package artifacts under `$SPS_CACHE/packages`.
diff --git a/PACKAGE-MAINTAINER.md b/PACKAGE-MAINTAINER.md
index 9012140..085ec4b 100644
--- a/PACKAGE-MAINTAINER.md
+++ b/PACKAGE-MAINTAINER.md
@@ -405,3 +405,60 @@ if GitHub rate-limits the probe. Downloaded tarballs are cached under
Run `src update` in the recipe trees after a successful apply, then build the
packages that moved.
+## Auditing the trees (`tools/audit-recipes`)
+
+`src update` validates recipe syntax, same-repository uniqueness, and the
+dependency graph. It never downloads anything, so it cannot tell you that an
+upstream tarball moved, was re-rolled, or now answers with an HTML sign-in
+page. That failure only surfaces when a user's `mkpkg` aborts on a checksum,
+which is the worst possible place to find out.
+
+`audit-recipes` covers the rest:
+
+```sh
+python3 tools/audit-recipes --trees /usr/src/sps/core:/usr/src/sps/extra
+```
+
+Offline it reports unknown recipe keys, missing required fields, a `name` that
+disagrees with its directory, mismatched source/hash counts, malformed or
+placeholder digests, one digest reused for two different URLs, self and
+duplicate dependencies, a dependency no recipe in the trees provides, runtime
+dependency cycles, duplicate names inside one tree, names shadowed across
+trees, plaintext `http://` sources, a remote URL that never mentions the
+version, and a build phase that escalates privilege or installs outside
+`$PKG`.
+
+Add `--net` to download every declared source and verify its SHA-256:
+
+```sh
+python3 tools/audit-recipes --trees ... --net --jobs 16
+```
+
+Sources are streamed through the hasher and never written to disk, so the
+whole tree costs bandwidth and time but no storage. Run it on a schedule
+rather than on every push.
+
+Useful switches:
+
+```text
+--only foo,bar audit a few packages (the rest of the tree still
+ resolves their dependencies)
+--fail-level warn make warnings fail the command too
+--json machine-readable findings
+--jobs N parallel downloads for --net
+--timeout N per-source download timeout
+```
+
+Both audits are also Make targets:
+
+```sh
+make audit-recipes RECIPE_TREES=/usr/src/sps/core:/usr/src/sps/extra
+make audit-recipes-net RECIPE_TREES=/usr/src/sps/core:/usr/src/sps/extra
+```
+
+One caution when writing your own checks against upstream hosts: do not send a
+browser `User-Agent`. SourceForge and several other hosts answer browser
+agents with an HTML interstitial and give `curl`/`wget` the real archive, so a
+spoofed agent turns every SourceForge recipe into a false hash mismatch.
+`mkpkg` uses a plain `curl -fL`, and `audit-recipes` matches it.
+
diff --git a/README.md b/README.md
index 6dd57d2..f99c6e2 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,9 @@ SPS is a set of tools rather than one large front end:
the number of installed packages).
- `pkcheck` checks installed files and database consistency.
- `pkmark` changes whether an installed package is explicit or dependency-only.
+- `pkconf` reconciles protected configuration files with the packaged defaults
+ an upgrade left beside them, the way CRUX has `rejmerge` and Gentoo has
+ `etc-update`.
- `setup` is the SPS Linux (Splux) dialog(1) installer (Slackware/FreeBSD
style). Optional; other projects using SPS do not need it.
- `mkiso` builds an SPS Linux live ISO (systemd by default; busybox init if
@@ -59,6 +62,11 @@ SPS is a set of tools rather than one large front end:
It walks core and extra recipes, finds the newest stable upstream, rewrites
version/source/hash, and records newly required libraries. See
[PACKAGE-MAINTAINER.md](PACKAGE-MAINTAINER.md).
+- `tools/audit-recipes` is the other maintainer command. It checks a recipe
+ tree for defects an index build cannot see, and with `--net` it downloads
+ every declared source and verifies its SHA-256. A tarball that upstream
+ moved or re-rolled is the most common way a source distribution stops
+ installing, and nothing else notices until a user's build aborts.
The split matters. `pkin` does not search repositories. `pkdel` does not solve
dependencies. `src` does not install anything. `sget` ties the lower-level tools
@@ -288,6 +296,28 @@ package, and whether an upgrade wrote a packaged default beside it as
`.sps-new`, so you can merge by hand before the next upgrade. `pkcheck
--modified` remains the low-level way to see every locally-changed owned file.
+To act on what it found, run `pkconf`:
+
+```sh
+pkconf # review each pending default, one at a time
+pkconf --list # what is waiting, without changing anything
+pkconf --diff /etc/ssl/openssl.cnf
+pkconf --accept /etc/ssl/openssl.cnf # take the packaged default
+pkconf --keep /etc/ssl/openssl.cnf # keep yours, drop the .sps-new
+pkconf --keep-all # after a big upgrade, keep every local file
+```
+
+The interactive review offers diff, take-the-new-file, keep-mine, and an
+`e` key that opens a scratch copy in `$EDITOR` so you can merge the two by
+hand. This is the same job CRUX gives `rejmerge` and Gentoo gives
+`etc-update`; SPS keeps it in a separate command rather than folding it into
+the upgrade, so an upgrade never blocks waiting for an answer.
+
+Taking the packaged default restores the file to the digest `pkin` recorded,
+so `pkcheck` reports the package clean again. Keeping your file leaves the
+path locally modified, which is the truth and is what the next upgrade will
+respect.
+
`pkin` is still a direct installer. `sget upgrade` starts from the explicit
`world` set, resolves that dependency closure, and upgrades it in dependency
order. A locally newer version is kept unless `--downgrade` is requested.