Connect Agent to Cloud
This section guides you through installing and securely connecting a new Netdata Agent to Netdata Cloud via the encrypted Agent-Cloud Link (ACLK). Connecting your agent to Netdata Cloud unlocks additional features like centralized monitoring and easier collaboration.
Connect
Install and Connect a New Agent
There are two places in the UI where you can add/connect your Node:
- Space/Room settings: Click the cogwheel (the bottom-left corner or next to the Room name at the top) and select "Nodes." Click the "+" button to add a new node.
- Nodes tab: Click on the "Add nodes" button.
Netdata Cloud will generate a command that you can execute on your Node to install and claim the Agent. The command is available for different installation methods:
Method | Description |
---|---|
Linux/FreeBSD/macOS | Install directly using the kickstart.sh script. |
Docker | Install as a container using the provided docker run command or YAML files (Docker Compose/Swarm). |
Kubernetes | Install inside the cluster using helm . Important: refer to the Kubernetes installation for detailed instructions. |
Once you've chosen your installation method, follow the provided instructions to install and connect the Agent.
Connect an Existing Agent
There are two methods to connect an already installed Netdata Agent to your Netdata Cloud Space:
- using the Netdata Cloud user interface (UI).
- using the claiming script.
Using the UI (recommended)
The UI method is the easiest and recommended way to connect your Agent. Here's how:
- Open your Agent local UI.
- Sign in to your Netdata Cloud account.
- Click the "Connect" button.
- Follow the on-screen instructions to connect your Agent.
Using claiming script
You can connect an Agent by running
the netdata-claim.sh script directly.
You can either run it with root privileges using sudo
or as the user running the Agent (typically netdata
).
The claiming script accepts options that control the connection process. You can specify these options using the following format:
netdata-claim.sh -OPTION=VALUE ...
Claiming script options:
Option | Description | Required | Default value |
---|---|---|---|
token | The claiming token for your Netdata Cloud Space. | yes | |
rooms | A comma-separated list of Rooms to add the Agent to. | no | The Agent will be added to the "All nodes" Room only. |
id | The unique identifier of the Agent. | no | The Agent's MACHINE_GUID. |
proxy | The URL of a proxy server to use for the connection, if necessary. | no |
Example:
netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2
This command connects the Agent and adds it to the "room1" and "room2" Rooms using your claiming token MYTOKEN1234567.
Reconnect
Linux based installations
To remove a node from your Space in Netdata Cloud, delete the cloud.d/
directory in your Netdata library directory.
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 Rooms in an unreachable state.
If you want to reconnect this node, you need to:
- Ensure that the
/var/lib/netdata/cloud.d
directory doesn't exist. In some installations, the path is/opt/netdata/var/lib/netdata/cloud.d
- Stop the Agent
- Ensure that the
uuidgen-runtime
package is installed. Runecho "$(uuidgen)"
and validate you get back a UUID - Copy the kickstart.sh command to add a node from your space and add to the end of it
--claim-id "$(uuidgen)"
. Run the command and look for the messageNode was successfully claimed.
- Start the Agent
Docker based installations
To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps:
Enter the running container you wish to remove from your Space
docker exec -it CONTAINER_NAME sh
Replacing
CONTAINER_NAME
with either the container's name or ID.Delete
/var/lib/netdata/cloud.d
and/var/lib/netdata/registry/netdata.public.unique.id
rm -rf /var/lib/netdata/cloud.d/
rm /var/lib/netdata/registry/netdata.public.unique.idStop and remove the container
Docker CLI:
docker stop CONTAINER_NAME
docker rm CONTAINER_NAMEReplacing
CONTAINER_NAME
with either the container's name or ID.Docker Compose:
Inside the directory that has thedocker-compose.yml
file, run:docker compose down
Docker Swarm:
Run the following, and replaceSTACK
with your Stack's name:docker stack rm STACK
Finally, go to your new Space, copy the installation command with the new claim token and run it.
If you are using adocker-compose.yml
file, you will have to overwrite it with the new claiming token.
The node should now appear online in that Space.
Regenerate Claiming Token
If in case of some security reason, or other, you need to revoke your previous claiming token and generate a new one you can achieve that from the Netdata Cloud UI.
On any screen where you see the connect the node to Netdata Cloud command you'll see above it, next to the updates channel, a button to Regenerate token. This action will invalidate your previous token and generate a fresh new one.
Only the administrators of a Space in Netdata Cloud can trigger this action.
Troubleshoot
If you're having trouble connecting a node, this may be because the ACLK 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.
"cloud-enabled"
"cloud-available"
"agent-claimed"
"aclk-available"
Note
On Netdata Agent version
1.32
(netdata -v
to find your version) and newer,sudo netdatacli aclk-state
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.
Note
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
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:
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.
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-prefix
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.
Note
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
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, which helps securely encrypt SSL connections.
We recommend you reinstall Netdata with a static build, 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
:
[global]
enabled = true
To fix this issue, reinstall Netdata using
your preferred method 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.
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
with details about your system and relevant output from error.log
.
agent-claimed is false / Claimed: No
You must connect your 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.
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
with details about your system and relevant output from error.log
.
Connecting reference
In the sections below, you can find reference material for the kickstart script, claiming script, connecting via the
Agent's command line tool, and details about the files found in cloud.d
.
The cloud.conf
file
This section defines how and whether your Agent connects to Netdata Cloud using the Agent-Cloud link(ACLK).
setting | default | info |
---|---|---|
enabled | yes | Controls whether the ACLK is active. Set to no to prevent the Agent from connecting to Netdata Cloud. |
cloud base url | https://app.netdata.cloud | The URL for the Netdata Cloud web application. Typically, this should not be changed. |
proxy | env | Specifies the proxy setting for the ACLK. Options: none (no proxy), env (use environment's proxy), or a URL (e.g., http://proxy.example.com:1080 ). |
Connection directory
Netdata stores the Agent's connection-related state in the Netdata library directory under cloud.d
. For a default
installation, this directory exists at /var/lib/netdata/cloud.d
. The directory and its files should be owned by the
user that runs the Agent, which is typically the netdata
user.
The cloud.d/token
file should contain the claiming-token and the cloud.d/rooms
file should contain the list of War
Rooms you added that node to.
The user can also put the Cloud endpoint's full certificate chain in cloud.d/cloud_fullchain.pem
so that the Agent
can trust the endpoint if necessary.
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.