121 lines
4.2 KiB
Markdown
121 lines
4.2 KiB
Markdown
# openUF
|
|
|
|
Daemon that makes an OpenWrt router appear as a UniFi AP to UniFi Network controllers.
|
|
|
|
## Implemented Features
|
|
|
|
| Feature | Description | Implementation |
|
|
| --- | --- | --- |
|
|
| **L2 Discovery** | UDP broadcast + multicast every 10s | `announce.c` → port 10001 |
|
|
| **Adoption** | AES-128-CBC handshake with the controller | `inform.c` → `handle_response()` |
|
|
| **Firmware spoofing** | Persists and reports the target version requested by an upgrade | `inform.c` → `handle_response()` |
|
|
| **WiFi Config** | Creates WiFi networks from the controller via UCI | `wlan.c` → `wlan_apply_config()` |
|
|
| **Band Steering** | 802.11k/v Neighbor Reports + BSS Transition | `wlan.c` → `apply_vap()` |
|
|
| **Fast Roaming** | 802.11r FT with mobility_domain derived from MAC | `wlan.c` → `apply_vap()` |
|
|
| **WPA3 / PMF** | SAE, SAE-mixed, 802.11w 0/1/2 | `wlan.c` → `sec_to_uci()` |
|
|
| **WiFi Clients** | MAC, signal, bitrate, bytes per VAP | `clients.c` → `iw station dump` |
|
|
| **Wired Clients** | MACs from bridge FDB | `clients.c` → `bridge fdb` |
|
|
| **CPU / RAM** | Real-time usage | `sysinfo.c` → `/proc/stat` + `/proc/meminfo` |
|
|
| **Interfaces** | Speed, duplex, rx/tx counters | `sysinfo.c` → `/proc/net/dev` |
|
|
| **Channel / RF** | Channel utilization, noise, tx_power | `sysinfo.c` → `iw survey dump` |
|
|
| **LLDP Send** | Custom frames via AF_PACKET raw socket | `lldp.c` → `lldp_send_frame()` |
|
|
| **LLDP Read** | Neighbors for UniFi topology | `lldp.c` → `lldpctl -f json` |
|
|
|
|
## Building in the dev container
|
|
|
|
```shell
|
|
# From the OpenWrt build root
|
|
cd /home/openwrt/openwrt
|
|
|
|
# Build only this package
|
|
make package/OpenUniFi/compile
|
|
|
|
# For a clean package rebuild
|
|
make package/OpenUniFi/clean
|
|
make package/OpenUniFi/compile
|
|
```
|
|
|
|
`Makefile.standalone` is an alternative for compiling directly on an OpenWrt
|
|
device that has the development dependencies installed:
|
|
|
|
```shell
|
|
make -f Makefile.standalone
|
|
```
|
|
|
|
Contributors and AI agents should read [`AGENTS.md`](AGENTS.md) for the concise
|
|
architecture map, invariants, and validation checklist.
|
|
|
|
## Changing Compiler Settings
|
|
|
|
```shell
|
|
# OpenWRT build directory
|
|
cd /home/openwrt/openwrt
|
|
|
|
# Change settings
|
|
make menuconfig
|
|
|
|
# export settings
|
|
./scripts/diffconfig.sh
|
|
|
|
# Paste settings into .devcontainer/openwrt.config file in the code
|
|
# Then rebuild the dev container by pressing F1 in VScode
|
|
# and typing rebuild and selecting rebuild dev container
|
|
```
|
|
|
|
## Configuration
|
|
|
|
On the access point, run the following to install the package:
|
|
|
|
```shell
|
|
# Install dependencies
|
|
# replace wpad-basic-mbedtls with wpad-mbedtls
|
|
apk del wpad-basic-mbedtls && apk add wpad-mbedtls && /etc/init.d/network restart
|
|
|
|
# Remove old installation
|
|
apk -r del openuf
|
|
|
|
# Install new version
|
|
apk add openuf-0.4.0-r1.apk --allow-untrusted
|
|
|
|
# Configure
|
|
vi /etc/openuf/openuf.conf
|
|
```
|
|
|
|
Example Configuration
|
|
|
|
```ini
|
|
controller_ip = # Empty: use IPv4 default gateway
|
|
lan_if = br-lan # Default Lan interface Name
|
|
ufmodel = u6-inwall # emulated model
|
|
inform_interval = 10 # inform interval
|
|
enable_announce = 1
|
|
enable_inform = 1 # Enable adoption and telemetry requests
|
|
enable_logging = 1 # Write diagnostics to /var/log/openuf.log
|
|
protocol_debug_level = 0 # 0=off, 1=safe response details,
|
|
# 2=full decrypted JSON (contains secrets)
|
|
|
|
```
|
|
|
|
Set `controller_ip` to a controller IPv4 address or hostname to override
|
|
autodetection. The automatic mode uses the IPv4 default-route gateway for
|
|
initial adoption; after adoption, the controller-provided inform URL is kept.
|
|
|
|
Daemon settings live in `/etc/openuf/openuf.conf`. Adoption and controller state
|
|
are persisted separately in `/etc/openuf/state.json`; do not copy that file
|
|
between devices because it contains the device authentication key.
|
|
|
|
Because UniFi firmware cannot run on the OpenWrt host, an upgrade request does
|
|
not download or install its image. Instead, openUF saves the requested firmware
|
|
version in `state.json` and reports it in subsequent inform packets.
|
|
|
|
---
|
|
|
|
## Glossary
|
|
|
|
### TNBU
|
|
|
|
TNBU is the magic string/identifier at the start of the binary packet format used in this custom Inform protocol implementation.
|
|
|
|
### CCQ
|
|
|
|
Client Connection Quality |