gNMI Guide
Ze includes a gNMI (gRPC Network Management Interface) server that exposes YANG-modeled configuration over the industry-standard gNMI protocol. This allows management by tools like gnmic, Ansible, and network controllers that speak gNMI.
Default feature-tag lists include ze_gnmi. A custom minimal build that needs
gNMI must include -tags "ze_core ze_gnmi".
Enabling gNMI
gNMI is disabled by default. Enable it via environment variables or YANG config.
Environment variables:
ze.gnmi.enabled=true
ze.gnmi.listen=0.0.0.0:9339
ze.gnmi.token=your-secret-token
YANG config (in ze.conf):
environment {
gnmi {
enabled true;
token your-secret-token;
server default {
ip 0.0.0.0;
port 9339;
}
}
}
Authentication
When ze.gnmi.token is set, every gNMI request must include a Bearer token in the authorization gRPC metadata header. The token is compared using constant-time comparison (SHA-256 hash with subtle.ConstantTimeCompare) to prevent timing attacks.
When no token is configured, the server accepts unauthenticated requests. This is only appropriate for loopback or trusted-network deployments.
TLS
To enable TLS on the gNMI gRPC transport:
ze.gnmi.tls.cert=/path/to/cert.pem
ze.gnmi.tls.key=/path/to/key.pem
Or in YANG config:
environment {
gnmi {
tls {
cert /path/to/cert.pem;
key /path/to/key.pem;
}
}
}
TLS certificates are loaded once at startup. Certificate rotation requires restarting the gNMI server.
Naming either file asks for TLS, and gNMI then serves TLS or nothing. It never
falls back to clear text. When only one of the two files is set, when a file
cannot be read, or when the certificate and key are not a valid pair, gNMI
does not start: nothing listens on its port, and Ze logs an error naming the
file, why, and the fix. The rest of the daemon keeps running. Restore the file
or correct environment gnmi tls cert / key (or ze.gnmi.tls.cert /
ze.gnmi.tls.key), then run ze signal restart: a reload does not restart
gNMI.
The error carries the code doctor-gnmi-tls-material, and ze doctor reports
the same cause before the daemon starts: its gnmi-tls-material check loads
the pair gNMI would serve, environment overrides included, and names the file,
why, and the fix. It also reports a certificate that is expired or not yet
valid as an error, and one within 30 days of expiry as a warning. It reports nothing when gNMI does not
start or names no TLS file. ze show diagnostic doctor-gnmi-tls-material
explains the code.
Supported RPCs
| RPC | Description |
|---|---|
| Capabilities | Returns supported YANG models, encodings (JSON and JSON_IETF), and gNMI version |
| Get | Reads config state from the running tree by path |
| Set | Applies config modifications atomically (update, replace, delete) |
| Subscribe ONCE | Snapshot of current config for requested paths |
| Subscribe STREAM | Continuous change notifications (from gNMI Set and external commits) |
Sensitive values
A leaf the YANG model marks ze:sensitive (a BGP MD5 password, a TACACS+ or
RADIUS shared key, the gNMI token) never reaches a client in clear. Get,
Subscribe ONCE and the STREAM notification that echoes a Set all carry it in
its reversible $9$ form, the form ze config fmt and the CLI write to the
config file. A value the config file already holds in $9$ form is answered
with that same text. The echo goes to every subscriber, so the key one client sent
is never shown to another.
Set accepts a sensitive value either in clear or in the $9$ form a Get
returned. A $9$ value is decoded to the key the daemon uses, and the config
keeps the $9$ text exactly as written, so a value read with Get and sent
back with Set leaves the config file unchanged.
When Set is refused
An update the session refuses (a path the schema does not hold, a list key
outside its type) ends the Set with status InvalidArgument, and nothing it
carried is applied. A refused key's message is the refusal Ze prints on every
surface, unchanged, so its last line is the fix. A session refusal that carries
no fix of its own is answered with the path, the cause, and a fix that says to
send the Set again with a path and a value the schema accepts.
A value the schema refuses (outside an enumeration, a range, a length or a
format) is refused when the Set commits: the status is Aborted, the message
starts commit: config validation failed:, and each refusal follows as its own
block, ending with the set command from the root that fixes it. The shape of
each block is
Value refusals.
When a call meets an internal defect
Every call and every Subscribe stream runs behind a panic boundary, outside the
token check. If a Ze defect is reached while one is served, only that call or
stream ends, with status Internal and a message that says so and names the
ze show crashes command that finds its crash record. A Set that ends this way
discards its uncommitted edits, so nothing it changed is applied. The listener
and every other call and stream keep running. The panic is logged, crash
recorded, and counted in ze_task_panics_total{component="gnmi",task="rpc"}
and ze_gnmi_errors_total{code="Internal"}
(monitoring).
CLI Status
Check gNMI server status from the SSH CLI when ze_gnmi is compiled in:
show gnmi
Returns JSON with: enabled, listen address, token configured, TLS configured, and active subscriber count.
Prometheus Metrics
| Metric | Type | Labels | Description |
|---|---|---|---|
ze_gnmi_requests_total |
counter | rpc | Total gNMI RPC requests |
ze_gnmi_subscribe_active |
gauge | -- | Active Subscribe STREAM connections |
ze_gnmi_errors_total |
counter | rpc, code | gNMI RPC errors by gRPC status code |
Usage with gnmic
Example using gnmic to get the full config tree:
gnmic -a 192.0.2.1:9339 --token your-secret-token get --path /
Example to subscribe to config changes:
gnmic -a 192.0.2.1:9339 --token your-secret-token subscribe --path / --mode stream
Limitations
- Subscribe POLL mode is not implemented
- Telemetry SAMPLE mode (periodic counter streaming) is not supported
- gNMI path target field (multi-target) is not supported
- TLS certificates are loaded at startup only; no hot rotation
- External config commits (web/CLI) send a generic config-changed notification, not per-path diffs