netdata_netdata/docs/netdata-agent/configuration/using-custom-ca-certificates-with-netdata.md

Using custom CA certificates with Netdata

When streaming over an encrypted connection, exporting metrics to a secure endpoint, collecting metrics from secure services, or connecting to an on-premises instance of Netdata Cloud, the Netdata Agent needs to be able to verify the TLS certificate of the remote system to ensure the security of the connection.

When the remote system is using a TLS certificate issued by a public certificate authority, this will work correctly out of box without a need to configure anything extra. However, if the TLS certificate was issued by a private CA, the certificate for that private CA must be installed on the system the Netdata Agent is running on for the connections to succeed.

The exact method of installing a certificate for a private CA depends on the installation type and the underlying platform:

• For native DEB/RPM packages, install the certificate in the system certificate store
• For static builds on Linux, see the instructions for using custom certificates with our static builds
• For our Docker images, see the instructions for using custom certificates with our Docker containers
• For local builds of Netdata on Linux, install the certificate in the system certificate store
• For Windows, see the instructions for installing custom certificates for Netdata

Installing certificates in the system certificate store on Linux

Exact instructions for installing certificates in the system certificate store on Linux vary based on the distribution. If instructions for your Linux distribution are not listed below, consult the documentation for your distribution for instructions.

Debian, Ubuntu, and derivatives

To install a custom CA certificate in the system certificate store on a Debian or Ubuntu system:

1. Ensure the certificate file to be installed is in PEM or DER format.
2. Copy the certificate file to /usr/local/share/certificates with a .crt file extension (for example, if the certificate file is named local.pem, copy it to this directory as local.crt). You may need to create this directory. The certificate file (and the directory) should have permissions set such that all users can read the file, but only the root user can write to it.
3. Run the command: sudo update-ca-certificates.

Red Hat Enterprise Linux, Fedora, and derivatives

To install a custom CA certificate in the system certificate store on a Red Hat Enterprise Linux or Fedora system:

1. Ensure the certificate file to be installed is in PEM or DER format.
2. Copy the certificate file to /etc/pki/ca-trust/source/anchors with a .crt file extension (for example, if the certificate file is named local.pem, copy it to this directory as local.crt). The certificate file should have permissions set such that all users can read the file, but only the root user can write to it.
3. Run the command: sudo update-ca-trust

Suse Linux Enterprise and openSUSE

To install a custom CA certificate in the system certificate store on a Suse Linux Enterprise or openSUSE system:

1. Ensure the certificate file to be installed is in PEM or DER format.
2. Copy the certificate file to /etc/pki/trust/anchors with a .crt file extension (for example, if the certificate file is named local.pem, copy it to this directory as local.crt). The certificate file should have permissions set such that all users can read the file, but only the root user can write to it.
3. Run the command: sudo update-ca-certificates

Arch Linux and derivatives

To install a custom CA certificate in the system certificate store on an Arch Linux system:

1. Ensure the certificate file to be installed is in PEM or DER format.
2. Copy the certificate file to /etc/ca-certificates/trust-store/anchors with a .crt file extension (for example, if the certificate file is named local.pem, copy it to this directory as local.crt). The certificate file should have permissions set such that all users can read the file, but only the root user can write to it.
3. Run the command: sudo update-ca-trust

Alpine Linux

To install a custom CA certificate in the system certificate store on an Alpine Linux system:

1. Install the ca-certificates package if it is not already installed.
2. Ensure the certificate file to be installed is in PEM or DER format.
3. Copy the certificate file to /usr/local/share/certificates with a .crt file extension (for example, if the certificate file is named local.pem, copy it to this directory as local.crt). You may need to create this directory. The certificate file (and the directory) should have permissions set such that all users can read the file, but only the root user can write to it.
4. Run the command: sudo update-ca-certificates.

Using custom certificates with our static builds

For most users of our static builds, simply installing the required certificate files in the system trust store as outlined above will be sufficient to get things working correctly, though the certificates should be installed in the system trust store before installing Netdata, otherwise they may not work until after the next time the agent is updated.

If you are using one of our static builds and installing the certificates in the system certificate store does not work, please open a bug report about it on GitHub, as this usually indicates that our static builds are not correctly handling certificates on your system.

Using custom certificates with our Docker images

The simplest way to use custom certificates with our Docker images is to create a custom Docker image that includes the required certificate.

A custom Docker image including the required certificate can be created using a Dockerfile similar to the following:

FROM netdata/netdata:stable

RUN mkdir -p /usr/local/share/certificates

COPY local.pem /usr/local/share/certificates

RUN update-ca-certificates

The COPY line should be updated to reflect the actual name of the certificate file to be included. Note that the certificate must be in PEM or DER format with a .crt extension.

Using custom certificates on Windows

Currently, Netdata does not provide integration for most components with the system certificate store on Windows. Instead, certificates must be installed into the bundled MSYS2 environment shipped as part of Netdata using the following instructions:

1. Ensure the certificate file to be installed is in PEM or DER format.
2. Copy the certificate file to C:\Program FIles\Netdata\etc\pki\ca-trust\source\anchors. You may need to create this directory.
3. In an administrative command prompt, run C:\Program Files\Netdata\usr\bin\update-ca-trust.exe