gnmi

Pre-Alpha. This page describes behavior that may change.

Ze includes a gNMI (gRPC Network Management Interface) server that exposes the YANG-modeled configuration over the industry-standard gNMI protocol. This lets tools that speak gNMI manage Ze, including gnmic, Ansible, and network controllers.

The server is gated by an environment variable (ze.gnmi.enabled), disabled by default, and listens on port 9339 by default.

Enabling gNMI

Enable 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 (under environment):

environment {
    gnmi {
        enabled true;
        token your-secret-token;
        server default {
            ip 0.0.0.0;
            port 9339;
        }
    }
}

Supported RPCs

RPC	Description
Capabilities	Returns supported YANG models, encodings (JSON_IETF), and gNMI version.
Get	Reads config state from the running tree by path.
Set	Applies config modifications atomically (update, replace, delete). Uses segment-based paths that preserve IP list keys.
Subscribe ONCE	Snapshot of current config for the requested paths.
Subscribe STREAM	Continuous change notifications from gNMI Set and external commits.

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

TLS is optional. To enable it on the gNMI gRPC transport, set both cert and key.

Environment variables:

ze.gnmi.tls.cert=/path/to/cert.pem
ze.gnmi.tls.key=/path/to/key.pem

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.

External config commits

Config commits that originate outside gNMI (the web UI, the CLI, and the managed component) notify Subscribe STREAM subscribers. These external commits send a generic config-changed notification rather than per-path diffs.

CLI status

Check gNMI server status from the SSH CLI:

show gnmi

This returns JSON with: enabled, listen address, token configured, TLS configured, and the active subscriber count.

Prometheus metrics

Metric	Type	Labels	Description
ze_gnmi_requests_total	counter	rpc	Total gNMI RPC requests.
ze_gnmi_subscribe_active	gauge	none	Active Subscribe STREAM connections.
ze_gnmi_errors_total	counter	rpc, code	gNMI RPC errors by gRPC status code.

Usage with gnmic

Get the full config tree:

gnmic -a 192.0.2.1:9339 --token your-secret-token get --path /

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

See also

• gRPC API
• REST API
• YANG Model
• Configuration

Adapted from main/docs/guide/gnmi.md.