# Operations: install, first run, upgrade, recovery

## Requirements

- Raspberry Pi 4 or 5 (other arm64 Debian systems with NetworkManager and an AP-capable radio
  may work but are untested)
- Raspberry Pi OS Lite 64-bit, Bookworm or Trixie, with NetworkManager (the default)
- Ethernet connected to the network you will manage it from
- ≥ 1 GiB free disk. An SSD (USB 3 or NVMe) is strongly recommended for captures: SD cards
  are slow and wear out.

## Install

```sh
tar xzf pilens-<ver>-linux-arm64.tar.gz && cd pilens-<ver>-linux-arm64
sudo ./install.sh                # explains every change and asks first
```

What it does, in order: checks the platform; detects interfaces and your SSH path; checks AP
support, disk, RAM and conflicting services; shows the plan; backs up
`/etc/NetworkManager/system-connections` and `nft list ruleset` to
`/var/backups/pilens/<time>/`; installs `tshark wireshark-common nftables dnsmasq-base iw`
from apt; installs PiLens to `/opt/pilens`; creates user `pilens`; installs systemd units;
initialises the database and TLS certificate; starts the services and checks they are healthy.
If any step fails, the trap rolls back (on an upgrade, the previous version is restored).

It does **not** touch existing network connections. The access point is created by the
wizard.

Options: `--mgmt-iface eth0 --mgmt-subnet 192.168.1.0/24` to override detection, `--yes`,
`--non-interactive --config setup.yaml`.

## First run

Open the URL printed by the installer and compare the certificate fingerprint. The wizard
asks for the setup token, creates the administrator, and then walks through management access,
uplink, Wi-Fi, client subnet, forwarding, inspection mode and storage. "Apply" performs the
transactional network change. If the browser loses power or the page reloads, the wizard
resumes: progress is kept in the browser, and the server holds what has actually been applied.

## Upgrade

Run the new package's `install.sh`. It detects the existing installation, keeps
`/var/lib/pilens`, replaces the binaries and units, and restarts. Migrations run automatically
on start. If the health check fails, the previous version is restored from the backup.

## Recovery

| Problem | Action |
|---|---|
| Services unhealthy, permissions wrong, dumpcap lost capabilities | `sudo /opt/pilens/repair.sh` |
| Forgotten password | `sudo -u pilens /opt/pilens/bin/pilens reset-password -user admin` (also disables TOTP and revokes sessions) |
| Locked out by the management subnet | On the console: `sudo nft delete table inet pilens`, then fix the subnet in the UI and apply. The table is restored at the next apply or reboot. |
| AP broken after a manual NM change | Re-apply from Network Settings, or `sudo nmcli connection up pilens-ap` |
| Need to return the Wi-Fi to client mode | `sudo nmcli connection down pilens-ap`. Your earlier Wi-Fi profile was never modified. |
| Bug report | `sudo /opt/pilens/diagnose.sh` (secrets redacted) |
| Remove | `sudo /opt/pilens/uninstall.sh` (keeps captures) or `--purge` |

The database is `/var/lib/pilens/pilens.db` (SQLite, WAL). To back it up: stop `pilens`, then
copy `pilens.db*` and `captures/`.

## Capture storage on an SSD

```sh
sudo systemctl stop pilens
sudo mkdir -p /mnt/ssd/pilens-captures && sudo chown pilens:pilens /mnt/ssd/pilens-captures
sudo systemctl edit pilens
#   [Service]
#   ExecStart=
#   ExecStart=/opt/pilens/bin/pilens serve -data /var/lib/pilens -listen :8443 -captures /mnt/ssd/pilens-captures
#   ReadWritePaths=/mnt/ssd/pilens-captures
#   [Unit]
#   RequiresMountsFor=/mnt/ssd/pilens-captures
sudo systemctl start pilens
```

## Service architecture and shutdown

`pilens-firewall` (oneshot, before networking) → `pilens-helper` (root) → `pilens-dnsmasq` →
`pilens` (Type=notify, watchdog 60 s). On SIGTERM, pilens stops accepting requests, stops any
capture (dumpcap flushes, the last segment is fsynced and hashed), and then exits. The timeout
is 60 s.