From 25fb3c876b8ab6d572243fe5919c4b894eb1be4a Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Tue, 18 Jun 2024 15:06:34 +0200 Subject: [PATCH] Doc: Distributed Monitoring: add section "External CA/PKI" The following already works: * Custom key sizes, e.g. 2048 bits * Custom key types, e.g. ECC * Multiple trusted root CAs in `/var/lib/icinga2/certs/ca.crt` * Different root CAs per cluster subtree, as long as each node trusts the issuers of the certificates of all nodes it's directly connected to * Any number of intermediate CAs --- doc/06-distributed-monitoring.md | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/06-distributed-monitoring.md b/doc/06-distributed-monitoring.md index b81f22b4b1..d8d5477c27 100644 --- a/doc/06-distributed-monitoring.md +++ b/doc/06-distributed-monitoring.md @@ -3227,6 +3227,53 @@ information/pki: Writing certificate to file 'icinga2-satellite1.localdomain.crt Copy and move these certificates to the respective instances e.g. with SSH/SCP. +#### External CA/PKI + +Icinga works best with its own certificates. +The commands described above take care of the optimal certificate properties. +Also, Icinga renews them periodically at runtime to avoid expiry. +But you can also provide your own certificates, +just like to any other application which uses TLS. + +!!! warning + + The only serious reasons to generate own certificates are company policies. + You are responsible for making Icinga working with your certificates, + as well as for [expiry monitoring](10-icinga-template-library.md#plugin-check-command-ssl_cert) + and renewal. + + Especially `icinga2 pki` CLI commands don't expect such certificates. + + Apropos renewal, do not provide the CA private key anywhere! + Icinga uses it to automatically renew certificates + with standard properties, not any custom ones. + +The basic requirements for all leaf certificates are: + +* Located in `/var/lib/icinga2/certs/NODENAME.crt` + and `/var/lib/icinga2/certs/NODENAME.key` +* Subject with CN matching the endpoint name +* A DNS SAN matching the endpoint name + +The CA certificate must be located in `/var/lib/icinga2/certs/ca.crt`. +Pretty much everything else is limited only by your company policy +and the OpenSSL versions your Icinga nodes use. E.g. the following works: + +* Custom key sizes, e.g. 2048 bits +* Custom key types, e.g. ECC +* Any number of intermediate CAs (but see limitations below) +* Multiple trusted root CAs in `/var/lib/icinga2/certs/ca.crt` +* Different root CAs per cluster subtree, as long as each node trusts the + certificate issuers of all nodes it's directly connected to + +Intermediate CA restrictions: + +* Each side has to provide its intermediate CAs along with the leaf certificate + in `/var/lib/icinga2/certs/NODENAME.crt`, ordered from leaf to root. +* Intermediate CAs may not be used directly as root CAs. To trust only specific + intermediate CAs, cross-sign them with themselves, so that you get equal + certificates except that they're self-signed. Use them as root CAs in Icinga. + ## Automation These hints should get you started with your own automation tools (Puppet, Ansible, Chef, Salt, etc.)