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

Docs: Add `pki verify` and adopt TLS certificate troubleshooting

This commit is contained in:
Michael Friedrich 2020-02-17 18:17:09 +01:00
parent 6f263a4922
commit a37472c479
3 changed files with 153 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/11-cli-commands.md
View File

@ -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 <command> [<arguments>]
@ -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

209
doc/15-troubleshooting.md
View File

@ -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 <a id="troubleshooting-certificate-verification-print"></a>
Pass the certificate file to the `--cert` CLI command parameter to print its details.
This prints a shorter version of `openssl x509 -in <file> -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 <a id="troubleshooting-certificate-verification-print-verify-ca"></a>
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 <a id="troubleshooting-certificate-verification-signed-by-ca"></a>
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) <a id="troubleshooting-certificate-verification-common-name-match"></a>
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 <a id="troubleshooting-certificate-signing"></a>
Icinga offers two methods:

3
doc/16-upgrading-icinga-2.md
View File

@ -10,6 +10,9 @@ follow the instructions for v2.7 too.
## Upgrading to v2.12 <a id="upgrading-to-2-12"></a>
* CLI
* New `pki verify` CLI command for better [TLS certificate troubleshooting](15-troubleshooting.md#troubleshooting-certificate-verification)
### Behavior changes <a id="upgrading-to-2-12-behavior-changes"></a>
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.