Skip to content

Commit 8238eda

Browse files
remingtoncremingtonc
committed
Improve doc
1 parent 9fb5217 commit 8238eda

File tree

2 files changed

+78
-64
lines changed

2 files changed

+78
-64
lines changed

‎README.md

Lines changed: 55 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ This library covers the gNMI defined `Capabilities`, `Get`, `Set`, and `Subscrib
1616
It is *highly* recommended that users of the library learn [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) syntax to significantly ease usage. Understanding how to read Protocol Buffers, and reference [`gnmi.proto`](https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto), will be immensely useful for utilizing gNMI and any other gRPC interface.
1717

1818
### gnmcli
19-
Since `v1.0.5` a gNMI CLI is available when this module is installed. `Capabilities`, `Subscribe`, `Get`, and rudimentary `Set` are supported. The CLI may be useful for simply interacting with a Cisco gNMI service, and also serves as a reference for how to use this `cisco_gnmi` library. CLI usage is documented at the bottom of this README in [gnmcli Usage](#gnmcli-usage).
19+
Since `v1.0.5` a gNMI CLI is available when this module is installed. `Capabilities`, `Get`, rudimentary `Set`, and `Subscribe` are supported. The CLI may be useful for simply interacting with a Cisco gNMI service, and also serves as a reference for how to use this `cisco_gnmi` library. CLI usage is documented at the bottom of this README in [gnmcli Usage](#gnmcli-usage).
2020

2121
### ClientBuilder
2222
Since `v1.0.0` a builder pattern is available with `ClientBuilder`. `ClientBuilder` provides several `set_*` methods which define the intended `Client` connectivity and a `construct` method to construct and return the desired `Client`. There are several major methods involved here:
@@ -186,7 +186,7 @@ If a new `gnmi.proto` definition is released, use `update_protos.sh` to recompil
186186
```
187187

188188
### gnmcli Usage
189-
The below details the current `gnmcli` usage options.
189+
The below details the current `gnmcli` usage options. Please note that `Set` operations may be destructive to operations and should be tested in lab conditions.
190190

191191
```
192192
gnmcli --help
@@ -199,6 +199,11 @@ subscribe
199199
get
200200
set
201201
202+
gnmcli capabilities 127.0.0.1:57500
203+
gnmcli get 127.0.0.1:57500
204+
gnmcli set 127.0.0.1:57500 -delete_xpath Cisco-IOS-XR-shellutil-cfg:host-names/host-name
205+
gnmcli subscribe 127.0.0.1:57500 -debug -auto_ssl_target_override -dump_file intfcounters.proto.txt
206+
202207
See <rpc> --help for RPC options.
203208
204209
@@ -235,7 +240,7 @@ positional arguments:
235240
optional arguments:
236241
-h, --help show this help message and exit
237242
-os {None,IOS XR,NX-OS,IOS XE}
238-
OS to use.
243+
OS wrapper to utilize. Defaults to IOS XR.
239244
-root_certificates ROOT_CERTIFICATES
240245
Root certificates for secure connection.
241246
-private_key PRIVATE_KEY
@@ -245,8 +250,9 @@ optional arguments:
245250
-ssl_target_override SSL_TARGET_OVERRIDE
246251
gRPC SSL target override option.
247252
-auto_ssl_target_override
248-
Root certificates for secure connection.
249-
-debug Print debug messages
253+
Use root_certificates first CN as
254+
grpc.ssl_target_name_override.
255+
-debug Print debug messages.
250256
```
251257

252258
#### Get
@@ -256,7 +262,6 @@ gnmcli get 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/count
256262
```
257263

258264
```
259-
gnmcli get --help
260265
usage: gnmcli [-h] [-xpath XPATH]
261266
[-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
262267
[-data_type [{ALL,CONFIG,STATE,OPERATIONAL}]] [-dump_json]
@@ -277,12 +282,12 @@ optional arguments:
277282
-h, --help show this help message and exit
278283
-xpath XPATH XPaths to Get.
279284
-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
280-
gNMI subscription encoding.
285+
gNMI Encoding.
281286
-data_type [{ALL,CONFIG,STATE,OPERATIONAL}]
282287
gNMI GetRequest DataType
283288
-dump_json Dump as JSON instead of textual protos.
284289
-os {None,IOS XR,NX-OS,IOS XE}
285-
OS to use.
290+
OS wrapper to utilize. Defaults to IOS XR.
286291
-root_certificates ROOT_CERTIFICATES
287292
Root certificates for secure connection.
288293
-private_key PRIVATE_KEY
@@ -292,21 +297,17 @@ optional arguments:
292297
-ssl_target_override SSL_TARGET_OVERRIDE
293298
gRPC SSL target override option.
294299
-auto_ssl_target_override
295-
Root certificates for secure connection.
296-
-debug Print debug messages
297-
```
298-
299-
#### Subscribe
300-
This command will output the `SubscribeResponse` to `stdout` or `-dump_file`. `-xpath` may be specified multiple times to specify multiple `Path`s for the `GetRequest`. Subscribe currently only supports a sampled stream. `ON_CHANGE` is possible but not implemented in the CLI, yet. :)
301-
```
302-
gnmcli subscribe 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_override
300+
Use root_certificates first CN as
301+
grpc.ssl_target_name_override.
302+
-debug Print debug messages.
303303
```
304304

305+
#### Set
306+
This command has not been validated. Please note that `Set` operations may be destructive to operations and should be tested in lab conditions.
305307
```
306-
gnmcli subscribe --help
307-
usage: gnmcli [-h] [-xpath XPATH] [-interval INTERVAL] [-dump_file DUMP_FILE]
308-
[-dump_json] [-sync_stop]
309-
[-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
308+
usage: gnmcli [-h] [-update_json_config UPDATE_JSON_CONFIG]
309+
[-replace_json_config REPLACE_JSON_CONFIG]
310+
[-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json]
310311
[-os {None,IOS XR,NX-OS,IOS XE}]
311312
[-root_certificates ROOT_CERTIFICATES]
312313
[-private_key PRIVATE_KEY]
@@ -315,22 +316,23 @@ usage: gnmcli [-h] [-xpath XPATH] [-interval INTERVAL] [-dump_file DUMP_FILE]
315316
[-auto_ssl_target_override] [-debug]
316317
netloc
317318
318-
Performs Subscribe RPC against network element.
319+
Performs Set RPC against network element.
319320
320321
positional arguments:
321322
netloc <host>:<port>
322323
323324
optional arguments:
324325
-h, --help show this help message and exit
325-
-xpath XPATH XPath to subscribe to.
326-
-interval INTERVAL Sample interval in seconds for Subscription.
327-
-dump_file DUMP_FILE Filename to dump to. Defaults to stdout.
326+
-update_json_config UPDATE_JSON_CONFIG
327+
JSON-modeled config to apply as an update.
328+
-replace_json_config REPLACE_JSON_CONFIG
329+
JSON-modeled config to apply as a replace.
330+
-delete_xpath DELETE_XPATH
331+
XPaths to delete.
332+
-no_ietf JSON is not IETF conformant.
328333
-dump_json Dump as JSON instead of textual protos.
329-
-sync_stop Stop on sync_response.
330-
-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
331-
gNMI subscription encoding.
332334
-os {None,IOS XR,NX-OS,IOS XE}
333-
OS to use.
335+
OS wrapper to utilize. Defaults to IOS XR.
334336
-root_certificates ROOT_CERTIFICATES
335337
Root certificates for secure connection.
336338
-private_key PRIVATE_KEY
@@ -340,17 +342,22 @@ optional arguments:
340342
-ssl_target_override SSL_TARGET_OVERRIDE
341343
gRPC SSL target override option.
342344
-auto_ssl_target_override
343-
Root certificates for secure connection.
344-
-debug Print debug messages
345+
Use root_certificates first CN as
346+
grpc.ssl_target_name_override.
347+
-debug Print debug messages.
345348
```
346349

347-
#### Set
348-
This command has not been validated.
350+
#### Subscribe
351+
This command will output the `SubscribeResponse` to `stdout` or `-dump_file`. `-xpath` may be specified multiple times to specify multiple `Path`s for the `GetRequest`. Subscribe currently only supports a sampled stream. `ON_CHANGE` is possible but not implemented in the CLI, yet. :)
349352
```
350-
gnmcli set --help
351-
usage: gnmcli [-h] [-update_json_config UPDATE_JSON_CONFIG]
352-
[-replace_json_config REPLACE_JSON_CONFIG]
353-
[-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json]
353+
gnmcli subscribe 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_override
354+
```
355+
356+
```
357+
gnmcli subscribe --help
358+
usage: gnmcli [-h] [-xpath XPATH] [-interval INTERVAL] [-dump_file DUMP_FILE]
359+
[-dump_json] [-sync_stop]
360+
[-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
354361
[-os {None,IOS XR,NX-OS,IOS XE}]
355362
[-root_certificates ROOT_CERTIFICATES]
356363
[-private_key PRIVATE_KEY]
@@ -359,23 +366,23 @@ usage: gnmcli [-h] [-update_json_config UPDATE_JSON_CONFIG]
359366
[-auto_ssl_target_override] [-debug]
360367
netloc
361368
362-
Performs Set RPC against network element.
369+
Performs Subscribe RPC against network element.
363370
364371
positional arguments:
365372
netloc <host>:<port>
366373
367374
optional arguments:
368375
-h, --help show this help message and exit
369-
-update_json_config UPDATE_JSON_CONFIG
370-
JSON-modeled config to apply as an update.
371-
-replace_json_config REPLACE_JSON_CONFIG
372-
JSON-modeled config to apply as an update.
373-
-delete_xpath DELETE_XPATH
374-
XPaths to delete.
375-
-no_ietf JSON is not IETF conformant.
376+
-xpath XPATH XPath to subscribe to.
377+
-interval INTERVAL Sample interval in seconds for Subscription. Defaults
378+
to 10.
379+
-dump_file DUMP_FILE Filename to dump to. Defaults to stdout.
376380
-dump_json Dump as JSON instead of textual protos.
381+
-sync_stop Stop on sync_response.
382+
-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
383+
gNMI Encoding.
377384
-os {None,IOS XR,NX-OS,IOS XE}
378-
OS to use.
385+
OS wrapper to utilize. Defaults to IOS XR.
379386
-root_certificates ROOT_CERTIFICATES
380387
Root certificates for secure connection.
381388
-private_key PRIVATE_KEY
@@ -385,8 +392,9 @@ optional arguments:
385392
-ssl_target_override SSL_TARGET_OVERRIDE
386393
gRPC SSL target override option.
387394
-auto_ssl_target_override
388-
Root certificates for secure connection.
389-
-debug Print debug messages
395+
Use root_certificates first CN as
396+
grpc.ssl_target_name_override.
397+
-debug Print debug messages.
390398
```
391399

392400
## Licensing

‎src/cisco_gnmi/cli.py

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,11 @@ def main():
5555
Supported RPCs:
5656
{supported_rpcs}
5757
58+
gnmcli capabilities 127.0.0.1:57500
59+
gnmcli get 127.0.0.1:57500 -xpath /interfaces/interface/state/counters
60+
gnmcli set 127.0.0.1:57500 -update_json_config newconfig.json
61+
gnmcli subscribe 127.0.0.1:57500 -xpath /interfaces/interface/state/counters -dump_file intfcounters.proto.txt
62+
5863
See <rpc> --help for RPC options.
5964
""".format(
6065
supported_rpcs="\n".join(list(rpc_map.keys()))
@@ -97,7 +102,7 @@ def gnmi_subscribe():
97102
)
98103
parser.add_argument(
99104
"-interval",
100-
help="Sample interval in seconds for Subscription.",
105+
help="Sample interval in seconds for Subscription. Defaults to 10.",
101106
type=int,
102107
default=10,
103108
)
@@ -117,7 +122,7 @@ def gnmi_subscribe():
117122
)
118123
parser.add_argument(
119124
"-encoding",
120-
help="gNMI subscription encoding.",
125+
help="gNMI Encoding.",
121126
type=str,
122127
nargs="?",
123128
choices=proto.gnmi_pb2.Encoding.keys(),
@@ -169,7 +174,7 @@ def gnmi_get():
169174
parser.add_argument("-xpath", help="XPaths to Get.", type=str, action="append")
170175
parser.add_argument(
171176
"-encoding",
172-
help="gNMI subscription encoding.",
177+
help="gNMI Encoding.",
173178
type=str,
174179
nargs="?",
175180
choices=proto.gnmi_pb2.Encoding.keys(),
@@ -214,7 +219,7 @@ def gnmi_set():
214219
"-update_json_config", help="JSON-modeled config to apply as an update."
215220
)
216221
parser.add_argument(
217-
"-replace_json_config", help="JSON-modeled config to apply as an update."
222+
"-replace_json_config", help="JSON-modeled config to apply as a replace."
218223
)
219224
parser.add_argument(
220225
"-delete_xpath", help="XPaths to delete.", type=str, action="append"
@@ -237,16 +242,17 @@ def load_json_file(filename):
237242
config = json.load(config_fd)
238243
return config
239244

240-
kwargs = {}
241-
if args.update_json_config:
242-
kwargs["update_json_configs"] = load_json_file(args.update_json_config)
243-
if args.replace_json_config:
244-
kwargs["replace_json_configs"] = load_json_file(args.replace_json_config)
245-
if args.no_ietf:
246-
kwargs["ietf"] = False
247-
client = __gen_client(args)
248-
set_response = client.set_json(**kwargs)
249-
logging.info(__format_message(set_response))
245+
if args.update_json_config or args.replace_json_config:
246+
kwargs = {}
247+
if args.update_json_config:
248+
kwargs["update_json_configs"] = load_json_file(args.update_json_config)
249+
if args.replace_json_config:
250+
kwargs["replace_json_configs"] = load_json_file(args.replace_json_config)
251+
if args.no_ietf:
252+
kwargs["ietf"] = False
253+
client = __gen_client(args)
254+
set_response = client.set_json(**kwargs)
255+
logging.info(__format_message(set_response))
250256
if args.delete_xpath:
251257
if getattr(client, "delete_xpaths", None) is not None:
252258
delete_response = client.delete_xpaths(args.xpath)
@@ -288,7 +294,7 @@ def __common_args_handler(parser):
288294
parser.add_argument("netloc", help="<host>:<port>", type=str)
289295
parser.add_argument(
290296
"-os",
291-
help="OS to use.",
297+
help="OS wrapper to utilize. Defaults to IOS XR.",
292298
type=str,
293299
default="IOS XR",
294300
choices=list(ClientBuilder.os_class_map.keys()),
@@ -303,10 +309,10 @@ def __common_args_handler(parser):
303309
parser.add_argument("-ssl_target_override", help="gRPC SSL target override option.")
304310
parser.add_argument(
305311
"-auto_ssl_target_override",
306-
help="Root certificates for secure connection.",
312+
help="Use root_certificates first CN as grpc.ssl_target_name_override.",
307313
action="store_true",
308314
)
309-
parser.add_argument("-debug", help="Print debug messages", action="store_true")
315+
parser.add_argument("-debug", help="Print debug messages.", action="store_true")
310316
args = parser.parse_args(sys.argv[2:])
311317
logging.basicConfig(level=logging.DEBUG if args.debug else logging.INFO)
312318
args.username = input("Username: ")

0 commit comments

Comments
 (0)