From e8d874ea9090ed638581a8dbf8060189c0d5f46d Mon Sep 17 00:00:00 2001 From: Nicolas Leiva Date: Tue, 26 Sep 2017 09:54:23 -0400 Subject: [PATCH] Update README.md --- README.md | 134 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 85 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index dfe485b..22d7c35 100644 --- a/README.md +++ b/README.md @@ -26,21 +26,21 @@ The end goal is to enable use-cases where multiple interactions with devices are * [Usage](#usage) + [Get Config](#get-config) + [Show Commands](#show-commands) - - [**Clear text**](#--clear-text--) - - [**JSON**](#--json--) + - [Clear text](#--clear-text--) + - [JSON](#--json--) + [Configuring the router](#configuring-the-router) - - [**CLI config** (Merge)](#--cli-config----merge-) - - [**JSON** (Merge)](#--json----merge-) - - [**JSON** (Replace)](#--json----replace-) - - [**Using a YANG config Template** (Merge)](#--using-a-yang-config-template----merge-) + - [CLI config (Merge)](#--cli-config----merge-) + - [JSON (Merge)](#--json----merge-) + - [JSON (Replace)](#--json----replace-) + - [Using a YANG config Template (Merge)](#--using-a-yang-config-template----merge-) + [Removing router config](#removing-router-config) - - [**JSON**](#--json---1) - + [**CLI config multiple routers simultaneously** (Merge)](#--cli-config-multiple-routers-simultaneously----merge-) + - [JSON](#--json---1) + + [CLI config multiple routers simultaneously (Merge)](#--cli-config-multiple-routers-simultaneously----merge-) + [Telemetry](#telemetry) - - [**JSON (GPBKV)**](#--json--gpbkv---) - - [**JSON (GPBKV): Exploring the fields**](#--json--gpbkv---exploring-the-fields--) - - [**JSON (GPBKV): OpenConfig**](#--json--gpbkv---openconfig--) - - [**GPB (Protobuf)**](#--gpb--protobuf---) + - [JSON (GPBKV)](#--json--gpbkv---) + - [JSON (GPBKV): Exploring the fields](#--json--gpbkv---exploring-the-fields--) + - [JSON (GPBKV): OpenConfig](#--json--gpbkv---openconfig--) + - [GPB (Protobuf)](#--gpb--protobuf---) + [Config and Validate](#config-and-validate) + [Service Layer API](#service-layer-api) - [Add an IPv6 route](#add-an-ipv6-route) @@ -57,12 +57,14 @@ The end goal is to enable use-cases where multiple interactions with devices are CLI examples to use the library are provided in the [example](example/) folder. The CLI specified in the examples is not definitive and might change as we go. -### Get Config +### Get Config (example/getconfig) Retrieves the config from one target device described in [config.json](example/input/config.json), for the YANG paths specified in [yangpaths.json](example/input/yangpaths.json). If you want to see it using [OpenConfig models](https://github.com/openconfig/public/tree/master/release/models), you can issue `./getconfig -ypath "../input/yangocpaths.json"` instead. -```shell -example/getconfig$ ./getconfig +- example/getconfig + +```console +$ ./getconfig Config from [2001:420:2cff:1204::5502:1]:57344 { @@ -87,10 +89,12 @@ Config from [2001:420:2cff:1204::5502:1]:57344 Provides the output of IOS XR cli commands for one router defined in [config.json](example/input/config.json). Two output format options are available; Unstructured text and JSON encoded: -#### **Clear text** +#### Clear text + +- example/showcmd ```console -example/showcmd$ ./showcmd -cli "show isis database" -enc text +$ ./showcmd -cli "show isis database" -enc text Output from [2001:420:2cff:1204::5502:1]:57344 @@ -108,10 +112,12 @@ mrstn-5501-1.cisco.com.00-00 0x0000000c 0x65d5 1150 0/0/0 2017/07/21 15:37:00 This process took 2.480039252s ``` -#### **JSON** +#### JSON -```shell -example/showcmd$ ./showcmd -cli "show isis database" -enc json +- example/showcmd + +```console +$ ./showcmd -cli "show isis database" -enc json Config from [2001:420:2cff:1204::5502:1]:57344 [{ @@ -140,12 +146,14 @@ Config from [2001:420:2cff:1204::5502:1]:57344 ### Configuring the router -#### **CLI config** (Merge) +#### CLI config (Merge) Applies CLI config commands on the device/router from the list in [config.json](example/input/config.json). +- example/setconfig + ```console -example/setconfig$ ./setconfig -cli "interface Lo11 ipv6 address 2001:db8::/128" +$ ./setconfig -cli "interface Lo11 ipv6 address 2001:db8::/128" Config applied to [2001:420:2cff:1204::5502:1]:57344 @@ -162,12 +170,14 @@ interface Loopback11 ! ``` -#### **JSON** (Merge) +#### JSON (Merge) Applies a YANG/JSON formatted config to one device/router (merges with existing config) from the list in [config.json](example/input/config.json). It reads the target from [yangconfig.json](example/input/yangconfig.json). +- example/mergeconfig + ```console -example/mergeconfig$ ./mergeconfig +$ ./mergeconfig Config merged on [2001:420:2cff:1204::5502:1]:57344 -> Request ID: 8162, Response ID: 8162 @@ -185,12 +195,14 @@ interface Loopback201 ! ``` -#### **JSON** (Replace) +#### JSON (Replace) Applies a YANG/JSON formatted config to one device/router (replaces the config for this section) from the list in [config.json](example/input/config.json). It learns the config to replace from [yangconfigrep.json](example/input/yangconfigrep.json). If we had merged instead, we would have ended up with two IPv6 addresses in this example. +- example/replaceconfig + ```console -example/replaceconfig$ ./replaceconfig +$ ./replaceconfig Config replaced on [2001:420:2cff:1204::5502:1]:57344 -> Request ID: 4616, Response ID: 4616 @@ -208,7 +220,7 @@ interface Loopback201 ! ``` -#### **Using a YANG config Template** (Merge) +#### Using a YANG config Template (Merge) Applies a YANG/JSON formatted config to one device/router (merges with existing config) from the list in [config.json](example/input/config.json). It takes a template ([bgp.json](example/input/template/bgp.json)), based on the BGP YANG model [Cisco-IOS-XR-ipv4-bgp-cfg](https://github.com/YangModels/yang/blob/master/vendor/cisco/xr/622/Cisco-IOS-XR-ipv4-bgp-cfg.yang), in this case and the specific parameters from [bgp-parameters.json](example/input/template/bgp-parameters.json). @@ -240,8 +252,10 @@ See below an extract from this [bgp.json](example/input/template/bgp.json) and n Now we execute and inmediatly request the updated BGP config from the device with a subsequent RPC call. -```shell -example/mergetemplate$ ./mergetemplate +- example/mergetemplate + +```console +$ ./mergetemplate Config merged on [2001:420:2cff:1204::5502:1]:57344 -> Request ID: 1866, Response ID: 1866 @@ -278,12 +292,14 @@ While templates are cool, I'd recommend exploring one of these alternatives to h ### Removing router config -#### **JSON** +#### JSON Removes YANG/JSON formatted config on one device/router from [config.json](example/input/config.json). It reads the config to delete from [yangdelconfig.json](example/input/yangdelconfig.json). The following example deletes both interfaces configured in the Merge example. See [yangdelintadd.json](example/input/yangdelintadd.json) to delete just the IP address and [yangdelintdesc.json](example/input/yangdelintdesc.json) for only the description of the interface. +- example/deleteconfig + ```console -example/deleteconfig$ ./deleteconfig +$ ./deleteconfig Config Deleted on [2001:420:2cff:1204::5502:1]:57344 -> Request ID: 2856, Response ID: 2856 @@ -302,12 +318,14 @@ no interface Loopback301 end ``` -### **CLI config multiple routers simultaneously** (Merge) +### CLI config multiple routers simultaneously (Merge) Applies CLI config commands to the list of routers specified on [config.json](example/input/config.json). Notice that even though we added two devices, the execution time did NOT increase. This is possible because of the use of [Golang Concurrency](https://blog.golang.org/pipelines) primitives. +- example/setconfiglist + ```console -example/setconfiglist$ ./setconfiglist -cli "interface Lo33 ipv6 address 2001:db8:33::1/128" +$ ./setconfiglist -cli "interface Lo33 ipv6 address 2001:db8:33::1/128" Config applied to [2001:420:2cff:1204::5502:2]:57344 @@ -352,12 +370,14 @@ interface Loopback33 ### Telemetry -#### **JSON (GPBKV)** +#### JSON (GPBKV) Subscribe to a Telemetry stream. The Telemetry message is defined in [telemetry.proto](proto/telemetry/telemetry.proto). The payload is JSON encoded (self-describing GPB). +- example/telemetry + ```console -example/telemetry$ ./telemetry -subs "LLDP" +$ ./telemetry -subs "LLDP" Time 1500666991103, Path: Cisco-IOS-XR-ethernet-lldp-oper:lldp/nodes/node/neighbors/details/detail { "NodeId": { @@ -391,7 +411,7 @@ telemetry model-driven ! ``` -#### **JSON (GPBKV): Exploring the fields** +#### JSON (GPBKV): Exploring the fields Same as the previous example using a Cisco native YANG model. However this time we explore the fields in order to produce a custom output. @@ -410,8 +430,10 @@ func exploreFields(f []*telemetry.TelemetryField, indent string) { The result looks like this: +- example/telemetrykv + ```console -example/telemetrykv$ ./telemetrykv +$ ./telemetrykv ****************************************************************************************** Time 01:24:48PM, Path: Cisco-IOS-XR-ethernet-lldp-oper:lldp/nodes/node/neighbors/details/detail ****************************************************************************************** @@ -433,12 +455,14 @@ Time 01:24:48PM, Path: Cisco-IOS-XR-ethernet-lldp-oper:lldp/nodes/node/neighbors ``` -#### **JSON (GPBKV): OpenConfig** +#### JSON (GPBKV): OpenConfig Same example as before, just calling a subscription that uses an OpenConfig model instead. The result looks like this: +- example/telemetrykv + ```console -example/telemetrykv$ ./telemetrykv -subs "BGP-OC" +$ ./telemetrykv -subs "BGP-OC" ****************************************************************************************** Time 01:08:03PM, Path: openconfig-bgp:bgp/neighbors/neighbor/state ****************************************************************************************** @@ -480,13 +504,14 @@ telemetry model-driven ! ``` - -#### **GPB (Protobuf)** +#### GPB (Protobuf) Again, we subscribe to a Telemetry stream but we request the content is encoded with [protobuf](https://developers.google.com/protocol-buffers/). To decode the message we need to look at the "LLDP neighbor details" definition in [lldp_neighbor.proto](proto/telemetry/lldp/lldp_neighbor.proto). We parse the message and modify the output to illustrate how to access to each field on it. +- example/telemetrygpb + ```console -example/telemetrygpb$ ./telemetrygpb -subs "LLDP" +$ ./telemetrygpb -subs "LLDP" Time 1500667512299, Path: Cisco-IOS-XR-ethernet-lldp-oper:lldp/nodes/node/neighbors/details/detail { "node_name": "0/RP0/CPU0", @@ -556,8 +581,10 @@ The example will run a config checklist, composed of three items as a result of The output of the example is very basic, but ilustrates all these points. Notice we receive BGP status every 5 seconds and the neighbor goes from bgp-st-idle to bgp-st-estab. +- example/configvalidate + ```console -example/configvalidate$ ./configvalidate +$ ./configvalidate ****************************************************************************************** Config merged on [2001:420:2cff:1204::5502:1]:57344 -> Request ID: 3018, Response ID: 3018 @@ -635,8 +662,10 @@ BGP Neighbor; IP: 2001:db8:cafe::2, ASN: 64512, State bgp-st-estab Add a new route to the IPv6 routing table. +- example/setroute + ```console -example/setroute$ ./setroute -pfx "2001:db8:1413::/48" -nh "2001:db8:cafe::2" +$ ./setroute -pfx "2001:db8:1413::/48" -nh "2001:db8:cafe::2" 2017/07/25 15:02:01 This process took 329.560647ms ``` @@ -705,35 +734,42 @@ mrstn-5502-1 emsd: [1058]: %MGBL-EMS-4-EMSD_PORT_RANGE : The configured port 565 You need to retrive the `ems.pem` file from the IOS XR device (after enabling gRPC/TLS) and put it in the [input](example/input) folder (or any other location specified in [config.json](example/input/config.json)). You can find the file in the router on either `/misc/config/grpc/` or `/var/xr/config/grpc`. +- /var/xr/config/grpc + ```console -[xrrouter.cisco.com:/var/xr/config/grpc]$ ls -la +$ ls -la total 20 drwxr-xr-x 3 root root 4096 Jul 5 17:47 . drwxr-xr-x 10 root root 4096 Jul 3 12:50 .. drwx------ 2 root root 4096 Jul 3 12:50 dialout -rw------- 1 root root 1675 Jul 5 17:47 ems.key -rw-rw-rw- 1 root root 1513 Jul 5 17:47 ems.pem -[xrrouter.cisco.com:/var/xr/config/grpc]$ ``` ## Compiling the proto files The Go generated code in [ems_grpc.pb.go](proto/ems/ems_grpc.pb.go) is the result of the following: +- proto/ems + ```console -proto/ems/$ protoc --go_out=plugins=grpc:. ems_grpc.proto +$ protoc --go_out=plugins=grpc:. ems_grpc.proto ``` The Go generated code in [lldp_neighbor.pb.go](proto/telemetry/lldp/lldp_neighbor.pb.go) is the result of the following: +- proto/telemetry/lldp + ```console -proto/telemetry/lldp$ protoc --go_out=. lldp_neighbor.proto +$ protoc --go_out=. lldp_neighbor.proto ``` ## Compiling the Examples Simply execute `go build` on the corresponding example folder. E.g. +- example/telemetry + ```console -example/telemetry$ go build +$ go build ```