Repository navigation
Systemd operation
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 -fExecStartPre 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 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.
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.
Settings come from three places, in this order:
-
Environment=lines in the unit, which are the built-in defaults. -
/etc/default/tuxchange, where you put your settings. -
/var/lib/tuxchange/relay.env, written by the daemon when you change the adapter or the rotation period from the GUI orctl. 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.
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.
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.
sudo ./install/install.sh uninstallStops 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.