RedBear-OS/local/docs/WIFI-VALIDATION-RUNBOOK.md

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:

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.

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:

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:

./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:

./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:

./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:

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:

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:

./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:

./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:

./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:

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:

./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.