Troubleshooting
A client doesn't network-boot
Check that PXE boot is enabled in its BIOS/UEFI and Secure Boot is disabled. Then watch the server while the client boots:
sudo journalctl -u dnsmasq -f- Nothing about the client's MAC address: its boot request doesn't reach the server. Check that it really network-boots (boot menu, often F12) and that it's on the same network segment.
- The request arrives but the client gets no answer: set
netstation_dnsmasq_log_dhcp: true, runserver, and look at the detailed log. In proxy mode, also check that the other DHCP server doesn't set options 60, 66 or 67. - dnsmasq hangs (high CPU, clients stop booting): some dnsmasq versions
hang in proxy mode. netstation avoids the known hang of 2.91 to 2.93, so if
it still happens, check
netstation_dnsmasq_extrafor adhcp-rangewith aset:tag. A watchdog checks every 2 minutes and restarts it (seesudo journalctl -u netstation-dnsmasq-watchdog). Check by hand withsudo netstation-dnsmasq-checkafter a client has booted; it measures CPU use, unread packets and whether TFTP still answers. If it keeps happening, pin a working version withnetstation_dnsmasq_version(see Configuration).
A client boots but stops with an error
Add a debug shell for one client, run server, and reboot that client:
netstation_clients:
- mac: "d8:9e:f3:37:53:a1"
settings:
DEBUG_SHELL: 1A client hangs while it starts
The boot splash hides the messages. Press Esc on the client to see them.
To boot one client without the splash, give it its own kernel parameters,
run server, and reboot that client:
netstation_clients:
- mac: "d8:9e:f3:37:53:a1"
settings:
KERNEL_PARAMETERS: nosplashThe client shows a login screen or loops back to it
On the client, press Ctrl+Alt+F2, log in with your server account, and run:
ls -la /home/kiosk # must exist and be owned by kiosk
findmnt /home/kiosk # must print nothing (home in RAM)
grep -rn autologin /etc/lightdm/
sudo tail -40 /var/log/lightdm/lightdm.logRemote Desktop fails on a client
The dialog on the client says roughly what went wrong, and crashes and errors come in as alerts. For xfreerdp3's full output, log in to the client while it's still on, and run:
sudo journalctl -t netstation-rdpThe client keeps its journal in memory, so it's gone after a reboot.
Exit code 136 means a screen is mirrored: keep
netstation_displays_side_by_side on.
Remote Mac doesn't work
- "ID does not exist" or it can't connect: the Mac isn't using this
server (Settings > Network on the Mac), isn't on the network, or RustDesk
isn't running on it. Check the server with
sudo systemctl status rustdesk-hbbs rustdesk-hbbrandsudo journalctl -u rustdesk-hbbs. - "Key mismatch": the key on the Mac isn't the server's. Show the right
one with
sudo cat /var/lib/rustdesk-server/id_ed25519.pub. - The screen shows, but mouse and keyboard do nothing: RustDesk on the Mac lacks Accessibility (see Setting up the Macs). Reopen RustDesk after allowing it.
- Lag: usually the Mac's Wi-Fi. A network cable fixes it; Retina resolutions on the Mac also cost speed.
- Alt and Cmd aren't swapped, or still swapped after the session: log in
to the client and check
systemctl status keyd. A logout always stops it.
On the client, journalctl -t netstation-mac shows each session and
RustDesk's output.
Clients don't wake
Check that Wake-on-LAN is allowed in the client's BIOS/UEFI (often under
power management). If it is, set netstation_wake_broadcast to the broadcast
address of the clients' network (e.g. 192.168.1.255) and run server.
Something can't reach the server
The server's firewall only lets in SSH, network boot, NFS, and Cockpit, WireGuard and RustDesk when they're on. It logs what it drops:
sudo journalctl -k --grep netstation-firewallAllow more with netstation_firewall_extra_rules (nftables rules, e.g.
tcp dport 8080 accept) and run server.
The scheduled staging build failed
sudo journalctl -u netstation-staging-build.service -n 100Production is never touched by a failed build.
The server is broken
Run the server playbook again. It's safe to run at any time and puts every
setting back. If the server is beyond repair, reinstall it from the
installer ISO, run server, then
build and promote a new image.