gNMI and gRPC dial-out alarms

The switch runs a gNMI server. A collector that subscribes ON_CHANGE to /readylinks-rlos:notification-status receives every alarm that is also sent as a NETCONF notification. There are two ways to reach the server:

Dial-out uses the OpenConfig grpctunnel protocol. Up to two dial-out servers can be set.

#Subscription

• One subscription per request. The switch serves only the first ON_CHANGE subscription in a SubscribeRequest. Use one request for alarms, and separate requests for anything else.
• No initial sync. No sync_response is sent. The stream stays quiet until the first alarm.
• No authentication. The gNMI server does not check a username or password. Access is controlled by TLS or mTLS (see Security).

#Payload

Each alarm arrives as one SubscribeResponse.update:

The leaf names and message formats are listed in Leaves and message formats.

update {
  timestamp: 1792591391520000000
  update {
    path { elem { name: "readylinks-rlos:notification-status" } }
    val { json_val: "{\"switch-port-downspeed\":\" Ethernet0/5's speed is 1000M, it support max speed is 2500M!\"}" }
  }
}

{"ghn-port-status": "ifIndex.3 linkDown mac: 00-13-ba-0c-68-57 name: modem-example"}

#Prerequisites

1. NETCONF is enabled (netconf enable). The gRPC service depends on it.
2. The global trap switch is on (snmp-server traps). Alarms follow the same switches as SNMP traps (see Gating). You don't need any trap receivers.
3. gRPC is enabled (grpc enable).

#Configure the switch

The grpc settings can be changed only while gRPC is stopped. Run grpc disable first, make the changes, then grpc enable.

#Dial-in

configure terminal
grpc disable
grpc grpchost 10000
grpc authentication enable
grpc enable
end

#Dial-out

configure terminal
grpc disable
grpc dialouthost 192.0.2.60 10001
grpc dialoutauthentication enable
grpc dialoutmtls enable
grpc certificate-upload filetype ca-file filename tunnel-ca.pem tftp 192.0.2.5
grpc certificate-upload filetype cert-file filename switch-client.crt tftp 192.0.2.5
grpc certificate-upload filetype key-file filename switch-client.key tftp 192.0.2.5
certificate-effect
grpc dialtargetId | hostname vendor model version
grpc dialout enable
grpc enable
end

• certificate-effect. Run this in global config mode to apply uploaded certificates straight away.
• dialtargetId delimiter. One of |, : or ;.
• dialtargetId parameters. One to five of hostname, vendor (the literal ReadyLinks), model, version (firmware version), and custom (the dialtarget value). Each can be used only once.

#Check

show grpc shows the service state, TLS and mTLS settings, the gNMI and HTTP ports, and for each dial-out server its state, host, port, target, target ID, and tunnel status.

#How dial-out works

1. The switch opens a gRPC connection to the tunnel server, using TLS or mTLS as configured, and registers its target. The target type is GNMI_GNOI, and the target ID is set by dialtargetId.
2. The collector asks the tunnel server for a session to that target.
3. The switch accepts the session and connects it to its local gNMI server. The collector then runs Subscribe through the tunnel, exactly as for dial-in.
4. If the connection to the tunnel server fails, the switch retries. The wait starts at 3 s and grows to at most 30 s between attempts.

The switch accepts a tunnel session only if the requested target ID starts with its own target ID and the type is GNMI_GNOI.

#Security

• Shared certificate. The gNMI server uses the same certificate, key and CA as the switch's HTTPS web server. Replacing the HTTPS certificate replaces the gNMI one too.
• TLS version. With grpc authentication enable, the gNMI server accepts TLS 1.3 only.

#Collector example (gnmic)

gnmic can act as the tunnel server and the gNMI client in one process. This is an example configuration. See the gnmic documentation for every option.

# gnmic.yaml
tunnel-server:
  address: ":10001"
  tls:
    ca-file: /etc/gnmic/switch-ca.pem      # CA that signed the switches' client certificates
    cert-file: /etc/gnmic/tunnel-server.crt
    key-file: /etc/gnmic/tunnel-server.key
    client-auth: require-verify            # mTLS
  targets:
    - id: ".*"
      type: GNMI_GNOI
      config:
        skip-verify: true                  # or tls-ca: the CA of the switch HTTPS certificate
        encoding: json

subscriptions:
  rlos-alarms:
    paths:
      - /readylinks-rlos:notification-status
    mode: stream
    stream-mode: on-change
    encoding: json

outputs:
  stdout:
    type: file
    file-type: stdout
    format: event

gnmic --config gnmic.yaml --use-tunnel-server subscribe

For dial-in, point gnmic at the switch directly:

gnmic -a 192.0.2.20:10000 --skip-verify -e json \
  subscribe --path /readylinks-rlos:notification-status --mode stream --stream-mode on-change

To test, unplug and reconnect a cable on a port with traps enabled. Two switch-port-status updates arrive, one for ifIndex.<N> linkDown and one for ifIndex.<N> linkUp.