gnmic-sub

View documentation for the original command

$ tldr gnmic subscribe

gnmic-sub [global options] [--path path...] [sub options]

-a, --address string
    Target gNMI server address (default: localhost:57400)

-u, --username string
    Username for authentication

-p, --password string
    Password for authentication

--insecure
    Use insecure gRPC connection (no TLS)

--cacert file
    CA certificate file for TLS

--tlscert file
    Client certificate file for mTLS

--tlskey file
    Client private key file for mTLS

--skip-verify
    Skip server certificate verification

-P, --path string[]
    gnmi paths to subscribe (repeatable, supports files)

-x, --xpath string[]
    XPath expressions for paths (repeatable, supports files)

--prefix string
    Common gnmi prefix for subscriptions

--encoding string
    Path/value encoding (json|proto|bytes, default: json)

-f, --format string
    Output format (json|proto|protobin|prototxt|jsonlines|event, default: json)

--stream-mode string
    Mode: STREAM|ONCE|POLL|ON_CHANGE (default: STREAM)

--poll-interval duration
    Poll interval for POLL mode (default: 10s)

--heartbeat-interval duration
    Heartbeat interval (default: 0s)

--sample-interval uint32
    Sample interval in seconds

--suppress-duplicates
    Skip duplicate notifications

--subscription-mode string
    Mode: gnmi|oc|kube|dialout (default: gnmi)

-uo, --updates-only
    Print only update messages (no sync)

-do, --data-only
    Print data only (no timestamp/header)

-to, --timestamp-only
    Print timestamps only

--timestamp-format string
    Format: unix|unixnano|rfc3339 (default: unixnano)

--split-header
    Split header from message body

--no-header
    Omit response header

--no-roots
    Do not print schema roots

--print-request
    Print encoded SubscribeRequest

--config file
    Configuration file path

--targets file
    Targets file for multi-target subs

--log string
    Log level/format (console|json|none)

The gnmic-sub command, part of the gnmic suite, enables subscription to real-time telemetry data from gNMI-compliant devices and servers. gNMI (gRPC Network Management Interface) is a standard protocol for network management and telemetry, widely used in modern networking for model-driven telemetry.

Users specify target addresses, subscription paths (using XPath or gnmi.Path syntax), encoding (JSON, Proto, Bytes), and stream modes like STREAM, ONCE, POLL, or ON_CHANGE. It supports heartbeats, sampling intervals, duplicate suppression, and multiple output formats including JSON, Proto, and JSON Lines for easy parsing in pipelines.

Common use cases include monitoring interface stats, CPU/memory on routers/switches, or custom YANG paths. It handles prefixes, origins, and multi-target subscriptions via config files or CLI flags. Security features cover TLS, client certs, and insecure mode for testing. Output can be filtered (updates/data/timestamp only) and formatted with timestamps in Unix, RFC3339, etc.

Ideal for automation, observability tools like Prometheus exporters, or ad-hoc debugging, gnmic-sub bridges gNMI streams to stdout or files, integrating seamlessly with jq, Kafka, or logging systems.

Requires gNMI server support on target; paths must match device's YANG models. High-volume streams may need tuning (e.g., sample/heartbeat). Dialout mode for servers pushing to gnmic. Config files override CLI flags selectively. No built-in persistence; use pipes/redirects for logging.

Basic stream: gnmic-sub -a 192.168.1.1:57400 -p /interfaces/interface/state
Poll mode: gnmic-sub -a target:10161 --stream-mode POLL --poll-interval 30s -p /system/temperature --format jsonlines

Uses TOML/YAML configs for complex setups: targets=[{name=sw1, address=sw1:57400}], subscriptions=[{paths=[/if/stats], mode=ON_CHANGE}]. Run gnmic-sub --config sub.toml.

Developed as part of the openconfig/gnmic project starting 2020 by Nicolas Brousse. Reached v0.1.0 in 2021 with full gNMI spec support. Actively maintained, v0.15+ added OC/Kube modes, dialout. Widely adopted in SONiC/Juniper/Cisco ecosystems for telemetry.

gnmic(8), grpcurl(1), ygot(1)