Classroom_Desktop/docs/networking.md

# Classroom networking

Ethernet remains the normal classroom connection. The package also installs
and enables NetworkManager so an administrator can add Wi-Fi when a room needs
it; there is no classroom Wi-Fi screen and no network name or password in the
package.

## Add Wi-Fi

From a terminal or SSH session, run:

```
sudo nmtui
```

Choose **Activate a connection**, select the church Wi-Fi network, enter its
password, and activate it. NetworkManager saves the connection as a system
connection and reconnects it automatically after reboot.

Useful checks:

```
nmcli device status
nmcli connection show
systemctl status NetworkManager
```

There is nothing to configure on a computer without Wi-Fi hardware.
NetworkManager starts normally, sees no Wi-Fi device, and Ethernet continues
to work.

## Existing Ethernet configuration

Do not remove or rewrite `/etc/network/interfaces` as part of this procedure.
Debian Trixie's NetworkManager configuration uses the `ifupdown` plugin with
`managed=false`, so any Ethernet interface declared there remains under
ifupdown's control. NetworkManager manages other interfaces, including Wi-Fi.
This preserves an existing static or ifupdown Ethernet setup.

The package disables `NetworkManager-wait-online.service`; no classroom
feature is allowed to hold boot waiting for Wi-Fi or Internet access. Saved
connections still reconnect automatically.

## Wi-Fi passwords, and who may see them

These are shared computers in rooms full of people. The classroom account
has to be able to USE the church Wi-Fi and must never be able to READ its
password. In a stock Plasma desktop those two are much closer together
than they look.

**Provision Wi-Fi with `classroom-wifi`, as root.** Not from the desktop.

```
classroom-wifi "Church Wi-Fi"      # prompts, never echoes, never in ps
classroom-wifi --list
classroom-wifi --forget "Old Network"
```

This is a requirement, not a convenience. A wireless network added from
the desktop becomes a **user** connection: NetworkManager records
`connection.permissions` naming whoever added it, and Debian allows that
user to read its secrets with **no authentication at all** —
`org.freedesktop.NetworkManager.settings.modify.own` ships as `yes` for an
active session. Plasma's applet then offers *Show Network's QR Code* on
every saved wireless connection, and that QR code contains the pre-shared
key. So a password typed in at the desktop is readable by the next person
to sit down.

`classroom-wifi` creates a **system** connection instead: no
`connection.permissions`, secrets in a root-only file
(`/etc/NetworkManager/system-connections/*.nmconnection`, 0600 root:root),
`psk-flags=0` so nothing lands in a login keyring. Every account can use
it, and NetworkManager reconnects at boot on its own — no teacher ever
re-enters it.

### What is refused, and what is deliberately not

`49-ekklesia-classroom-network.rules` answers at NetworkManager rather
than in a menu, because hiding buttons is not a control: the applet's
*Show Network's QR Code* and *Configure…* are contextual actions that do
**not** consult the Kiosk key which hides its settings button.

Refused for `classroom`: `settings.modify.own`, `settings.modify.system`,
`wifi.share.protected`, `wifi.share.open`, `settings.modify.hostname`,
`settings.modify.global-dns`, `reload`, `checkpoint-rollback`.

Left alone on purpose: `network-control`, `wifi.scan`,
`enable-disable-network`, `enable-disable-wifi`. None of them returns a
secret, and they are what connecting and seeing a network are made of. A
rule that protected a password by taking the room off the internet would
not be a trade this room can make. Automatic reconnection does not go
through polkit at all — NetworkManager does it as root — so nothing here
can stop the room coming back after a reboot.

An administrator's own account and root are untouched. To lift any of it
for maintenance, drop a file of the same name into
`/etc/polkit-1/rules.d/`, which polkit reads first.

## A Wi-Fi the Debian installer set up

Symptom: the internet works, Chrome loads pages, and the panel insists
there is no connection. Scanning finds nothing either.

Both are true at once, and they have one cause. If the installer was
given the Wi-Fi, it wrote the network into `/etc/network/interfaces`.
ifupdown brings that up with its own `wpa_supplicant` and `dhcpcd`, which
is the working internet. NetworkManager ships here with
`plugins=ifupdown` and `[ifupdown] managed=false`, so an interface named
in that file is marked **unmanaged** — and an unmanaged device is not a
radio NetworkManager will report on or scan with.

Measured on the Bible study laptop:

```
$ nmcli device status
wlp2s0  wifi  unmanaged  --
$ nmcli networking connectivity
none                                  # while curl fetched fine
$ nmcli device wifi list
SSID  SIGNAL                          # nothing, and the radio is enabled
```

`managed=false` stays. It is what keeps a tower's static Ethernet under
ifupdown's control where an administrator put it. Only a **wireless**
interface is moved.

### Moving it, while watching

This is never done by an upgrade. It moves a machine's only link between
two managers, and the machine it could strand is a laptop in a locked
room. `classroom-migrate` only looks and says what it found. An
administrator does the rest, over SSH, watching:

```
classroom-wifi --check              # who owns it; changes nothing
classroom-wifi --adopt --dry-run    # what would change; changes nothing
classroom-wifi --adopt              # do it
classroom-wifi --rollback           # undo it, at any time afterwards
```

`--adopt` creates a NetworkManager **system** connection from the SSID
and key already in that file — so the password never leaves the machine,
is never printed, and lands in a 0600 root-only file with `psk-flags=0`,
exactly as `classroom-wifi` provisions any other network. The stanza is
then commented out, the interface handed over, and the result checked:
the connection must be active **on that interface** and the machine must
really fetch something. Checking only "is the machine online" would pass
on a machine with a second link while the Wi-Fi sat dead.

If any of that fails — including a command that is not installed, or an
interrupt — the original file is put back and ifupdown gets the interface
again. It refuses to start at all if `ifdown`/`ifup` are missing, because
that would be a one-way door.

The original is kept at `/etc/network/interfaces.before-ekklesia-classroom`.

### What 0.2.5 got wrong, and what 0.2.6 changed

The prayer-room laptop's Wi-Fi is **hidden** — `ROGC Classroom`, an SSID
with a space in it, announced by nothing. `--adopt` built a connection,
failed to bring it up, rolled back, and left the adapter belonging to
nobody. Four separate defects, all fixed:

**1. The hidden flag was thrown away.** The stanza said `wpa-scan-ssid 1`
and the parser read it — into `options`, where the only accessor ignored
it. The generated profile had `802-11-wireless.hidden: no`, and
NetworkManager will not associate with an SSID it has not seen in a scan.
A hidden one is never in a scan. `credentials()` returned a pair; there
is now a `profile()` that returns the whole network, and `add()` writes
`802-11-wireless.hidden` in **both** directions rather than only when
true — a default that happens to be right is not an answer.

**2. `ifdown` ran after the stanza was commented out.** ifupdown reads
`/etc/network/interfaces` to find out how to bring an interface down.
With the stanza gone it says *"Ignoring unknown interface"* and does
nothing — so ifupdown's own `wpa_supplicant` and DHCP client were still
holding the radio when NetworkManager was asked to associate with it.
Two supplicants on one interface is a fight NetworkManager loses. The
order is now: **`ifdown` first, while the file still says how; rewrite
the file second.**

**3. The rollback left the adapter unmanaged.** `restore()` ended with
`nmcli device set <dev> managed no`, which is right while ifupdown can
actually bring the interface up. When `ifup` fails too, those two lines
are a wireless adapter neither manager owns: no connection, and a panel
that cannot even scan. That is the state the laptop was found in, and it
is why `sudo nmcli device set wlp2s0 managed yes` was a manual recovery
step. The rollback now escalates — if ifupdown cannot get the network
back either, the interface is handed to NetworkManager rather than left
with neither, and it says so loudly.

**4. A `#` in a password was silently truncated.** The parser cut every
line at its first `#`. `interfaces(5)` is explicit that only whole-line
comments exist — *"end-of-line comments are NOT supported"* — so a
pre-shared key containing `#` became a prefix of itself, and the only
symptom is an association that fails exactly the way a wrong password
fails.

Two smaller ones went with them. The rollback un-comments its own marked
lines in place instead of copying the backup over the whole file, because
the backup is written once and never refreshed — a whole-file restore
silently reverted any *wired* change an administrator made in between.
And `nmcli -t` output is now split on its own escaping rules rather than
on `:`, with `LC_ALL=C`, so a network whose name contains a colon cannot
make a successful migration look like a failed one.

`--adopt` also now refuses a network it cannot recreate — WPA-Enterprise
has no pre-shared key to carry across — *before* taking the interface
away from ifupdown to find out, and reports any `unmanaged-devices` line
in NetworkManager's own configuration, which survives the stanza going
away and would otherwise leave the interface belonging to nobody after a
restart.

Verified against a real NetworkManager 1.52.1: the keyfile it writes
carries `hidden=true`, `ssid=ROGC Classroom` with its space, and a psk
containing `#` intact, at 0600 root:root with no `connection.permissions`.
`tests/test-classroom-wifi-adopt.sh` drives the whole hand-over against
stubbed tools and asserts the ordering, the rollback and the managed
state.

**The prayer-room laptop must not be migrated again.** Its stanza is
already gone, so `--adopt` reports "nothing to adopt" and exits 0 without
touching anything; there is a test for exactly that.

After the migration the panel shows the connection at the next login, the
room can scan, and the credential protection below applies to it like any
other system connection.

### Recovery when there is no network at all

There is deliberately no teacher-facing "join a network" dialog in this
release. Anything that lets the room add a connection also lets the room
own it, and an owned connection is a readable one. Recovery is an
administrator running `classroom-wifi` over SSH, or at the machine
through the maintenance terminal chord. If a room ever needs to join a
network unattended, that workflow has to be designed so the connection it
creates still belongs to the machine — not bolted on by relaxing the rule
above.