Multi-WAN gateway daemon. One binary, mwan, for linux/amd64 and linux/arm64.
The binary links libyang and libsysrepo statically through cgo and serves its
configuration over the management datastore. The standards a change must meet
are in AGENTS.md.
Read the gateway architecture for provider selection, routing, failover, and planned designs.
The documentation guide includes MWAN specifications, implementation plans, runbooks, and execution records copied from Configs. It also explains which commands still require the Configs checkout.
The router VPP reference covers optional binary API control, shared memory counters, and native CPU profiling.
Run mwan to list commands. Each command provides its arguments, flags,
defaults, and examples through --help:
mwan ifmgr --help
mwan help deploy wait-deployHelp does not read configuration or start gateway operations. Commands that
use TOML accept --config; the first supplied path overrides MWAN_CONFIG.
The CLI also accepts the existing single-hyphen flag spelling, such as
-config.
gateway-status, config-state, and the debug inspection and probe views
accept --output-format text or --output-format json. The status commands
default to JSON, and debug views default to text. Finite JSON output contains
one object or array. Use --verbose to print diagnostic logs to standard error.
Run mwan health to probe each enabled WAN with its configured ping targets,
attempt count, HTTP URLs, and timeout from WANCONFIG. Linux requires raw socket
permission for ICMP probes. TOML supplies application settings through the
existing --config option. Health probes do not load optional application
observation files or write daemon health state.
mwan health --config /etc/mwan/config.toml
mwan health --watch --output-format jsonThe command checks every configured target in a complete sweep and sends the configured number of ping attempts per target. Each address family with ping targets also receives one HTTP request per configured URL. Empty families and disabled policies do not trigger probes.
The command defaults to text and exits after a complete sweep. Finite JSON
contains one array of raw probe records. --watch starts each WAN independently
and waits for that WAN's configured interval after its previous sweep finishes.
Watched JSON contains one record per line as attempts complete. Interrupting
the command cancels probes and waits for workers to finish.
Records include WAN identity, interface, family, target, attempt, timestamp,
returned measurements, and probe errors. Completed failed probes remain result
data. Argument, configuration, and output errors cause a nonzero exit. Use
--network and --schema-dir to select the existing WANCONFIG document and
validation models, and --verbose for diagnostic logs on standard error.
| Path | What it holds |
|---|---|
gateway/cmd/mwan |
The binary: every subcommand |
gateway/internal/installspec |
The role table and the units, drop-ins and policy that mwan install writes |
gateway/internal |
The daemon: interface management modules, BGP, health, the agent, the wanconfig publisher |
gateway/internal/yangpub/schema |
The YANG modules the binary embeds |
gateway/proto, gateway/gen |
The mwan.v1 wire contract and its generated code |
gateway/yang/instances |
The network documents the instance gate validates |
gateway/tools |
The wanconfig stack packaging tool and its builder image |
provider |
The terraform-provider-mwan OpenTofu provider: data sources for the release archives and the files each role installs |
The units, drop-ins, YANG schema, and read-only RESTCONF policy are inside the
binary, so a host runs the files the release it pins was built from rather than
whatever a deploying checkout held. mwan install puts them on the host:
mwan install # Print help
mwan install --role wan --apply # install everything that role owns
mwan install --print-schema /tmp/schema # write the YANG modules for validation
What a role installs:
- Every role writes its systemd units and drop-ins, then re-enables them, so a
unit whose
WantedBymoved loses the symlink under its old target. - The
wanrole installs or updates the YANG modules in sysrepo and imports the read-only NACM policy into each of startup and running that does not already hold it.
The verb renders no template and reads no site value, so every file it writes
is byte-identical at every site. configs renders the files that need one.
A second --apply run reports no change and leaves every timestamp alone.
--root <dir> writes under another directory, asks systemd for nothing, and
keeps its own sysrepo repository below the root, which is how to inspect a run
without affecting the machine. The verb never restarts the daemon; that
decision stays with whatever called it.
The reporter uses the existing TOML configuration and WANCONFIG document. Its runtime requirements are:
| Requirement | Purpose |
|---|---|
| Linux | Interface, connection, CPU, and memory counters. |
| RRDtool | Graph history and image rendering. |
| Liberation Mono | Graph text. |
| Email configuration | Recipient and SMTP2GO credential or msmtprc_path. |
CAP_NET_RAW |
WAN probes. |
CAP_NET_ADMIN |
Linux connection accounting. |
MWAN writes report history to state_directory and runs the executable at rrdtool_path. Both paths must be absolute:
[report]
state_directory = "/var/lib/mwan/reporting"
rrdtool_path = "/usr/local/bin/rrdtool"Disabled kernel byte accounting makes client attribution incomplete. WAN interface measurements remain available independently of client accounting.
Reporting commands:
| Command | Operation |
|---|---|
mwan report watch |
Collect measurements and send scheduled reports and incident emails. |
mwan report send |
Send a summary from saved observations. |
The --network option selects the WANCONFIG document, and --schema-dir selects its YANG validation models. Read reporting behavior for measurement meanings and incident handling.
The build and lint pipeline is go-makefile,
fetched at parse time. Run make -C gateway help for the shared targets.
make -C gateway build-check # vet, lint, govulncheck, and the Go version gate
make -C gateway check-yang # the YANG model and instance gates
make -C gateway test # the suite
make -C gateway build # build on a Linux host
make -C gateway docker-make TARGETS=... # any make targets in the builder container
make -C gateway docker-make-amd64 TARGETS=... # the same in the amd64 container, emulated on arm64
make -C gateway build-wanconfig-all # the linux binary for amd64 and for arm64
make -C gateway test-docker-all # the suite in the amd64 and the arm64 container
Darwin cannot build the sysrepo binding. Run make -C gateway docker-make on
macOS to run the quality gate, test suite, and YANG gates in the builder
container. Run build-docker, build-check-docker, lint-docker,
vet-docker, or test-docker separately with make -C gateway to select one
Docker target. check-yang also uses the builder container on macOS.
The container is a Debian image with the pinned libyang and sysrepo and yanglint
installed, and it builds the cgo dependencies for its own architecture. The
Docker targets need Docker. They use the host architecture unless
WANCONFIG_DOCKER_ARCH sets amd64 or arm64, and the other architecture
runs under emulation.
The builder and firewall tests use Docker Compose. Each invocation creates its own project and temporary cache volumes. The runner removes its test containers, network, volumes, and temporary directory after success, failure, or interruption. Host source files and test results remain available. Docker retains its images and build layers.
The container lints its own architecture, which is linux/arm64 on Apple Silicon.
CI lints linux/amd64. CI also compiles the binary and the stack packages on a native arm64 runner and runs the suite there. A change that breaks arm64 fails those checks.
On a Linux host, the YANG gates need yanglint from the libyang2-tools
package.
Pushing to main builds, signs, attests, and publishes the release the deploy
installs. Nothing else produces a shipped binary.