Networking — Tinklas

Tinklas owns all network configuration. It is two programs and one wire protocol:

Piece	What it is
tinklasd	The daemon. The sole owner of the Wi-Fi control plane.
tinklas	The command line, and the backend the Network settings pane uses.
The protocol	A local socket between them, and between the daemon and the desktop tray.

There is exactly one owner of the radio, deliberately. Nothing else in the system may talk to it.

Why a daemon rather than just a command

Three things a one-shot command structurally cannot do.

Reconnect after an access point kicks you off. The kernel honours a deauth: it tears the link down, hands the default route back to the wired interface, and deliberately does not reconnect, because the credentials belong to userland. Without a daemon the link then stays down until a human runs a command.

Push events to the desktop tray. The compositor's tray may never block the frame loop, and both interesting radio calls block for a long time — a scan sweeps every channel with a dwell on each, and a connect runs authentication, association and the WPA2 handshake, which can sit for seconds. The tray is a non-blocking client of the daemon and never touches the radio itself.

Hold the boot-time reapply and retry it. Applying a saved network is one shot; the daemon retries a join that failed.

It is a system service, not a session one. An earlier design was started by the desktop session, which made a machine's network depend on a desktop coming up — so a headless or Wi-Fi-only box had no way back.

The radio switch

The Wi-Fi switch is persisted in network.conf, and it is off on a machine that has never joined a network.

Off means the hardware is idle: the scanner parks and the antenna is not worked.

The switch state is in the kernel log. The daemon writes one line at start, one on every change, and one on either side of every join — never an SSID and never a passphrase. This exists because an empty Wi-Fi menu caused by the switch being off looks exactly like a scan that found nothing, and the only thing that can tell them apart is a line saying which it was.

Is the radio real?

A software radio is compiled into every kernel and registers only when the kernel command line asks for it. It beacons two software access points and is what makes the whole 802.11 stack — scan, authentication, association, the WPA2 handshake and the encrypted data path — exercisable with no hardware at all.

It is opt-in for a reason. It used to register on every boot, and on a machine with a real card it appeared tens of seconds before the real driver replaced it — so the owner was shown two fabricated, clickable networks. A machine with real Wi-Fi must never present invented networks to a human.

On a machine whose real radio has no driver, the software radio is the only one the kernel has. The status then honestly reads "a radio, two networks in range", which is true and completely misleading — the networks are inside the kernel.

So the answer is carried explicitly, and every client says so:

Where	What it shows
The daemon's first log line	That the radio is simulated, and that every network it reports is software
tinklas status	sim=yes on the interface line
tinklas scan	A note on stderr when the rows are simulated
The menu-bar tray	"Wi-Fi: Simulated", with an explanation under the list
System Preferences → Network	The long form, under the network list

A user interface that cannot tell a simulation from a scan will present a simulation as a scan. That is not a hypothesis — it happened, and it was then misdiagnosed as a hardware fault.

An empty scan list has four meanings

tinklas scan used to print nothing and exit successfully whether the switch was off, the machine had no radio, no daemon answered, or the sweep genuinely ran over an empty band.

The reason now goes to stderr — stdout stays the machine-readable columns — and the exit code answers the one question a caller actually has: did the sweep run?

Code	Meaning
0	The sweep ran. Zero rows is then a real measurement of an empty band.
1	No daemon answered.
2	The Wi-Fi switch is off, so nothing was swept.
3	This machine has no Wi-Fi hardware.

Rows are printed only when the sweep ran. The daemon answers a scan request from its cache immediately — deliberately, so an open Wi-Fi menu does not go blank while it waits — and with the switch off no sweep ever follows. Rows on stdout are a measurement to whatever reads them, and nobody reads the exit code and the list at the same time, so when no sweep ran the list is empty.

Scan pacing

Three limits stack, and the daemon never bypasses the kernel's own floor.

Limit	Value	Why
Kernel hard floor	250 ms	Added after a scan flood livelocked a machine.
On-demand coalescing	5 s	A user interface hammering scan folds into one sweep.
Background sweep	5 minutes	An earlier 30-second sweep was itself a scan flood on real hardware.

DHCP, DNS and status

Leases are renewed, rebound and given up properly rather than being acquired once and forgotten, and the resolver configuration follows the lease.

tinklas status prints one line per interface under its own name, and tinklas connect reports the answer however long the join takes, rather than returning before the outcome is known.