Agent claiming is part of the onboarding process when creating a workspace in Netdata Cloud. Each workspace gets its own common invitation mechanism, which begins with the administrators of the workspace creating a claiming-token. They, or other users is their organization, can then use the claiming-token to add an agent to their workspace.

To claim a Netdata agent, you first send a claiming request to Netdata Cloud (from the agent node). Once the Netdata Cloud validates the claiming request of the agent (based on the claiming token), and returns a successful result, the node is considered claimed.

The user can claim an agent by directly calling the netdata-claim.sh script as the netdata user and passing the following arguments:

-token=TOKEN
    where TOKEN is the workspace claiming-token.
-rooms=ROOM1,ROOM2,...
    where ROOMX is the workspace war-room to join. This list is optional.
-url=URL_BASE
    where URL_BASE is the Netdata Cloud endpoint base URL. By default, this is https://netdata.cloud.
-id=AGENT_ID
    where AGENT_ID is the unique identifier of the agent. This is the agent's MACHINE_GUID by default.
-hostname=HOSTNAME
    where HOSTNAME is the result of the hostname command by default.

For example, the following command claims an agent and adds it to rooms room1 and room2:

netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2

You should then update the netdata service about the result with netdatacli:

netdatacli reload-claiming-state

This reloads the agent claiming state from disk.

The user can trigger agent claiming by calling the netdata service binary with the additional command line parameters:

-W "claim -token=TOKEN -rooms=ROOM1,ROOM2"

For example:

/usr/sbin/netdata -D -W "claim -token=MYTOKEN1234567 -rooms=room1,room2"

If need be, the user can override the agent's defaults by providing additional arguments like those described here.

Netdata stores the agent claiming-related state in the user configuration directory under claim.d, e.g. in /etc/netdata/claim.d. The user can put files in this directory to provide defaults to the -token and -rooms arguments. These files should be owned by the netdata user.

The claim.d/token file should contain the claiming-token and the claim.d/rooms file should contain the list of war-rooms.

The user can also put the Cloud endpoint's full certificate chain in claim.d/cloud_fullchain.pem so that the agent can trust the endpoint if necessary.