AZ-NIX-CLIENTS/roles/thin-client/README.md

roles/thin-client — AZ-NIX-CLIENTS Thin Client Fleet

NixOS role for the AZ-TC-NN fleet. Replaces a Windows 10 workstation with a locked-down NixOS + KDE Plasma client that authenticates against Active Directory and provides pre-configured RDP, browser, and Office-Web access.

This document describes the provisioning workflow for a new Fleet Host.

Decision summary

All 20 design decisions from the grilling session are captured in the top-level default.nix comments and the individual submodule headers. Quick reference:

Area	Decision
Hardware	Dell OptiPlex Micro (3020/3040/5040/7040) + generic-x86_64-uefi fallback
Deployment	Stock Linux ISO + nixos-anywhere
Disk	BTRFS (@root, @home, @nix, @persist, @snapshots), zstd
AD	Realm AZ-GROUP / DNS az-group.local, pre-created computer accounts + keytab via agenix
Shell	bash for domain users
Session	KDE Plasma 6, Wayland, SDDM, no autologin
Sudo	%domain admins with password; local sascha.koenig + jannik.mueller as break-glass
WiFi	802.1X EAP-TLS per-machine, NetworkManager + wpa_supplicant (not iwd)
SMB	pam_mount, Kerberos, DFS namespace, lax offline
RDP	System-wide Remmina, Kerberos SSO, fullscreen multi-monitor, audio local only
Office	5 .desktop shortcuts via chromium --app=URL; Outlook + Teams autostart
Chromium	ManagedBookmarks, sync disabled, uBlock Origin + Bitwarden, no local passwords
RustDesk	Client + daemon, self-hosted server, pre-shared key, Wayland portal pre-authorized
OBS	Pre-configured "AZ-Default" profile, output to ~/Videos/OBS/
NetBird	Per-host setup key, corp DNS + NetBird DNS parallel, accept-routes
Printers	Single Pull-Print queue, direct IPPS, Avahi off
Branding	Light: corporate wallpaper + SDDM logo + property footer, no banner
Updates	system.autoUpgrade daily at 03:00, reboot window 03:00-05:00
Monitoring	node_exporter → Pushgateway, Alloy → Loki (journal), Snipe-IT asset check-in (daily 03:30)
Rollout	Pilot: 3 hosts, 2 weeks; then 5 → 10 → rest

Provisioning workflow for a new Fleet Host

Assuming you've copied hosts/AZ-TC-01/default.nix to hosts/AZ-TC-NN/default.nix, updated networking.hostName, added the flake entry, and committed.

Step 1 — Pre-create the AD computer account + keytab

Run from a host that can reach the AD DC (e.g. AZ-LT-NIX). Requires adcli (available on the admin workstation via nix-shell -p adcli if not installed).

Prerequisite: the target OU must exist in AD. If OU=ThinClients,... doesn't exist yet, create it first (or omit --domain-ou to use the default CN=Computers,... container).

# Pre-create the computer object in the ThinClients OU
adcli preset-computer \
  --domain=az-group.local \
  --domain-ou="OU=ThinClients,DC=az-group,DC=local" \
  --os-name="NixOS" --os-version="26.05" \
  --login-user=administrator \
  AZ-TC-01.az-group.local

# Produce a keytab for that pre-created computer object.
# --host-fqdn redirects adcli from the local machine to the AZ-TC-01
# account; -K writes only to the specified path (does NOT modify the
# local machine's /etc/krb5.keytab).
adcli join \
  --domain=az-group.local \
  --host-fqdn=AZ-TC-01.az-group.local \
  --os-name="NixOS" --os-version="26.05" \
  --login-user=administrator \
  -K /tmp/AZ-TC-01.keytab

# Verify the keytab has expected principals
klist -k /tmp/AZ-TC-01.keytab
# Expected principals:
#   AZ-TC-01$@AZ-GROUP
#   host/AZ-TC-01.az-group.local@AZ-GROUP
#   RestrictedKrbHost/AZ-TC-01.az-group.local@AZ-GROUP
#   HOST/AZ-TC-01@AZ-GROUP
#   RestrictedKrbHost/AZ-TC-01@AZ-GROUP

# Provision the agenix secret
agenix -e secrets/AZ-TC-01-krb5-keytab.age
# In the editor: paste /tmp/AZ-TC-01.keytab contents, save, exit.
rm /tmp/AZ-TC-01.keytab

Tip: if you already have an admin TGT (via kinit administrator@AZ-GROUP), you can replace --login-user=administrator with --login-ccache=${KRB5CCNAME:-/tmp/krb5cc_$(id -u)} to skip the password prompt.

Step 2 — Provision NetBird setup key

In the NetBird UI (https://netbird.az-group.local):

1. Go to Setup Keys → Generate new key.
2. Name: AZ-TC-01, Type: one-time (or reusable for fleet), Expires: 90d.
3. Copy the key value.
4. agenix -e secrets/AZ-TC-01-netbird-setupkey.age → paste the key.

Step 3 — Provision WiFi client certificate

In AD CS (https://certsrv.az-group.local/certsrv):

1. Request a Certificate → Advanced certificate request.

2. Template: Workstation Authentication (or your corp 802.1X template).

3. Subject: CN=AZ-TC-01$.

4. Export the cert + private key as PKCS#12 (.pfx), with exportable key.

5. Convert to combined PEM (cert + key in one file):

   openssl pkcs12 -in AZ-TC-01.pfx -out AZ-TC-01.pem -nodes
   

6. agenix -e secrets/AZ-TC-01-wifi-client-cert.age → paste the PEM.

Step 4 — Provision RustDesk credentials

# Generate a strong permanent password per host
PW=$(openssl rand -base64 24)
echo -n "$PW" > /tmp/AZ-TC-01-rustdesk-pw.txt
agenix -e secrets/AZ-TC-01-rustdesk-password.age
# Paste /tmp/AZ-TC-01-rustdesk-pw.txt contents.
rm /tmp/AZ-TC-01-rustdesk-pw.txt

The shared rustdesk-psk.age is one-time setup, reused for all hosts.

Step 5 — Provision the host

Boot the OptiPlex from a stock Linux ISO (any modern NixOS installer ISO or Ubuntu live ISO works). From the admin workstation:

# Bootstrap nixos-anywhere into the booted ISO (via SSH or physical console)
# Then run the install:
nixos-anywhere \
  --flake .#AZ-TC-01 \
  --disko-config ./roles/thin-client/deployment/disko.nix \
  root@<target-ip>

The host will:

1. Partition the disk via disko (BTRFS layout).
2. Install NixOS from the flake.
3. Reboot into the new system.
4. On first boot: agenix decrypts secrets, sssd starts with keytab, NetBird enrolls via setup key, WiFi connects via EAP-TLS.

Step 6 — Capture the host's SSH host key

After first boot:

ssh-keyscan -t ed25519 AZ-TC-01.netbird | awk '{print $2 " " $3}'

Update secrets.nix with the real AZ-TC-01 SSH key value (replacing the PLACEHOLDER line). Rebuild and redeploy.

Option reference

All tunable parameters live under az.tc.*:

Option	Default	Description
az.tc.enable	false	Activate the thin-client role
az.tc.hardwareClass	generic-x86_64-uefi	One of dell-optiplex-micro or generic-x86_64-uefi
az.tc.site	default	Site identifier (informational)
az.tc.ad.ou	OU=ThinClients,DC=az-group,DC=local	AD Organizational Unit for computer objects
az.tc.wifi.ssid	AZ-CORP	Corp WiFi SSID
az.tc.wifi.caCert	./assets/corp-wifi-ca.pem	Corp CA cert (NOT secret)
az.tc.netbird.managementUrl	https://netbird.az-group.local:443	NetBird server URL
az.tc.smb.dfsNamespace	\\\\az-group.local\\dfs	DFS namespace root
az.tc.smb.userShare	users/%u	Per-user share path
az.tc.smb.commonShares	[public software]	Common share names
az.tc.smb.mountRoot	/mnt/az-dfs	Local mount root
az.tc.printing.pullPrintEndpoint	ipps://pull-print.az-group.local:443/ipp/print	Pull-Print IPPS URI
az.tc.printing.queueName	Pull-Print	Local CUPS queue name
az.tc.rdp.servers	[{name="TS Berlin"; fqdn="ts-berlin.az-group.local";}]	TS endpoints
az.tc.chromium.homepage	https://www.office.com	Browser homepage
az.tc.chromium.bookmarks	[Outlook, Teams, SharePoint, Office]	Managed bookmarks
az.tc.chromium.bitwardenServerUrl	https://vault.bitwarden.com	Bitwarden URL
az.tc.rustdesk.serverHost	rustdesk.az-group.local	RustDesk server host
az.tc.branding.hotline	+49 30 1234567	IT hotline for footer
az.tc.branding.wallpaper	./assets/wallpaper.svg	Wallpaper path
az.tc.branding.logo	./assets/logo.svg	Logo path
az.tc.branding.company	AzIntec GmbH	Company name
az.tc.monitoring.prometheusPushGateway	pushgateway.az-group.local:9091	Pushgateway URL
az.tc.monitoring.lokiUrl	http://loki.az-group.local:3100	Loki URL
az.tc.monitoring.snipeItUrl	https://snipeit.az-group.local	Snipe-IT base URL
az.tc.monitoring.assetTool	snipe-it	Asset tool integration
az.tc.deployment.diskDevice	/dev/sda	Disko target disk
az.tc.deployment.swapSizeGB	4	Swap size in GB

Open items before pilot deploy

These placeholders need real values before pilot deploy. They're flagged with # TODO: in the respective modules.

• Real corp WiFi SSID
• Real CA root cert (replace corp-wifi-ca.pem)
• Real DFS namespace path
• Real common share names
• Real Terminal Server endpoints
• Real Chromium bookmarks (Intranet, Helpdesk, ERP, HR)
• Real Bitwarden server URL (if self-hosted)
• Real RustDesk server hostname
• Real Pull-Print IPPS endpoint
• Real NetBird management URL
• Real Prometheus Pushgateway URL
• Real Loki URL
• Real IT-Hotline phone number
• Real corporate wallpaper asset (replace placeholder SVG)
• Real corporate logo asset (replace placeholder SVG)
• Real AD DCs (az-dc01.az-group.local, az-dc02.az-group.local — currently guessed)
• Real AD Computer OU DN

Build validation

To validate the config without deploying:

# Eval-check all hosts
nix flake check

# Build a pilot host closure (full closure, takes ~20 min uncached)
nix build --no-link .#nixosConfigurations.AZ-TC-01.config.system.build.toplevel

# Try a VM boot
nix run .#nixosConfigurations.AZ-TC-01.config.system.build.vm

All three pilot hosts pass both nix flake check and full closure build.

Placeholder assertions

The role ships with placeholder assertions that fire at build time if operator-relevant values are still defaults. To silence for lab/staging hosts, set az.tc.site = "staging" (see hosts/AZ-TC-01/default.nix).

Currently asserted:

• az.tc.wifi.ssid != "AZ-CORP" — real Corp SSID must be set
• az.tc.branding.hotline != "+49 30 1234567" — real hotline must be set
• az.tc.branding.company != "AzIntec GmbH" — real company name must be set

Add more assertions as customer-specific values firm up.