[Tutorial] StoneWork + GNS3



05/04/2021

PANTHEON.tech has made its data plane for managing cloud-native network functions, StoneWork, available on the GNS 3 marketplace. This makes it easy for anybody to try out our all-in-one solution, which can combine multiple cloud-native network functions from our CNF portfolio, in a separate environment.

This tutorial will give you the basics on how to set-up StoneWork in an environment, where you can safely test out interaction and its positioning within your (simulated) network.

The goal of this tutorial is to have a basic setup, where we will:

Setup StoneWork interface IP address
Set the status of StoneWork to UP
Verify the connection by pinging the address

Read the complete post after subscribing:

Network management tooling has a habit of lagging behind the hardware it is supposed to control.

You upgrade your switches to 400G, your AI training cluster generates telemetry at a rate SNMP was never designed to handle, and you are still polling every 60 seconds, waiting for a response. gNMI (gRPC Network Management Interface) fixes this. PANTHEON.tech contributed a native gNMI plugin to OpenDaylight, and you can now wire it into Java applications.

This guide covers the architecture, the code, and a full walkthrough for running the controller against a local gNMI device simulator.

Why gNMI belongs in your stack

gNMI runs on gRPC, which means HTTP/2 and Protocol Buffers. Three properties make it worth the migration:

Binary framing over Protobuf eliminates NETCONF's XML verbosity, cutting payload size and CPU cost at both ends.

Streaming telemetry via the Subscribe RPC shifts the model from polling to push: the device sends state the moment something changes. Three modes exist: STREAM for continuous high-frequency data, ON_CHANGE for event-driven notifications (a link going down, a buffer overflowing), and SAMPLE for periodic snapshots.

Atomic Set operations make configuration changes transactional: either the entire config applies, or none of it does, eliminating the partial-state failures that break SNMP-based automation.

In AI training clusters, a buffer overflow during a training run costs hours of compute. A polling interval of 60 seconds means the problem sits undetected.

The OpenDaylight gNMI Plugin

PANTHEON.tech, as the largest contributor to OpenDaylight's codebase, built and upstreamed the gNMI plugin to the opendaylight/gnmi repository. The plugin provides:

gNMI Southbound: a gRPC client that manages connections to gNMI-capable devices and handles Capabilities, Get, and Set RPCs.
RESTCONF Northbound: all gNMI operations are exposed via standard RESTCONF over HTTP/JSON, so your automation tooling does not need to speak gRPC.
MD-SAL integration: the plugin translates the binary gRPC world into OpenDaylight's Model-Driven Service Abstraction Layer, making device data available as YANG-modelled datastore entries.

The canonical deployment vehicle for the plugin is the lighty-rcgnmi-app, which this guide uses throughout.

Solving the Karaf problem with lighty.io

Standard OpenDaylight ships as an Apache Karaf OSGi container. Karaf is powerful, but carries a real operational cost: startup can take several minutes, memory use is high, and dependency resolution degrades as the module count grows.

lighty.io is an SDK that runs ODLs core components (MD-SAL, YANG Tools, the global schema context) in a plain Java SE environment, without an OSGi container. Startup drops from minutes to seconds. The memory footprint shrinks enough to fit Kubernetes deployments and microservice architectures comfortably.

To use the gNMI plugin inside Karaf, the opendaylight/gnmi repository ships a runnable Karaf distribution. For microservices, containers, or fast local iteration, use lighty.io.

Architecture overview

                ┌────────────────────────────────────────────┐
                │           lighty-rcgnmi-app (JVM)          │
                │                                            │
                │  ┌───────────────┐   ┌──────────────────┐  │
HTTP/JSON  ───► │  │   RESTCONF    │──►│  lighty.io       │  │
                │  │   Northbound  │   │  Controller      │  │
                │  └───────────────┘   │  (MD-SAL, YANG)  │  │
                │                      └────────┬─────────┘  │
                │                               │            │
                │                      ┌────────▼─────────┐  │
                │                      │  gNMI Southbound │  │
                │                      │  (gRPC client)   │  │
                └──────────────────────┴────────┬─────────┴──┘  
                                                │ gRPC/TLS
                                       ┌────────▼─────────┐
                                       │  gNMI Device     │
                                       │  (router/switch/ │
                                       │   simulator)     │
                                       └──────────────────┘

RESTCONF requests arrive at the northbound, traverse MD-SAL, and the southbound plugin translates them to gNMI GetRequest or SetRequest. Device data flows back the same path in reverse.

Prerequisites

Java 21 or later
Maven 3.9.5 or later
curl (or Postman/Bruno)
Linux-based system (for the bash commands in the simulator setup)

Building the RCgNMI application

Clone the lighty repository and build the full project. The initial build downloads the ODL artifact set, so expect a few minutes on first run.

git clone https://github.com/PANTHEONtech/lighty.git
cd lighty
mvn clean install

To build only the RCgNMI application and its dependencies, use the partial build flag:

mvn clean install -pl lighty-applications/lighty-rcgnmi-app-aggregator/lighty-rcgnmi-app -am

The build produces a self-contained .zip distribution at:

lighty-applications/lighty-rcgnmi-app-aggregator/lighty-rcgnmi-app/target/lighty-rcgnmi-app-<version>-bin.zip

Running the test application with the nuilt-in simulator

The fastest way to validate the setup is to run the RCgNMI controller alongside the bundled gNMI device simulator. The simulator starts with pre-configured OpenConfig state and config data, and communicates over TLS.

Step 1 - Start the RCgNMI Controller

cd lighty-examples/lighty-gnmi-community-restconf-app

# Unzip the controller
unzip ../../lighty-applications/lighty-rcgnmi-app-aggregator/lighty-rcgnmi-app/target/lighty-rcgnmi-app-24.0.0-SNAPSHOT-bin.zip

# Start with the pre-prepared example config
java -jar lighty-rcgnmi-app-24.0.0-SNAPSHOT/lighty-rcgnmi-app-24.0.0-SNAPSHOT.jar -c example_config.json

A successful start prints a log line like:

INFO [main] (RCgNMIApp.java:98) - RCgNMI lighty.io application started in 10.10 s

The RESTCONF API listens on port 8888. Default credentials are admin / admin.

Step 2 - Start the gNMI device simulator

Open a second terminal:

cd lighty-examples/lighty-gnmi-community-restconf-app

unzip ../../lighty-modules/lighty-gnmi/lighty-gnmi-device-simulator/target/lighty-gnmi-device-simulator-24.0.0-SNAPSHOT-bin.zip

java -jar lighty-gnmi-device-simulator-24.0.0-SNAPSHOT/lighty-gnmi-device-simulator-24.0.0-SNAPSHOT.jar \
  -c simulator/simulator_config.json

The simulator listens on port 10161.

Step 3 - Add TLS certificates to the keystore

The controller stores TLS credentials in MD-SAL, keyed by a keystore-id. Load the example certificates bundled with the use-case:

curl --request POST 'http://127.0.0.1:8888/restconf/operations/gnmi-certificate-storage:add-keystore-certificate' \
  --header 'Content-Type: application/json' \
  --data-raw "{
      \"input\": {
          \"keystore-id\": \"keystore-id-1\",
          \"ca-certificate\": \"$(cat certificates/ca.crt)\",
          \"client-key\": \"$(cat certificates/client.key)\",
          \"client-cert\": \"$(cat certificates/client.crt)\"
      }
  }"

If your private key has a passphrase, add "passphrase": "your-passphrase" to the input. The controller encrypts the key material using ODL's AAA encryption service before storing it.

Step 4 - Connect the simulator to the controller

Add the simulator as a node in gnmi-topology:

curl --request PUT 'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "node": [
          {
              "node-id": "gnmi-simulator",
              "connection-parameters": {
                  "host": "127.0.0.1",
                  "port": 10161,
                  "keystore-id": "keystore-id-1",
                  "credentials": {
                      "username": "admin",
                      "password": "admin"
                  }
              },
              "extensions-parameters": {
                  "gnmi-parameters": {
                      "use-model-name-prefix": true
                  }
              }
          }
      ]
  }'

When the mount point is established, the controller logs:

INFO [gnmi_executor-1] (GnmiMountPointRegistrator.java:52) - Mount point for node gnmi-simulator created
INFO [gnmi_executor-0] (GnmiNodeListener.java:105) - Connection with node Uri{_value=gnmi-simulator} established successfully

Step 5 - Check vonnection dtatus

curl --request GET \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator'

Look for "node-status": "READY" in the response. If the connection failed, a failure-details field explains why.

CRUD Operations over RESTCONF → gNMI

Once a device's mount point is READY, RESTCONF requests targeting its path translate to gNMI operations. The mapping is:

HTTP Method	gNMI Operation	Notes
`GET`	`GnmiGet`	Returns CONFIG + STATE merged by default
`PUT`/`POST`	`GnmiSet` (update/replace)	Replaces the target resource
`PATCH`	`GnmiSet` (update)	Merges into the existing resource
`DELETE`	`GnmiSet` (delete)	Removes the target path

A GET without a content query parameter triggers two underlying gNMI requests, one CONFIG and one STATE, and the controller merges the responses. To target one explicitly, append ?content=config or ?content=nonconfig.

Reading device state

Get all interface data from the connected simulator:

curl --request GET \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator/yang-ext:mount/openconfig-interfaces:interfaces'

Get authentication configuration from the config datastore:

curl --request GET \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator/yang-ext:mount/openconfig-system:system/aaa/authentication?content=config'

Writing configuration

Replace the authentication config on the device:

curl --request PUT \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator/yang-ext:mount/openconfig-system:system/aaa/authentication' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "openconfig-system:authentication": {
          "config": {
              "authentication-method": [
                  "openconfig-aaa-types:TACACS_ALL"
              ]
          }
      }
  }'

Patching (merging) configuration

Append a new authentication method without overwriting existing ones:

curl --request PATCH \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator/yang-ext:mount/openconfig-system:system/aaa/authentication/config' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "openconfig-system:config": {
          "authentication-method": [
              "openconfig-aaa-types:RADIUS_ALL"
          ]
      }
  }'

Deleting configuration

curl --location --request DELETE \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator/yang-ext:mount/openconfig-system:system/aaa/authentication/config'

Disconnecting a device

curl --request DELETE \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator'

Loading YANG models for schema context

Before the gNMI southbound creates a mount point for a device, it builds a schema context: a complete picture of which YANG models the device implements. The gNMI Capabilities response provides model names and versions, but not their content. You need to supply the actual YANG files separately.

You have two options:

Option A — at startup via configuration file. Add a gnmi block to your configuration.json:

{
  "gnmi": {
    "initialYangsPaths": [
      "/path/to/yang/models/folder"
    ],
    "initialYangModels": [
      {
        "nameSpace": "http://openconfig.net/yang/interfaces",
        "name": "openconfig-interfaces",
        "revision": "2021-04-06"
      }
    ]
  }
}

Option B — at runtime via RPC. Upload a model to a running instance (escape the quotes inside the body):

curl --request POST 'http://127.0.0.1:8888/restconf/operations/gnmi-yang-storage:upload-yang-model' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "input": {
          "name": "openconfig-interfaces",
          "semver": "2.4.3",
          "body": "YANG_MODEL_CONTENT_WITH_ESCAPED_QUOTES"
      }
  }'

If a device does not report all its capabilities in the Capabilities response (a common issue with devices that use augmenting models), use force-capability in the connection request to override what the controller uses:

curl --request PUT \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=my-device' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "node": [
          {
              "node-id": "my-device",
              "connection-parameters": {
                  "host": "192.168.1.100",
                  "port": 9090,
                  "connection-type": "INSECURE"
              },
              "extensions-parameters": {
                  "force-capability": [
                      {"name": "openconfig-if-ethernet", "version": "2.6.2"},
                      {"name": "openconfig-if-ip",       "version": "2.3.1"}
                  ]
              }
          }
      ]
  }'

Connection types

Three connection modes exist:

TLS (recommended) — add certificates to the keystore first, then reference the keystore-id in the connection request (shown in Steps 3 and 4 above).

INSECURE — skips TLS certificate validation. Equivalent to the --skip-verify flag in gnmic. For dev and lab environments only.

PLAINTEXT — non-TLS connection with no encryption. Set "connection-type": "PLAINTEXT" in connection-parameters.

# Insecure connection (dev/test only)
curl --request PUT \
  'http://127.0.0.1:8888/restconf/data/network-topology:network-topology/topology=gnmi-topology/node=node-id-1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "node": [
          {
              "node-id": "node-id-1",
              "connection-parameters": {
                  "host": "127.0.0.1",
                  "port": 9090,
                  "connection-type": "INSECURE"
              }
          }
      ]
  }'

Running with docker

To skip the local build, run the controller in Docker:

# Build the Docker image
mvn clean install -P docker

# Run the container
docker run -it --name lighty-rcgnmi --network host --rm lighty-rcgnmi

To mount a custom configuration:

docker run -it --name lighty-rcgnmi --network host \
  -v /absolute/path/to/configuration.json:/lighty-rcgnmi/configuration.json \
  -v /absolute/path/to/log4j2.xml:/lighty-rcgnmi/log4j2.xml \
  --rm lighty-rcgnmi -c configuration.json -l log4j2.xml

Deploying to Kubernetes

A Helm chart is included in the repository under lighty-rcgnmi-app-helm/helm. With a running cluster (tested with minikube / microk8s):

# For microk8s — import the Docker image first
bash lighty-rcgnmi-app-helm/helm/microk8s-uploadDocker.sh

# Install the chart
cd lighty-rcgnmi-app-helm/helm
microk8s helm3 install lighty-rcgnmi-app ./lighty-rcgnmi-app-helm/

# Uninstall
microk8s helm3 uninstall lighty-rcgnmi-app

Startup configuration (initial YANG-modelled data, device connection nodes) goes into configmaps.yaml, so you do not need to rebuild the image per environment.

Using the Karaf distribution (ODL Native)

Teams already on the OpenDaylight Karaf distribution can install the gNMI plugin as a feature from the opendaylight/gnmi repository:

# Build from the gnmi repo root
mvn clean install

# Navigate to the built Karaf distribution and start it
cd karaf/target/assembly/bin
./karaf

# Inside the Karaf console
feature:install odl-gnmi-all

The RESTCONF API is on port 8181 for Karaf deployments. The request paths use /rests/ rather than /restconf/, but the gNMI topology paths and payloads are identical:

# Karaf — note the different port and /rests/ prefix
curl --request GET \
  'http://127.0.0.1:8181/rests/data/network-topology:network-topology/topology=gnmi-topology/node=gnmi-simulator' \
  -u admin:admin

Runtime log configuration

Default logging uses Log4j2. To override at startup:

java -Dlog4j.configurationFile=/path/to/log4j2.xml -jar lighty-rcgnmi-app-<version>.jar

Log levels can also be changed at runtime without restarting, using JMX:

jconsole <ip>:1099

Navigate to MBeans → org.apache.logging.log4j2 → loggers → StatusLogger → level and double-click the value to change it.

What you have now

Running all the steps above gives you:

A gNMI controller with a RESTCONF API, backed by OpenDaylight's MD-SAL and YANG Tools, starting in under 15 seconds.
A device mount point that translates standard HTTP verbs into transactional gNMI Get and Set operations.
A local simulator for iterating against OpenConfig YANG models without touching real hardware.
Clear paths to Docker and Kubernetes deployment when you are ready to move off a laptop.

The lighty-gnmi-community-restconf-app is the reference implementation. Once you understand the request flow (RESTCONF path → MD-SAL → gNMI mount point → device), extending it to your own YANG models or adding northbound logic comes down to configuration and plugin wiring.

Resources:

[How-To] Evaluate an Enterprise Network Orchestration & Automation Platform

May 25, 2026

Why vendor lock-in still dominates procurement. Most enterprise network teams do not set out to achieve full vendor lock-in. It accumulates through years of individually reasonable purchasing decisions. You buy the best switch for this data center, the best SD-WAN...

[Case Study] Scalable Wi-Fi Orchestration: Vendor-Agnostic Abstraction with OpenDaylight

May 21, 2026

To enable seamless application deployment at scale, a leading software company needed to eliminate the bottleneck of manual, vendor-specific network configuration. PANTHEON.tech transformed this vision into a high-performance orchestration layer, by leveraging our...

Quantum-Proof VPP: Bringing Post-Quantum Security to the Data Plane

May 11, 2026

The quantum computing era is not a distant theoretical concern - it is an engineering reality that network architects and security teams need to address as soon as possible. At the intersection of high-performance, open-source networking and cutting-edge post-quantum...