tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7381 from Icinga/feature/docs-tls 

Refine the term 'TLS' instead of 'SSL'
This commit is contained in:
Michael Friedrich 2019-08-01 09:43:10 +02:00 committed by GitHub
parent 82a5025ad6 3562e92173
commit 924b0c6f24
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 27 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/08-advanced-topics.md
View File

@ -543,7 +543,7 @@ Database | PostgreSQL | [postgres](10-icinga-template-library.md#plugin-contri
Database | Housekeeping | Check the database size and growth and analyse metrics to examine trends. Database | Housekeeping | Check the database size and growth and analyse metrics to examine trends.
Database | DB IDO | [ido](10-icinga-template-library.md#itl-icinga-ido) (more below) Database | DB IDO | [ido](10-icinga-template-library.md#itl-icinga-ido) (more below)
Webserver | Apache2, Nginx, etc. | [http](10-icinga-template-library.md#plugin-check-command-http), [apache-status](10-icinga-template-library.md#plugin-contrib-command-apache-status), [nginx_status](10-icinga-template-library.md#plugin-contrib-command-nginx_status) Webserver | Apache2, Nginx, etc. | [http](10-icinga-template-library.md#plugin-check-command-http), [apache-status](10-icinga-template-library.md#plugin-contrib-command-apache-status), [nginx_status](10-icinga-template-library.md#plugin-contrib-command-nginx_status)
Webserver | Certificates | [http](10-icinga-template-library.md#plugin-check-command-http) Webserver | Certificates | [http](10-icinga-template-library.md#plugin-check-command-http), [Icinga certificate monitoring](https://icinga.com/products/icinga-certificate-monitoring/)
Webserver | Authorization | [http](10-icinga-template-library.md#plugin-check-command-http) Webserver | Authorization | [http](10-icinga-template-library.md#plugin-check-command-http)
Notifications | Mail (queue) | [smtp](10-icinga-template-library.md#plugin-check-command-smtp), [mailq](10-icinga-template-library.md#plugin-check-command-mailq) Notifications | Mail (queue) | [smtp](10-icinga-template-library.md#plugin-check-command-smtp), [mailq](10-icinga-template-library.md#plugin-check-command-mailq)
Notifications | SMS (GSM modem) | [check_sms3_status](https://exchange.icinga.com/netways/check_sms3status) Notifications | SMS (GSM modem) | [check_sms3_status](https://exchange.icinga.com/netways/check_sms3status)
@ -578,7 +578,10 @@ apply Service "ido-mysql" {
More specific database queries can be found in the [DB IDO](14-features.md#db-ido) chapter. More specific database queries can be found in the [DB IDO](14-features.md#db-ido) chapter.
Distributed setups should include specific [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks). Distributed setups should include specific [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks).
You might also want to add additional checks for SSL certificate expiration.
You might also want to add additional checks for TLS certificate expiration.
This can be done using the [Icinga certificate monitoring](https://icinga.com/products/icinga-certificate-monitoring/) module.
## Advanced Configuration Hints <a id="advanced-configuration-hints"></a> ## Advanced Configuration Hints <a id="advanced-configuration-hints"></a>

8
doc/12-icinga2-api.md
View File

@ -2400,7 +2400,7 @@ $ vim icinga.py
import requests, json import requests, json
# Replace 'localhost' with your FQDN and certificate CN # Replace 'localhost' with your FQDN and certificate CN
# for SSL verification # for TLS verification
request_url = "https://localhost:5665/v1/objects/services" request_url = "https://localhost:5665/v1/objects/services"
headers = { headers = {
'Accept': 'application/json', 'Accept': 'application/json',
@ -2444,7 +2444,7 @@ $ vim icinga.rb
require 'rest_client' require 'rest_client'
# Replace 'localhost' with your FQDN and certificate CN # Replace 'localhost' with your FQDN and certificate CN
# for SSL verification # for TLS verification
request_url = "https://localhost:5665/v1/objects/services" request_url = "https://localhost:5665/v1/objects/services"
headers = { headers = {
"Accept" => "application/json", "Accept" => "application/json",
@ -2491,7 +2491,7 @@ $ vim icinga.php
#!/usr/bin/env php #!/usr/bin/env php
<?php <?php
# Replace 'localhost' with your FQDN and certificate CN # Replace 'localhost' with your FQDN and certificate CN
# for SSL verification # for TLS verification
$request_url = "https://localhost:5665/v1/objects/services"; $request_url = "https://localhost:5665/v1/objects/services";
$username = "root"; $username = "root";
$password = "icinga"; $password = "icinga";
@ -2556,7 +2556,7 @@ use JSON;
use Data::Dumper; use Data::Dumper;
# Replace 'localhost' with your FQDN and certificate CN # Replace 'localhost' with your FQDN and certificate CN
# for SSL verification # for TLS verification
my $request_host = "https://localhost:5665"; my $request_host = "https://localhost:5665";
my $userpass = "root:icinga"; my $userpass = "root:icinga";

2
doc/14-features.md
View File

@ -386,7 +386,7 @@ apply Service "disk" for (disk => attributes in host.vars.disks) {
} }
``` ```
This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated This is a typical pattern for checking individual disks, NICs, TLS certificates etc associated
with a host. What would be useful is to have the data points tagged with the specific instance with a host. What would be useful is to have the data points tagged with the specific instance
for that check. This would allow you to query time series data for a check on a host and for a for that check. This would allow you to query time series data for a check on a host and for a
specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables: specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables:

34
doc/15-troubleshooting.md
View File

@ -1075,25 +1075,6 @@ Not valid before: Jul 12 07:39:55 2019 GMT
Not valid after: Jul 8 07:39:55 2034 GMT Not valid after: Jul 8 07:39:55 2034 GMT
``` ```
### Certificate Problems with OpenSSL 1.1.0 <a id="troubleshooting-certificate-openssl-1-1-0"></a>
Users have reported problems with SSL certificates inside a distributed monitoring setup when they
* updated their Icinga 2 package to 2.7.0 on Windows or
* upgraded their distribution which included an update to OpenSSL 1.1.0.
Example during startup on a Windows client:
```
critical/SSL: Error loading and verifying locations in ca key file 'C:\ProgramData\icinga2\etc/icinga2/pki/ca.crt': 219029726, "error:0D0E20DE:asn1 encoding routines:c2i_ibuf:illegal zero content"
critical/config: Error: Cannot make SSL context for cert path: 'C:\ProgramData\icinga2\etc/icinga2/pki/client.crt' key path: 'C:\ProgramData\icinga2\etc/icinga2/pki/client.key' ca path: 'C:\ProgramData\icinga2\etc/icinga2/pki/ca.crt'.
```
A technical analysis and solution for re-creating the public CA certificate is
available in [this advisory](https://icinga.com/2017/08/30/advisory-for-ssl-problems-with-leading-zeros-on-openssl-1-1-0/).
## Cluster and Clients Troubleshooting <a id="troubleshooting-cluster"></a> ## Cluster and Clients Troubleshooting <a id="troubleshooting-cluster"></a>
This applies to any Icinga 2 node in a [distributed monitoring setup](06-distributed-monitoring.md#distributed-monitoring-scenarios). This applies to any Icinga 2 node in a [distributed monitoring setup](06-distributed-monitoring.md#distributed-monitoring-scenarios).
@ -1125,12 +1106,12 @@ works (default port is `5665`).
# nmap icinga2-agent1.localdomain # nmap icinga2-agent1.localdomain
``` ```
### Cluster Troubleshooting SSL Errors <a id="troubleshooting-cluster-ssl-errors"></a> ### Cluster Troubleshooting TLS Errors <a id="troubleshooting-cluster-tls-errors"></a>
If the cluster communication fails with SSL error messages, make sure to check If the cluster communication fails with TLS/SSL error messages, make sure to check
the following the following
* File permissions on the SSL certificate files * File permissions on the TLS certificate files
* Does the used CA match for all cluster endpoints? * Does the used CA match for all cluster endpoints?
* Verify the `Issuer` being your trusted CA * Verify the `Issuer` being your trusted CA
* Verify the `Subject` containing your endpoint's common name (CN) * Verify the `Subject` containing your endpoint's common name (CN)
@ -1151,7 +1132,7 @@ If the connection attempt fails or your CA does not match, [verify the certifica
#### Cluster Troubleshooting Unauthenticated Clients <a id="troubleshooting-cluster-unauthenticated-clients"></a> #### Cluster Troubleshooting Unauthenticated Clients <a id="troubleshooting-cluster-unauthenticated-clients"></a>
Unauthenticated nodes are able to connect. This is required for client setups. Unauthenticated nodes are able to connect. This is required for agent/satellite setups.
Master: Master:
@ -1159,13 +1140,14 @@ Master:
[2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga2-agent1.localdomain' (unauthenticated) [2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga2-agent1.localdomain' (unauthenticated)
``` ```
Client as command execution bridge: Agent as command execution bridge:
``` ```
[2015-07-13 18:29:26 +1000] notice/ClusterEvents: Discarding 'execute command' message from 'icinga2-master1.localdomain': Invalid endpoint origin (client not allowed). [2015-07-13 18:29:26 +1000] notice/ClusterEvents: Discarding 'execute command' message from 'icinga2-master1.localdomain': Invalid endpoint origin (client not allowed).
``` ```
If these messages do not go away, make sure to [verify the master and client certificates](15-troubleshooting.md#troubleshooting-certificate-verification). If these messages do not go away, make sure to [verify the master and agent certificates](15-troubleshooting.md#troubleshooting-certificate-verification).
### Cluster Troubleshooting Message Errors <a id="troubleshooting-cluster-message-errors"></a> ### Cluster Troubleshooting Message Errors <a id="troubleshooting-cluster-message-errors"></a>
@ -1212,7 +1194,7 @@ If the cluster zones do not sync their configuration, make sure to check the fol
* Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`. * Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`.
** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes. ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes.
** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`. ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones-stage` and copy them to the production directory `/var/lib/icinga2/api/zones` upon successful validation (since v2.11).
* The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener * The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener
[accepts config](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not. [accepts config](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not.

8
doc/19-technical-concepts.md
View File

@ -540,11 +540,11 @@ Each node certificate must be signed by the private CA key.
Note: The following description uses `parent node` and `child node`. Note: The following description uses `parent node` and `child node`.
This also applies to nodes in the same cluster zone. This also applies to nodes in the same cluster zone.
During the connection attempt, an SSL handshake is performed. During the connection attempt, a TLS handshake is performed.
If the public certificate of a child node is not signed by the same If the public certificate of a child node is not signed by the same
CA, the child node is not trusted and the connection will be closed. CA, the child node is not trusted and the connection will be closed.
If the SSL handshake succeeds, the parent node reads the If the TLS handshake succeeds, the parent node reads the
certificate's common name (CN) of the child node and looks for certificate's common name (CN) of the child node and looks for
a local Endpoint object name configuration. a local Endpoint object name configuration.
@ -1085,7 +1085,7 @@ benchmark this when TCP connections are broken and timeouts are encountered.
#### Master Processes Incoming Connection <a id="technical-concepts-tls-network-io-connection-handling-incoming"></a> #### Master Processes Incoming Connection <a id="technical-concepts-tls-network-io-connection-handling-incoming"></a>
* The node starts a new ApiListener, this invokes `AddListener()` * The node starts a new ApiListener, this invokes `AddListener()`
* Setup SSL Context * Setup TLS Context (SslContext)
* Initialize global I/O engine and create a TCP acceptor * Initialize global I/O engine and create a TCP acceptor
* Resolve bind host/port (optional) * Resolve bind host/port (optional)
* Listen on IPv4 and IPv6 * Listen on IPv4 and IPv6
@ -1101,7 +1101,7 @@ benchmark this when TCP connections are broken and timeouts are encountered.
* Loop over all configured zones, exclude global zones and not direct parent/child zones * Loop over all configured zones, exclude global zones and not direct parent/child zones
* Get the endpoints configured in the zones, exclude: local endpoint, no 'host' attribute, already connected or in progress * Get the endpoints configured in the zones, exclude: local endpoint, no 'host' attribute, already connected or in progress
* Call `AddConnection()` * Call `AddConnection()`
* Spawn a new Coroutine after making the SSL context * Spawn a new Coroutine after making the TLS context
* Use the global I/O engine for socket I/O * Use the global I/O engine for socket I/O
* Create TLS stream * Create TLS stream
* Connect to endpoint host/port details * Connect to endpoint host/port details

8
doc/21-development.md
View File

@ -1400,7 +1400,7 @@ This requires at least v2.11.
#### Requirements #### Requirements
OpenSSL 1.0.x doesn't build anymore, so we're explicitly using 1.1.x here. Explicitly use OpenSSL 1.1.x, older versions are out of support.
``` ```
brew install ccache boost cmake bison flex openssl@1.1 mysql-connector-c++ postgresql libpq brew install ccache boost cmake bison flex openssl@1.1 mysql-connector-c++ postgresql libpq
@ -2245,7 +2245,7 @@ After building Icinga 2 yourself, your package build system should at least run
install requirements: install requirements:
* enable the `checker`, `notification` and `mainlog` feature by default * enable the `checker`, `notification` and `mainlog` feature by default
* run 'icinga2 api setup' in order to enable the `api` feature and generate SSL certificates for the node * run 'icinga2 api setup' in order to enable the `api` feature and generate TLS certificates for the node
### Run Icinga 2 <a id="development-package-builds-run-icinga"></a> ### Run Icinga 2 <a id="development-package-builds-run-icinga"></a>
@ -2317,9 +2317,9 @@ The Windows MSI packages are located at https://packages.icinga.com/windows/
#### Requirements <a id="development-package-builds-windows-requirements"></a> #### Requirements <a id="development-package-builds-windows-requirements"></a>
* 32 or 64-bit system * 32 or 64-bit system
* Visual Studio >= 14 2015 * Visual Studio >= 14.1 2017
* CMake >= 2.6 * CMake >= 2.6
* OpenSSL >= 1.0.1 * OpenSSL >= 1.1.1
* Flex and Bison * Flex and Bison
##### Visual Studio ##### Visual Studio

2
doc/23-migrating-from-icinga-1x.md
View File

@ -1553,6 +1553,6 @@ and configuration distribution problems Icinga 1.x distributed monitoring curren
Icinga 2 implements a new built-in Icinga 2 implements a new built-in
[distributed monitoring architecture](06-distributed-monitoring.md#distributed-monitoring-scenarios), [distributed monitoring architecture](06-distributed-monitoring.md#distributed-monitoring-scenarios),
including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ. including config and check distribution, IPv4/IPv6 support, TLS certificates and zone support for DMZ.
High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay
logs on connection loss ensuring that the event history is kept in sync. logs on connection loss ensuring that the event history is kept in sync.