gnmic-sub

View documentation for the original command

$ tldr gnmic subscribe

gnmic sub [flags] [paths...]

--encoding
    Specifies the encoding format for the data values received, e.g.,
JSON_IETF, PROTO, ASCII.

-f, --file
    Reads gNMI paths to subscribe to from a specified file.

--format
    Defines the output format of the received notifications, e.g.,
Event, JSON, ProtobufText.

-i, --interval
    Sets the sample interval for
SAMPLE stream subscriptions.

-m, --mode
    The overall subscription mode:
ONCE (single snapshot),
STREAM (continuous updates), or
POLL (client-driven pull).

--sub-mode
    For
STREAM subscriptions, specifies the streaming mode:
SAMPLE (periodic updates),
ON_CHANGE (event-driven updates), or
TARGET_DEFINED.

-o, --output-file
    Directs the output of received telemetry to a specified file instead of stdout.

-p, --prefix
    Applies a common gNMI path prefix to all specified paths.

--target
    Specifies the target name for the gNMI connection.

--target-address
    The gRPC endpoint address of the gNMI target
(e.g., localhost:57400).

--username, --password
    Credentials for authenticating with the gNMI target.

--tls-ca, --tls-cert, --tls-key
    Paths to CA, client certificate, and client key files for secure TLS communication.

--tls-insecure
    Disables TLS certificate validation (use with caution).

[paths...]
    One or more gNMI paths to subscribe to
(e.g., /interfaces/interface[name=eth0]/state/counters).

The gnmic-sub command is a core component of the gnmic CLI client, designed for subscribing to and receiving telemetry data and state information from gNMI (gRPC Network Management Interface) enabled network devices. It allows users to establish continuous streaming sessions, request one-time snapshots, or poll for specific data points from device sensors and configuration state.

gnmic-sub supports various subscription modes (e.g., STREAM, ONCE, POLL), different value encodings (e.g., JSON_IETF, PROTO), and flexible output formats, making it an indispensable tool for network monitoring, automation, and integration with data collection pipelines. It provides a powerful way to observe real-time network behavior and changes.

gnmic-sub relies on a gNMI-capable server on the network device. The behavior and available data depend entirely on the device's gNMI agent implementation. Users must ensure network connectivity and proper firewall rules. Understanding gNMI path syntax and data models (YANG) is crucial for effective use. Some devices might not support all subscription modes, encodings, or specific paths, leading to errors or incomplete data.

gnmic-sub supports different subscription modes as defined by the gNMI specification:
ONCE: Requests a single snapshot of the specified paths. The subscription terminates after receiving the data.
STREAM: Establishes a continuous stream of updates. This mode further divides into:
    SAMPLE: Periodic updates at a specified interval, even if the data hasn't changed.
    ON_CHANGE: Updates only when the data changes, providing event-driven notifications.
    TARGET_DEFINED: Allows the target device to define the streaming behavior, often a combination of sample and on-change.
POLL: The client explicitly sends poll requests at chosen intervals to receive current updates.

gNMI supports various data encodings for the values in telemetry updates, affecting how data is serialized and transmitted. Common encodings supported by gnmic-sub include:
JSON_IETF: JSON format adhering to RFC 7951 (IETF JSON), commonly used for YANG data.
PROTO: Google Protocol Buffer encoded data, efficient for machine-to-machine communication.
ASCII: Simple ASCII text encoding.
BYTES: Raw byte representation.
JSON: Generic JSON format (non-IETF standard).
GOPROTO: Go-specific Protocol Buffer encoding.

The command can format the received gNMI notifications for better readability or integration with other tools:
Event: A human-readable, structured event-based output, showing path, value, and metadata.
JSON: Raw JSON output of the gNMI notification message.
ProtobufText: Text-formatted Protocol Buffer output, useful for debugging.
flat: A flattened, simpler JSON output format, often preferred for easy parsing.
Protobuf: Raw binary Protocol Buffer output.

The gnmic project was initiated to provide a robust, open-source command-line interface for interacting with network devices using the gNMI protocol. Its development aimed to simplify operations such as telemetry subscription, configuration retrieval, and modification, which are fundamental to modern network automation and observability practices. gnmic-sub emerged as a primary feature to leverage gNMI's powerful streaming capabilities for real-time network state monitoring, playing a key role in making gNMI accessible to network engineers and developers.

gnmic get(1), gnmic set(1), gnmic capabilities(1), grpc(1)