1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
|
<!--
title: "Connect Agent to Cloud"
description: "Connecting a Netdata Agent, running on a distributed node, to Netdata Cloud securely via the encrypted Agent-Cloud link (ACLK)."
custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md
-->
# Connect Agent to Cloud
You can securely connect a Netdata Agent, running on a distributed node, to Netdata Cloud. A Space's
administrator creates a **claiming token**, which is used to add an Agent to their Space via the [Agent-Cloud link
(ACLK)](/aclk/README.md).
Are you just starting out with Netdata Cloud? See our [get started with
Cloud](https://learn.netdata.cloud/docs/cloud/get-started) guide for a walkthrough of the process and simplified
instructions.
When connecting an agent (also referred to as a node) to Netdata Cloud, you must complete a verification process that proves you have some level of authorization to manage the node itself. This verification is a security feature that helps prevent unauthorized users from seeing the data on your node.
Only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script generated by
Netdata Cloud.
> The connection process ensures no third party can add your node, and then view your node's metrics, in a Cloud account,
> Space, or War Room that you did not authorize.
By connecting a node, you opt-in to sending data from your Agent to Netdata Cloud via the [ACLK](/aclk/README.md). This
data is encrypted by TLS while it is in transit. We use the RSA keypair created during the connection process to authenticate the
identity of the Netdata Agent when it connects to the Cloud. While the data does flow through Netdata Cloud servers on its way
from Agents to the browser, we do not store or log it.
You can connect a node during the Netdata Cloud onboarding process, or after you created a Space by clicking on **Connect
Nodes** in the [Spaces management area](https://learn.netdata.cloud/docs/cloud/spaces#manage-spaces).
There are two important notes regarding connecting nodes:
- _You can only connect any given node in a single Space_. You can, however, add that connected node to multiple War Rooms
within that one Space.
- You must repeat the connection process on every node you want to add to Netdata Cloud.
## How to connect a node
There will be three main flows from where you might want to connect a node to Netdata Cloud.
* when you are on an [
War Room](#empty-war-room) and you want to connect your first node
* when you are at the [Manage Space](#manage-space-or-war-room) area and you select **Connect Nodes** to connect a node, coming from Manage Space or Manage War Room
* when you are on the [Nodes view page](https://learn.netdata.cloud/docs/cloud/visualize/nodes) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow
Please note that only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script, generated by Netdata Cloud, to trigger the connection process.
### Empty War Room
Either at your first sign in or following ones, when you enter Netdata Cloud and are at a War Room that doesn’t have any node added to it, you will be able to:
* connect a new node to Netdata Cloud and add it to the War Room
* add a previously connected node to the War Room
If your case is to connect a new node and add it to the War Room, you will need to tell us what environment the node is running on (Linux, Docker, macOS, Kubernetes) and then we will provide you with a script to initiate the connection process. You just will need to copy and paste it into your node's terminal. See one of the following sections depending on your case:
* [Linux](#connect-an-agent-running-in-linux)
* [Docker](#connect-an-agent-running-in-docker)
* [macOS](#connect-an-agent-running-in-macos)
* [Kubernetes](#connect-a-kubernetes-clusters-parent-netdata-pod)
Repeat this process with every node you want to add to Netdata Cloud during onboarding. You can also add more nodes once you've
finished onboarding.
### Manage Space or War Room
To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script
given by Netdata Cloud into your node's terminal.
When coming from [Nodes view page](https://learn.netdata.cloud/docs/cloud/visualize/nodes) the room parameter is already defined to current War Room.
### Connect an agent running in Linux
If you want to connect a node that is running on a Linux environment, the script that will be provided to you by Netdata Cloud is the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script) which will install the Netdata Agent on your node, if it isn't already installed, and connect the node to Netdata Cloud. It should be similar to:
```
bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
```
The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see
the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
Please note that to run it you will either need to have root privileges or run it with the user that is running the agent, more details on the [Connect an agent without root privileges](#connect-an-agent-without-root-privileges) section.
For more details on what are the extra parameters `claim-token`, `claim-rooms` and `claim-url` please refer to [Connect node to Netdata Cloud during installation](/packaging/installer/methods/kickstart.md#connect-node-to-netdata-cloud-during-installation).
### Connect an agent without root privileges
If you don't want to run the installation script to connect your nodes to Netdata Cloud with root privileges, you can discover which user is running the Agent,
switch to that user, and run the script.
Use `grep` to search your `netdata.conf` file, which is typically located at `/etc/netdata/netdata.conf`, for the `run
as user` setting. For example:
To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script
given by Netdata Cloud into your node's terminal.
```bash
grep "run as user" /etc/netdata/netdata.conf
# run as user = netdata
```
The default user is `netdata`. Yours may be different, so pay attention to the output from `grep`. Switch to that user
and run the script.
```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
```
### Connect an agent running in Docker
To connect an instance of the Netdata Agent running inside of a Docker container, it is recommended that you follow
the instructions and use the commands provided either in the `Nodes` tab of an [empty War Room](#empty-war-room) on Netdata Cloud or
in the shelf that appears when you click **Connect Nodes** and select **Docker**.
However, users can also claim a new node by claiming environment variables in the container to have it automatically
connected on startup or restart.
For the connection process to work, the contents of `/var/lib/netdata` _must_ be preserved across container
restarts using a persistent volume. See our [recommended `docker run` and Docker Compose
examples](/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.
#### Using environment variables
The Netdata Docker container looks for the following environment variables on startup:
- `NETDATA_CLAIM_TOKEN`
- `NETDATA_CLAIM_URL`
- `NETDATA_CLAIM_ROOMS`
- `NETDATA_CLAIM_PROXY`
If the token and URL are specified in their corresponding variables _and_ the container is not already connected,
it will use these values to attempt to connect the container, automatically adding the node to the specified War
Rooms. If a proxy is specified, it will be used for the connection process and for connecting to Netdata Cloud.
These variables can be specified using any mechanism supported by your container tooling for setting environment
variables inside containers.
When using the `docker run` command, if you have an agent container already running, it is important to know that there will be a short period of downtime. This is due to the process of recreating the new agent container.
The command to connect a new node to Netdata Cloud is:
```bash
docker run -d --name=netdata \
-p 19999:19999 \
-v netdataconfig:/etc/netdata \
-v netdatalib:/var/lib/netdata \
-v netdatacache:/var/cache/netdata \
-v /etc/passwd:/host/etc/passwd:ro \
-v /etc/group:/host/etc/group:ro \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
-v /etc/os-release:/host/etc/os-release:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--security-opt apparmor=unconfined \
-e NETDATA_CLAIM_TOKEN=TOKEN \
-e NETDATA_CLAIM_URL="https://app.netdata.cloud" \
-e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \
-e NETDATA_CLAIM_PROXY=PROXY \
netdata/netdata
```
>Note: This command is suggested for connecting a new container. Using this command for an existing container recreates the container, though data
and configuration of the old container may be preserved. If you are claiming an existing container that can not be recreated,
you can add the container by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and following
the instructions and commands provided or by following the instructions in an [empty War Room](#empty-war-room).
The output that would be seen from the connection process when using other methods will be present in the container logs.
Using the environment variables like this to handle the connection process is the preferred method of connecting Docker containers
as it works in the widest variety of situations and simplifies configuration management.
#### Using Docker compose
If you use `docker compose`, you can copy the config provided by Netdata Cloud, which should be same as the one below:
```bash
version: '3'
services:
netdata:
image: netdata/netdata
container_name: netdata
hostname: example.com # set to fqdn of host
ports:
- 19999:19999
restart: unless-stopped
cap_add:
- SYS_PTRACE
security_opt:
- apparmor:unconfined
volumes:
- netdataconfig:/etc/netdata
- netdatalib:/var/lib/netdata
- netdatacache:/var/cache/netdata
- /etc/passwd:/host/etc/passwd:ro
- /etc/group:/host/etc/group:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /etc/os-release:/host/etc/os-release:ro
environment:
- NETDATA_CLAIM_TOKEN=TOKEN
- NETDATA_CLAIM_URL="https://app.netdata.cloud"
- NETDATA_CLAIM_ROOMS=ROOM1,ROOM2
volumes:
netdataconfig:
netdatalib:
netdatacache:
```
Then run the following command in the same directory as the `docker-compose.yml` file to start the container.
```bash
docker-compose up -d
```
#### Using docker exec
Connect a _running Netdata Agent container_, where you don't want to recreate the existing container, append the script offered by Netdata Cloud to a `docker exec ...` command, replacing
`netdata` with the name of your running container:
```bash
docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
```
The values for `ROOM1,ROOM2` can be found by by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and copying the `rooms=` value in the command provided.
The script should return `Agent was successfully claimed.`. If the connection process returns errors, or if
you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
### Connect an agent running in macOS
To connect a node that is running on a macOS environment the script that will be provided to you by Netdata Cloud is the [kickstart](/packaging/installer/methods/macos.md#install-netdata-with-our-automatic-one-line-installation-script) which will install the Netdata Agent on your node, if it isn't already installed, and connect the node to Netdata Cloud. It should be similar to:
```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh) --install /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
```
The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see
the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
### Connect a Kubernetes cluster's parent Netdata pod
Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#connect-your-kubernetes-cluster-to-netdata-cloud)
for details on connecting a parent Netdata pod.
### Connect through a proxy
A Space's administrator can connect a node through HTTP(S) proxy.
You should first configure the proxy in the `[cloud]` section of `netdata.conf`. The proxy settings you specify here
will also be used to tunnel the ACLK. The default `proxy` setting is `none`.
```conf
[cloud]
proxy = none
```
The `proxy` setting can take one of the following values:
- `none`: Do not use a proxy, even if the system configured otherwise.
- `env`: Try to read proxy settings from set environment variables `http_proxy`.
- `http://[user:pass@]host:ip`: The ACLK and connection process will use the specified HTTP(S) proxy.
For example, a HTTP proxy setting may look like the following:
```conf
[cloud]
proxy = http://203.0.113.0:1080 # With an IP address
proxy = http://proxy.example.com:1080 # With a URL
```
You can now move on to connecting. When you connect with the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script) script, add the `--claim-proxy=` parameter and
append the same proxy setting you added to `netdata.conf`.
```bash
bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud --claim-proxy socks5h://203.0.113.0:1080
```
Hit **Enter**. The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if
you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
### Troubleshooting
If you're having trouble connecting a node, this may be because the [ACLK](/aclk/README.md) cannot connect to Cloud.
With the Netdata Agent running, visit `http://NODE:19999/api/v1/info` in your browser, replacing `NODE` with the IP
address or hostname of your Agent. The returned JSON contains four keys that will be helpful to diagnose any issues you
might be having with the ACLK or connection process.
```json
"cloud-enabled"
"cloud-available"
"agent-claimed"
"aclk-available"
```
On Netdata agent version `1.32` (`netdata -v` to find your version) and newer, the `netdata -W aclk-state` command can be used to get some diagnostic information about ACLK. Sample output:
```
ACLK Available: Yes
ACLK Implementation: Next Generation
New Cloud Protocol Support: Yes
Claimed: Yes
Claimed Id: 53aa76c2-8af5-448f-849a-b16872cc4ba1
Online: Yes
Used Cloud Protocol: New
```
Use these keys and the information below to troubleshoot the ACLK.
#### kickstart: unsupported Netdata installation
If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package.
If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,
please remove that package and reinstall using our [recommended kickstart
script](/docs/get-started.mdx#install-on-linux-with-one-line-installer-recommended).
#### kickstart: Failed to write new machine GUID
If you run the kickstart script but don't have privileges required for the actions done on the connecting to Netdata Cloud process you will get the following error:
```bash
Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id.
```
For a successful execution you will need to run the script with root privileges or run it with the user that is running the agent, more details on the [Connect an agent without root privileges](#connect-an-agent-without-root-privileges) section.
#### bash: netdata-claim.sh: command not found
If you run the claiming script and see a `command not found` error, you either installed Netdata in a non-standard
location or are using an unsupported package. If you installed Netdata in a non-standard path using the `--install`
option, you need to update your `$PATH` or run `netdata-claim.sh` using the full path. For example, if you installed
Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script.
If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,
please remove that package and reinstall using our [recommended kickstart
script](/docs/get-started.mdx#install-on-linux-with-one-line-installer-recommended).
#### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)
If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS
6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old
versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which
helps securely encrypt SSL connections.
We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart-64.md), which uses an
up-to-date version of OpenSSL with hostname validation enabled.
If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit
with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to
man-in-the-middle attacks.
#### cloud-enabled is false
If `cloud-enabled` is `false`, you probably ran the installer with `--disable-cloud` option.
Additionally, check that the `enabled` setting in `var/lib/netdata/cloud.d/cloud.conf` is set to `true`:
```conf
[global]
enabled = true
```
To fix this issue, reinstall Netdata using your [preferred method](/packaging/installer/README.md) and do not add the
`--disable-cloud` option.
#### cloud-available is false / ACLK Available: No
If `cloud-available` is `false` after you verified Cloud is enabled in the previous step, the most likely issue is that
Cloud features failed to build during installation.
If Cloud features fail to build, the installer continues and finishes the process without Cloud functionality as opposed
to failing the installation altogether. We do this to ensure the Agent will always finish installing.
If you can't see an explicit error in the installer's output, you can run the installer with the `--require-cloud`
option. This option causes the installation to fail if Cloud functionality can't be built and enabled, and the
installer's output should give you more error details.
You may see one of the following error messages during installation:
- Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to
Netdata Cloud.
- Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect
this node to Netdata Cloud.
- Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to
Netdata Cloud.
- Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect
this node to Netdata Cloud.
- Could not find cmake, which is required to build libwebsockets. The install process will continue, but you may not
be able to connect this node to Netdata Cloud.
- Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud
support will be disabled.
- Failed to build JSON-C. Netdata Cloud support will be disabled.
- Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled.
One common cause of the installer failing to build Cloud features is not having one of the following dependencies on
your system: `cmake`, `json-c` and `OpenSSL`, including corresponding `devel` packages.
You can also look for error messages in `/var/log/netdata/error.log`. Try one of the following two commands to search
for ACLK-related errors.
```bash
less /var/log/netdata/error.log
grep -i ACLK /var/log/netdata/error.log
```
If the installer's output does not help you enable Cloud features, contact us by [creating an issue on
GitHub](https://github.com/netdata/netdata/issues/new?labels=bug%2C+needs+triage%2C+ACLK&template=bug_report.md&title=The+installer+failed+to+prepare+the+required+dependencies+for+Netdata+Cloud+functionality)
with details about your system and relevant output from `error.log`.
#### agent-claimed is false / Claimed: No
You must [connect your node](#how-to-connect-a-node).
#### aclk-available is false / Online: No
If `aclk-available` is `false` and all other keys are `true`, your Agent is having trouble connecting to the Cloud
through the ACLK. Please check your system's firewall.
If your Agent needs to use a proxy to access the internet, you must [set up a proxy for
connecting](#connect-through-a-proxy).
If you are certain firewall and proxy settings are not the issue, you should consult the Agent's `error.log` at
`/var/log/netdata/error.log` and contact us by [creating an issue on
GitHub](https://github.com/netdata/netdata/issues/new?labels=bug%2C+needs+triage%2C+ACLK&template=bug_report.md&title=ACLK-available-is-false)
with details about your system and relevant output from `error.log`.
### Remove and reconnect a node
To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory.
```bash
cd /var/lib/netdata # Replace with your Netdata library directory, if not /var/lib/netdata/
sudo rm -rf cloud.d/
```
This node no longer has access to the credentials it was used when connecting to Netdata Cloud via the ACLK.
You will still be able to see this node in your War Rooms in an **unreachable** state.
If you want to reconnect this node, you need to create a new identity by adding `-id=$(uuidgen)` to
the claiming script parameters (not yet supported on the
|