Skip to main content

Configuring certificates

TLS​

How it works​

The TLS (1.3) connection is negotiated by the client (poller or agent, depending on the direction) and requires certificates. Depending on the connection direction, the agent/the poller checks that the IP/DNS used to reach the server strictly matches the information in the certificate. If this is not the case, the connection is not allowed. The verification is performed on the alt_names block of the certificate, which may contain several DNS, IP, or CN entries.

Certificate files​

Supported formats are :

  • public certificate file, CA or wildcard: .crt/.cer
  • private key file: .key

Certificate files stored on the poller must be stored in /etc/pki/, either at the root or in a subdirectory. They must have the following permissions:

chmod 644 /etc/pki/agent*

Certificate files stored on the host can be stored in the directory of your choice.

These files can also be saved directly in the certificate store. In this case, it is not necessary to enter them in the configuration made on the host (Host configuration column in the table below).

Summary of possible configurations​

When connecting to the poller, the agent verifies that the IP/DNS entered in the Poller endpoint parameter of the agent configuration strictly matches the information in the certificate (SAN or CN). If this is not the case, the connection is not allowed.

Use caseFile(s) on the pollerFile(s) on the host (if not loaded in the certificate store)Poller configuration (interface)Host configuration
Certificate signed by a CAPublic certificate and private key filesCA fileIn the OTLP receiver section:
  • Public certificate: path to the public certificate (example: '/etc'/pki'/certificate.crt)
  • Private key: path to the private key (example: '/etc'/pki'/certificate.key)
  • CA: empty
  • Poller endpoint: IP/DNS of the poller
  • Private key file/private_key: empty
  • Certificate file: empty
  • Trusted CA's certificate file/ca_certificate: path to the CA
  • Certificate Common Name/ca_name: empty
Self-signed certificatePublic certificate and private key filesPublic certificate fileIn the OTLP receiver section:
  • Public certificate: path to the public certificate (example: '/etc'/pki'/certificate.crt)
  • Private key: path to the private key (example: '/etc'/pki'/certificate.key)
  • CA: empty, except when a double handshake is needed
  • Poller endpoint: IP/DNS of the poller
  • Private Key file/private_key: empty
  • Certificate file/public_certificate: empty
  • Trusted CA's certificate file/ca_certificate: path to the public certificate
  • Certificate Common Name/ca_name: empty
Wildcard certificateWildcard and private key filesWildcard fileIn the OTLP receiver section:
  • Public certificate: Wildcard certificate file
  • Private key: path to the private key
  • CA: empty
  • Private Key file/private_key: empty
  • Certificate file/public_cert: empty
  • Trusted CA's certificate file/ca_certificate: path to the wildcard certificate
  • Certificate Common Name/ca_name: empty
Public certificate (managed service, e.g. central Centreon Cloud poller)NoneNoneIn the OTLP receiver section:
  • Public certificate: empty
  • Private key: empty
  • CA: empty
  • Poller endpoint: IP/DNS of the load balancer bearing the public certificate
  • Private Key file/private_key: empty
  • Certificate file/public_cert: empty
  • Trusted CA's certificate file/ca_certificate: empty
  • Certificate Common Name/ca_name : empty
Public certificate (key files)Public certificate and private key filesNoneIn the OTLP receiver section:
  • Public certificate: path to the public certificate (example: '/etc'/pki'/certificate.crt)
  • Private key: path to the private key (example: '/etc'/pki'/certificate.key)
  • CA: empty
  • Poller endpoint: IP/DNS of the poller
  • Private Key file/private_key: empty
  • Certificate file/public_cert: empty
  • Trusted CA's certificate file/ca_certificate: empty
  • Certificate Common Name/ca_name: empty

Insecure TLS​

How it works​

Some configurations require a more flexible approach to establishing the connection.

In TLS, the client (agent or poller) verifies that the IP/DNS used to reach the server strictly matches the information in the certificate. If this is not the case, the connection is refused. The verification is performed on the alt_names block of the certificate, which may contain multiple DNS, IP, or CN entries.

It may sometimes be necessary to accept the connection, even when this correspondence is not verified.

For example, in the case of an MSP, which mutualize pollers for its customers. The hosts within the customer base do not know the DNS of the pollers and must use the IP, which will not necessarily match the information in the certificate. This makes particular sense in cases where the same certificate must be used on multiple pollers, and security restrictions do not allow the use of a wildcard.

The unsecured TLS encryption mode addresses this use case.

In unsecured TLS, the client (agent/poller) first checks the client's “Common Name CA” field.

  • If the “Common Name CA” field is filled in, its value is compared with the certificate information, which must match exactly.
  • If the “Common Name CA” field is empty, the verification is based on the IP/DNS used to reach the server, as in TLS mode.

If no match is found, the connection is denied. The verification is performed on the subject and alt_names blocks of the certificate, which may contain multiple DNS, IP, or CN entries.

Certificate files​

See dedicated section for TLS, prerequisites are the same.

Summary of possible configurations​

The configuration is similar to the one specified for TLS.

The difference lies in the use of the “Common Name CA” field on the client side.

The Certificate Common Name/ca_name field will contain the value (DNS, IP, or CN) specified in the certificate.

How to generate a self-signed certificate (optional)​

If you do not have a certificate, you can generate a self-signed one. To generate a self-signed certificate that is valid for one year, run the following command on your poller or host:

openssl req -new -subj '/CN={server_hostname}' \
                 -addext "subjectAltName = DNS:{alt_server_DNS}, IP:{alt_server_IP}" \
                 -days 365 -nodes -x509 \
                 -newkey rsa:2048 -keyout {key} -out {cert}
  • {key} = path to the private key file
  • {cert} = path to the public certificate file
  • {server_hostname} = DNS name of the server and/or use {alt_poller_DNS} and/or use {alt_poller_IP} In TLS encryption mode, the DNS/IP of the server used by the client must correspond to a CN or SAN (altName) entry in the certificate ({server_hostname}). The line -subj '/CN={server_hostname}' \ is optional if SANs are defined. In unsecured TLS encryption mode, the server's DNS/IP may differ from the certificate information. In this case, you will need to enter the value to be used in “Common Name CA” in the client configuration.

Certificate files stored on the poller must be stored in /etc/pki/, either at the root or in a subdirectory. They must have the following permissions:

chmod 644 /etc/pki/agent*

{server_hostname} must match the DNS/IP used in Poller endpoint (Installer) / *endpoint (json), in the agent configuration, on the host.

Testing mode: unencrypted communication​

You can leave the connection unencrypted for test purposes only. In this mode, you do not need any certificates or tokens.

Note that this connection will only last for one hour. Do not use this setting in production!

To configure this mode, select No TLS from the Encryption level list in the Agent configuration window.

The agent will be configured the following way on the host:

{
  "log_level":"info",
  "endpoint":"<POLLER IP/DNS>:4317",
  "encryption" : "false",
  "host":"host_1",
  "log_type":"file",
  "log_file":"/var/log/centreon-monitoring-agent/centagent.log" 
}