# vpp-maglev

Health checker, gRPC control plane, CLI, and web dashboard for the VPP
`lb` (load-balancer) plugin. Runs as a set of three binaries under one
Debian package:

- **`maglevd`** — the long-running health-checker daemon. Probes backends
  (HTTP, TCP, ICMP), tracks their aggregate state, programs the VPP
  dataplane via the `lb` plugin binary API, and exposes everything
  over a gRPC API + Prometheus `/metrics` endpoint.
- **`maglevc`** — the interactive CLI client. Tab-completing shell with
  inline help; also runs one-shot commands for scripting.
- **`maglevd-frontend`** — optional web dashboard. One binary with a
  SolidJS Single-Page-App; connects to one or more maglevds over gRPC and
  serves a live HTTP view (read-only `/view/` and optional basic-auth
  `/admin/` with mutating commands).

## Build and install

```sh
make install-deps # installs all build-time dependencies
make              # builds build/<arch>/ binaries
make test         # runs all tests
make pkg-deb      # creates a Debian package for amd64 and arm64
```

Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go`
and `protoc-gen-go-grpc`. The SolidJS bundle under
`cmd/frontend/web/` is built automatically via `make` through the
`maglevd-frontend-web` target, which needs `npm`.

Produces `vpp-maglev_<version>_amd64.deb` and
`vpp-maglev_<version>_arm64.deb` in the `build/` directory by
cross-compiling with `GOOS=linux GOARCH=<arch>`. Requires `dpkg-deb`
(available on any Debian/Ubuntu host). The installed binaries report
the exact git commit via `maglevd --version` (and similarly for
`maglevc` / `maglevd-frontend`).

## Running

After installing, `maglevd` is enabled automatically but
`maglevd-frontend` is **not** — it's opt-in, so the web dashboard
doesn't surprise anyone who just wanted the daemon:

```sh
# edit /etc/vpp-maglev/maglev.yaml, then:
systemctl enable --now vpp-maglev

# optional: web dashboard. Edit /etc/default/vpp-maglev to set
# MAGLEV_FRONTEND_ARGS and (optionally) MAGLEV_FRONTEND_USER /
# MAGLEV_FRONTEND_PASSWORD for /admin/ access, then:
systemctl enable --now vpp-maglev-frontend
```

Or run the components by hand:

```sh
maglevd --config /etc/vpp-maglev/maglev.yaml --grpc-addr :9090
maglevd --version                         # print version and exit

maglevc --server localhost:9090           # interactive shell
maglevc show frontends                    # one-shot
maglevc -color=false show backends        # one-shot, no ANSI color
maglevc set backend nginx0-ams pause

maglevd-frontend -server localhost:9090 -listen :8080
```

Send `SIGHUP` to `maglevd` to reload config without restarting.
`maglevd` requires:

- `CAP_NET_RAW` for ICMP health checks (raw sockets).
- `CAP_SYS_ADMIN` when `healthchecker.netns` is set so probes can
  `setns(CLONE_NEWNET)` into the dataplane namespace. Without it,
  every probe errors out with `enter netns "<name>": operation not
  permitted`.

The Debian systemd unit grants both via `AmbientCapabilities` /
`CapabilityBoundingSet`, so `systemctl start vpp-maglev` works out
of the box. When running by hand under a non-root user, grant them
via `setcap cap_net_raw,cap_sys_admin=eip /usr/sbin/maglevd` or
equivalent.

`maglevd-frontend` also ignores `SIGHUP` so a controlling-terminal
disconnect (e.g. closing the SSH session it was started from)
doesn't kill the daemon; `SIGTERM` / `SIGINT` remain the clean
shutdown signals.

Every flag on every binary also has an environment-variable
equivalent (e.g. `MAGLEV_CONFIG`, `MAGLEV_GRPC_ADDR`,
`MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three
programs can be driven entirely via env in containerized
deployments.

## Documentation

- A minimal configuration file in
  [debian/maglev.yaml](debian/maglev.yaml) shows every knob.
- [docs/user-guide.md](docs/user-guide.md) — flags, signals, and
  `maglevc` command reference.
- [docs/config-guide.md](docs/config-guide.md) — full YAML reference.
- [docs/healthchecks.md](docs/healthchecks.md) — health state
  machine, probe scheduling, rise/fall semantics.
- Manpages: `maglevd(8)`, `maglevc(1)`, `maglevd-frontend(8)`.

## Docker

```sh
docker build -t maglevd .
docker run --cap-add NET_RAW \
  -v /etc/vpp-maglev:/etc/vpp-maglev maglevd

# With netns-scoped health checks (maglev.yaml sets healthchecker.netns):
docker run --cap-add NET_RAW --cap-add SYS_ADMIN \
  -v /etc/vpp-maglev:/etc/vpp-maglev \
  -v /var/run/netns:/var/run/netns maglevd
```