github.com/aristanetworks/goarista@v0.0.0-20240514173732-cca2755bbd44/cmd/gnmireverse_client/README.md (about)

     1  # gNMIReverse client
     2  
     3  The gNMIReverse client is a process that issues gNMI RPCs to a gNMI target
     4  (typically running on the same host as this process) and forwards the
     5  responses to a gNMIReverse server. This can be used to reverse the
     6  dial direction of a gNMI Subscribe or gNMI Get.
     7  
     8  
     9  ## Installation
    10  
    11  * Build the gNMIReverse client and copy the executable to the target device.
    12  
    13  Compiling the client requires Go 1.16 or later. Instructions for installing Go can be
    14  found [here](https://go.dev/doc/install). Once Go is installed you can run:
    15  
    16  ```
    17  GOOS=linux go install github.com/aristanetworks/goarista/cmd/gnmireverse_client@latest
    18  ```
    19  
    20  This will install the `gnmireverse_client` binary in the `$HOME/go/bin` or
    21  `$HOME/go/bin/linux_amd64` directory by default. Run `go help install` for more information.
    22  
    23  
    24  ## Options
    25  
    26  Run the program with the flag `--help` or `-h` to see the full list of options and documentation.
    27  
    28   Option                    | Description
    29  :--------------------------|:-------------------------------------------------------------------------
    30  `username`                 | Username to authenticate with the target (gNMI server).
    31  `password`                 | Password to authenticate with the target (gNMI server).
    32  `credentials_file`         | File containing username and/or password to authenticate with target, in YAML form of:<br/>`username: admin`<br/>`password: pass123`<br/>Credentials specified with `-username` or `-password` take precedence.
    33  `target_addr`              | Address of the gNMI server running on the device.<br/>- Form: `[vrf/]address:port`<br/>- Example: `default/127.0.0.1:6030`, `mgmt/localhost:9339`
    34  `target_value`             | Target name to include in the prefix of all responses to identify the device.
    35  `target_tls_insecure`      | Use TLS connection with the target and do not verify the target certificate. Used if the gNMI server is configured with a TLS certificate and mutual TLS authentication is not enforced.<br/>By default, a plaintext connection is used with the target.
    36  `collector_addr`           | Address of the gNMIReverse server collecting the data.<br/>- Form: `[vrf/]host:port`<br/>- Example: `1.2.3.4:6000`, `mgmt/collector1:10000`
    37  `source_addr`              | Address to use as source in connection to the collector. An IPv6 address must be enclosed in square brackets when specified with a port.<br/>- Form: `ip[:port]` or `:port`<br/>- Example: `10.2.3.4`, `[::1]:1234`, `:1234`
    38  `collector_tls`            | Use TLS connection with the gNMIReverse server.<br/>- Default: `true`
    39  `collector_tls_skipverify` | Do not verify the collector TLS certificate. Used if mutual TLS authentication is not enforced.
    40  `collector_compression`    | Compression method used when streaming to the gNMIReverse server.<br/>- Default: `none`<br/>- Options: `gzip`
    41  `origin`                   | Path origin. Applies to all specified Subscribe/Get paths.
    42  `subscribe`                | Path to subscribe to with `TARGET_DEFINED` mode with an optional heartbeat interval.<br/>Can be repeated multiple times to specify multiple paths.<br/>- Form: `path[@heatbeat_interval]`<br/>- Example: `/system/processes`,`/components/component/state@1m`
    43  `sample`                   | Path to subscribe to with `SAMPLE` mode.<br/>Can be repeated multiple times to specify multiple paths.<br/>- Form: `path@sample_interval`<br/>- Example: `/interfaces/interface/state/counters@30s`
    44  `get`                      | Path to retrieve using a periodic gNMI Get.<br/>Can be repeated multiple times to specify multiple paths.<br/>Arista EOS native origin paths can be specified with the prefix `eos_native:`. This allows for specifying both OpenConfig and EOS native origin paths.<br/>- Example: `/system/memory`, `eos_native:/Sysdb/hardware`
    45  `get_file`                 | File containing a list of paths separated by newlines to retrieve periodically using Get.
    46  `get_sample_interval`      | Interval between periodic Get requests.<br/>- Example: `400ms`, `2.5s`, `1m`
    47  `get_mode`                 | Operation mode to gather notifications for the `GetResponse` message.<br/>- Default: `get`<br/>- Options:<br/>`get` Gather notifications using Get.<br/>`subscribe` Gather notifications using Subscribe. `Notification` messages from the Subscribe sync are bundled into one `GetResponse`. With Subscribe, individual leaf updates and their respective data source timestamps are gathered (instead of a single subtree and one current timestamp with Get).
    48  `v`                        | Log level verbosity. Enables gRPC logging.
    49  
    50  
    51  ## gNMI Subscribe dial-out
    52  
    53  The client requires a gNMI target address to connect to and a
    54  gNMIReverse server to send the subscription results.
    55  
    56  For example, on an Arista EOS device the client can be configured in the CLI:
    57  
    58  ```
    59  daemon gnmireverse
    60     exec /mnt/flash/gnmireverse_client
    61        -username USER
    62        -password PASS
    63        -target_addr=mgmt/127.0.0.1:6030
    64        -collector_addr=mgmt/1.2.3.4:6000
    65        -target_value=device1
    66        -sample interfaces/interface/state/counters@30s
    67        -subscribe network-instances
    68     no shutdown
    69  ```
    70  
    71  * The username and password authenticates with the gNMI server.
    72  * The client is connecting to the gNMI server locally on `127.0.0.1:6030` in the `mgmt` VRF.
    73  * The client is connecting through the `mgmt` VRF to the gNMIReverse server listening on `1.2.3.4:6000`.
    74  * Interface counters sampled every 30 seconds are streamed to the collector.
    75  * Changes as they happen to network-instances config and state are streamed to the collector.
    76  
    77  
    78  ## gNMI Get dial-out
    79  
    80  An example CLI configuration on an Arista EOS device to stream responses using gNMI Get:
    81  
    82  ```
    83  daemon gnmireverse
    84     exec /mnt/flash/gnmireverse_client
    85        -username admin
    86        -password pass
    87        -target_addr=mgmt/127.0.0.1:6030
    88        -collector_addr=mgmt/1.2.3.4:6000
    89        -target_value=device1
    90        -get_sample_interval 10s
    91        -get /interfaces/interface/state/counters
    92        -get /system/memory
    93        -get eos_native:/Sysdb/hardware
    94     no shutdown
    95  ```
    96  
    97  * Every 10 seconds, a gNMI Get is issued to the target to retrieve interface counters and memory state from the OpenConfig paths and Sysdb hardware state from the Arista EOS native path.
    98  * The `GetResponse` from the target is forwarded to the collector via a stream.
    99  * The Get paths can also be specified using a `-get_file` containing:
   100  ```
   101  /interfaces/interface/state/counters
   102  /system/memory
   103  eos_native:/Sysdb/hardware
   104  ```
   105  
   106  ### Get with Subscribe
   107  
   108  By default, a gNMI Get is issued and the resulting `GetResponse` is streamed. For a non-leaf path, Get typically retrieves the entire subtree as a single JSON value along with one timestamp which is of the current time.
   109  
   110  It may be preferable to instead retrieve individual leaf updates under a path. This would be similar to updates received via a Subscribe. The flag `-get_mode subscribe` changes the Get dial-out behavior to retrieve updates using a Subscribe instead of a Get. At each sample interval, `Notification` messages from the Subscribe sync are gathered. All individual leaf updates and their respective data source timestamps are bundled into one `GetResponse` message.
   111  
   112  
   113  ## Collector
   114  
   115  A collector implementing a gNMIReverse server can be installed with:
   116  
   117  ```
   118  go install github.com/aristanetworks/goarista/cmd/gnmireverse_server@latest
   119  ```
   120  Run the program with the flag `--help` or `-h` to see the full list of options.
   121  
   122  
   123  ## gRPC compression
   124  
   125  By default, the gNMIReverse client sends uncompressed gRPC messages to the gNMIReverse server.
   126  For Get RPCs, the message size is typically larger than individual Subscribe messages so usually,
   127  the message is more compressible. As a result, it may be preferable to enable gzip gRPC compression
   128  with `-collector_compression gzip` to lower bandwidth. Ensure that the gNMIReverse server supports
   129  the gzip gRPC compression method. Note that this may cause an increase in CPU load on the target
   130  device due to compression overhead.
   131  
   132  ## gRPC maximum message size
   133  
   134  By default, gRPC limits the maximum incoming message size to 4 MB. For gNMI Get, a large
   135  `GetResponse` can result if many paths are retrieved and/or the data trees are large. As a result,
   136  it is possible for the message to exceed the default maximum size. In these cases, it is necessary
   137  to configure the gNMIReverse server to accept larger message sizes from the gNMIReverse client.
   138  
   139  ## Debugging
   140  
   141  Use `-v 1` or above to enable gRPC logging. This is useful for checking that a connection has
   142  been established with the target and collector.