Skip to content

Commit cda0412

Browse files
remingtoncremingtonc
authored
Merge pull request #1 from cisco-ie/readme-docs
Improve README documentation
2 parents 52dcbf2 + cdbdedd commit cda0412

File tree

1 file changed

+229
-13
lines changed

1 file changed

+229
-13
lines changed

‎README.md‎

Lines changed: 229 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,242 @@
11
# gNMI - gRPC Network Management Interface
2-
3-
This repository contains reference Go implementations for gNMI.
2+
> Reference Go implementations for gNMI, a service defining an interface for a network management system to interact with a network element.
43
54
**Note:** This is not an official Google product.
65

76
The implementations include:
87

9-
- client library implementation using `gnmi.proto`
8+
- Client library implementation using `gnmi.proto`
109
- CLI for interacting with a gNMI service
11-
- Caching collector that connects to multiple gNMI targets and makes the data
12-
available over a single gNMI Subscribe RPC to clients
10+
- Caching collector which connects to multiple gNMI targets and makes the data available over a single gNMI Subscribe RPC to clients
1311

14-
## Installing
12+
## Client Library
13+
The main entry point for using the client libraries is in
14+
`github.com/openconfig/gnmi/client`.
1515

16-
To install the CLI, run
16+
See [godoc pages](https://godoc.org/github.com/openconfig/gnmi/client) for documentation and usage examples.
1717

18-
go get -u github.com/openconfig/gnmi/cmd/gnmi_cli
18+
## CLI
19+
The CLI provides reference gNMI functionality for verification against server implementations. For a complete list of arguments, run `gnmi_cli -h`.
1920

20-
## Client libraries
21+
```
22+
./gnmi_cli -h
23+
Usage of ./gnmi_cli:
24+
-a value
25+
Short for address.
26+
-address value
27+
Address of the GNMI target to query.
28+
-alsologtostderr
29+
log to standard error as well as files
30+
-c uint
31+
Short for count.
32+
-ca_crt string
33+
CA certificate file. Used to verify server TLS certificate.
34+
-capabilities
35+
When set, CLI will perform a Capabilities request. Usage: gnmi_cli -capabilities [-proto <gnmi.CapabilityRequest>] -address <address> [other flags ...]
36+
-client_crt string
37+
Client certificate file. Used for client certificate-based authentication.
38+
-client_key string
39+
Client private key file. Used for client certificate-based authentication.
40+
-client_types value
41+
List of explicit client types to attempt, one of: gnmi. (default gnmi)
42+
-count uint
43+
Number of polling/streaming events (0 is infinite).
44+
-d string
45+
Short for delimiter. (default "/")
46+
-delimiter string
47+
Delimiter between path nodes in query. Must be a single UTF-8 code point. (default "/")
48+
-display_indent string
49+
Output line, per nesting-level indent. (default " ")
50+
-display_prefix string
51+
Per output line prefix.
52+
-display_size
53+
Display the total size of query response.
54+
-display_type string
55+
Display output type (g, group, s, single, p, proto). (default "group")
56+
-ds
57+
Short for display_size.
58+
-dt string
59+
Short for display_type. (default "group")
60+
-get
61+
When set, CLI will perform a Get request. Usage: gnmi_cli -get -proto <gnmi.GetRequest> -address <address> [other flags ...]
62+
-insecure
63+
When set, CLI will not verify the server certificate during TLS handshake.
64+
-l Short for latency.
65+
-latency
66+
Display the latency for receiving each update (Now - update timestamp).
67+
-log_backtrace_at value
68+
when logging hits line file:N, emit a stack trace
69+
-log_dir string
70+
If non-empty, write log files in this directory
71+
-logtostderr
72+
log to standard error instead of files
73+
-p string
74+
Short for request proto.
75+
-pi duration
76+
Short for polling_interval. (default 30s)
77+
-polling_interval duration
78+
Interval at which to poll in seconds if polling is specified for query_type. (default 30s)
79+
-proto string
80+
Text proto for gNMI request.
81+
-q value
82+
Short for query.
83+
-qt string
84+
Short for query_type. (default "once")
85+
-query value
86+
Comma separated list of queries. Each query is a delimited list of OpenConfig path nodes which may also be specified as a glob (*). The delimeter can be specified with the --delimiter flag.
87+
-query_type string
88+
Type of result, one of: (o, once, p, polling, s, streaming). (default "once")
89+
-sd duration
90+
Short for streaming_duration.
91+
-server_name string
92+
When set, CLI will use this hostname to verify server certificate during TLS handshake.
93+
-set
94+
When set, CLI will perform a Set request. Usage: gnmi_cli -set -proto <gnmi.SetRequest> -address <address> [other flags ...]
95+
-stderrthreshold value
96+
logs at or above this threshold go to stderr
97+
-streaming_duration duration
98+
Length of time to collect streaming queries (0 is infinite).
99+
-t string
100+
Short for target.
101+
-target string
102+
Name of the gNMI target.
103+
-timeout duration
104+
Terminate query if no RPC is established within the timeout duration. (default 30s)
105+
-timestamp string
106+
Specify timestamp formatting in output. One of (<empty string>, on, raw, <FORMAT>) where <empty string> is disabled, on is human readable, raw is int64 nanos since epoch, and <FORMAT> is according to golang time.Format(<FORMAT>)
107+
-ts string
108+
Short for timestamp.
109+
-u Short for updates_only.
110+
-updates_only
111+
Only stream updates, not the initial sync. Setting this flag for once or polling queries will cause nothing to be returned.
112+
-v value
113+
log level for V logs
114+
-vmodule value
115+
comma-separated list of pattern=N settings for file-filtered logging
116+
-with_user_pass
117+
When set, CLI will prompt for username/password to use when connecting to a target.
118+
```
21119

22-
The main entry point for using the client libraries is in
23-
`github.com/openconfig/gnmi/client`.
120+
### Installation
121+
To install the CLI, run:
122+
123+
```bash
124+
go get -u github.com/openconfig/gnmi/cmd/gnmi_cli
125+
```
126+
127+
### Authentication
128+
* `-with_user_pass` will prompt the user at runtime for authentication credentials.
129+
130+
### Proto Specification
131+
The gNMI CLI client can consume a textual proto format which is useful when testing.
132+
133+
`subscribe_interfaces.proto.txt`
134+
```proto
135+
subscribe: <
136+
prefix: <>
137+
subscription: <
138+
path: <
139+
elem: <
140+
name: "interfaces"
141+
>
142+
elem: <
143+
name: "interface"
144+
>
145+
>
146+
mode: SAMPLE
147+
sample_interval: 30000000000
148+
>
149+
mode: STREAM
150+
encoding: PROTO
151+
>
152+
```
153+
154+
### Examples
155+
156+
```bash
157+
gnmi_cli -address 127.0.0.1:57400 -insecure -with_user_pass -qt s -proto "$(cat subscribe_interfaces.proto.txt)"`
158+
```
159+
160+
## Caching Collector
161+
The Caching Collector is a reference collector implementation which may connect to multiple gNMI targets and make the data available over a single gNMI Subscribe RPC to clients. For a complete list of arguments, run `gnmi_collector -h`.
162+
163+
```
164+
./gnmi_collector -h
165+
Usage of ./gnmi_collector:
166+
-alsologtostderr
167+
log to standard error as well as files
168+
-cert_file string
169+
File path for TLS certificate.
170+
-config_file string
171+
File path for collector configuration.
172+
-dial_timeout duration
173+
Timeout for dialing a connection to a target. (default 1m0s)
174+
-key_file string
175+
File path for TLS key.
176+
-log_backtrace_at value
177+
when logging hits line file:N, emit a stack trace
178+
-log_dir string
179+
If non-empty, write log files in this directory
180+
-logtostderr
181+
log to standard error instead of files
182+
-metadata_update_period duration
183+
Period for target metadata update. 0 disables updates.
184+
-port int
185+
server port
186+
-size_update_period duration
187+
Period for updating the target size in metadata. 0 disables updates.
188+
-stderrthreshold value
189+
logs at or above this threshold go to stderr
190+
-v value
191+
log level for V logs
192+
-vmodule value
193+
comma-separated list of pattern=N settings for file-filtered logging
194+
```
195+
196+
### Installation
197+
To install the Collector, run:
198+
199+
```bash
200+
go get -u github.com/openconfig/gnmi/cmd/gnmi_collector
201+
```
202+
### Configuration
203+
Configuration is specified with a textual proto format.
204+
205+
`example.cfg`
206+
```proto
207+
request: <
208+
key: "interfaces"
209+
value: <
210+
subscribe: <
211+
prefix: <
212+
origin: "openconfig"
213+
>
214+
subscription: <
215+
path: <
216+
elem: <
217+
name: "interfaces"
218+
>
219+
>
220+
>
221+
>
222+
>
223+
>
224+
target: <
225+
key: "target1"
226+
value: <
227+
addresses: "127.0.0.1:9998"
228+
credentials: <
229+
username: "username"
230+
password: "password"
231+
>
232+
request: "interfaces"
233+
>
234+
>
235+
```
236+
237+
### Examples
238+
After starting a collector, you should be able to use other gNMI clients to retrieve information from the collector by connecting to the specified port.
24239

25-
See [godoc pages](https://godoc.org/github.com/openconfig/gnmi/client) for
26-
documentation and usage examples.
240+
```bash
241+
gnmi_collector -config_file example.cfg -cert_file cert.pem -key_file key.pem -port 8888 -alsologtostderr
242+
```

0 commit comments

Comments
 (0)