Files
VDI-Linux/README.md
T
Mistercoolertyper e9a447da4d preseed: bring the readable vdi-post.sh copy back in line with what runs
15d6518 rewrote the late_command payload (inline pkcon sequence -> delegation to
/usr/local/sbin/vdi-offline-update, plus enabling vdi-offline-update.timer) but
left the readable comment copy of the same script ~100 lines above it unchanged.
The two are meant to be the same script, so anyone reading preseed.cfg to learn
what a Debian install does was reading something that no longer matched the
payload. Caught by 8cc5's validator, which compares them byte-for-byte.

No behaviour change: the runtime payload was already correct. Also fixes a stale
comment - packagekit-tools was described as being used by /root/auto_update.sh,
which now delegates; the helper is what calls pkcon, and packagekit-tools is
still required for it.

Verified independently by running the reassembled late_command against a fake
/target: the generated script is 70 lines, parses, delegates, contains no inline
pkcon sequence, enables the timer, and is byte-identical to the comment copy.

Also tightens the README's claim about other updaters: unattended-upgrades is
absent, and apt.systemd.daily gates every install step on 'command -v
unattended-upgrade', so apt-daily-upgrade only refreshes the index. Checked
rather than asserted.
2026-11-04 10:38:13 +01:00

22 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

  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

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.

Updates

The Fedora clients update through PackageKit: pkcon refresh, pkcon update, and an offline update that is downloaded in the background and applied at the next boot. Debian does the same, with one addition (a polkit rule) and one rewrite (the scheduler).

Updating without a password

A user in the sudo group can refresh and install updates from the desktop without being asked for a password, as on Fedora. This needs a polkit rule, because Debian's shipped policy does not cover it:

  • /usr/share/polkit-1/rules.d/org.freedesktop.packagekit.rules grants passwordless access only to upgrade-system and trigger-offline-update.
  • system-sources-refresh (what pkcon refresh uses) and system-update (what pkcon update uses) are auth_admin, so a desktop user is prompted.
  • /usr/share/polkit-1/rules.d/50-default.rules makes unix-group:sudo the admin identity, so the prompt is for the user's own password.

update_local_repo.py therefore installs /etc/polkit-1/rules.d/60-vdi-no-password-updates.rules, allowing system-sources-refresh, system-update and package-install for members of group sudo. Deliberately not granted: package-remove, package-reinstall, package-install-untrusted - a normal user still cannot remove packages or install an untrusted one without a password.

Measured with pkcheck: with the rule, pkcheck --action-id org.freedesktop.packagekit.system-sources-refresh returns 0 (authorised); with the rule removed it returns 2 (authentication required). The test harness asserts both directions, because a check that cannot fail proves nothing.

One thing that did not work and is worth knowing: the rule was first written with subject.local == true, to limit it to seats physically in front of the machine. That clause never matches in this environment - the rule silently did nothing and users were still prompted - so it was removed and the reasoning is recorded in the source. The consequence is that a sudo-group user on a remote session can also update without a password, which is the same trust level that group already has through sudo.

Root never needs a password either, which is what makes the cron job and the timer work.

The offline update

Debian 13's PackageKit 1.3.1 supports the same offline-update mechanism the Fedora clients use, so the approach ports directly:

  1. pkcon refresh force - refresh the package index.
  2. pkcon update --only-download - download the updates without installing.
  3. pkcon offline-get-prepared - confirm a payload is ready.
  4. pkcon offline-trigger - arm the update.

Step 4 creates /system-update as a symlink to /var/lib/PackageKit/prepared-update, and systemd's packagekit-offline-update.service (wired into system-update.target, shipped by the packagekit package) applies it on the next boot. The desktop is never sitting on a half-applied transaction.

Step 3 is load-bearing, not ceremony: offline-get-prepared exits 4 when nothing is prepared, and triggering anyway fails and can leave a dangling /system-update symlink, which breaks the next boot. The if is what prevents that.

Two details that differ from the Fedora script:

  • pkcon exit code 5 means "no packages to update", which is the normal answer on a patched machine. It is not a failure and is not logged as one.
  • The download runs under systemd-inhibit --what=sleep:idle --mode=block so the machine does not suspend mid-download. No DISPLAY is needed, which matters because the timer runs outside any session.

Who runs it, and when

Fedora Debian
Citrix repo refresh cron, 10 min cron, 10 min
offline update @reboot via /root/auto_update.sh vdi-offline-update.timer, 6 h + boot, throttled

On Debian the offline update is a systemd timer (vdi-offline-update.timer, OnBootSec=15min, OnUnitActiveSec=6h, Persistent=true, RandomizedDelaySec=15min) running /usr/local/sbin/vdi-offline-update. systemd owns the scheduling, output goes to the journal, and a failure is visible in systemctl status vdi-offline-update.service. The script also keeps a 6-hour throttle stamp at /var/lib/vdi-offline-update.last so a manual run and the timer cannot pile up.

/root/auto_update.sh is kept for parity with Fedora and simply execs /usr/local/sbin/vdi-offline-update, so there is one implementation rather than two copies of the pkcon sequence.

Note on scope: these files are installed by update_local_repo.py, not only by the preseed. That means machines already provisioned before this change pick up the polkit rule and the timer on their next 10-minute cron run - the same back-fill approach configure_kde.py already uses for the Plasma settings. The preseed additionally enables the timer directly so a fresh install has offline updates from the first boot.

Why not unattended-upgrades

Debian's usual answer for automatic updates is unattended-upgrades, and it is the wrong instrument here: it installs security updates silently while the user is working, which is the thing the offline-update flow exists to avoid, and it does not give a desktop user a no-password update button. It is left uninstalled, and pkgsel/update-policy is none in the preseed so the installer does not pull it in.

Debian still ships apt-daily.timer and apt-daily-upgrade.timer, which run regardless. They are not a second updater in practice: /usr/lib/apt/apt.systemd.daily gates every install step on command -v unattended-upgrade, so with that package absent the timer refreshes the package index and stops. Verified on trixie - the only effect is a cache refresh, not a silent upgrade.

Building an install ISO

On Fedora, ks.cfg is handed to the installer on a second medium or over the network. Debian's equivalent is to bake preseed.cfg into the installation ISO and point the boot menu at it, so the stick is self-contained.

apt-get install xorriso
./debian/make-iso.sh debian-13.7.0-amd64-netinst.iso vdi-debian.iso

The script copies the preseed to /preseed.cfg on the image and adds this to every kernel line in every boot menu:

auto=true priority=critical preseed/file=/cdrom/preseed.cfg
  • auto=true is an alias for auto-install/enable; it delays the locale and keyboard questions so the preseed can answer them.
  • priority=critical is an alias for debconf/priority; nothing below critical is asked.
  • preseed/file=/cdrom/preseed.cfg reads the preseed from the ISO itself. The preseed-md5 checksum parameter is deliberately not used: it must match exactly and breaks the moment the preseed is edited.

The script verifies its own output instead of trusting xorriso's exit status: the preseed is byte-identical on the image, every kernel line carries the parameters, both El Torito boot images (BIOS and UEFI) are present, and no file from the source ISO is missing. It exits non-zero rather than writing an ISO that would boot to an interactive prompt.

Two things worth knowing if you modify it:

  • Every menu file is patched, not a fixed list. On a Debian netinst the BIOS menu is isolinux/isolinux.cfg, which contains only include menu.cfg and default vesamenu.c32; the entry that actually boots by default is in isolinux/gtk.cfg (label installgui, menu default). Patching only the obvious files leaves the default BIOS entry unpatched and the machine still stops to prompt. The script discovers every *.cfg under /isolinux and /boot/grub and patches the ones with kernel lines.
  • The image is not extracted and rebuilt. xorriso -as mkisofs over an extracted tree grows a netinst from 792 MB to 988 MB, because Debian's ISO shares identical file extents between paths and extraction duplicates them all. Instead the original session is copied and only the changed files are mapped over it (-indev SRC -outdev DST -boot_image any replay -map ...), which keeps the deduplication and the boot record intact.

Verified against debian-13.7.0-amd64-netinst.iso: 20 of 20 BIOS kernel lines and 20 of 20 UEFI kernel lines patched, all 1010 source files present, preseed byte-identical, both boot images intact, output 792 MB.

The inventory number is still asked for on the console. The preseed cannot guess it, and it has to be read from a human.

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:

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.