diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md index 7eac4247c..0e7175b36 100644 --- a/doc/11-cli-commands.md +++ b/doc/11-cli-commands.md @@ -38,6 +38,7 @@ Supported commands: * pki save-cert (saves another Icinga 2 instance's certificate) * pki sign-csr (signs a CSR) * pki ticket (generates a ticket) + * pki verify (verify TLS certificates: CN, signed by CA, is CA; Print certificate) * variable get (gets a variable) * variable list (lists all variables) @@ -570,7 +571,7 @@ You will need them in the [distributed monitoring chapter](06-distributed-monito ``` # icinga2 pki --help -icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0) +icinga2 - The Icinga 2 network monitoring daemon (version: v2.12.0) Usage: icinga2 [] @@ -582,6 +583,7 @@ Supported commands: * pki save-cert (saves another Icinga 2 instance's certificate) * pki sign-csr (signs a CSR) * pki ticket (generates a ticket) + * pki verify (verify TLS certificates: CN, signed by CA, is CA; Print certificate) Global options: -h [ --help ] show this help message diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md index 19d9f85d4..fdb29570f 100644 --- a/doc/15-troubleshooting.md +++ b/doc/15-troubleshooting.md @@ -1032,94 +1032,179 @@ Print the CA and client certificate and ensure that the following attributes are * v3 extensions must set the basic constraint for `CA:TRUE` (ca.crt) or `CA:FALSE` (client certificate). * Subject Alternative Name is set to the resolvable DNS name (required for REST API and browsers). - Navigate into the local certificate store: ``` $ cd /var/lib/icinga2/certs/ ``` -Print the CA certificate: +Make sure to verify the agents' certificate and its stored `ca.crt` in `/var/lib/icinga2/certs` and ensure that +all instances (master, satellite, agent) are signed by the **same CA**. + +Compare the `ca.crt` file from the agent node and compare it to your master's `ca.crt` file. + + +Since 2.12, you can use the built-in CLI command `pki verify` to perform TLS certificate validation tasks. + +> **Hint** +> +> The CLI command uses exit codes aligned to the [Plugin API specification](05-service-monitoring.md#service-monitoring-plugin-api). +> Run the commands followed with `echo $?` to see the exit code. + +These CLI commands can be used on Windows agents too without requiring the OpenSSL binary. + +#### Print TLS Certificate + +Pass the certificate file to the `--cert` CLI command parameter to print its details. +This prints a shorter version of `openssl x509 -in -text`. ``` -$ openssl x509 -in ca.crt -text +$ icinga2 pki verify --cert icinga2-agent2.localdomain.crt -Certificate: - Data: - Version: 3 (0x2) - Serial Number: 1 (0x1) - Signature Algorithm: sha256WithRSAEncryption - Issuer: CN=Icinga CA - Validity - Not Before: Feb 23 14:45:32 2016 GMT - Not After : Feb 19 14:45:32 2031 GMT - Subject: CN=Icinga CA - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - Public-Key: (4096 bit) - Modulus: -... - Exponent: 65537 (0x10001) - X509v3 extensions: - X509v3 Basic Constraints: critical - CA:TRUE - Signature Algorithm: sha256WithRSAEncryption -... +information/cli: Printing certificate 'icinga2-agent2.localdomain.crt' + + Version: 3 + Subject: CN = icinga2-agent2.localdomain + Issuer: CN = Icinga CA + Valid From: Feb 14 11:29:36 2020 GMT + Valid Until: Feb 10 11:29:36 2035 GMT + Serial: 12:fe:a6:22:f5:e3:db:a2:95:8e:92:b2:af:1a:e3:01:44:c4:70:e0 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: icinga2-agent2.localdomain + Fingerprint: 40 98 A0 77 58 4F CA D1 05 AC 18 53 D7 52 8D D7 9C 7F 5A 23 B4 AF 63 A4 92 9D DC FF 89 EF F1 4C ``` -Print the client public certificate: +You can also print the `ca.crt` certificate without any further checks using the `--cert` parameter. + +#### Print and Verify CA Certificate + +The `--cacert` CLI parameter allows to check whether the given certificate file is a public CA certificate. ``` -$ openssl x509 -in icinga2-agent1.localdomain.crt -text +$ icinga2 pki verify --cacert ca.crt -Certificate: - Data: - Version: 3 (0x2) - Serial Number: - 86:47:44:65:49:c6:65:6b:5e:6d:4f:a5:fe:6c:76:05:0b:1a:cf:34 - Signature Algorithm: sha256WithRSAEncryption - Issuer: CN=Icinga CA - Validity - Not Before: Aug 20 16:20:05 2016 GMT - Not After : Aug 17 16:20:05 2031 GMT - Subject: CN=icinga2-agent1.localdomain - Subject Public Key Info: - Public Key Algorithm: rsaEncryption - Public-Key: (4096 bit) - Modulus: -... - Exponent: 65537 (0x10001) - X509v3 extensions: - X509v3 Basic Constraints: critical - CA:FALSE - X509v3 Subject Alternative Name: - DNS:icinga2-agent1.localdomain - Signature Algorithm: sha256WithRSAEncryption -... +information/cli: Checking whether certificate 'ca.crt' is a valid CA certificate. + + Version: 3 + Subject: CN = Icinga CA + Issuer: CN = Icinga CA + Valid From: Jul 31 12:26:08 2019 GMT + Valid Until: Jul 27 12:26:08 2034 GMT + Serial: 89:fe:d6:12:66:25:3a:c5:07:c1:eb:d4:e6:f2:df:ca:13:6e:dc:e7 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: + Fingerprint: 9A 11 29 A8 A3 89 F8 56 30 1A E4 0A B2 6B 28 46 07 F0 14 17 BD 19 A4 FC BD 41 40 B5 1A 8F BF 20 + +information/cli: OK: CA certificate file 'ca.crt' was verified successfully. ``` -Make sure to verify the client's certificate and its received `ca.crt` in `/var/lib/icinga2/certs` and ensure that -both instances are signed by the **same CA**. +In case you pass a wrong certificate, an error is shown and the exit code is `2` (Critical). ``` -$ openssl verify -verbose -CAfile /var/lib/icinga2/certs/ca.crt /var/lib/icinga2/certs/icinga2-master1.localdomain.crt +$ icinga2 pki verify --cacert icinga2-agent2.localdomain.crt -icinga2-master1.localdomain.crt: OK +information/cli: Checking whether certificate 'icinga2-agent2.localdomain.crt' is a valid CA certificate. + + Version: 3 + Subject: CN = icinga2-agent2.localdomain + Issuer: CN = Icinga CA + Valid From: Feb 14 11:29:36 2020 GMT + Valid Until: Feb 10 11:29:36 2035 GMT + Serial: 12:fe:a6:22:f5:e3:db:a2:95:8e:92:b2:af:1a:e3:01:44:c4:70:e0 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: icinga2-agent2.localdomain + Fingerprint: 40 98 A0 77 58 4F CA D1 05 AC 18 53 D7 52 8D D7 9C 7F 5A 23 B4 AF 63 A4 92 9D DC FF 89 EF F1 4C + +critical/cli: CRITICAL: The file 'icinga2-agent2.localdomain.crt' does not seem to be a CA certificate file. ``` -``` -$ openssl verify -verbose -CAfile /var/lib/icinga2/certs/ca.crt /var/lib/icinga2/certs/icinga2-agent1.localdomain.crt +#### Verify Certificate is signed by CA Certificate -icinga2-agent1.localdomain.crt: OK -``` - -Fetch the `ca.crt` file from the client node and compare it to your master's `ca.crt` file: +Pass the certificate file to the `--cert` CLI parameter, and the `ca.crt` file to the `--cacert` parameter. +Common troubleshooting scenarios involve self-signed certificates and untrusted agents resulting in disconnects. ``` -$ scp icinga2-agent1:/var/lib/icinga2/certs/ca.crt test-client-ca.crt -$ diff -ur /var/lib/icinga2/certs/ca.crt test-client-ca.crt +$ icinga2 pki verify --cert icinga2-agent2.localdomain.crt --cacert ca.crt + +information/cli: Verifying certificate 'icinga2-agent2.localdomain.crt' + + Version: 3 + Subject: CN = icinga2-agent2.localdomain + Issuer: CN = Icinga CA + Valid From: Feb 14 11:29:36 2020 GMT + Valid Until: Feb 10 11:29:36 2035 GMT + Serial: 12:fe:a6:22:f5:e3:db:a2:95:8e:92:b2:af:1a:e3:01:44:c4:70:e0 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: icinga2-agent2.localdomain + Fingerprint: 40 98 A0 77 58 4F CA D1 05 AC 18 53 D7 52 8D D7 9C 7F 5A 23 B4 AF 63 A4 92 9D DC FF 89 EF F1 4C + +information/cli: with CA certificate 'ca.crt'. + + Version: 3 + Subject: CN = Icinga CA + Issuer: CN = Icinga CA + Valid From: Jul 31 12:26:08 2019 GMT + Valid Until: Jul 27 12:26:08 2034 GMT + Serial: 89:fe:d6:12:66:25:3a:c5:07:c1:eb:d4:e6:f2:df:ca:13:6e:dc:e7 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: + Fingerprint: 9A 11 29 A8 A3 89 F8 56 30 1A E4 0A B2 6B 28 46 07 F0 14 17 BD 19 A4 FC BD 41 40 B5 1A 8F BF 20 + +information/cli: OK: Certificate with CN 'icinga2-agent2.localdomain' is signed by CA. ``` +#### Verify Certificate matches Common Name (CN) + +This allows to verify the common name inside the certificate with a given string parameter. +Typical troubleshooting involve upper/lower case CNs (Windows). + +``` +$ icinga2 pki verify --cert icinga2-agent2.localdomain.crt --cn icinga2-agent2.localdomain + +information/cli: Verifying common name (CN) 'icinga2-agent2.localdomain in certificate 'icinga2-agent2.localdomain.crt'. + + Version: 3 + Subject: CN = icinga2-agent2.localdomain + Issuer: CN = Icinga CA + Valid From: Feb 14 11:29:36 2020 GMT + Valid Until: Feb 10 11:29:36 2035 GMT + Serial: 12:fe:a6:22:f5:e3:db:a2:95:8e:92:b2:af:1a:e3:01:44:c4:70:e0 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: icinga2-agent2.localdomain + Fingerprint: 40 98 A0 77 58 4F CA D1 05 AC 18 53 D7 52 8D D7 9C 7F 5A 23 B4 AF 63 A4 92 9D DC FF 89 EF F1 4C + +information/cli: OK: CN 'icinga2-agent2.localdomain' matches certificate CN 'icinga2-agent2.localdomain'. +``` + +In the example below, the certificate uses an upper case CN. + +``` +$ icinga2 pki verify --cert icinga2-agent2.localdomain.crt --cn icinga2-agent2.localdomain + +information/cli: Verifying common name (CN) 'icinga2-agent2.localdomain in certificate 'icinga2-agent2.localdomain.crt'. + + Version: 3 + Subject: CN = ICINGA2-agent2.localdomain + Issuer: CN = Icinga CA + Valid From: Feb 14 11:29:36 2020 GMT + Valid Until: Feb 10 11:29:36 2035 GMT + Serial: 12:fe:a6:22:f5:e3:db:a2:95:8e:92:b2:af:1a:e3:01:44:c4:70:e0 + + Signature Algorithm: sha256WithRSAEncryption + Subject Alt Names: ICINGA2-agent2.localdomain + Fingerprint: 40 98 A0 77 58 4F CA D1 05 AC 18 53 D7 52 8D D7 9C 7F 5A 23 B4 AF 63 A4 92 9D DC FF 89 EF F1 4C + +critical/cli: CRITICAL: CN 'icinga2-agent2.localdomain' does NOT match certificate CN 'icinga2-agent2.localdomain'. +``` + + + ### Certificate Signing Icinga offers two methods: diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md index 7d18fed58..1a6cb338d 100644 --- a/doc/16-upgrading-icinga-2.md +++ b/doc/16-upgrading-icinga-2.md @@ -10,6 +10,9 @@ follow the instructions for v2.7 too. ## Upgrading to v2.12 +* CLI + * New `pki verify` CLI command for better [TLS certificate troubleshooting](15-troubleshooting.md#troubleshooting-certificate-verification) + ### Behavior changes The behavior of multi parent [dependencies](03-monitoring-basics.md#dependencies) was fixed to e.g. render hosts unreachable when both router uplinks are down.