@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 162 lines 4.76 KB
Rendered Raw
1 # Configuring Metrics Centralization Points
2
3 :::tip
4
5 **What You'll Learn**
6
7 How to configure streaming between Netdata Children and Parents using stream.conf, including basic setup, TLS/SSL encryption, and troubleshooting connection issues.
8
9 :::
10
11 Metrics streaming configuration for both Netdata Children and Parents is done via `stream.conf`.
12
13 :::important
14
15 **Configuration File Security**
16
17 `netdata.conf` and `stream.conf` have the same `ini` format, but `netdata.conf` is considered a non-sensitive file, while `stream.conf` contains API keys, IPs and other sensitive information that enable communication between Netdata Agents.
18
19 :::
20
21 ## Understanding stream.conf Structure
22
23 `stream.conf` has two main sections:
24
25 - The `[stream]` section includes options for the **sending Netdata** (i.e., Netdata Children, or Netdata Parents that stream to Grand Parents, or to other sibling Netdata Parents in a cluster).
26 - The rest includes multiple sections that define API keys for the **receiving Netdata** (i.e., Netdata Parents).
27
28 ## Edit stream.conf
29
30 To edit `stream.conf`, run this on your terminal:
31
32 ```bash
33 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
34 sudo ./edit-config stream.conf
35 ```
36
37 Your editor will open, with defaults and commented `stream.conf` options.
38
39 ## Configuration Steps
40
41 <details>
42 <summary><strong>Configuring a Netdata Parent</strong></summary><br/>
43
44 To enable the reception of metrics from Netdata Children, generate a random API key with this command:
45
46 ```bash
47 uuidgen
48 ```
49
50 Then, copy the UUID generated, [edit `stream.conf`](#edit-streamconf), find the section that reads like the following and replace `API_KEY` with the UUID you generated:
51
52 ```ini
53 [API_KEY]
54 # Accept metrics streaming from other Agents with the specified API key
55 enabled = yes
56 ```
57
58 Save the file and restart Netdata.
59
60 <br/>
61 </details>
62
63 <details>
64 <summary><strong>Configuring Netdata Children</strong></summary><br/>
65
66 To enable streaming metrics to a Netdata Parent, [edit `stream.conf`](#edit-streamconf), and at the `[stream]` section at the top, set:
67
68 ```ini
69 [stream]
70 # Stream metrics to another Netdata
71 enabled = yes
72 # The IP and PORT of the parent
73 destination = PARENT_IP_ADDRESS:19999
74 # The shared API key, generated by uuidgen
75 api key = API_KEY
76 ```
77
78 Save the file and restart Netdata.
79
80 <br/>
81 </details>
82
83 <details>
84 <summary><strong>Enable TLS/SSL Communication</strong></summary><br/>
85
86 While encrypting the connection between your parent and child nodes is recommended for security, it's not required to get started.
87
88 This example uses self-signed certificates.
89
90 :::note
91
92 **Prerequisites**
93
94 This section assumes you have read the documentation on [how to edit the Netdata configuration files](/docs/netdata-agent/configuration/README.md).
95
96 :::
97
98 ### SSL Setup Process
99
100 1. **Parent node**
101 To generate an SSL key and certificate using `openssl`, take a look at the related section around [Securing Netdata Agents](/src/web/server/README.md#examples) in our Documentation.
102
103 2. **Child node**
104 Update `stream.conf` to enable SSL/TLS and allow self-signed certificates. Append ':SSL' to the destination and uncomment 'ssl skip certificate verification'.
105
106 ```text
107 [stream]
108 enabled = yes
109 destination = 203.0.113.0:SSL
110 ssl skip certificate verification = yes
111 api key = 11111111-2222-3333-4444-555555555555
112 ```
113
114 :::note
115
116 The `:SSL` suffix enables TLS encryption for Netdata's custom streaming protocol. This is different from HTTPS—Netdata streaming uses its own binary protocol over TCP, and TLS adds encryption on top of that protocol.
117
118 :::
119
120 3. **Restart both nodes**
121 Restart the Netdata Agent on both the parent and child nodes to stream encrypted metrics using TLS/SSL.
122
123 <br/>
124 </details>
125
126 ## Troubleshooting Streaming Connections
127
128 You can find any issues related to streaming at Netdata logs.
129
130 <details>
131 <summary><strong>From the UI</strong></summary><br/>
132
133 Netdata logs to systemd-journald by default, and its logs are available at the `Logs` tab of the UI. At the `MESSAGE_ID` field look for `Netdata connection from child` and `Netdata connection to parent`.
134
135 <br/>
136 </details>
137
138 <details>
139 <summary><strong>From the terminal</strong></summary><br/>
140
141 **On the Parents:**
142
143 ```bash
144 journalctl -r --namespace=netdata MESSAGE_ID=ed4cdb8f1beb4ad3b57cb3cae2d162fa
145 ```
146
147 **On the Children:**
148
149 ```bash
150 journalctl -r --namespace=netdata MESSAGE_ID=6e2e3839067648968b646045dbf28d66
151 ```
152
153 <br/>
154 </details>
155
156 ## Next Steps
157
158 ### Sizing Netdata Parents
159
160 After configuring your metrics centralization setup, you'll want to properly size your Netdata Parents to handle the expected load from your Children nodes.
161
162 For detailed information on resource requirements and optimization strategies, see [Resource Utilization](https://learn.netdata.cloud/docs/netdata-agent/resource-utilization/).