Add Debian 13 (trixie) support alongside Fedora
The provisioning path now runs on both package families. Fedora behaviour is
unchanged: the Fedora publishing code issues the same ten operations in the
same order as before, verified by recording the call sequence from both
implementations against a stubbed environment.
update_local_repo.py
Detects the family from /etc/os-release and dispatches to sync_fedora() or
sync_debian(). Release assets are filtered by extension, so neither family
sees the other's packages. The Debian path builds a flat apt-ftparchive
repository at the same /var/local/citrix-repo, publishes
local-citrix-repo.list, and runs apt-get update.
Fixes found while testing:
- tqdm is now an optional dependency. A stock Debian 13 image has no pip and
no tqdm, and dying at import would take down provisioning over a progress
bar.
- sync_debian prunes stale *.deb files before repopulating. The Fedora path
gets this for free by writing fixed filenames; Debian filenames carry the
version, so without pruning every old version stayed indexed and apt always
picked the highest, making rollback impossible.
- The apt source file is resolved next to the script rather than from the
working directory, with a hardcoded canonical fallback, so a foreign cwd or
a missing file cannot break the 10-minute cron job.
local-citrix-repo.list
The apt counterpart of local-citrix-repo.repo, which stays as-is for dnf.
Uses trusted=yes rather than a signature: the repository is generated on the
machine from packages this script downloaded itself, so a signature would only
prove the machine signed its own work, and it would add a gpg dependency that
Debian 13 does not ship by default. Index integrity is still enforced through
the hashes in Release.
debian/preseed.cfg
The debian-installer equivalent of ks.cfg. Same locale, keyboard, timezone,
passwords, inventory-derived hostname/user/password, disk auto-detection,
Firefox managed bookmarks, Citrix and TeamViewer installs, auto-update script,
cron jobs and disable-sleep unit. Every directive was checked against the
templates in the real trixie udebs. Documented gaps, all inherent to preseed
vs kickstart: uppercase usernames are rejected by user-setup and so are
created in late_command; d-i has no lsblk, openssl, chvt or openvt, so disk
detection reads /sys/block and the inventory prompt goes to /dev/console with
a kernel-cmdline override and a timeout; pip install tqdm becomes
python3-tqdm from apt because of PEP 668.
debian/test/
Harness covering the Debian path on a real Debian 13 machine: repo build,
sources.list validity, apt visibility after purging the list cache, install
resolution, idempotency, stale-package pruning, corrupt-index rejection, and
Fedora non-regression. 52 pass, 3 skip (each skip states why).
Known limitations are listed in README.md under "What the tests do NOT prove":
no real d-i install has been run, and the generated post-install script is
verified as well-formed rather than executed against a target root.
This commit is contained in:
1 parent
5d9b278270
commit
6ddb1d251a
6 files changed
+2779
-277
No files matched your search
@@ -1 +1,264 @@
|
||||
# VDI-Linux
|
||||
|
||||
Provisioning for the REYHER VDI clients. Two package families are supported from
|
||||
this branch:
|
||||
|
||||
| | Fedora | Debian |
|
||||
|---|---|---|
|
||||
| installer input | `ks.cfg` (Anaconda kickstart) | `debian/preseed.cfg` (debian-installer) |
|
||||
| desktop | `@^kde-desktop-environment` | `kde-desktop` task |
|
||||
| Citrix packages | `ICAClient.rpm`, `ctxusb.rpm` | `icaclient`, `ctxusb` |
|
||||
| local repo build | `createrepo_c` | `apt-ftparchive` |
|
||||
| local repo config | `/etc/yum.repos.d/local-citrix-repo.repo` | `/etc/apt/sources.list.d/local-citrix-repo.list` |
|
||||
| repo refresh | `dnf makecache` | `apt-get update` |
|
||||
| browser | `firefox` | `firefox-esr` |
|
||||
|
||||
`update_local_repo.py` picks the path itself from `/etc/os-release`, so the same
|
||||
file and the same cron job work on both. `configure_kde.py` is distro-neutral and
|
||||
runs unchanged on both.
|
||||
|
||||
## What runs, and when
|
||||
|
||||
1. The installer provisions the base system from `ks.cfg` or `debian/preseed.cfg`.
|
||||
2. A `%post` / `late_command` step writes the Firefox managed bookmarks, clones
|
||||
this repository to `/root/VDI-Linux`, installs TeamViewer, writes
|
||||
`/root/auto_update.sh`, installs the `disable-sleep` systemd unit, and adds the
|
||||
cron jobs.
|
||||
3. A cron job runs `update_local_repo.py` every 10 minutes as root. That script
|
||||
pulls this repo, applies the KDE settings, downloads the newest Citrix
|
||||
packages from the Gitea release, republishes the local repository, and
|
||||
refreshes the package manager's index.
|
||||
4. `@reboot` runs `/root/auto_update.sh` once the network is up, which
|
||||
pre-downloads system updates and prepares an offline update.
|
||||
|
||||
## update_local_repo.py
|
||||
|
||||
```
|
||||
detect_package_family() /etc/os-release -> "fedora" | "debian"
|
||||
main() git pull, apply KDE settings, desktop shortcut,
|
||||
is_newer_release(), then sync_fedora() or sync_debian()
|
||||
```
|
||||
|
||||
`fetch_release_info()` filters release assets by the running family's extension,
|
||||
so a Fedora client never sees the `.deb` assets and a Debian client never sees the
|
||||
`.rpm` assets. Both families read the same Gitea release.
|
||||
|
||||
### Fedora path
|
||||
|
||||
Unchanged from the previously deployed version. Fixed asset filenames
|
||||
(`ctxusb.rpm`, `ICAClient.rpm`) are downloaded into `/temp/packages`, copied into
|
||||
`/var/local/citrix-repo`, indexed with `createrepo_c`, and published with
|
||||
`local-citrix-repo.repo` (`gpgcheck=1` against the imported
|
||||
`RPM-GPG-KEY-citrix-local`), then `dnf makecache` and `pkcon refresh force`.
|
||||
|
||||
This path was verified to issue the same ten operations in the same order with
|
||||
the same arguments as `main`, by running both implementations against a stubbed
|
||||
environment and diffing the recorded call sequence. See "Regression testing".
|
||||
|
||||
### Debian path
|
||||
|
||||
The Debian assets are named with the version embedded
|
||||
(`icaclient_26.08.0.225_amd64.deb`), so they are matched by package-name prefix
|
||||
rather than by exact filename. They are downloaded, copied into the same
|
||||
`/var/local/citrix-repo`, and indexed with
|
||||
|
||||
```sh
|
||||
cd /var/local/citrix-repo
|
||||
apt-ftparchive packages . > Packages
|
||||
gzip -c Packages > Packages.gz
|
||||
apt-ftparchive release . > Release
|
||||
```
|
||||
|
||||
That is a flat ("trivial") apt archive: the packages, `Packages`, `Packages.gz`
|
||||
and `Release` all sit directly in the directory, with no `dists/` tree. apt reads
|
||||
it through `local-citrix-repo.list`:
|
||||
|
||||
```
|
||||
deb [trusted=yes] file:/var/local/citrix-repo ./
|
||||
```
|
||||
|
||||
The suite is `./` - a path ending in a slash, no component - which is what marks
|
||||
a flat repository.
|
||||
|
||||
**Why `trusted=yes` and not a signed repository.** The Fedora side signs because
|
||||
it already has an RPM key. On Debian the repository is generated on the machine,
|
||||
from packages this script has just downloaded itself, so a signature would only
|
||||
prove that the machine signed its own work. Signing would also add a real
|
||||
dependency: Debian 13 has no `gpg` installed by default, and apt verifies with
|
||||
`sqv` (Sequoia) rather than `gpgv`, so generating and trusting a key inside a
|
||||
d-i install is a new failure mode for no gain.
|
||||
|
||||
`trusted=yes` does **not** disable integrity checking. It tells apt not to
|
||||
require a signature over the `Release` file; apt still verifies every index file
|
||||
against the hashes in `Release`, and a tampered `Packages` fails with
|
||||
`E: Failed to fetch ... Hash Sum mismatch`. What it gives up is proof of
|
||||
*authorship*, which is meaningless for a repository the machine builds from its
|
||||
own downloads.
|
||||
|
||||
**Stale packages are pruned.** The Fedora path writes fixed filenames, so a new
|
||||
release overwrites the old ones and the repository can never hold two versions.
|
||||
Debian filenames carry the version, so `sync_debian()` deletes every `*.deb` from
|
||||
the repository directory before repopulating it. Without that, every previous
|
||||
version would stay indexed and apt would always pick the highest, making a
|
||||
rollback by publishing an older build impossible.
|
||||
|
||||
**Refreshing the index.** apt has no per-source equivalent of dnf's
|
||||
`metadata_expire`; the index is re-read only when `apt-get update` runs.
|
||||
`sync_debian()` runs it after rebuilding, and the 10-minute cron job runs
|
||||
`sync_debian()`, so the index does not go stale in practice.
|
||||
|
||||
### Where the `.deb` files come from
|
||||
|
||||
1. Assets attached to the newest Gitea release, matched by package-name prefix.
|
||||
2. If the release has no `.deb` assets, `$VDI_DEB_DIR` (default
|
||||
`/temp/packages/deb`), so an operator can stage the two files on the machine
|
||||
without publishing a release.
|
||||
|
||||
If neither has them the script fails with a message naming both places. It does
|
||||
not fall back to converting the RPMs: `alien` is unmaintained and would break the
|
||||
Citrix pre/post-install scripts, which is a worse outcome than a clear failure.
|
||||
|
||||
### Runtime requirements on Debian
|
||||
|
||||
`apt-utils` (for `apt-ftparchive`), `python3`, `git`, and optionally
|
||||
`python3-tqdm`. `tqdm` is only the download progress bar and the script falls
|
||||
back to a no-op if it is missing, but without `apt-utils` or `python3` the cron
|
||||
job fails every 10 minutes with the reason only visible in
|
||||
`/var/log/update_local_repo.log`.
|
||||
|
||||
## configure_kde.py
|
||||
|
||||
Writes KWin's `[Libinput][Defaults][Touchpad]` group (so it applies to every
|
||||
touchpad regardless of vendor), the PowerDevil AC/Battery/LowBattery profiles,
|
||||
and KScreenLocker. Also installs `/usr/local/bin/vdi-kde-settings` plus an XDG
|
||||
autostart entry that re-applies the settings inside a running session.
|
||||
|
||||
Verified working unchanged on Debian 13 (Plasma 6.3.6): `kwriteconfig6` ships in
|
||||
`libkf6config-bin`, which the `kde-desktop` task pulls in, and the resulting
|
||||
`/etc/xdg/{kcminputrc,powerdevilrc,kscreenlockerrc}` are correct. It is idempotent
|
||||
- a second run changes nothing.
|
||||
|
||||
It prefers `sudo -n -u <user>` over `runuser` because on Fedora that also performs
|
||||
the SELinux context transition needed to reach another user's session bus. On
|
||||
Debian either works; `runuser` comes from `util-linux`, which is always present,
|
||||
so the Debian path does not depend on `sudo` being installed. **If you rely on
|
||||
`sudo` on Debian, install the `sudo` package explicitly** - the `kde-desktop`
|
||||
task does not pull it in.
|
||||
|
||||
## Firefox managed bookmarks
|
||||
|
||||
Both families write the same file:
|
||||
|
||||
```
|
||||
/etc/firefox/policies/policies.json (0644, root:root)
|
||||
```
|
||||
|
||||
On Debian this is correct and must not be "fixed". `firefox-esr` 153.6 was traced
|
||||
with `strace` and it stats exactly one path, `/etc/firefox/policies/policies.json`
|
||||
- not `/etc/firefox-esr/policies/`, not `/usr/lib/firefox-esr/distribution/`.
|
||||
Debian's build has `MOZ_SYSTEM_POLICIES` compiled in, which is why it honours the
|
||||
standard location. Moving the file to `/etc/firefox-esr/policies/` because the
|
||||
Debian package owns that directory would silently disable managed bookmarks.
|
||||
|
||||
## Debian vs Fedora: known differences
|
||||
|
||||
These are inherent to preseed vs kickstart, not oversights:
|
||||
|
||||
- **Uppercase usernames are impossible via preseed.** `user-setup-udeb` validates
|
||||
against `[a-z][-a-z0-9_]*$` and re-prompts on failure, which would stall an
|
||||
unattended install. `VDI-ADMIN` is therefore created with `useradd` in
|
||||
`late_command`, and `passwd/make-user` is set to false.
|
||||
- **Disk detection cannot use `lsblk`.** d-i has no `lsblk` and no `openssl`, so
|
||||
the kickstart's `lsblk -d -o rm` / `openssl passwd -6` have no direct
|
||||
equivalent. The preseed reads `/sys/block/*/removable` plus `udevadm info`, and
|
||||
sets passwords with `chpasswd` in the target instead of hashing in the
|
||||
installer.
|
||||
- **There is no `chvt`/`openvt` in d-i**, so the kickstart's "switch to TTY3 and
|
||||
prompt" trick cannot be reproduced. The inventory number is prompted on
|
||||
`/dev/console`, with a `vdi.inventory=NNNNN` kernel-cmdline override and a
|
||||
`00000` fallback so an unattended run cannot hang forever.
|
||||
- **Password hash format.** The kickstart hashes with `openssl passwd -6`
|
||||
(SHA-512 crypt). `chpasswd` on trixie produces yescrypt by default. Same
|
||||
outcome, different hash - worth knowing if anything inspects `/etc/shadow`.
|
||||
- **`git clone` of the internal Gitea server fails soft on Debian.** The Fedora
|
||||
kickstart aborts the install if the clone fails; the preseed logs and
|
||||
continues, because the 10-minute cron job retries the work on the next run and
|
||||
a half-provisioned machine is more useful than no machine.
|
||||
- **The Citrix install is two steps.** On Fedora `dnf install ICAClient ctxusb`
|
||||
resolves from the local repo directly. On Debian the packages come from the
|
||||
local repo that `update_local_repo.py` builds, so `late_command` must run it
|
||||
first, then `apt-get install -y icaclient ctxusb`, then `apt-get install -f -y`.
|
||||
|
||||
## Testing
|
||||
|
||||
`debian/test/run-tests.sh` exercises the Debian side on a real Debian 13 machine
|
||||
and asserts the Fedora side is unregressed. Run it as root on a Debian 13 host or
|
||||
WSL instance:
|
||||
|
||||
```sh
|
||||
bash debian/test/run-tests.sh
|
||||
```
|
||||
|
||||
It builds a throwaway apt repository from the real Citrix `.deb` files, points a
|
||||
temporary `sources.list` entry at it, and confirms apt can see and resolve the
|
||||
packages. It does not touch `/var/local/citrix-repo` and cleans up after itself.
|
||||
See `debian/test/README.md` for what it covers and what it cannot.
|
||||
|
||||
### What the tests do NOT prove
|
||||
|
||||
Being explicit, because these are the gaps that matter and it is easy to read a
|
||||
green summary as more than it is:
|
||||
|
||||
- **No real d-i install has been run.** `debian/preseed.cfg` is validated by
|
||||
`debconf-set-selections` (the real parser), by checking every directive name
|
||||
against the templates in the actual trixie udebs, and by executing
|
||||
`late_command` with `/target` redirected to a scratch tree. That proves the
|
||||
file parses, the directives exist, and the generated scripts are well formed.
|
||||
It does not prove that an unattended install completes on real hardware - the
|
||||
disk detection, the partitioner and the console prompt have never run in a
|
||||
live installer.
|
||||
- **The generated post-install script is not executed against a real target.**
|
||||
`/root/vdi-post.sh` writes `/etc/hostname`, `/etc/hosts`, `/etc/crontab` and
|
||||
`/etc/systemd/system/*` by absolute path, so running it on a build machine
|
||||
would modify the build machine. It is covered by `bash -n` and by reading the
|
||||
generated text, plus assertions on the inventory arithmetic it derives.
|
||||
- **No KDE session has been exercised.** `configure_kde.py` is tested as far as
|
||||
writing `/etc/xdg/*` and the autostart entry, and its `--session` path is
|
||||
exercised only against a machine with no session bus (the clean no-op). The
|
||||
live `busctl` calls against a running KWin/PowerDevil are untested.
|
||||
- **The Citrix packages are never installed.** The tests prove apt can see them
|
||||
and that dependency resolution succeeds (`apt-get install --simulate`), not
|
||||
that `icaclient`'s pre/post-install scripts complete. Those scripts are large
|
||||
and touch the X11 session; installing them in CI is its own project.
|
||||
- **The Fedora path is verified by equivalence, not by running it on Fedora.**
|
||||
The regression test compares the commands the Fedora code issues against
|
||||
`main`. It does not perform a real `createrepo_c`/`dnf` cycle on a Fedora host.
|
||||
|
||||
### Regression testing the Fedora path
|
||||
|
||||
A file diff is the wrong instrument for `update_local_repo.py`, because the
|
||||
Fedora and Debian code now share a file. The meaningful check is behavioural:
|
||||
run the Fedora publishing path from both `main` and this branch against a stubbed
|
||||
environment and compare the recorded sequence of operations. They must be
|
||||
identical - same downloads, same destinations, same `createrepo_c`, `rpm
|
||||
--import`, `dnf makecache` and `pkcon refresh force` calls, in the same order.
|
||||
|
||||
`configure_kde.py`, `local-citrix-repo.repo` and `RPM-GPG-KEY-citrix-local` are
|
||||
untouched by this branch, and `git diff main -- <those files>` is empty.
|
||||
|
||||
### Traps when testing on Debian
|
||||
|
||||
- **Purge apt's list cache between cases.** `/var/lib/apt/lists` caches the
|
||||
index, so a wrong signing key can still appear to work (exit 0, package
|
||||
visible). Any test that does not purge produces a false pass.
|
||||
- **`core.autocrlf=true` on a Windows checkout rewrites the worktree to CRLF.**
|
||||
The repository stores LF, so Linux clients are fine, but copying the worktree
|
||||
into a Linux test box gives `#!/usr/bin/python3\r` and direct execution fails
|
||||
with a confusing "No such file or directory". Copy `git show HEAD:file` or strip
|
||||
the CRs.
|
||||
- **`strings` is not installed on a stock Debian image.** `strings ... | grep`
|
||||
with stderr discarded returns empty and looks like a clean negative. Use
|
||||
`grep -a` on the binary, or install `binutils`.
|
||||
- **`firefox-esr --headless --dump-dom` hangs under WSL** (RenderCompositorSWGL
|
||||
cannot map a framebuffer, and it exits 124 on timeout). A tiny DOM from it is
|
||||
an error page, not a result. Trace the syscalls instead.
|
||||
Reference in new issue
Block a user