gNMI Dial-out

Synopsis

The gNMI dial-out device (type: gnmi_dialout) takes the gNMI telemetry that Nokia SR OS routers (7250 IXR, 7450 ESS, 7750 SR, 7950 XRS and VSR) stream when they dial out: the router connects to Director and publishes a gNMI notification every time a subscription's sample interval comes, or when a value changes for a subscription on change. Every notification is written as a record for every list entry its values are of. Port statistics, CPU, memory, BGP, services and the rest of SR OS's state tree arrive this way. It is Telegraf's gnmi_listener input.

The router pushes, and nothing is polled. Dial-out is what a network uses when a router may open connections but not accept them: Director needs no route to the router and no credentials of it. For a router Director can reach, the gNMI device subscribes to its gNMI server instead (dial-in), which SR OS also serves. For the dial-out of Cisco IOS XR, IOS XE and NX-OS, use the Cisco MDT device.

gNMI itself defines no dial-out: every vendor that has one wraps gNMI's messages in a gRPC service of its own. The device takes Nokia's (protocol: nokia), which SR OS 20.5 and later speak.

note

The gNMI dial-out device needs Director 2.3.1 or later. With no Director or cluster at that version selected, the wizard shows gNMI dial-out devices are unavailable on directors or clusters below version 2.3.1 and the device cannot be created.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: gnmi_dialout
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    protocol: <string>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      client_ca_name: <string>
      client_auth_required: <boolean>
      min_tls_version: <string>
      max_tls_version: <string>
    max_message_size: <numeric>
    emit_deletes: <boolean>
    reuse: <boolean>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
`id`	Y	-	Unique numeric identifier
`name`	Y	-	Device name
`description`	N	-	Optional description
`type`	Y	-	Must be `gnmi_dialout`
`tags`	N	-	Optional tags
`pipelines`	N	-	Optional pre-processor pipelines
`status`	N	`true`	Enable/disable the device

Listener

Field	Required	Default	Description
`address`	N	`0.0.0.0`	The address to listen on
`port`	N	`57400`	The port the routers' destination group names, from `1` to `65535`. The device binds it, so no other device on the Director can take it
`protocol`	N	`nokia`	The dial-out service the routers publish to. `nokia`, Nokia SR OS's `Nokia.SROS.DialoutTelemetry`, is the only one; any other value is refused
`max_message_size`	N	`4194304`	The largest message taken, in bytes, from `65536` (64 KiB) to `67108864` (64 MiB), both as it arrives and once it is decompressed. The default is 4 MiB
`emit_deletes`	N	`false`	Write a deletion event for every path a router says was deleted. See Records

TLS

Field	Required	Default	Description
`tls.status`	N	`false`	Take the routers' dial-out over TLS. Requires `tls.cert_name` and `tls.key_name`
`tls.cert_name`	Y*	-	The certificate the listener presents. The router's TLS client profile trusts its CA
`tls.key_name`	Y*	-	The certificate's private key
`tls.passphrase`	N	-	Passphrase for an encrypted private key
`tls.client_ca_name`	N	-	The CA that signed the routers' own certificates
`tls.client_auth_required`	N**	`false`	Require every router to present a certificate of its own, signed by `tls.client_ca_name`
`tls.min_tls_version`	N	-	Minimum accepted TLS version (`tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`)
`tls.max_tls_version`	N	-	Maximum accepted TLS version

* = Required when tls.status is true.
** = Requires tls.client_ca_name.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
Inline PEM content — used verbatim when the value contains -----BEGIN.
Environment variable — ${ENV_VAR}.
Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

Advanced Configuration

Field	Required	Default	Description
`reuse`	N	`true`	Share the port with a listener that is still closing when the device starts again, so a restart is not refused

A configuration that cannot run stops the device with Configuration error and names the property: a protocol other than nokia, a message size out of its bounds, an emit_deletes that is not a switch, TLS without a certificate and key it can read, or tls.client_auth_required without tls.client_ca_name.

How a Router Dials Out

A router is configured with three things:

a destination group: this Director's address and port, and TLS or not;
a sensor group: the paths;
a persistent subscription that ties them together with a mode, a sample interval and an encoding.

Persistent subscriptions are SR OS's dial-out: they outlive the gRPC session, and the router dials out again whenever its session ends. A minimal one, in MD-CLI, without TLS:

/configure system telemetry destination-group "vm" allow-unsecure-connection
/configure system telemetry destination-group "vm" destination 192.0.2.10 port 57400 router-instance "management"
/configure system telemetry sensor-groups sensor-group "port_stats" path "/state/port[port-id=*]/statistics"
/configure system telemetry persistent-subscriptions subscription "port_stats" admin-state enable
/configure system telemetry persistent-subscriptions subscription "port_stats" sensor-group "port_stats"
/configure system telemetry persistent-subscriptions subscription "port_stats" mode sample
/configure system telemetry persistent-subscriptions subscription "port_stats" sample-interval 10000
/configure system telemetry persistent-subscriptions subscription "port_stats" destination-group "vm"
/configure system telemetry persistent-subscriptions subscription "port_stats" encoding json

The sample interval is in milliseconds. A destination group holds up to two destinations, which the router uses in turn. With TLS on the device, the destination group names a TLS client profile (tls-client-profile) instead of allow-unsecure-connection. The profile trusts the CA of the listener's certificate and, for tls.client_auth_required, presents the router's own.

note

This configuration follows Nokia's SR OS documentation.

The Encoding

The encoding the subscription names decides what Director can read. Configure json: every SR OS release sends it the same way. Which of proto and bytes sends typed values, and which Nokia's binary encoding, depends on configure system grpc gnmi proto-version:

`encoding`	What the router sends	What is written
`json`, on every release	A container's values as one JSON object, at the container's path	Merged in at that path, its members named as fields are
`proto` with `proto-version latest`; `bytes` with `proto-version v0.7.0`	gNMI's typed values: every leaf an update of its own	Every value as it is typed
`bytes` with `proto-version latest`; `proto` with `proto-version v0.7.0`	Nokia's own binary encoding of its YANG models (`proto_bytes`), which is release-specific and needs Nokia's `.proto` files to decode	Not decoded: a value of it is written in base64, with a warning once a stream naming the path and `/configure system telemetry persistent-subscriptions subscription "<name>" encoding json`

The Stream

The router calls Publish of the Nokia.SROS.DialoutTelemetry service and keeps the stream open: every message on it is a gNMI SubscribeResponse. The listener answers each one once its records are written.

With the stream, the router sends the name of the subscription it publishes and its own system-name. Both are optional: a router that sends neither has its values written under the table telemetry, and is named by its address.
A message larger than max_message_size closes its stream with RESOURCE_EXHAUSTED, and is logged; the router dials out again.
A message that cannot be read is left out and answered, and the stream goes on.
A sync_response, which says the router has published every path once, writes nothing.
A message compressed with gzip, zstd, snappy or lz4 is decompressed.
Keepalives need no setting. The listener takes a ping as often as every five seconds, with or without a stream open.

A problem with what a router publishes — a message that cannot be read, a value that cannot be written, a path nested too deep, values in Nokia's binary encoding — is logged once for as long as its stream lasts, since a router publishes the same thing at every interval.

Records

A notification says when its values were sampled and under which prefix (a path every update of it is under), and holds updates (a path below the prefix and its value) and deletes (paths). Its values are one ECS record for every list entry they are of:

{
  "@timestamp": "2026-09-21T14:13:20.123456789Z",
  "ecs": { "version": "8.11.0" },
  "event": { "module": "gnmi", "dataset": "gnmi.dialout", "kind": "metric", "category": ["host"], "type": ["info"] },
  "observer": { "vendor": "VirtualMetric", "product": "gNMI dial-out", "name": "gnmi-dialout", "hostname": "director-01" },
  "network": { "protocol": "gnmi", "transport": "tcp" },
  "client": { "ip": "192.0.2.21", "address": "192.0.2.21", "port": 40112 },
  "host": { "name": "pe-ams-01" },
  "gnmi": {
    "dialout": {
      "subscription": "port_stats",
      "table": "port_stats",
      "path": "/state/port[port-id=1/1/c1/1]/statistics",
      "labels": { "port_id": "1/1/c1/1" },
      "port_stats": {
        "state": { "port": { "statistics": { "in_octets": 5000, "out_octets": 10000, "in_errors": 0 } } }
      }
    }
  }
}

A record per list entry. The counters of two ports, published in one notification, are two records.
The table. The values are under gnmi.dialout.<table>. The table is the subscription's name the router sends, made a field's name: lower case, an underscore for every character other than a letter, a digit or an underscore (Port-Stats 1/1 is port_stats_1_1), and at most 64 characters. A name that would clash with a member beside it (subscription, table, path, origin, target, labels, deleted) takes an underscore after it (path_). A stream with no subscription name writes under telemetry.
Values are nested by their whole path, the prefix's elements and the update's, one level per element, without namespaces and with an underscore for every hyphen, as the gNMI device names its fields: in-octets under /state/port[port-id=1/1/c1/1]/statistics is gnmi.dialout.<table>.state.port.statistics.in_octets.
Labels. The keys of the list entries on a value's path are under gnmi.dialout.labels, with an underscore for every hyphen (port-id is port_id). A key whose name an entry above already took is named after its element too: /network-instances/network-instance[name=Base]/protocols/protocol[name=bgp] gives name and protocol_name.
What was published, and where. gnmi.dialout.subscription is the subscription's name as the router sent it, gnmi.dialout.path the notification's prefix with its keys, gnmi.dialout.origin the YANG model the values are in, when one is named, and gnmi.dialout.target the prefix's target, when the router names one.
Values are written as the gNMI device writes them: text, whole numbers, numbers, switches, and lists of them. Bytes, and a protobuf message of the router's own, are written in base64. JSON_IETF's 64-bit integers, which it sends as strings, stay strings. A NaN or an infinity, which JSON cannot hold, is left out.
Time. A record is dated by its notification's timestamp. A notification dated before 2000, as a router sending milliseconds where gNMI says nanoseconds would date it, is dated when it arrived.
The router is host.name, by its system-name. Where its stream came from is client.ip, client.address and client.port. The listener is the observer.
A deletion. With emit_deletes, a path the router says was deleted is a deletion event (event.kind: event, event.category: configuration, event.type: deletion, event.action: delete) with the deleted path as gnmi.dialout.deleted, its keys as gnmi.dialout.labels, and no values. Without it, deletions write nothing.
Limits. A path of more than 128 elements is left out with a warning, since a record nests a level for every element.

Records are written under definition ID 860, as network log records.

Connection States

Connected: the configuration is read and the port can be bound.
Connection error: the port cannot be bound.
Configuration error: a configuration that cannot run — see Advanced Configuration.

When the device stops, every router's stream is ended at once. What is being written of a message at that moment is cut off; the router publishes again when it dials out again. A message waits for room in the device's buffer, and the router's stream waits with it.

Every node of a cluster runs the device. A router sends to the node its destination group names, or to a load balancer in front of the nodes.

Migrating from Telegraf

Where the device departs from Telegraf's gnmi_listener input:

Telegraf	This device
`address`, `localhost:57400` by default	`address` and `port`, `0.0.0.0` and `57400`. One device per listener
Every metric is named `gnmi`	The table is the subscription's name, from the stream's metadata, which Telegraf does not read
The `source` tag, the peer's address	`client.ip`, `client.address` and `client.port`; the router's `system-name` is `host.name`
A field per value, named by its path below the prefix	Values nested by their whole path under the table, without namespaces
Tags from keys; `prefix_tag_key_with_path`	`gnmi.dialout.labels`: the key's name, with the element's name on a clash
The `path` tag, the prefix without keys, or guessed by `path_guessing_strategy`	`gnmi.dialout.path`, the prefix with its keys; nothing is guessed
`emit_delete_metrics`, a metric with `operation=delete` per deleted path	`emit_deletes`, a deletion event per deleted path
`yang_model_paths`, `vendor_specific`	No counterpart: JSON_IETF's 64-bit numbers stay strings, and SR OS sends no vendor header
A message that cannot be decoded ends the stream	It is left out and answered; the stream goes on
gRPC's own limits: 4 MiB a message, a ping every five minutes at most	`max_message_size`, 64 KiB to 64 MiB; keepalive is taken every five seconds, with no setting
`tls_cert`, `tls_key`, `tls_allowed_cacerts`	`tls`: a client certificate is required, or only checked when one is presented, with `tls.client_auth_required`

Console

In the console, go to Fleet Management > Devices and choose gNMI dial-out, under Protocols beside gNMI and Cisco MDT. The wizard's steps after General settings are:

Protocol settings: Listen address (Optional), Port, and the TLS settings: the TLS encryption switch, and enabled, the certificate and its private key, the passphrase, client certificate verification with the routers' CA, and the minimum and maximum TLS version. The step's description names what a router needs: a destination group with this Director's address and port, naming a TLS client profile when TLS is on, and a persistent subscription that sends there in the json or bytes encoding. The protocol is not a field: Nokia SR OS, the only one, is used.
Advanced settings:
- Under Messages, Maximum message size (Optional) and Deletion events.
- Socket address reuse: lets the listener bind its port while the one it replaces is still closing, so a restart is not refused.
- The Simulation section.

Simulation

The device can be simulated as the other listeners are — see Device Simulation. The gnmi_dialout_telemetry sample generates records of SR OS port statistics, CPU usage and memory, in the shape Records shows.

Examples

TLS with Router Certificates

Taking the telemetry of SR OS core routers over TLS, with a certificate required of every router, and deletion events on...

devices:
  - id: 512400520
    name: gnmi-dialout
    description: Port, CPU and memory telemetry of the SR OS core routers
    type: gnmi_dialout
    status: true
    properties:
      address: "0.0.0.0"
      port: 57400
      protocol: nokia
      tls:
        status: true
        cert_name: "gnmi.example.com.crt"
        key_name: "gnmi.example.com.key"
        client_ca_name: "routers-ca.crt"
        client_auth_required: true
      max_message_size: 4194304
      emit_deletes: true

Without TLS

Taking the telemetry of lab routers whose destination group dials out with allow-unsecure-connection...

devices:
  - id: 512400521
    name: gnmi-dialout-lab
    description: Telemetry of the lab routers, without TLS
    type: gnmi_dialout
    status: true
    properties:
      address: "0.0.0.0"
      port: 57401

Synopsis​

Schema​

Configuration​

Device​

Listener​

TLS​

Advanced Configuration​

How a Router Dials Out​

The Encoding​

The Stream​

Records​

Connection States​

Migrating from Telegraf​

Console​

Simulation​

Examples​

TLS with Router Certificates​

Without TLS​

Synopsis

Schema

Configuration

Device

Listener

TLS

Advanced Configuration

How a Router Dials Out

The Encoding

The Stream

Records

Connection States

Migrating from Telegraf

Console

Simulation

Examples

TLS with Router Certificates

Without TLS