# maglevd

Health checker and gRPC control plane for VPP Maglev load balancing.

## Build

```sh
make          # builds build/<arch>/maglevd and build/<arch>/maglevc
make test     # runs all tests
make proto    # regenerates gRPC stubs from proto/maglev.proto
make lint     # runs golangci-lint
```

Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go` and
`protoc-gen-go-grpc`.

## Debian package

```sh
make pkg-deb
```

Produces `vpp-maglev_<version>_amd64.deb` and `vpp-maglev_<version>_arm64.deb`
in the project root by cross-compiling with `GOOS=linux GOARCH=<arch>`.
Requires `dpkg-deb` (available on any Debian/Ubuntu host).

The package installs:

| Path | Content |
|---|---|
| `/usr/sbin/maglevd` | Health-checker daemon |
| `/usr/bin/maglevc` | Interactive CLI client |
| `/lib/systemd/system/maglevd.service` | systemd unit |
| `/etc/default/maglev` | Environment file for the unit (conffile) |
| `/etc/maglev/maglev.yaml` | Example configuration file (conffile) |
| `/usr/share/man/man8/maglevd.8.gz` | Man page |
| `/usr/share/man/man1/maglevc.1.gz` | Man page |

After installing, the unit is enabled but not started automatically:

```sh
# edit /etc/maglev/maglev.yaml, then:
systemctl start maglevd
```

## Run

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

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

Send `SIGHUP` to `maglevd` to reload config without restarting.
`maglevd` requires `CAP_NET_RAW` for ICMP health checks.

## Minimal config

```yaml
maglev:
  healthchecks:
    http:
      type: http
      port: 80
      params:
        path: /healthz
      interval: 2s
      timeout: 3s

  backends:
    web0: {address: 192.0.2.10, healthcheck: http}
    web1: {address: 192.0.2.11, healthcheck: http}

  frontends:
    web:
      address: 192.0.2.1
      protocol: tcp
      port: 80
      pools:
        - name: primary
          backends:
            web0: {}
            web1: {}
```

See [docs/user-guide.md](docs/user-guide.md) for flags, signals, and `maglevc` usage.
See [docs/config-guide.md](docs/config-guide.md) for the full configuration reference.
See [docs/healthchecks.md](docs/healthchecks.md) for health state machine details.

## Docker

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