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.