Skip to content

Systemd operation

Fin edited this page Nov 14, 2026 · 2 revisions

Systemd operation

The unit

install/install.sh install copies the code to /opt/tuxchange and writes /etc/systemd/system/tuxchange.service, which runs that root-owned copy. Re-run it after updating your checkout.

sudo systemctl start tuxchange
sudo systemctl stop tuxchange
systemctl status tuxchange
journalctl -u tuxchange -f

What the unit does on every start

ExecStartPre runs scripts/sp_monitor.sh up, which takes the adapter from NetworkManager and builds the active-monitor interface from scratch. ExecStopPost runs down, which tears it back down and hands the adapter back, including when the service fails. Restarting the service therefore also recovers a wedged radio.

The watchdog

The daemon sends WATCHDOG=1 from inside its sniffing loop, at most every five seconds. If the radio freezes, the heartbeat stops and systemd restarts this service:

WatchdogSec=120
Restart=always
RestartSec=15

120 seconds is far longer than any single blocking call in the loop (the receive timeout is 0.25 s), and a freeze costs at most two minutes.

The service cannot reboot your machine

FailureAction=none
SuccessAction=none
StartLimitAction=none

The daemon states these even though none is the default, because other values such as reboot, poweroff and reboot-force must never be set here. StartLimitIntervalSec=0 removes the restart rate limit, so a radio that comes back after an hour is picked up even if the unit restarted many times in the first minute.

This applies to the service. scripts/tuxchange-link, a separate debugging tool, does arm a timed forced reboot while it runs. See the CLI reference.

Configuration, and who wins

Settings come from three places, in this order:

  1. Environment= lines in the unit, which are the built-in defaults.
  2. /etc/default/tuxchange, where you put your settings.
  3. /var/lib/tuxchange/relay.env, written by the daemon when you change the adapter or the rotation period from the GUI or ctl. It is listed last so that those changes win.

A later EnvironmentFile beats an earlier one, and beats a unit Environment= line for the same key regardless of order. All three are root-owned. The daemon checks each value before saving it.

Variable Default Meaning
SP_IFACE (empty) Real wireless interface; empty picks the first ath9k adapter.
SP_MON mon0 Monitor interface to create.
SP_STORE /var/lib/tuxchange Where messages live. Must be a directory only root can change.
SP_CHANNELS 1,6,11 Channels to watch.
SP_WINDOW 180 Seconds of radio time per pass.
SP_IDLE 2 Pause between passes.
SP_ROTATE 0 Identity rotation period; 0 never rotates.
SP_EXTRA (empty) Extra arguments passed straight to sp_relay.py run.
SP_CONTROL_USER the user who ran the installer The one non-root user allowed to use the control socket.

After editing: sudo systemctl restart tuxchange.

Privilege

The service runs as root. These settings limit it somewhat, but the capability set is broad, so treat it as a privileged process:

CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN CAP_SYS_ADMIN CAP_DAC_OVERRIDE CAP_CHOWN CAP_FOWNER CAP_SETUID CAP_SETGID CAP_KILL
ProtectHostname=yes
ProtectControlGroups=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
LockPersonality=yes

The installer also writes /etc/polkit-1/rules.d/50-tuxchange.rules, granting one named desktop user permission to start, stop and restart this one unit and nothing else. Tuxchange never writes to /etc/sudoers.d.

Logs

SyslogIdentifier=tuxchange, so:

journalctl -u tuxchange -f
journalctl -u tuxchange --since "1 hour ago"

Per-pass run logs live under the store directory and are readable only by root. --keep-runs bounds how many are kept.

Uninstalling

sudo ./install/install.sh uninstall

Stops and disables the unit and removes the unit file, the polkit rule, the menu entry and /opt/tuxchange. It leaves /etc/default/tuxchange, your keys in /etc/tuxchange and your store alone.

Clone this wiki locally