Files
VDI-Linux/README.md
T

432 lines
22 KiB
Markdown
Raw Normal View History

# VDI-Linux
2025-11-04 15:19:37 +01:00
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`.
## 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:
```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.