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.

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.