gNMI for Configuration Management

Objective

In this lesson you will enable the gNMI API on a network device, create a secure outbound gRPC tunnel to a tunnel server, and use a tunnel-server client to Subscribe to configuration changes. You will also perform an interactive configuration change (hostname) and observe the gNMI subscription update. This matters in production because gNMI-based telemetry and configuration enables centralized, programmatic management of many devices without requiring direct inbound management access — useful for devices behind NAT or in segmented management VRFs.

Topology

ASCII topology — only the new tunnel server and its IP are added for this lesson. The device uses a management VRF called vrfMgmt to source the tunnel.

R1 (network device) vrf: vrfMgmt gNMI/gRPC tunnel client | | gRPC tunnel (outbound) | Ubuntu Tunnel Server (gnmic) Interface eth0: 10.1.1.3 gRPC tunnel server listener: 10.1.1.3:4000

Important: The only explicit IP required by this lab is 10.1.1.3 on the tunnel server. The device uses the vrf named vrfMgmt as the source for the tunnel.

Device Table

Device	Role	Notes
R1	Network device (IOS-style CLI)	gNMI/gRPC tunnel client, uses vrfMgmt
Ubuntu (10.1.1.3)	Tunnel server / gnmic	Listens on TCP port 4000 for tunnel connections

Quick Recap

This lesson continues from Lesson 1 where a managed device was prepared for programmability. We now:

• Enable the gNMI/gRPC interfaces on the device control plane.
• Create a gRPC tunnel client on the device so it can establish an outbound connection to a tunnel server.
• Run the tunnel server (gnmic) on 10.1.1.3 and use it to Subscribe to the device's hostname configuration.
• Change the device hostname via CLI and observe the gNMI subscription notification.

No other devices or IP addresses are added beyond the tunnel server at 10.1.1.3.

Key Concepts

• gNMI (gRPC Network Management Interface): a gRPC-based protocol that supports GET, SET, and Subscribe operations to retrieve or change device configuration/state. Think of it like a remote configuration API for the device.
• gRPC Tunnel: the device makes an outbound, persistent gRPC connection to a tunnel server, allowing management clients to reach the device through that tunnel (useful when the device has no inbound management connectivity).
• Subscribe semantics: when you subscribe to a path (for example, system/config/hostname), the server will send updates on changes. In sample/stream modes, updates arrive periodically or on change events.
• VRF sourcing for tunnels: using a management VRF (vrfMgmt) ensures the tunnel uses the correct control-plane routing and security boundaries. In production this isolates management traffic from production data-plane traffic.
• Operational workflow: enable device-side gNMI services, configure tunnel client to a trusted tunnel server, run a tunnel-server client, then validate GET/SET/Subscribe behavior.

Step-by-step configuration

Each step follows the pattern: What we are doing, commands (full config mode entry and exit), what just happened, a real-world note, and verification with expected output.

Step 1: Enable gNMI (gnxi) secure service

What we are doing: Enable the gNMI service stack (gnxi) and initialize secure mode so the device will accept and initiate secure gNMI/gRPC tunnels. This establishes the device control-plane endpoints needed for GET/SET/Subscribe operations.

configure terminal
gnxi
gnxisecure -init service internal
gnxisecure -allow -self-signed -trustpoint TP-self-signed -2328416372
gnxisecure -password -auth
end

What just happened:

• gnxi enters the gNMI/gNOI configuration context.
• gnxisecure -init service internal initializes the secure gNMI service using the device's internal service bindings.
• gnxisecure -allow -self-signed -trustpoint TP-self-signed -2328416372 configures the device to allow self-signed certificates using the named trustpoint (this simplifies lab TLS handling).
• gnxisecure -password -auth configures the authentication method for gNMI; when prompted you should use the lab password (Lab@123) for the administrative account in this lab environment.

Real-world note: In production you should NOT allow self-signed trustpoints; use proper PKI and certificate validation to avoid MITM risk.

Verify:

show running-config | section gnxi
gnxi
 gnxisecure -init service internal
 gnxisecure -allow -self-signed -trustpoint TP-self-signed -2328416372
 gnxisecure -password -auth

Expected output above shows the gnxi secure settings in the running configuration.

Step 2: Configure gRPC tunnel client on the device

What we are doing: Configure the device to open an outbound gRPC tunnel to the tunnel server at 10.1.1.3 port 4000, sourcing the connection from vrfMgmt, and target the GNMI/GNOI services. This is required so management clients can reach the device through the server.

configure terminal
gnxi
gnxigrpctunnel dest ubuntuvm address 10.1.1.3 port 4000
gnxigrpctunnel source -vrfMgmt
gnxigrpctunnel target GNMI_GNOI
gnxigrpctunnel enable
end

What just happened:

• gnxigrpctunnel dest ubuntuvm address 10.1.1.3 port 4000 defines a named tunnel destination (ubuntuvm) with the server IP and port.
• gnxigrpctunnel source -vrfMgmt instructs the device to originate the tunnel from the management VRF named vrfMgmt, ensuring the management path uses the correct routing/ACLs.
• gnxigrpctunnel target GNMI_GNOI sets the tunnel target service to gNMI/gNOI endpoints.
• gnxigrpctunnel enable activates the tunnel configuration so the device will attempt to connect out to the server.

Real-world note: Matching ports and IPs between the device and tunnel server is essential; mismatched ports (e.g., 5000 vs 4000) are a common cause of failures.

Verify:

show running-config | include gnxigrpctunnel
gnxigrpctunnel dest ubuntuvm address 10.1.1.3 port 4000
gnxigrpctunnel source -vrfMgmt
gnxigrpctunnel target GNMI_GNOI
gnxigrpctunnel enable

Expected output above shows the tunnel client configuration present in the running configuration.

Step 3: Prepare the tunnel-server configuration file and start gnmic

What we are doing: On the tunnel server (10.1.1.3) we create a tunnel_server_config.yaml that tells the tunnel server to accept device tunnel connections on port 4000 and provides the client credentials the tunnel-server should present to management clients. Then we start the tunnel-server client (gnmic) to accept incoming device connections and allow client subscriptions.

Contents of tunnel_server_config.yaml (create on Ubuntu at 10.1.1.3):

# tunnel_server_config.yaml
insecure: false
skip-verify: true
log: true
username: admin
password: Lab@123
tunnel-server:
  address: ":4000"
target-wait-time: "10s"

Start the tunnel-server subscribe test (run on 10.1.1.3):

gnmic --config ./tunnel_server_config.yaml --use-tunnel-server subscribe --path system/config/hostname -i10s --stream-mode sample

What just happened:

• The YAML config instructs the tunnel server to listen on port 4000 for incoming device tunnels, and uses the admin credentials (Lab@123) for any gNMI client interactions.
• The gnmic command starts a subscription to system/config/hostname through the tunnel server. The --use-tunnel-server flag binds gnmic to tunnel-server behavior so it accepts device-provided tunnels.

Real-world note: Using tunnel-server tooling removes the requirement for devices to be directly reachable from the operator network. This is often used for devices in remote sites or behind NAT.

Verify (on the tunnel server console):

# Sample subscribe output from gnmic (first lines)
Subscribe to path: /system/config/hostname
Established tunnel-server listening on :4000
Waiting for device tunnel connections...
Device connected: device-id=<device-uuid> from 10.1.1.3:XXXXX
update:
  path: system/config/hostname
  value: "R1-Initial"

Expected output shows the tunnel server listening, a device connecting, and the initial hostname value returned via the subscription.

Step 4: Change the device hostname and observe gNMI Subscribe update

What we are doing: Modify the device hostname via CLI to generate a configuration change. The active gnmic subscribe session should receive an update with the new hostname because it is subscribing to system/config/hostname.

configure terminal
hostname R1-Lab
end

What just happened:

• hostname R1-Lab updates the device configuration under system config for the hostname. This is a configuration change that the device's gNMI implementation will expose via the subscribed path. The subscription (on the tunnel server) will detect the change and push an update over the existing tunnel.

Real-world note: Subscriptions that observe configuration paths are valuable to detect drift from a configuration baseline or to confirm automated changes applied by orchestration systems.

Verify (on the device):

show running-config | include hostname
hostname R1-Lab

Verify (on the tunnel server gnmic console):

# Sample subscribe update after change
update:
  path: system/config/hostname
  value: "R1-Lab"
timestamp: 2026-04-02T12:34:56.789Z

Expected output shows the subscription delivering the updated hostname value "R1-Lab" after the CLI change.

Verification Checklist

• Check 1: gNMI secure service is configured on the device. Verify with show running-config | section gnxi and confirm gnxisecure -init and trustpoint lines exist.
• Check 2: gRPC tunnel client configured to reach 10.1.1.3:4000 from vrfMgmt. Verify with show running-config | include gnxigrpctunnel and confirm destination and enable lines are present.
• Check 3: gnmic subscription receives updates when device hostname changes. Verify by running the gnmic ... subscribe --path system/config/hostname command on 10.1.1.3 and confirming update notifications appear after changing the device hostname.

Common Mistakes

Symptom	Cause	Fix
No connection to tunnel server, device never shows as connected on gnmic	Port mismatch between device tunnel config and tunnel-server (e.g., device set to 4000 but server listening on another port)	Verify both sides use port 4000; adjust gnxigrpctunnel dest ... port 4000 or server tunnel-server.address accordingly
Subscription shows initial state but not updates after config change	Subscription mode may be sample-only or tunnel connection not using the management VRF	Ensure gnxigrpctunnel source -vrfMgmt is set and the management VRF has routing to the tunnel server; re-subscribe using gnmic
TLS validation failures on tunnel connection	Self-signed certificate not allowed or server/client certificate mismatch	In lab allow self-signed with trustpoint, but in production deploy proper PKI; verify trustpoint is configured and certificates match
gnxisecure commands not accepting the password	Interactive password prompt was missed or wrong prompt used	Use the lab password Lab@123 when prompted; check gnxisecure -password -auth was entered in config mode

Key Takeaways

• gNMI provides programmatic GET/SET/Subscribe access to device configuration and state; Subscribe is powerful for seeing live changes as they happen.
• gRPC Tunnels allow a device to make an outbound connection to a tunnel server, enabling management tools to connect without requiring inbound device connectivity — ideal for remote or NATed devices.
• Always match tunnel server IPs and ports and source the correct management VRF (vrfMgmt) so the control-plane path is predictable and secure in production environments.
• For production use, avoid self-signed certificates — use PKI and proper trust validation to prevent man-in-the-middle attacks. In labs, self-signed trustpoints simplify setup, but understand the security tradeoffs.

Tip: Think of the gRPC tunnel like a VPN for the gNMI API — the device initiates the outbound tunnel and the operator connects into that tunnel to run GET/SET/Subscribe operations. This pattern scales well when devices cannot be reached directly.