diff --git a/doc/08-advanced-topics.md b/doc/08-advanced-topics.md index d58558bcb..3d7772d58 100644 --- a/doc/08-advanced-topics.md +++ b/doc/08-advanced-topics.md @@ -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 | 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 | 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) 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) @@ -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. 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 diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index bb84e66b3..ccecc587f 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -2400,7 +2400,7 @@ $ vim icinga.py import requests, json # Replace 'localhost' with your FQDN and certificate CN -# for SSL verification +# for TLS verification request_url = "https://localhost:5665/v1/objects/services" headers = { 'Accept': 'application/json', @@ -2444,7 +2444,7 @@ $ vim icinga.rb require 'rest_client' # Replace 'localhost' with your FQDN and certificate CN -# for SSL verification +# for TLS verification request_url = "https://localhost:5665/v1/objects/services" headers = { "Accept" => "application/json", @@ -2491,7 +2491,7 @@ $ vim icinga.php #!/usr/bin/env php 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 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: diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md index 01c5921bd..66c43aef4 100644 --- a/doc/15-troubleshooting.md +++ b/doc/15-troubleshooting.md @@ -1075,25 +1075,6 @@ Not valid before: Jul 12 07:39:55 2019 GMT Not valid after: Jul 8 07:39:55 2034 GMT ``` - -### Certificate Problems with OpenSSL 1.1.0 - -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 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 ``` -### Cluster Troubleshooting SSL Errors +### Cluster Troubleshooting TLS Errors -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 -* File permissions on the SSL certificate files +* File permissions on the TLS certificate files * Does the used CA match for all cluster endpoints? * Verify the `Issuer` being your trusted CA * 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 -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: @@ -1159,13 +1140,14 @@ Master: [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). ``` -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 @@ -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`. ** 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 [accepts config](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not. diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md index 00eac5c58..61ad03b3e 100644 --- a/doc/19-technical-concepts.md +++ b/doc/19-technical-concepts.md @@ -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`. 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 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 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 * 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 * Resolve bind host/port (optional) * 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 * Get the endpoints configured in the zones, exclude: local endpoint, no 'host' attribute, already connected or in progress * 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 * Create TLS stream * Connect to endpoint host/port details diff --git a/doc/21-development.md b/doc/21-development.md index 55609fba3..82bbe8d6d 100644 --- a/doc/21-development.md +++ b/doc/21-development.md @@ -1400,7 +1400,7 @@ This requires at least v2.11. #### 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 @@ -2245,7 +2245,7 @@ After building Icinga 2 yourself, your package build system should at least run install requirements: * 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 @@ -2317,9 +2317,9 @@ The Windows MSI packages are located at https://packages.icinga.com/windows/ #### Requirements * 32 or 64-bit system -* Visual Studio >= 14 2015 +* Visual Studio >= 14.1 2017 * CMake >= 2.6 -* OpenSSL >= 1.0.1 +* OpenSSL >= 1.1.1 * Flex and Bison ##### Visual Studio diff --git a/doc/23-migrating-from-icinga-1x.md b/doc/23-migrating-from-icinga-1x.md index aaf5e0262..b55d0cc7c 100644 --- a/doc/23-migrating-from-icinga-1x.md +++ b/doc/23-migrating-from-icinga-1x.md @@ -1553,6 +1553,6 @@ and configuration distribution problems Icinga 1.x distributed monitoring curren Icinga 2 implements a new built-in [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 logs on connection loss ensuring that the event history is kept in sync.