Skip to content

Commit

Permalink
Doc: Distributed Monitoring: add section "External CA/PKI"
Browse files Browse the repository at this point in the history
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
  • Loading branch information
Al2Klimov committed Nov 15, 2024
1 parent 7a20d98 commit 25fb3c8
Showing 1 changed file with 47 additions and 0 deletions.
47 changes: 47 additions & 0 deletions doc/06-distributed-monitoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <a id="distributed-monitoring-automation"></a>

These hints should get you started with your own automation tools (Puppet, Ansible, Chef, Salt, etc.)
Expand Down

0 comments on commit 25fb3c8

Please sign in to comment.