# Mark VIII Field Runbook

Operational procedures for running Mark VIII v1.4.0+ on a WiFi Pineapple
Pager. The reliability subsystem is documented in the README; this file is
the how-to-run-it companion.

## Pre-engagement checklist (2 minutes)

From the Dashboard health panel (or `scripts/smoke.sh` over SSH):

- [ ] Health chip green; guard chip shows `GUARD OK` (not PENDING).
- [ ] Both monitors present (`wlan0mon`, `wlan1mon`).
- [ ] Reliability counters sane: no unexpected boots since last check;
      rollbacks/restarts at expected values.
- [ ] Recent events feed shows a clean `boot` entry for this session.
- [ ] RF plan as intended: `PHY0: OPS`, `PHY1:` in the state you want.

If anything fails: run `sh /tmp/smoke.sh` (re-upload via
`scp scripts/smoke.sh root@<ip>:/tmp/` if tmpfs was cleared) and read
which check fails before deploying to a target environment.

## During an engagement

- **Prefer phy1 for any uplink** (`POST /api/rfplan/role {"role":"uplink",
  "ssid":...,"psk":...}`). phy0 stays fully hoppable for 2.4 GHz work.
  Expect 5 GHz recon limited to the uplink's channel while associated.
- **Switching back**: `{"role":"attack"}` tears the STA down with a gated
  reload; verify the RF chip flips and wlan1mon hops again.
- **Watch the events feed.** Occasional `guard_fix` entries are the
  supervisor healing stock-daemon regressions (STA re-parks, UCI
  re-applies) — normal. A stream of them means the stock UI is fighting
  you: stop touching the stock PineAP page mid-engagement.
- **Rollback watchdogs** arm around risky operations. If the web UI dies
  after an operation, wait ~60 s: the watchdog restores the pre-op snapshot
  automatically or promotes the change once healthy. Do NOT power-cycle
  before that window passes.
- **Never** hand-edit `/etc/config/pineapd` mid-engagement; use Mark VIII
  endpoints. Hand edits race the stock daemon and the reconciler.

## After an engagement

1. Stop attacks and switch phy1 to `idle`.
2. Export loot (Handshakes export, HTML/CSV reports). Loot lives under
   `/root/loot/**` and survives reboots — pull it off-box anyway.
3. Save a profile (Settings → Reliability), e.g. `post-<site>-<date>`.
4. Skim events for `rollback` / `mem_warn` entries worth noting.

## Recovery procedures

### Web UI unreachable but device seems alive

Wait 60 s — a rollback watchdog may be mid-restore. Then SSH:

    curl -fsS http://127.0.0.1:8080/ >/dev/null && echo up

If still down, check whether a watchdog is running (`ps | grep watchdog`)
and let it finish; if it already rolled back but the UI did not return,
restart the service: `/etc/init.d/pagerwebui start`.

### Roll everything back to a known-good state

Settings → Reliability → restore `lastknown-good` (auto-captured whenever
the system has been healthy for 5 minutes), or over SSH:

    python3 /mmc/mk8/releases/current/user/remote_access/pager-webui/server.py \
        --rollback-snapshot lastknown-good

### After a firmware upgrade or factory reset

The overlay is wiped; Mark VIII is gone but `/mmc/mk8/` (profiles,
journal, releases) survives. Reinstall:

    ./scripts/deploy.sh --password '<device password>'

The deploy re-installs mk8-guard + service from your release; profiles and
history are still there. Verify with `sh /tmp/smoke.sh`.

### Device totally unreachable

Power cycle. On boot, mk8-guard re-applies safe PineAP UCI before pineapd
starts, so the device comes back crash-free even if the stock daemon had
been left in a bad state. If SSH is still refused after full boot, use the
Hak5 first-boot recovery for the firmware image you are on.

## Known limitations

- Role drill in smoke needs a real AP: `SMOKE_UPLINK_SSID=... [--write]`.
- While phy1 carries an uplink, 5 GHz recon sees only that channel
  (radio physics, not a bug).
- Idle monitors park on one channel between scans; hopping resumes during
  recon scans (verified: ch48 -> ch157 -> ch40).
- Journal is capped at 4 x 5 MB on /mmc; counters read the newest ~5000
  entries.