@cryptotaxi247 / netdata-1 / commits / af198c0f2

Add documentation outlining how to use custom CA certificates with Netdata. (#19754)

Austin S. Hemmelgarn committed Mar 4, 2025 at 08:16 UTC af198c0f25de01ae16a8d426f36496f840515c5a
1 file changed +121
docs/netdata-agent/configuration/using-custom-ca-certificates-with-netdata.md new
+121
@@ -0,0 +1,121 @@
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`