gNMI

The gNMI protocol is a rapidly growing industry standard for network management. Holo daemon includes a gNMI module that can be used to programmatically configure and monitor the daemon. The module is enabled by default and listens on TCP port 10161.

The gNMI interface is defined in the gnmi.proto and gnmi_ext.proto files, available at https://github.com/rwestphal/holo/blob/devel/proto/. The complete gNMI specification can be found at https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md.

Examples

To get started with gNMI, the easiest way is to use the gnmic command-line tool which you can find at https://gnmic.kmrd.dev/. Below are a few examples of using gnmic to communicate with holod:

• Retrieve device capabilities (Capabilities RPC):

$ gnmic -a [::1]:10161 -u admin -p admin --insecure capabilities
gNMI version: 0.8.1
supported models:
  - iana-if-type, IANA, 2017-01-19
  - ietf-interfaces, IETF NETMOD (Network Modeling) Working Group, 2018-01-09
  - ietf-routing-types, IETF RTGWG - Routing Area Working Group, 2017-10-13
  - ietf-bfd-types, IETF BFD Working Group, 2022-09-22
  - ietf-routing, IETF NETMOD (Network Modeling) Working Group, 2018-03-13
  - ietf-key-chain, IETF RTGWG - Routing Area Working Group, 2017-06-15
  - ietf-ip, IETF NETMOD (Network Modeling) Working Group, 2018-01-09
  - ietf-segment-routing, IETF SPRING - SPRING Working Group, 2021-05-26
  - ietf-segment-routing-common, IETF SPRING - SPRING Working Group, 2021-05-26
  - ietf-segment-routing-mpls, IETF SPRING - SPRING Working Group, 2021-05-26
  - ietf-bfd-ip-mh, IETF BFD Working Group, 2022-09-22
  - ietf-bfd, IETF BFD Working Group, 2022-09-22
  [snip]
supported encodings:
  - PROTO
  - JSON_IETF

• Update the running configuration (Set RPC):

$ gnmic -a [::1]:10161 -u admin -p admin --insecure set --update-path /ietf-routing:routing/control-plane-protocols/control-plane-protocol[type="ietf-ospf:ospfv2"][name="main"]/ietf-ospf:ospf/enable --update-value false
{
  "source": "[::1]:10161",
  "timestamp": 1680554842,
  "time": "1969-12-31T21:00:01.680554842-03:00"
}

• Retrieve the running configuration (Get RPC):

$ gnmic -a [::1]:10161 -u admin -p admin --insecure get --type CONFIG --encoding json_ietf --path /ietf-routing:routing | head -n 20
[
  {
    "source": "[::1]:10161",
    "timestamp": 1680555639,
    "time": "1969-12-31T21:00:01.680555639-03:00",
    "updates": [
      {
        "Path": "ietf-routing:routing",
        "values": {
          "routing": {
            "ietf-routing:routing": {
              "control-plane-protocols": {
                "control-plane-protocol": [
                  {
                    "ietf-ospf:ospf": {
                      "areas": {
                        "area": [
                          {
                            "area-id": "0.0.0.0",
                            "interfaces": 

• Retrieve state data (Get RPC):

$ gnmic -a [::1]:10161 -u admin -p admin --insecure get --type STATE --encoding json_ietf --path /ietf-routing:routing | head -n 20
[
  {
    "source": "[::1]:10161",
    "timestamp": 1680555326,
    "time": "1969-12-31T21:00:01.680555326-03:00",
    "updates": [
      {
        "Path": "ietf-routing:routing",
        "values": {
          "routing": {
            "ietf-routing:routing": {
              "control-plane-protocols": {
                "control-plane-protocol": [
                  {
                    "ietf-bfd:bfd": {
                      "ietf-bfd-ip-mh:ip-mh": {
                        "summary": {
                          "number-of-sessions": 0,
                          "number-of-sessions-admin-down": 0,
                          "number-of-sessions-down": 0,

Naturally, it is also possible to use gNMI programmatically in any programming language that has gRPC bindings available.

Limitations

At present, the gNMI module does not offer support for the Subscribe RPC, which is commonly used for streaming telemetry data.

Configuration

The gNMI module has the following configuration options:

  # gNMI northbound plugin configuration
  [plugins.gnmi]
    # Enable or disable the plugin
    enabled = true
    # gNMI server listening address
    address = "[::1]:10161"
    # Optional gNMI TLS configuration
    [plugins.gnmi.tls]
      # Enable or disable TLS authentication
      enabled = false
      # TLS certificate
      certificate = "/etc/ssl/private/holo.pem"
      # TLS key
      key = "/etc/ssl/certs/holo.key"