rpi-hostap Documentation
Lightweight Docker container that turns a Raspberry Pi into a wireless Access Point with DHCP server. See the main README for overview, prerequisites, quick start and the environment variable reference.
View the full documentation site: rpi-hostap documentation site
How do I…
Section titled “How do I…”| Goal | Variable(s) | Docs |
|---|---|---|
| Change the network name or password | SSID, WPA_PASSPHRASE |
README environment variables |
| Hide my SSID (don’t broadcast the network name) | HIDE_SSID=1 |
README |
| Only let specific devices (my laptop) connect | MAC_FILTER=1, MAC_ACL_FILE |
MAC address filtering |
| Block specific devices | MAC_FILTER=2, MAC_ACL_FILE |
MAC address filtering |
| Limit how many clients can connect | MAX_STATIONS |
README |
| Stop clients from seeing each other | AP_ISOLATION=1 |
README |
| Use WPA3 (or WPA2/WPA3 transition mode) | WPA_VERSION=3 / mixed |
WPA3 (SAE), verifying client SAE support |
| Get faster WiFi (802.11n/ac, 5 GHz) | HW_MODE=a, CHANNEL, HT_ENABLED, HT_CAPAB, VHT_ENABLED, VHT_CAPAB |
HT/VHT tuning |
| Use a different channel / country | CHANNEL, COUNTRY_CODE |
Regional channel validation |
| Change the AP’s IP address or DHCP range | AP_ADDR, SUBNET, DHCP_RANGE, DHCP_LEASE |
README |
| Change DNS servers given to clients | PRI_DNS, SEC_DNS |
README |
| Enable IPv6 for clients | IPV6=1 |
IPv6 support |
| Restrict NAT to specific outgoing interfaces | OUTGOINGS |
Outgoing interfaces |
| Make IP forwarding persist across reboots | host sysctl config | NAT / IP forwarding |
| List connected clients | CTRL_INTERFACE=1 + clients.sh |
Client inspection |
| Count connected clients | CTRL_INTERFACE=1 + clients.sh count |
Client inspection |
| Show DHCP leases | CTRL_INTERFACE=1 + clients.sh leases |
DHCP leases |
| Disconnect a client | CTRL_INTERFACE=1 + clients.sh deauth <mac-address> |
Client inspection |
| Verify the AP is actually beaconing | HEALTHCHECK_DEEP=1 |
Deep healthcheck |
| Give a DFS channel time to start (CAC wait) | HEALTHCHECK_START_PERIOD |
Deep healthcheck: DFS channels |
| Test my configuration without touching the system | --validate flag |
Dry-run validation |
| Fix “Could not connect to kernel driver” | - | Troubleshooting |
| Fix a container that exits immediately | - | Troubleshooting |
| Diagnose missing IPv6 connectivity on clients | IPV6 |
IPv6 troubleshooting |
Understand why the container is unhealthy |
HEALTHCHECK_START_PERIOD, HEALTHCHECK_DEEP |
Health Check |
| Preserve crash logs for debugging | FAILURE_LOG_DIR, FAILURE_LOG_KEEP, FAILURE_LOG_PATH |
Preserved failure logs |
| Audit a running system against its config | --check flag |
Runtime state audit |
| Require minimum connected clients | HEALTHCHECK_MIN_STATIONS |
Minimum station count |
| Auto-select WiFi channel | CHANNEL=acs |
ACS |
| Use a non-standard WiFi driver | DRIVER |
Driver override |
| Inject custom hostapd options | HOSTAPD_EXTRA_OPTS |
Extra hostapd options |
Contents
Section titled “Contents”| Document | Description |
|---|---|
| SPEC | Project requirements: purpose, functional and non-functional requirements, non-goals |
| Configuration | HT/VHT tuning, MAC filtering, WPA3/SAE, regional channels |
| Networking | NAT / IP forwarding, IPv6 support, outgoing interfaces |
| Validation | Dry-run config checks with --validate |
| Operations | Client inspection, runtime diagnostics |
| Troubleshooting | Common errors: kernel driver conflicts, containers exiting immediately |
| Health Check | Container healthcheck internals, grace periods, deep healthcheck |
| CI | E2E Test workflow, hwsim module cache and branch scoping |
Quick reference
Section titled “Quick reference”| Task | Where |
|---|---|
| List all environment variables | README table |
| Test a configuration without touching the system | wlanstart.sh --validate |
Complete docker run example with all option groups |
README |
| List connected clients | clients.sh |
Last updated: 2026-08-24