216 lines
6.5 KiB
Markdown
216 lines
6.5 KiB
Markdown
# Red Bear OS Wi‑Fi Validation Runbook
|
||
|
||
This runbook is the canonical operator path for exercising the current bounded Intel Wi‑Fi stack on
|
||
either a real Red Bear OS target or a VFIO-backed Red Bear guest.
|
||
|
||
It does **not** claim that Wi‑Fi is fully solved. Its job is to make the remaining hardware/runtime
|
||
validation step reproducible and evidence-oriented.
|
||
|
||
## Goal
|
||
|
||
Produce one or both of the following from a real target execution:
|
||
|
||
- a successful bounded Wi‑Fi lifecycle run (`redbear-phase5-wifi-check`)
|
||
- a structured evidence bundle (`redbear-phase5-wifi-capture`) for debugging real failures
|
||
|
||
## Path A — Bare Metal Runtime Validation
|
||
|
||
Use this when Red Bear OS is booted on a real machine with a supported Intel Wi‑Fi device.
|
||
|
||
### In target runtime
|
||
|
||
For an interactive operator path before or alongside the packaged checkers, the new console client is:
|
||
|
||
```bash
|
||
redbear-netctl-console
|
||
```
|
||
|
||
It is a Redox-native **ncurses** terminal client, and it uses the same bounded `/scheme/wifictl`
|
||
and `/etc/netctl` surfaces as the scripted/operator flows.
|
||
|
||
```bash
|
||
redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json
|
||
test-wifi-baremetal-runtime.sh
|
||
```
|
||
|
||
### Artifacts to preserve
|
||
|
||
- `/tmp/redbear-phase5-wifi-capture.json`
|
||
- terminal output from `redbear-phase5-wifi-check`
|
||
- terminal output from `test-wifi-baremetal-runtime.sh`
|
||
- any serial console log captured during the run
|
||
|
||
Recommended host-side naming after copying artifacts off the target:
|
||
|
||
- `wifi-baremetal-capture.json`
|
||
- `wifi-baremetal-serial.log`
|
||
- `wifi-baremetal-console.log`
|
||
|
||
Recommended staging pattern on the host:
|
||
|
||
```bash
|
||
run_dir=./wifi-baremetal-$(date +%Y%m%d-%H%M%S)
|
||
mkdir -p "$run_dir"
|
||
# copy the capture/log files into that directory
|
||
./local/scripts/package-wifi-validation-artifacts.sh \
|
||
"${run_dir}.tar.gz" \
|
||
"$run_dir"
|
||
```
|
||
|
||
Optional packaging step on the host:
|
||
|
||
```bash
|
||
./local/scripts/package-wifi-validation-artifacts.sh
|
||
```
|
||
|
||
The resulting tarball now includes a small manifest file with the packaged paths and file checksums
|
||
for regular files when `sha256sum` is available on the host.
|
||
|
||
Optional summary step on the host:
|
||
|
||
```bash
|
||
./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-baremetal-capture.json
|
||
# or
|
||
./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-validation-artifacts.tar.gz
|
||
# or use the packaged analyzer directly on the captured JSON
|
||
redbear-phase5-wifi-analyze ./wifi-baremetal-capture.json
|
||
```
|
||
|
||
Optional one-shot post-run step on the host:
|
||
|
||
```bash
|
||
./local/scripts/finalize-wifi-validation-run.sh \
|
||
./wifi-baremetal-capture.json \
|
||
./wifi-validation-artifacts.tar.gz \
|
||
./wifi-baremetal-serial.log \
|
||
./wifi-baremetal-console.log
|
||
```
|
||
|
||
## Path B — VFIO/QEMU Validation
|
||
|
||
Use this when a host can safely detach an Intel Wi‑Fi PCI function and pass it through to a Red Bear
|
||
guest.
|
||
|
||
### On the host
|
||
|
||
First, validate the host prerequisites:
|
||
|
||
```bash
|
||
sudo ./local/scripts/validate-wifi-vfio-host.sh \
|
||
--host-pci 0000:xx:yy.z \
|
||
--expect-driver iwlwifi
|
||
```
|
||
|
||
This preflight now exits non-zero when blockers are found, so it is safe to use as an automation
|
||
gate before attempting VFIO passthrough validation.
|
||
|
||
Then run the full passthrough validation wrapper:
|
||
|
||
```bash
|
||
sudo ./local/scripts/run-wifi-passthrough-validation.sh \
|
||
--host-pci 0000:xx:yy.z \
|
||
--host-driver iwlwifi \
|
||
--artifact-dir ./wifi-validation-$(date +%Y%m%d-%H%M%S)
|
||
```
|
||
|
||
Default output artifacts from that wrapper:
|
||
|
||
- `./wifi-passthrough-capture.json`
|
||
- `./wifi-passthrough-capture.json.meta.json`
|
||
|
||
If `--artifact-dir` is provided, those files are written into that directory instead.
|
||
|
||
Recommended packaging step afterwards:
|
||
|
||
```bash
|
||
./local/scripts/package-wifi-validation-artifacts.sh \
|
||
./wifi-passthrough-artifacts.tar.gz \
|
||
./wifi-validation-YYYYMMDD-HHMMSS
|
||
```
|
||
|
||
That tarball also includes the manifest/checksum file described above.
|
||
|
||
Optional summary step afterwards:
|
||
|
||
```bash
|
||
./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-passthrough-artifacts.tar.gz
|
||
# or
|
||
redbear-phase5-wifi-analyze ./wifi-passthrough-capture.json
|
||
```
|
||
|
||
Optional one-shot post-run step afterwards:
|
||
|
||
```bash
|
||
./local/scripts/finalize-wifi-validation-run.sh \
|
||
./wifi-passthrough-capture.json \
|
||
./wifi-passthrough-artifacts.tar.gz \
|
||
./wifi-passthrough-capture.json.meta.json
|
||
```
|
||
|
||
For structured follow-up after a failed run, use:
|
||
|
||
- `local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md`
|
||
|
||
You can override those paths explicitly if needed:
|
||
|
||
```bash
|
||
sudo ./local/scripts/run-wifi-passthrough-validation.sh \
|
||
--host-pci 0000:xx:yy.z \
|
||
--host-driver iwlwifi \
|
||
--capture-output ./wifi-passthrough-capture.json \
|
||
--metadata-output ./wifi-passthrough-capture.meta.json
|
||
```
|
||
|
||
The wrapper handles:
|
||
|
||
1. binding the selected device to `vfio-pci`
|
||
2. launching the Red Bear guest passthrough harness
|
||
3. running `redbear-phase5-network-check` and `redbear-phase5-wifi-run` inside the guest
|
||
4. collecting the packaged Wi‑Fi capture bundle back to the host
|
||
5. writing a host-side metadata sidecar for the run
|
||
6. restoring the host driver afterwards
|
||
|
||
### Artifact to preserve
|
||
|
||
- `./wifi-passthrough-capture.json`
|
||
- `./wifi-passthrough-capture.meta.json`
|
||
- full terminal log from the wrapper invocation
|
||
|
||
Optional packaging step on the host:
|
||
|
||
```bash
|
||
./local/scripts/package-wifi-validation-artifacts.sh
|
||
```
|
||
|
||
## Minimum Evidence for a Real Runtime Attempt
|
||
|
||
At minimum, keep all of the following together:
|
||
|
||
- the capture JSON bundle
|
||
- the console output of the checker/wrapper
|
||
- the exact PCI BDF used for the Intel Wi‑Fi device
|
||
- whether the run was bare metal or VFIO/QEMU
|
||
|
||
## What Success Means Today
|
||
|
||
Current success is still **bounded** success:
|
||
|
||
- the Intel driver/runtime lifecycle can be exercised on a real target
|
||
- the Wi‑Fi control/profile/reporting stack can observe that lifecycle, including honest bounded
|
||
pending/associating connect state when real association is not yet proven
|
||
- the default bounded validation profile is `wifi-open-bounded`, which intentionally avoids turning
|
||
DHCP handoff into a false requirement for lifecycle-only validation
|
||
- the packaged runtime checker currently proves that bounded open-profile path by default; WPA2-PSK
|
||
is implemented and covered by host/unit-level regressions, but is not yet the default packaged
|
||
runtime validation path
|
||
- a structured evidence bundle is captured for debugging
|
||
|
||
This is **not yet** the same as:
|
||
|
||
- real AP scan/association proof
|
||
- real packet/data-path proof
|
||
- DHCP success over a true wireless link
|
||
- validated end-to-end Wi‑Fi connectivity
|
||
|
||
Those remain the next debugging targets after the first real target execution.
|