gnmitarget

README

gNMI Target

gNMI Target for standard OS clients using a selection of supported OpenConfig YANG modules.

Usage

To update the generated ygot structs from yang modules you can simply run make generate-yang-models.

To use the target: (after the obligatory go install) run gnmi-target start to start the gNMI server with default configuration (OS client: ubuntu)

Options to start the gNMI target

To start the target with TLS you have to provide a certificate (command line option --cert <path-to-cert>) and a private key (command line option --key <path-to-key>)

It is recommended to always use TLS.

For testing purposes the Makefile provides the option make self-certs. This generates a self-signed certificate and the corresponding private key. They are both stored under the directory artifacts/ssl in the source code directory.

However, you can also run the target with not TLS enabled by specifying the command line option --insecure.

Requesting Data from the target

With TLS and self-signed certificates

To request all data with gnmiclient run this command

gnmic -a localhost:7030 -u admin -p admsdsdin --skip-verify get --path "/"

With no TLS

To request all data with gnmiclient: run this command

gnmic -a localhost:7030 -u admin -p admsdsdin --insecure get --path "/"

---

Further Documentation

Please see the documentation folder for more in-depth information about the different parts and features of the gnmi-target.

---

Binaries

At the moment it's recommended to use binary executables when using the target. You can find executables for various systems on the Release page. For every commit on develop and master you can download executable artifacts as well.

Code structure

This section explains the underlying philosophy of the code structure within the gNMI Target, and notes how the developers should aim to keep it going forward.

The gNMI Target consists of three basic parts, which are further augmented with needed functionality:

1. The gnmitarget package, which acts as the central controller and bridge between the os client and the gNMI server. It currently consists only of the target.go file. It alone should hold persistent data and provide access to it, most importantly the ygot-generated gnmitargetygot.go-struct which contains all configuration information.
2. The gnmiserver package, which contains the actual gNMI server and communicates with the rest of the world and answers gNMI requests. All data in these request answers should be loaded from the central struct in gnmitarget.
3. The os_clients package, containing multiple clients for different os (currently ubuntu as default and freebsd). The os clients must implement the Os_client interface. The clients communicate with the underlying host OS and read/write data as requested. All read data should be updated into the central struct in gnmitarget.

These three main components are augmented with:

• The cmd package, containing cobra/viper commands to control the target via command line
• The config folder, containing cobra config files and the serialized ygot struct in JSON format for persistence
• The modeldata package, containing the modeldata.go file specifying the currently supported subset of yang modules (to answer Capabilities requests), and the ygot-generated gnmitargetygot.go-struct from all possibly supported yang modules.
• The yang-modules folder, containing all possibly supported yang modules which ygot used to generate the struct
• The imported ygot submodule from github, which is (currently) used for ygot generation and helper functions for data conversion within the os clients.
• The main.go file containing the go:generate ygot command and cobra command hook
• The usual go, git, license, readme and CI/CD docker files

---

YANG Modules

Our aim is to someday support the following YANG modules (dependencies not listed):

• openconfig-interfaces
• openconfig-if-ip
• openconfig-if-ethernet
• openconfig-if-tunnel
• openconfig-if-8021x
• openconfig-acl
• openconfig-lldp
• openconfig-platform
• openconfig-platform-cpu
• openconfig-platform-fan
• openconfig-platform-psu
• openconfig-platform-software
• openconfig-probes
• openconfig-relay-agent
• openconfig-system
• openconfig-vlan
• openconfig-network-instance

These modules were selected based on their probable usefulness in the context of a basic endpoint client (PC running a general purpose OS) with additional modules for future extension on specialized network equipment (switches etc.), and converted into Go structs using ygot and are available for implementation.
Currently none are fully supported.
In future versions it will be possible to request the current state of supported modules via the gNMI Capabilities command.

Devcontainer - local

For this method you only need docker and vscode with the plugin Dev Containers from Microsoft installed. After you installed the required tools, you can simply open the folder in the dev container. Either you click on Open in Container if a pop-up appears on the bottom right, or by selecting Open in Container after clicking on Remote Explorer in the left bar in VSCode. Please note: depending on your internet connection and the performance of the device, the initial creation of the container can take several minuts or longer! Furthermore the initial git discovery of every submodule in this repo (if installed) can also take some minutes.

The devcontainer has everything you need in it (even relevant VSCode plugins), so you should not need anything more. Please keep in mind that this setup is not tested thoroughly!

Documentation

Index

• type GnmiTarget
  • func NewGnmiTarget(schema *ytypes.Schema, model ygot.ValidatedGoStruct, ...) *GnmiTarget
  • func (gt *GnmiTarget) Start(bindAddress string, certFile string, keyFile string, caFile string, ...) error
• type Logic

Types

type GnmiTarget

type GnmiTarget struct {
	ΛEnum                     map[string]map[int64]ygot.EnumDefinition
	YangModelChangeDispatcher *not.Dispatcher
	// contains filtered or unexported fields
}

GnmiTarget is a gnmi target that can be run on a operating system.

func NewGnmiTarget

func NewGnmiTarget(
	schema *ytypes.Schema,
	model ygot.ValidatedGoStruct,
	modeldata []*pbGNMI.ModelData,
	unmarshalFn func(data []byte, destStruct ygot.GoStruct, opts ...ytypes.UnmarshalOpt) error,
	ΛEnum map[string]map[int64]ygot.EnumDefinition,
	yangHandlers ...handler.PathHandler,
) *GnmiTarget

func (*GnmiTarget) Start

func (gt *GnmiTarget) Start(bindAddress string, certFile string, keyFile string, caFile string, insecure bool) error

type Logic

type Logic interface {
	Init() (ygot.ValidatedGoStruct, error)
	Callback(newConfig, existingConfig ygot.ValidatedGoStruct) error
}