NHPREP — Hands-On CCNA, CCNP, CCIE Labs & Networking Courses

Objective

In this lesson you will learn the fundamentals of gRPC, the underlying technologies that make modern network APIs (like gNMI and gNOI) efficient and scalable: Protocol Buffers, HTTP/2, and bidirectional streaming. You will enable the device Guest Shell, prepare the platform microservice prerequisites that the reference material shows (gnxi secure authentication and NACM read-rule population), and verify those steps. This matters in production because gRPC-based APIs are the high-performance control plane used for telemetry and configuration at scale — for example, a collector subscribing to model-driven telemetry from hundreds of IOS‑XE devices uses gNMI (over gRPC) to receive compact, streaming updates with low overhead.

Real-world scenario: In a campus or data center where automation tools must both push configuration and receive high-frequency telemetry, gRPC + Protocol Buffers minimize bandwidth and CPU usage compared to text-based APIs. Enabling Guest Shell and platform gRPC security primitives is a common Day‑0 task on IOS‑XE devices before operational automation tools are connected.

Topology & Device Table

ASCII topology (management-plane view). The topology below models the device running IOS‑XE with a Guest Shell (embedded CentOS container) and a collector host that will act as an automation/telemetry receiver. IP addresses are shown on the management interfaces.

Router/Device <--> Collector (GM = management interface)

[IOS-XE-Device] GigabitEthernet0/0 (Mgmt) 192.168.100.10/24  <----Ethernet----> 192.168.100.20/24 Collector-Linux
    | Guest Shell (embedded CentOS container)

Device table

Device	Interface	IP Address	Subnet Mask	Role
IOS-XE-Device	GigabitEthernet0/0 (Mgmt)	192.168.100.10	255.255.255.0	Device management / gNMI/gNOI origin
Collector	eth0	192.168.100.20	255.255.255.0	Telemetry/config collector / client

Important: This lesson focuses on the protocol fundamentals and enabling the device-side prerequisites shown in the reference material (Guest Shell, gnxi secure auth flag, and NACM population). The Collector is shown conceptually; we do not configure collector services in this lesson.

Key Concepts (theory before CLI)

gRPC is RPC over HTTP/2: gRPC leverages HTTP/2 as the transport to gain multiplexing, header compression, and streaming semantics. Think of HTTP/2 as the highway, and gRPC as a high-speed train that uses that highway to run many simultaneous trips without contention. In practice, this allows multiple gNMI RPCs (GET, SET, SUBSCRIBE) to coexist on a single TCP connection efficiently.
Protocol Buffers (protobuf) — compact binary schema: Protobuf defines the message schemas and serializes messages into compact binary wire format. Compared to text‑based encodings (like JSON), protobuf reduces bandwidth and parsing CPU — important when streaming many telemetry samples from many devices.
Bidirectional streaming: gRPC supports streaming in four flavors: unary, client streaming, server streaming, and bidirectional streaming. gNMI uses streaming for telemetry (SUBSCRIBE) where the server pushes updates and the client can send control messages. This behaves like an open, continuous channel — think of it as a persistent duplex phone call rather than repeated individual calls.
Security and service control on the device: Production devices run microservices for gNMI/gNOI access. The reference shows two important device-side primitives: the gnxi secure authentication flag (to enable secure password auth for gNMI/gNOI microservices) and NACM (NETCONF Access Control Model) read-rule population commands. In production, enabling proper service authentication and RBAC is essential before exposing gRPC services to automation systems.
Operational flow example: When a collector dials into a device (Dial‑In), it opens a gRPC connection, performs TLS/mTLS (if configured), and calls the gNMI Subscribe RPC to start receiving telemetry. When Dial‑Out (gRPC Tunnel) is used, devices initiate the connection to a collector and push telemetry. Understanding streams and flow control helps tune collector scaling and device CPU/memory planning.

Step-by-step configuration

We will perform a small set of tasks (all derived from the reference material) to prepare the IOS‑XE device: enable Guest Shell, run its bash, enable the gnxi secure authentication flag, and populate NACM read-only rules. Each step contains the exact commands shown in the reference, explanation, and verification.

Step 1: Enable Guest Shell

What we are doing: We enable the embedded Guest Shell on the IOS‑XE device. Guest Shell provides an isolated CentOS container where automation agents and tooling (Python, gNMI client tools, etc.) can run. Enabling Guest Shell is often required for Day‑0 scripts (like ZTP) and local automation testing.

iosxe# guestshell enable

What just happened: The command starts the Guest Shell service (an isolated Linux container). This creates a containerized environment with Python and other utilities separated from the device control plane, allowing safe execution of automation or bootstrap scripts without impacting IOS‑XE processes.

Real-world note: In production, administrators enable Guest Shell temporarily for ZTP or automation tasks and then disable or restrict it to reduce attack surface.

Verify:

iosxe# guestshell run bash
[iosxe-container]$

Expected behavior: The guestshell run bash prompt indicates you have an interactive shell inside the Guest Shell container. If the container failed to start the guestshell enable command would return an error instead of letting you run bash.

Step 2: Launch Guest Shell bash

What we are doing: We transition into the Guest Shell interactive bash to confirm the environment and to demonstrate running commands inside the container. This validates the Guest Shell is usable for running local gNMI/gNOI client tools when needed.

iosxe# guestshell run bash

What just happened: This invocation opens an interactive bash session within the Guest Shell container. From here, operators can run Python scripts, lightweight gRPC client binaries, or inspection utilities that are isolated from IOS‑XE control processes.

Real-world note: Use Guest Shell for local development or for executing ZTP python scripts fetched via DHCP Option 67, as referenced in the material.

Verify:

[iosxe-container]$ whoami
root
[iosxe-container]$ pwd
/home/guestshell

Expected output: You should see root as the user and a Guest Shell home directory. This proves the container is running and interactive.

Step 3: Enable gnxi secure password authentication

What we are doing: We enable the gnxi secure password authentication mode on the device so the gNMI/gNOI microservices enforce the secure password authentication behavior. The reference indicates this flag is required to use NACM read-only rules for gNMI.

gnxi secure -password -auth

What just happened: Executing this flag (as shown in the reference) configures the gnxi service to require secure password-based authentication. In practice, this toggles the microservice behavior to accept only properly authenticated RPCs, aligning device-side service behavior with RBAC controls.

Real-world note: Always enable strong authentication for gRPC services in production; otherwise automation systems may connect with insufficient protection.

Verify:

iosxe# show running-config | include gnxi
gnxi secure -password -auth


<div class="topology-diagram">
<img src="data:image/svg+xml;base64,PD9wbGFudHVtbCAxLjIwMjYuMT8+PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiBjb250ZW50U3R5bGVUeXBlPSJ0ZXh0L2NzcyIgZGF0YS1kaWFncmFtLXR5cGU9Ik5XRElBRyIgaGVpZ2h0PSIxNjZweCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ibm9uZSIgc3R5bGU9IndpZHRoOjM3NXB4O2hlaWdodDoxNjZweDtiYWNrZ3JvdW5kOiNGRkZGRkY7IiB2ZXJzaW9uPSIxLjEiIHZpZXdCb3g9IjAgMCAzNzUgMTY2IiB3aWR0aD0iMzc1cHgiIHpvb21BbmRQYW49Im1hZ25pZnkiPjxkZWZzLz48Zz48dGV4dCBmaWxsPSIjMDAwMDAwIiBmb250LWZhbWlseT0ic2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMiIgbGVuZ3RoQWRqdXN0PSJzcGFjaW5nIiB0ZXh0TGVuZ3RoPSI3OS4wNDg4IiB4PSI1IiB5PSIxNi4xMzg3Ij5NYW5hZ2VtZW50PC90ZXh0Pjx0ZXh0IGZpbGw9IiMwMDAwMDAiIGZvbnQtZmFtaWx5PSJzYW5zLXNlcmlmIiBmb250LXNpemU9IjEyIiBsZW5ndGhBZGp1c3Q9InNwYWNpbmciIHRleHRMZW5ndGg9Ijc2LjU2NDUiIHg9IjcuNDg0NCIgeT0iMzAuMTA3NCI+MTkyLjAuMi4wLzI0PC90ZXh0PjxyZWN0IGZpbGw9IiNFMkUyRjAiIGhlaWdodD0iNSIgc3R5bGU9InN0cm9rZTojMTgxODE4O3N0cm9rZS13aWR0aDoxOyIgd2lkdGg9IjI3OC43MTI5IiB4PSI4OS4wNDg4IiB5PSIxNi40Njg4Ii8+PHBhdGggZD0iTTE1MS43ODk2LDIxLjQ2ODggTDE1MS43ODk2LDcwLjY3NTgiIGZpbGw9Im5vbmUiIHN0eWxlPSJzdHJva2U6IzE4MTgxODtzdHJva2Utd2lkdGg6MTsiLz48dGV4dCBmaWxsPSIjMDAwMDAwIiBmb250LWZhbWlseT0ic2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMSIgbGVuZ3RoQWRqdXN0PSJzcGFjaW5nIiB0ZXh0TGVuZ3RoPSIxMDEuNDgxNCIgeD0iMTAxLjA0ODgiIHk9IjM0LjU3NTciPnIxLmxhYi5uaHByZXAuY29tPC90ZXh0Pjx0ZXh0IGZpbGw9IiMwMDAwMDAiIGZvbnQtZmFtaWx5PSJzYW5zLXNlcmlmIiBmb250LXNpemU9IjExIiBsZW5ndGhBZGp1c3Q9InNwYWNpbmciIHRleHRMZW5ndGg9IjUyLjQ4MSIgeD0iMTAxLjA0ODgiIHk9IjQ3LjM4MDQiPjE5Mi4wLjIuMTwvdGV4dD48dGV4dCBmaWxsPSIjMDAwMDAwIiBmb250LWZhbWlseT0ic2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMSIgbGVuZ3RoQWRqdXN0PSJzcGFjaW5nIiB0ZXh0TGVuZ3RoPSIyOS4yODMyIiB4PSIxMDEuMDQ4OCIgeT0iNjAuMTg1MSI+R2kwLzA8L3RleHQ+PHBhdGggZD0iTTI5MS4xNDYsMjEuNDY4OCBMMjkxLjE0Niw3MC42NzU4IiBmaWxsPSJub25lIiBzdHlsZT0ic3Ryb2tlOiMxODE4MTg7c3Ryb2tlLXdpZHRoOjE7Ii8+PHRleHQgZmlsbD0iIzAwMDAwMCIgZm9udC1mYW1pbHk9InNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTEiIGxlbmd0aEFkanVzdD0ic3BhY2luZyIgdGV4dExlbmd0aD0iMTM3LjIzMTQiIHg9IjIyMi41MzAzIiB5PSIzNC41NzU3Ij5jb2xsZWN0b3IubGFiLm5ocHJlcC5jb208L3RleHQ+PHRleHQgZmlsbD0iIzAwMDAwMCIgZm9udC1mYW1pbHk9InNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTEiIGxlbmd0aEFkanVzdD0ic3BhY2luZyIgdGV4dExlbmd0aD0iNTkuNDc5NSIgeD0iMjIyLjUzMDMiIHk9IjQ3LjM4MDQiPjE5Mi4wLjIuMTA8L3RleHQ+PHRleHQgZmlsbD0iIzAwMDAwMCIgZm9udC1mYW1pbHk9InNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTEiIGxlbmd0aEFkanVzdD0ic3BhY2luZyIgdGV4dExlbmd0aD0iMjUuMDUwOCIgeD0iMjIyLjUzMDMiIHk9IjYwLjE4NTEiPmV0aDA8L3RleHQ+PHJlY3QgZmlsbD0iI0YxRjFGMSIgaGVpZ2h0PSIzMy45Njg4IiBzdHlsZT0ic3Ryb2tlOiMxODE4MTg7c3Ryb2tlLXdpZHRoOjAuNTsiIHdpZHRoPSIzNS45NzI3IiB4PSIxMzEuODAzMiIgeT0iNzAuNjc1OCIvPjx0ZXh0IGZpbGw9IiMwMDAwMDAiIGZvbnQtZmFtaWx5PSJzYW5zLXNlcmlmIiBmb250LXNpemU9IjEyIiBsZW5ndGhBZGp1c3Q9InNwYWNpbmciIHRleHRMZW5ndGg9IjE1Ljk3MjciIHg9IjE0MS44MDMyIiB5PSI5MS44MTQ1Ij5SMTwvdGV4dD48cmVjdCBmaWxsPSIjRjFGMUYxIiBoZWlnaHQ9IjMzLjk2ODgiIHN0eWxlPSJzdHJva2U6IzE4MTgxODtzdHJva2Utd2lkdGg6MC41OyIgd2lkdGg9IjEwNi42NzE5IiB4PSIyMzUuODEwMSIgeT0iNzAuNjc1OCIvPjx0ZXh0IGZpbGw9IiMwMDAwMDAiIGZvbnQtZmFtaWx5PSJzYW5zLXNlcmlmIiBmb250LXNpemU9IjEyIiBsZW5ndGhBZGp1c3Q9InNwYWNpbmciIHRleHRMZW5ndGg9Ijg2LjY3MTkiIHg9IjI0NS44MTAxIiB5PSI5MS44MTQ1Ij5Db2xsZWN0b3JfSG9zdDwvdGV4dD48P3BsYW50dW1sLXNyYyBvb2pGb0tuQ0x3WmNLYjM4SW9xZnBvX0FMbDFEcDRqQ0p5ckRwSWkxMm9pZTlBUWE1QUtNNW9sT0FZV1BNWGhmNlVXMWlSd0hZSDlPQ2lYRzhIZjlHUDZYTmF2WWFidlVIYTVIUWU1VVNkdmtKMXZDWnM1Q2Rka2NXUncxS2dtck1BVHBWYXZFUWQ5OVZiNnlIdHZuMk9lZm9KMGZ0OE9QbjAzVGNtNHJoOVFoNVcwMD8+PC9nPjwvc3ZnPg==" alt="Network Topology Diagram" style="max-width:100%;height:auto;background:#fff;padding:16px;border:1px solid #e5e7eb;border-radius:8px;" />
</div>

cisco
request platform software yang-management nacm populate -read-rule

What just happened: This management-plane request creates NACM rules that restrict Create/Update/Delete/Exec operations while permitting Read. Essentially, this enforces a read-only policy for users or services matched by the rule, minimizing the risk of accidental or malicious configuration changes through programmatic APIs.

Real-world note: In production, apply least-privilege NACM rules before exposing gNMI to untrusted collectors.

Verify:

iosxe# show platform software yang-management nacm
NACM rules configured:
  Rule 1: read-only rule applied to gNMI services
  Permissions: read
  Affected services: gNMI

Expected output: A summary of NACM rules showing a read-only rule applied. (Exact output formatting may vary by IOS‑XE release; the key verification is to see the read-only rule listed.)

Step 5: Confirm gNMI/gNOI services are present (service discovery via show CLI)

What we are doing: We use the device CLI show facilities (as referenced) to list gNMI/gNOI microservice status/ports. This helps confirm the services are available and that the authentication and NACM configurations will apply to them.

iosxe# show platform software yang-management services
gNMI service: enabled
gNOI service: enabled
gnxi auth mode: secure -password -auth

What just happened: The show command enumerates the yang-management microservices. Seeing gNMI/gNOI listed with the secure auth mode reaffirms that the device-side RPC endpoints are ready and secured.

Real-world note: Before integrating with collectors, verify service availability and authentication to avoid surprises when a large number of clients connect.

Verify:

iosxe# show platform software yang-management services
gNMI service: enabled
gNOI service: enabled
gnxi auth mode: secure -password -auth

Expected output: As above — the services should be enabled and authentication set to secure mode.

Verification Checklist

Check 1: Guest Shell is enabled and interactive. Verify with guestshell run bash and expect an interactive root shell prompt inside the container.
Check 2: gnxi secure password authentication is enabled. Verify with show running-config | include gnxi and expect to see gnxi secure -password -auth.
Check 3: NACM read-rule is populated for read-only access. Verify with show platform software yang-management nacm and expect to see a read-only rule entry for gNMI.
Check 4: gNMI/gNOI microservices are enabled. Verify with show platform software yang-management services and expect gNMI/gNOI to be listed as enabled.

Common Mistakes

Symptom	Cause	Fix
guestshell run bash fails	Guest Shell was not enabled or failed to start	Re-run `guestshell enable` and check container logs; ensure device has resources and Guest Shell is permitted by policy
gNMI/gNOI services not listed	Microservices not enabled or platform service not running	Confirm platform yang-management services are installed and enabled; enable gnxi secure mode as required
NACM read-rule not taking effect	NACM population command not run or wrong context	Run `request platform software yang-management nacm populate -read-rule` as shown and re-check NACM rules
Automation client unable to authenticate	gnxi secure auth not set, or wrong credentials used	Ensure `gnxi secure -password -auth` is configured and that client uses matching authentication method; use least-privilege NACM rules

Key Takeaways

gRPC is built on HTTP/2 and uses Protocol Buffers for compact, efficient messages — this combination allows high‑throughput, low‑latency RPCs used by gNMI/gNOI.
Bidirectional streaming is central to telemetry use cases: subscriptions create a persistent, efficient channel for updates from devices to collectors.
Before connecting automation tools, enable device-side service primitives: Guest Shell (for local tooling), secure gnxi authentication, and NACM read-rule population to enforce least privilege.
In production, always verify service status and authentication settings using the device show facilities shown above to avoid exposing uncontrolled write access.

Tip: Think of gNMI over gRPC like a persistent, low-overhead subscription feed: configuration operations are occasional writes, telemetry is constant streaming — secure the writes and scale the reads.

End of Lesson 1 — gRPC Protocol Fundamentals.