# User Guide

## maglevd

`maglevd` is the health-checker daemon. It probes backends according to the
configuration file, maintains their health state, and exposes a gRPC API for
inspection and control.

### Flags

| Flag | Environment variable | Default | Description |
|---|---|---|---|
| `--config` | `MAGLEV_CONFIG` | `/etc/maglev/maglev.yaml` | Path to the YAML configuration file. |
| `--grpc-addr` | `MAGLEV_GRPC_ADDR` | `:9090` | TCP address on which the gRPC server listens. |
| `--log-level` | `MAGLEV_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, or `error`. |
| `--version` | — | — | Print version, commit hash, and build date, then exit. |

Flags take precedence over environment variables. Both are optional; defaults
are used for anything not set.

### Signals

| Signal | Effect |
|---|---|
| `SIGHUP` | Reload the configuration file. New backends are started, removed backends are stopped, backends whose health-check config is unchanged continue probing without interruption. |
| `SIGTERM` / `SIGINT` | Graceful shutdown. Active gRPC streams are closed, the server drains, then the process exits. |

### Capabilities

`maglevd` requires `CAP_NET_RAW` when any health check uses `type: icmp`.
All other check types (`tcp`, `http`) use normal TCP sockets and require no
special capabilities.

### Logging

All log output is written to stdout as JSON using Go's `log/slog`. The first
line logged after the logger is configured is a `starting` record that includes
`version`, `commit`, and `date`. Every state change emits a `backend-transition`
line at `INFO` level. Set `--log-level debug` to see individual probe attempts
and their outcomes.

---

## maglevc

`maglevc` is the interactive control-plane client. It connects to a running
`maglevd` over gRPC and either executes a single command or drops into an
interactive shell.

### Usage

```sh
maglevc [--server host:port] [--color[=bool]] [command...]
```

| Flag | Default | Description |
|---|---|---|
| `--server` | `localhost:9090` | Address of the `maglevd` gRPC server. |
| `--color` | `true` | Colorize static field labels in output (dark blue ANSI). Pass `--color=false` to disable, e.g. when piping. |

When `command` arguments are supplied the command is executed and `maglevc`
exits. When no arguments are given an interactive shell is started and the
build version is printed on entry.

### Commands

```
show version                     Print build version, commit hash, and build date.

show frontends                   List all frontend names.
show frontend <name>             Show address, protocol, port, description, and pools.
                                 Each pool lists its backends with weights (if != 100)
                                 and marks disabled backends with [disabled].

show backends                    List all backend names.
show backend <name>              Show address, current state (with duration in that state),
                                 enabled flag, health check, and recent state transitions
                                 with timestamps and how long ago each occurred.

show healthchecks                List all health-check names.
show healthcheck <name>          Show full health-check configuration.

set backend <name> pause         Suspend health checking for a backend, freezing its state.
set backend <name> resume        Resume health checking; backend re-enters unknown state
                                 and is probed immediately.

quit / exit                      Leave the interactive shell.
```

### Interactive shell

The shell prompt is `maglev> `. Two completion mechanisms are available:

**Tab completion** — pressing `<Tab>` at any point completes the current token.
Fixed keywords (commands and subcommands) are completed from the command tree.
Backend, frontend, and health-check names are fetched live from the server with
a 1-second timeout. If the partial token is unambiguous the word is completed
in place; if multiple candidates exist they are listed and the prompt is
restored.

**Inline help (`?`)** — typing `?` at any point prints the available
completions for the current position, with a short description next to each
keyword. The `?` character is not added to the input line.

Commands and keywords support **prefix matching**: typing `sh b` is equivalent
to `show backend` provided the prefix is unambiguous. Exact matches always take
priority over prefix matches, so `show backend` and `show backends` are
unambiguous even though one is a prefix of the other.

### Command tree and parser

Commands form a tree of `Node` values. Each node has a fixed `Word` (a keyword)
or is a *slot node* (marked by a `Dynamic` function that enumerates valid
values at completion time). The parser (`Walk`) descends the tree token by
token:

1. Try to match the current token against the fixed-keyword children of the
   current node (exact match first, then unique prefix match).
2. If no fixed child matches, try a slot child — any token is accepted and
   stored as an argument.
3. Stop when tokens are exhausted or no match is found.

The leaf node reached by `Walk` must have a `Run` function; otherwise the
available sub-commands at that position are printed as help. Arguments
collected from slot nodes are passed to `Run` as a slice.

Example walk for `set backend nginx0-ams pause`:

```
root → set → backend → <name>(nginx0-ams collected as arg) → pause
```

`pause.Run` is called with `args = ["nginx0-ams"]`.