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.
13 KiB
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
- The installer provisions the base system from
ks.cfgordebian/preseed.cfg. - A
%post/late_commandstep writes the Firefox managed bookmarks, clones this repository to/root/VDI-Linux, installs TeamViewer, writes/root/auto_update.sh, installs thedisable-sleepsystemd unit, and adds the cron jobs. - A cron job runs
update_local_repo.pyevery 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. @rebootruns/root/auto_update.shonce 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
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
- Assets attached to the newest Gitea release, matched by package-name prefix.
- If the release has no
.debassets,$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 hasMOZ_SYSTEM_POLICIEScompiled 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-udebvalidates against[a-z][-a-z0-9_]*$and re-prompts on failure, which would stall an unattended install.VDI-ADMINis therefore created withuseraddinlate_command, andpasswd/make-useris set to false. - Disk detection cannot use
lsblk. d-i has nolsblkand noopenssl, so the kickstart'slsblk -d -o rm/openssl passwd -6have no direct equivalent. The preseed reads/sys/block/*/removableplusudevadm info, and sets passwords withchpasswdin the target instead of hashing in the installer. - There is no
chvt/openvtin d-i, so the kickstart's "switch to TTY3 and prompt" trick cannot be reproduced. The inventory number is prompted on/dev/console, with avdi.inventory=NNNNNkernel-cmdline override and a00000fallback so an unattended run cannot hang forever. - Password hash format. The kickstart hashes with
openssl passwd -6(SHA-512 crypt).chpasswdon trixie produces yescrypt by default. Same outcome, different hash - worth knowing if anything inspects/etc/shadow. git cloneof 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 ctxusbresolves from the local repo directly. On Debian the packages come from the local repo thatupdate_local_repo.pybuilds, solate_commandmust run it first, thenapt-get install -y icaclient ctxusb, thenapt-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:
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.cfgis validated bydebconf-set-selections(the real parser), by checking every directive name against the templates in the actual trixie udebs, and by executinglate_commandwith/targetredirected 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.shwrites/etc/hostname,/etc/hosts,/etc/crontaband/etc/systemd/system/*by absolute path, so running it on a build machine would modify the build machine. It is covered bybash -nand by reading the generated text, plus assertions on the inventory arithmetic it derives. - No KDE session has been exercised.
configure_kde.pyis tested as far as writing/etc/xdg/*and the autostart entry, and its--sessionpath is exercised only against a machine with no session bus (the clean no-op). The livebusctlcalls 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 thaticaclient'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 realcreaterepo_c/dnfcycle 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/listscaches 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=trueon 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\rand direct execution fails with a confusing "No such file or directory". Copygit show HEAD:fileor strip the CRs.stringsis not installed on a stock Debian image.strings ... | grepwith stderr discarded returns empty and looks like a clean negative. Usegrep -aon the binary, or installbinutils.firefox-esr --headless --dump-domhangs 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.