| 1 | # Using custom CA certificates with Netdata |
| 2 | |
| 3 | When streaming over an encrypted connection, exporting metrics to a secure endpoint, collecting metrics from secure |
| 4 | services, or connecting to an on-premises instance of Netdata Cloud, the Netdata Agent needs to be able to verify |
| 5 | the TLS certificate of the remote system to ensure the security of the connection. |
| 6 | |
| 7 | When the remote system is using a TLS certificate issued by a public certificate authority, this will work correctly |
| 8 | out of box without a need to configure anything extra. However, if the TLS certificate was issued by a private |
| 9 | CA, the certificate for that private CA must be installed on the system the Netdata Agent is running on for the |
| 10 | connections to succeed. |
| 11 | |
| 12 | The exact method of installing a certificate for a private CA depends on the installation type and the underlying |
| 13 | platform: |
| 14 | |
| 15 | - For native DEB/RPM packages, [install the certificate in the system certificate store](#installing-certificates-in-the-system-certificate-store-on-linux) |
| 16 | - For static builds on Linux, [see the instructions for using custom certificates with our static builds](#using-custom-certificates-with-our-static-builds) |
| 17 | - For our Docker images, [see the instructions for using custom certificates with our Docker containers](#using-custom-certificates-with-our-docker-images) |
| 18 | - For local builds of Netdata on Linux, [install the certificate in the system certificate store](#installing-certificates-in-the-system-certificate-store-on-linux) |
| 19 | - For Windows, [see the instructions for installing custom certificates for Netdata](#using-custom-certificates-on-windows) |
| 20 | |
| 21 | ## Installing certificates in the system certificate store on Linux |
| 22 | |
| 23 | Exact instructions for installing certificates in the system certificate store on Linux vary based on the |
| 24 | distribution. If instructions for your Linux distribution are not listed below, consult the documentation for your |
| 25 | distribution for instructions. |
| 26 | |
| 27 | ### Debian, Ubuntu, and derivatives |
| 28 | |
| 29 | To install a custom CA certificate in the system certificate store on a Debian or Ubuntu system: |
| 30 | |
| 31 | 1. Ensure the certificate file to be installed is in PEM or DER format. |
| 32 | 2. Copy the certificate file to `/usr/local/share/certificates` with a `.crt` file extension (for example, if |
| 33 | the certificate file is named `local.pem`, copy it to this directory as `local.crt`). You may need to create |
| 34 | this directory. The certificate file (and the directory) should have permissions set such that all users can |
| 35 | read the file, but only the root user can write to it. |
| 36 | 3. Run the command: `sudo update-ca-certificates`. |
| 37 | |
| 38 | ### Red Hat Enterprise Linux, Fedora, and derivatives |
| 39 | |
| 40 | To install a custom CA certificate in the system certificate store on a Red Hat Enterprise Linux or Fedora system: |
| 41 | |
| 42 | 1. Ensure the certificate file to be installed is in PEM or DER format. |
| 43 | 2. Copy the certificate file to `/etc/pki/ca-trust/source/anchors` with a `.crt` file extension (for example, |
| 44 | if the certificate file is named `local.pem`, copy it to this directory as `local.crt`). The certificate file |
| 45 | should have permissions set such that all users can read the file, but only the root user can write to it. |
| 46 | 3. Run the command: `sudo update-ca-trust` |
| 47 | |
| 48 | ### Suse Linux Enterprise and openSUSE |
| 49 | |
| 50 | To install a custom CA certificate in the system certificate store on a Suse Linux Enterprise or openSUSE system: |
| 51 | |
| 52 | 1. Ensure the certificate file to be installed is in PEM or DER format. |
| 53 | 2. Copy the certificate file to `/etc/pki/trust/anchors` with a `.crt` file extension (for example, if the certificate |
| 54 | file is named `local.pem`, copy it to this directory as `local.crt`). The certificate file should have permissions |
| 55 | set such that all users can read the file, but only the root user can write to it. |
| 56 | 3. Run the command: `sudo update-ca-certificates` |
| 57 | |
| 58 | ### Arch Linux and derivatives |
| 59 | |
| 60 | To install a custom CA certificate in the system certificate store on an Arch Linux system: |
| 61 | |
| 62 | 1. Ensure the certificate file to be installed is in PEM or DER format. |
| 63 | 2. Copy the certificate file to `/etc/ca-certificates/trust-store/anchors` with a `.crt` file extension (for example, |
| 64 | if the certificate file is named `local.pem`, copy it to this directory as `local.crt`). The certificate file |
| 65 | should have permissions set such that all users can read the file, but only the root user can write to it. |
| 66 | 3. Run the command: `sudo update-ca-trust` |
| 67 | |
| 68 | ### Alpine Linux |
| 69 | |
| 70 | To install a custom CA certificate in the system certificate store on an Alpine Linux system: |
| 71 | |
| 72 | 1. Install the `ca-certificates` package if it is not already installed. |
| 73 | 2. Ensure the certificate file to be installed is in PEM or DER format. |
| 74 | 3. Copy the certificate file to `/usr/local/share/certificates` with a `.crt` file extension (for example, if |
| 75 | the certificate file is named `local.pem`, copy it to this directory as `local.crt`). You may need to create |
| 76 | this directory. The certificate file (and the directory) should have permissions set such that all users can |
| 77 | read the file, but only the root user can write to it. |
| 78 | 4. Run the command: `sudo update-ca-certificates`. |
| 79 | |
| 80 | ## Using custom certificates with our static builds |
| 81 | |
| 82 | For most users of our static builds, simply installing the required certificate files in the system trust store |
| 83 | [as outlined above](#installing-certificates-in-the-system-certificate-store-on-linux) will be sufficient to get |
| 84 | things working correctly, though the certificates should be installed in the system trust store _before_ installing |
| 85 | Netdata, otherwise they may not work until after the next time the agent is updated. |
| 86 | |
| 87 | If you are using one of our static builds and installing the certificates in |
| 88 | the system certificate store does not work, please [open a bug report about it on |
| 89 | GitHub](https://github.com/netdata/netdata/issues/new?template=BUG_REPORT.yml), as this usually indicates that |
| 90 | our static builds are not correctly handling certificates on your system. |
| 91 | |
| 92 | ## Using custom certificates with our Docker images |
| 93 | |
| 94 | The simplest way to use custom certificates with our Docker images is to create a custom Docker image that includes |
| 95 | the required certificate. |
| 96 | |
| 97 | A custom Docker image including the required certificate can be created using a Dockerfile similar to the following: |
| 98 | |
| 99 | ``` |
| 100 | FROM netdata/netdata:stable |
| 101 | |
| 102 | RUN mkdir -p /usr/local/share/certificates |
| 103 | |
| 104 | COPY local.pem /usr/local/share/certificates |
| 105 | |
| 106 | RUN update-ca-certificates |
| 107 | ``` |
| 108 | |
| 109 | The `COPY` line should be updated to reflect the actual name of the certificate file to be included. Note that |
| 110 | the certificate must be in PEM or DER format with a `.crt` extension. |
| 111 | |
| 112 | ## Using custom certificates on Windows |
| 113 | |
| 114 | Currently, Netdata does not provide integration for most components with the system certificate store on |
| 115 | Windows. Instead, certificates must be installed into the bundled MSYS2 environment shipped as part of Netdata |
| 116 | using the following instructions: |
| 117 | |
| 118 | 1. Ensure the certificate file to be installed is in PEM or DER format. |
| 119 | 2. Copy the certificate file to `C:\Program Files\Netdata\etc\pki\ca-trust\source\anchors`. You may need to create |
| 120 | this directory. |
| 121 | 3. In an administrative command prompt, run `C:\Program Files\Netdata\usr\bin\update-ca-trust.exe` |