Skip to content
agoodkindPublic

About

Multi-WAN gateway daemon

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

891 Commits

Folders and files

Repository files navigation

mwan

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.

Documentation

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.

Command help

Run mwan to list commands. Each command provides its arguments, flags, defaults, and examples through --help:

mwan ifmgr --help
mwan help deploy wait-deploy

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

Check WAN health

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 json

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

Layout

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

Installing what the binary owns

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 WantedBy moved loses the symlink under its old target.
  • The wan role 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.

Reporting

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.

Building and testing

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.

Releasing

Pushing to main builds, signs, attests, and publishes the release the deploy installs. Nothing else produces a shipped binary.

About

Multi-WAN gateway daemon

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages