From 166bb086062e2dfc96b312488ca4929c80bdfea2 Mon Sep 17 00:00:00 2001 From: Karim Radhouani Date: Sat, 22 Jul 2023 11:38:35 -0700 Subject: [PATCH] add a gNMI target TLS session docs page --- README.md | 2 +- docs/changelog.md | 18 +- ..._with_gnmi_server_and_prometheus_output.md | 4 +- docs/global_flags.md | 2 +- docs/index.md | 2 +- docs/user_guide/configuration_file.md | 2 +- .../target_discovery/consul_discovery.md | 0 .../target_discovery/discovery_intro.md | 0 .../target_discovery/docker_discovery.md | 0 .../target_discovery/file_discovery.md | 3 +- .../target_discovery/http_discovery.md | 0 docs/user_guide/{ => targets}/targets.md | 6 +- .../user_guide/targets/targets_session_sec.md | 176 ++++++++++++++++++ mkdocs.yml | 16 +- 14 files changed, 205 insertions(+), 26 deletions(-) rename docs/user_guide/{ => targets}/target_discovery/consul_discovery.md (100%) rename docs/user_guide/{ => targets}/target_discovery/discovery_intro.md (100%) rename docs/user_guide/{ => targets}/target_discovery/docker_discovery.md (100%) rename docs/user_guide/{ => targets}/target_discovery/file_discovery.md (98%) rename docs/user_guide/{ => targets}/target_discovery/http_discovery.md (100%) rename docs/user_guide/{ => targets}/targets.md (97%) create mode 100644 docs/user_guide/targets/targets_session_sec.md diff --git a/README.md b/README.md index eb2021c0..27a8a607 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Documentation available at [https://gnmic.openconfig.net](https://gnmic.openconf * **gNMI data manipulation** `gnmic` collector has [data transformation](https://gnmic.openconfig.net/user_guide/event_processors/intro/) capabilities that can be used to adapt the collected data to your specific use case. * **Dynamic targets loading** - `gnmic` support [target loading at runtime](https://gnmic.openconfig.net/user_guide/target_discovery/discovery_intro/) based on input from external systems. + `gnmic` support [target loading at runtime](https://gnmic.openconfig.net/user_guide/targets/target_discovery/discovery_intro/) based on input from external systems. * **YANG-based path suggestions** Your CLI magically becomes a YANG browser when `gnmic` is executed in [prompt](https://gnmic.openconfig.net/user_guide/prompt_suggestions/) mode. In this mode the flags that take XPATH values will get auto-suggestions based on the provided YANG modules. In other words - voodoo magic :exploding_head: * **Multi-target operations** diff --git a/docs/changelog.md b/docs/changelog.md index fbbc2c49..74362d06 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -93,7 +93,7 @@ - Loaders - - The [HTTP loader](user_guide/target_discovery/http_discovery.md) now supports different authentication schemas as well as setting a template from a local file. + - The [HTTP loader](user_guide/targets/target_discovery/http_discovery.md) now supports different authentication schemas as well as setting a template from a local file. ### v0.28.0 - December 7th 2022 @@ -198,7 +198,7 @@ - Add gNMI responses constructors - Add gRPC tunnel proto messages constructors -- [Target Discovery](user_guide/target_discovery/discovery_intro.md): +- [Target Discovery](user_guide/targets/target_discovery/discovery_intro.md): - Add the option to transform the loaded targets format using a Go text template for file and HTTP loaders - Poll based target loaders (file, HTTP and docker) now support a startup delay timer @@ -244,7 +244,7 @@ Add the ability to execute processors with Get command flag [`--processor`](cmd/get.md#processor) on GetResponse messages. -- [Target Discovery](user_guide/target_discovery/discovery_intro.md): +- [Target Discovery](user_guide/targets/target_discovery/discovery_intro.md): Add the ability to run [actions](user_guide/actions/actions.md) on target discovery or deletion. @@ -298,23 +298,23 @@ - Target Loaders: - - [HTTP Loader](user_guide/target_discovery/http_discovery.md) + - [HTTP Loader](user_guide/targets/target_discovery/http_discovery.md) gNMIc can now dynamically discover targets from a remote HTTP server. HTTP Loader is now properly instrumented using Prometheus metrics. - - [File Loader](user_guide/target_discovery/file_discovery.md) + - [File Loader](user_guide/targets/target_discovery/file_discovery.md) Supports remote files (ftp, sftp, http(s)) in addition to local file system files. File loader is now properly instrumented using Prometheus metrics. - - [Consul Loader](user_guide/target_discovery/consul_discovery.md) + - [Consul Loader](user_guide/targets/target_discovery/consul_discovery.md) Consul Loader is now properly instrumented using Prometheus metrics. - - [Docker Loader](user_guide/target_discovery/docker_discovery.md) + - [Docker Loader](user_guide/targets/target_discovery/docker_discovery.md) Docker Loader is now properly instrumented using Prometheus metrics. @@ -336,7 +336,7 @@ Add support for [gNMI server](user_guide/outputs/gnmi_output.md) output type -- [Target configuration](user_guide/targets.md): +- [Target configuration](user_guide/targets/targets.md): Support multiple IP addresses per target, all addresses are tried simultaneously. The first successful gRPC connection is used. @@ -366,7 +366,7 @@ - Target Loaders: - [Consul loader](user_guide/target_discovery/consul_discovery.md#services-watch) update: Add support for gNMI target discovery from Consul services. + [Consul loader](user_guide/targets/target_discovery/consul_discovery.md#services-watch) update: Add support for gNMI target discovery from Consul services. - Get Request: diff --git a/docs/deployments/clusters/containerlab/cluster_with_gnmi_server_and_prometheus_output.md b/docs/deployments/clusters/containerlab/cluster_with_gnmi_server_and_prometheus_output.md index ee01a924..83473d9c 100644 --- a/docs/deployments/clusters/containerlab/cluster_with_gnmi_server_and_prometheus_output.md +++ b/docs/deployments/clusters/containerlab/cluster_with_gnmi_server_and_prometheus_output.md @@ -16,8 +16,8 @@ The aggregation `gNMIc` instance exposes a Prometheus output that is registered The whole lab is pretty much self organising: -- The `gNMIc` cluster instances discover the targets dynamically using a [Docker Loader](../../../user_guide/target_discovery/docker_discovery.md) -- The `gNMIc` standalone instance, discovers the cluster instance using a [Consul Loader](../../../user_guide/target_discovery/consul_discovery.md) +- The `gNMIc` cluster instances discover the targets dynamically using a [Docker Loader](../../../user_guide/targets/target_discovery/docker_discovery.md) +- The `gNMIc` standalone instance, discovers the cluster instance using a [Consul Loader](../../../user_guide/targets/target_discovery/consul_discovery.md) - The Prometheus server discovers gNMIc's Prometheus output using [Consul Service Discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#consul_sd_config)
diff --git a/docs/global_flags.md b/docs/global_flags.md index bf81a8ca..84b9c79b 100644 --- a/docs/global_flags.md +++ b/docs/global_flags.md @@ -249,7 +249,7 @@ The skip verify flag `[--skip-verify]` indicates that the target should skip the ### targets-file -The `[--targets-file]` flag is used to configure a [file target loader](user_guide/target_discovery/file_discovery.md) +The `[--targets-file]` flag is used to configure a [file target loader](user_guide/targets/target_discovery/file_discovery.md) ### timeout diff --git a/docs/index.md b/docs/index.md index b05ac405..d870b5ab 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,7 @@ * **gNMI data manipulation** `gnmic` collector supports [data transformation](user_guide/event_processors/intro/) capabilities that can be used to adapt the collected data to your specific use case. * **Dynamic targets loading** - `gnmic` support [target loading at runtime](user_guide/target_discovery/discovery_intro.md) based on input from external systems. + `gnmic` support [target loading at runtime](user_guide/targets/target_discovery/discovery_intro.md) based on input from external systems. * **YANG-based path suggestions** Your CLI magically becomes a YANG browser when `gnmic` is executed in [prompt](user_guide/prompt_suggestions.md) mode. In this mode the flags that take XPATH values will get auto-suggestions based on the provided YANG modules. In other words - voodoo magic :exploding_head: * **Multiple configuration sources** diff --git a/docs/user_guide/configuration_file.md b/docs/user_guide/configuration_file.md index 521c6ba5..97316190 100644 --- a/docs/user_guide/configuration_file.md +++ b/docs/user_guide/configuration_file.md @@ -48,7 +48,7 @@ get-path: /configure/system/name # `get` command local flag Another example: the [`update-path`](../cmd/set.md#1-in-line-update-implicit-type) flag of a [`set`](../cmd/set.md) will be `set-update-path` in the configuration file. #### Targets -It is possible to specify multiple targets with different configurations (credentials, timeout,...). This is described in [Multiple targets](targets.md) documentation article. +It is possible to specify multiple targets with different configurations (credentials, timeout,...). This is described in [Multiple targets](targets/targets.md) documentation article. #### Subscriptions It is possible to specify multiple subscriptions and associate them with different targets in a flexible way. This configuration option is described in [Multiple subscriptions](subscriptions.md) documentation article. diff --git a/docs/user_guide/target_discovery/consul_discovery.md b/docs/user_guide/targets/target_discovery/consul_discovery.md similarity index 100% rename from docs/user_guide/target_discovery/consul_discovery.md rename to docs/user_guide/targets/target_discovery/consul_discovery.md diff --git a/docs/user_guide/target_discovery/discovery_intro.md b/docs/user_guide/targets/target_discovery/discovery_intro.md similarity index 100% rename from docs/user_guide/target_discovery/discovery_intro.md rename to docs/user_guide/targets/target_discovery/discovery_intro.md diff --git a/docs/user_guide/target_discovery/docker_discovery.md b/docs/user_guide/targets/target_discovery/docker_discovery.md similarity index 100% rename from docs/user_guide/target_discovery/docker_discovery.md rename to docs/user_guide/targets/target_discovery/docker_discovery.md diff --git a/docs/user_guide/target_discovery/file_discovery.md b/docs/user_guide/targets/target_discovery/file_discovery.md similarity index 98% rename from docs/user_guide/target_discovery/file_discovery.md rename to docs/user_guide/targets/target_discovery/file_discovery.md index 9528efa0..2e1fa402 100644 --- a/docs/user_guide/target_discovery/file_discovery.md +++ b/docs/user_guide/targets/target_discovery/file_discovery.md @@ -56,11 +56,12 @@ loader: The `--targets-file` flag takes precedence over the `loader` configuration section. The targets file can be either a `YAML` or a `JSON` file (identified by its extension json, yaml or yml), and follows the same format as the main configuration file `targets` section. -See [here](../../user_guide/targets.md#target-option) +See [here](../../../user_guide/targets/targets.md#target-option) ### Examples #### Local File + ``` yaml loader: type: file diff --git a/docs/user_guide/target_discovery/http_discovery.md b/docs/user_guide/targets/target_discovery/http_discovery.md similarity index 100% rename from docs/user_guide/target_discovery/http_discovery.md rename to docs/user_guide/targets/target_discovery/http_discovery.md diff --git a/docs/user_guide/targets.md b/docs/user_guide/targets/targets.md similarity index 97% rename from docs/user_guide/targets.md rename to docs/user_guide/targets/targets.md index df491aba..753f48ed 100644 --- a/docs/user_guide/targets.md +++ b/docs/user_guide/targets/targets.md @@ -2,11 +2,11 @@ Sometimes it is needed to perform an operation on multiple devices; be it getting the same leaf value from a given set of the network elements or setting a certain configuration element to some value. -For cases like that `gnmic` offers support for multiple targets operations which a user can configure both via CLI flags as well as with the [file-based configuration](configuration_file.md). +For cases like that `gnmic` offers support for multiple targets operations which a user can configure both via CLI flags as well as with the [file-based configuration](../configuration_file.md). ### CLI configuration -Specifying multiple targets in the CLI is as easy as repeating the [`--address`](../global_flags.md#address) flag. +Specifying multiple targets in the CLI is as easy as repeating the [`--address`](../../global_flags.md#address) flag. ```shell ❯ gnmic -a router1.lab.net:57400 \ @@ -215,4 +215,4 @@ Consider the `get` command acting on two routers getting their names: [router2.lab.net:57400] } ``` -Notice how in the output the different gNMI targets are prefixed with the target address to make the output easy to read. If those prefixes are not needed, you can make them disappear with [`--no-prefix`](../global_flags.md#no-prefix) global flag. \ No newline at end of file +Notice how in the output the different gNMI targets are prefixed with the target address to make the output easy to read. If those prefixes are not needed, you can make them disappear with [`--no-prefix`](../../global_flags.md#no-prefix) global flag. diff --git a/docs/user_guide/targets/targets_session_sec.md b/docs/user_guide/targets/targets_session_sec.md new file mode 100644 index 00000000..0fa12a8f --- /dev/null +++ b/docs/user_guide/targets/targets_session_sec.md @@ -0,0 +1,176 @@ +# Targets session security + +In line with the guidelines detailed in the [gNMI Specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md#31-session-security-authentication-and-rpc-authorization), it is mandatory to establish an encrypted TLS session between the client and the server. This measure is essential to ensure secure communication within the gNMI protocol. + +```text +The session between the client and server MUST be encrypted using TLS - +and a target or client MUST NOT fall back to unencrypted sessions. +The target and client SHOULD implement TLS >= 1.2. +``` + +`gNMIc` provides the ability to tailor and modify the TLS session parameters of the gNMI client according to your specific requirements. + +## TLS session types + +When it comes to establishing a TLS session using `gNMIc`, various options are available to suit different use cases and environmental requirements. Whether it's a one-way TLS session, a session without certificate validation, or a mutual TLS (mTLS) session, each type caters to specific needs. The selection largely depends on the user's scenario and the degree of security and validation necessary. The upcoming sections will detail each of these session types, offering guidelines to aid in choosing the most appropriate for your specific requirements. + +### Simple TLS session w/o server certificate validation + +For scenarios requiring a simple TLS session without server certificate validation, such as in certain testing or development environments, you can use gNMIc's `--skip-verify` flag or the `skip-verify` attribute. This mode bypasses the typical certificate verification process and establishes a secure connection without validating the server's identity. Please exercise caution when using this feature, as it may expose the connection to potential security vulnerabilities. It is recommended primarily for non-production environments or controlled testing situations. + +=== "cli" + ```shell + gnmic -a router1 --skip-verify \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + skip-verify: true + ``` + +### Simple TLS session with server certificate validation + +When establishing a simple TLS session with server certificate validation for enhanced security, gNMIc offers the --tls-ca flag or the tls-ca attribute. These options allow you to point to a Certificate Authority (CA) certificate file. By doing so, the session not only ensures encrypted communication but also verifies the server's identity through its certificate. This validation process greatly enhances the security of the connection, ensuring the client is communicating with the intended server. It's an advisable setting for production environments where data security and integrity are crucial. + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + ``` + +### Simple TLS session with server certificate validation and server name override + +There are circumstances where the server's identity, as indicated by its certificate, doesn't match its expected hostname. For such scenarios, gNMIc enables the initiation of a simple TLS session with both server certificate validation and server name override. This functionality can be utilized by employing the `--tls-server-name` flag or the `tls-server-name` attribute. + +By overriding the server name in the TLS session, users can specify a different hostname that matches the server's certificate, even if it's not the actual hostname of the server. This allows for successful validation and secure communication even in cases of server name discrepancies due to reasons like load balancing, proxying, etc... + +This feature is particularly beneficial in complex network scenarios or during migrations, where server names might not yet align with their certificates. By ensuring both secure encrypted communication and flexible server name accommodation, it adds an extra layer of adaptability for secure communication, particularly in dynamic or complex network environments. + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + --tls-server-name server1 \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + tls-server-name: server1 + ``` + +### Mutual TLS (mTLS) session + +For heightened security scenarios, gNMIc supports mutual TLS (mTLS) sessions. mTLS not only verifies the server's identity to the client, but also the client's identity to the server. This reciprocal verification is achieved using the --tls-cert and --tls-key flags, or the tls-cert and tls-key attributes. These options allow the user to specify a client certificate and client key, respectively. + +By providing a client certificate (`--tls-cert` or `tls-cert` attribute) and a client key (`--tls-key` or `tls-key` attribute), gNMIc allows the server to confirm the identity of the client, ensuring that the client is legitimate and authorized to access the server resources. + +Mutual TLS is particularly beneficial in use cases where both ends of a connection need to confirm the other's identity, providing a significantly higher level of trust and security. It reduces the risk of man-in-the-middle attacks and is especially valuable in environments where sensitive data is transmitted or strict access control is required. + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + --tls-cert ./router1.cert \ + --tls-key ./router.key \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + tls-cert: ./router1.cert + tls-key: ./router1.key + ``` + +### mTLS session with server name override + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + --tls-server-name server1 \ + --tls-cert ./router1.cert \ + --tls-key ./router.key \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + tls-server-name: server1 + tls-cert: ./router1.cert + tls-key: ./router1.key + ``` + +## Configuring the client's TLS version + +By default, `gNMIc` establishes a TLS session using the Golang's default TLS version (1.2), minimum version (1.2), and maximum version (1.3). + +However, there might be scenarios where users need to control the TLS session negotiation to either test the server behavior or force the session into a specific version. To accommodate these needs, gNMIc provides flexibility by allowing users to explicitly set the TLS version. + +Users can manipulate the negotiated TLS version using the flags (or target attributes) `--tls-version`, `--tls-min-version`, and `--tls-max-version`. These flags give control over the TLS session parameters, facilitating testing and customization of the communication session according to specific requirements. + +Example: Forcing the client and server to use TLS1.3 + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + --tls-cert ./router1.cert \ + --tls-key ./router.key \ + --tls-version 1.3 \ + --tls-min-version 1.3 \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + tls-cert: ./router1.cert + tls-key: ./router1.key + tls-version: 1.3 + tls-min-version: 1.3 + ``` + +## Decrypting gNMI traffic using Wireshark + +To facilitate advanced debugging or network analysis, gNMIc allows for the decryption of gNMI TLS traffic using the popular network protocol analyzer, Wireshark. The `--log-tls-secret` flag is instrumental in achieving this, as it stores the session pre-master secret, which can subsequently be used to decrypt TLS traffic. + +When `--log-tls-secret` is used, the session's pre-master secret will be stored in a file named `.tlssecret.log`. This secret enables Wireshark to decrypt the otherwise secure and encrypted TLS traffic between the client and the server. + +Decryption of TLS traffic is particularly useful for network troubleshooting, performance optimization, or security audits. It allows network administrators or developers to deeply inspect packet data, diagnose network issues, and better understand data flows. However, this practice should be used carefully and ethically, given the sensitive nature of decrypted traffic, especially in production environments. + +=== "cli" + ```shell + gnmic -a router1 --tls-ca ./ca.pem \ + --log-tls-secret \ + --tls-cert ./router1.cert \ + --tls-key ./router.key \ + get --path /interface/oper-state + ``` +=== "file" + ```yaml + targets: + router1: + address: router1 + tls-ca: ./ca.pem + log-tls-secret: true + tls-cert: ./router1.cert + tls-key: ./router1.key + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 117d28b7..fca2a3ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,13 +28,14 @@ nav: - File configuration: user_guide/configuration_file.md - Targets: - - Configuration: user_guide/targets.md + - Configuration: user_guide/targets/targets.md + - Session Security: user_guide/targets/targets_tls.md - Discovery: - - Introduction: user_guide/target_discovery/discovery_intro.md - - File Discovery: user_guide/target_discovery/file_discovery.md - - Consul Discovery: user_guide/target_discovery/consul_discovery.md - - Docker Discovery: user_guide/target_discovery/docker_discovery.md - - HTTP Discovery: user_guide/target_discovery/http_discovery.md + - Introduction: user_guide/targets/target_discovery/discovery_intro.md + - File Discovery: user_guide/targets/target_discovery/file_discovery.md + - Consul Discovery: user_guide/targets/target_discovery/consul_discovery.md + - Docker Discovery: user_guide/targets/target_discovery/docker_discovery.md + - HTTP Discovery: user_guide/targets/target_discovery/http_discovery.md - Subscriptions: user_guide/subscriptions.md @@ -280,7 +281,8 @@ markdown_extensions: - pymdownx.snippets: check_paths: true - pymdownx.superfences - - pymdownx.tabbed + - pymdownx.tabbed: + alternate_style: true - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde