0817b8822 · cryptotaxi247/netdata-1

@@ -1,381 +1,164 @@

1 # Connect Agent to Cloud

2

3 -This guide walks you through the process of securely connecting a Netdata Agent to Netdata Cloud via the encrypted

4 -Agent-Cloud Link ([ACLK](/src/aclk/README.md)).

3 +This section guides you through installing and securely connecting a new Netdata Agent to Netdata Cloud via the

4 +encrypted Agent-Cloud Link ([ACLK](/src/aclk/README.md)). Connecting your agent to Netdata Cloud unlocks additional

5 +features like centralized monitoring and easier collaboration.

6

6 -When connecting an Agent (also known as a node) to Netdata Cloud, it's essential to complete a verification process.

7 -This process ensures that you have the necessary authorization level to manage the node effectively. Verification serves

8 -as a crucial security measure, preventing unauthorized access to the data on your node. Note that only administrators of

9 -a Space in Netdata Cloud can access the claiming token and the corresponding script generated by Netdata Cloud.

7 +## Connect

8

11 -> **Info**

12 ->

13 -> The connection process guarantees that no third party can add your node to a Cloud account, Space, or War Room without

14 -> your authorization, thus preventing unauthorized access to your node's metrics.

15 -

16 -When you connect your node, its data is securely sent to Netdata Cloud using ACLK. We verify your agent's identity and

17 -can access the data only while it's being transferred. Netdata Cloud does not store or log your monitoring data

18 -

19 -There are several ways to connect your node to Netdata Cloud:

20 -

21 -- During Netdata Cloud onboarding: This is the easiest option if you're just getting started.

22 -- From your Space: Click on "Connect Nodes" in the Space's left sidebar.

23 -- Prompts within the app: Look out for prompts to connect nodes throughout the Netdata Cloud app.

24 -

25 -> **Note**

26 ->

27 -> Each node can be connected to a single Space in Netdata Cloud. However, you can add that connected node to multiple

28 -> War Rooms within the same Space. You'll need to repeat the connection process for each additional node you want to

29 -> monitor.

9 +### Install and Connect a New Agent

10

31 -## How to connect a node

11 +There are two places in the UI where you can add/connect your Node:

12

33 -There are three main ways to connect your node to Netdata Cloud:

13 +- **Space/Room settings**: Click the cogwheel (the bottom-left corner or next to the War Room name at the top) and

14 + select "Nodes." Click the "+" button to add

15 + a new node.

16 +- [**Nodes tab**](/docs/dashboards-and-charts/nodes-tab.md): Click on the "Add nodes" button.

17

35 -- From your [War Room](#empty-war-room): This is ideal if you're setting up your first node and want to start monitoring

36 - right away.

37 -- From the [Space Management screen](#manage-space-or-war-room-area): Click "Connect Nodes" to add a new node to your

38 - existing Space.

39 -- From the [Nodes tab](/docs/dashboards-and-charts/nodes-tab.md): While you can see

40 - connected nodes here, the connection process itself happens in the Space Management screen.

18 +Netdata Cloud will generate a command that you can execute on your Node to install and claim the Agent. The command is

19 +available for different installation methods:

20

42 -### Empty War Room

21 +| Method | Description |

22 +|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

23 +| Linux/FreeBSD/macOS | Install directly using the [kickstart.sh](/packaging/installer/methods/kickstart.md) script. |

24 +| Docker | Install as a container using the provided docker run command or YAML files (Docker Compose/Swarm). |

25 +| Kubernetes | Install inside the cluster using `helm`. **Important**: refer to the [Kubernetes installation](/packaging/installer/methods/kubernetes.md#deploy-netdata-on-your-kubernetes-cluster) for detailed instructions. |

26

44 -When you enter a War Room with no nodes, you can either:

27 +Once you've chosen your installation method, follow the provided instructions to install and connect the Agent.

28

46 -1. Connect a New Node: Netdata Cloud will guide you through connecting a new node directly to the War Room. Simply

47 - select the environment where your node is running (e.g., Linux, Docker). Once you select the environment,

48 - Netdata Cloud will generate a unique script. Copy and paste the script into your terminal.

49 -2. Add a Previously Connected Node: If you already have a node connected to Netdata Cloud, you can easily add it to this

50 - War Room.

29 +### Connect an Existing Agent

30

52 -Once you've chosen your option, refer to the specific instructions for your environment:

31 +There are two methods to connect an already installed Netdata Agent to your Netdata Cloud Space:

32

54 -- [Linux](#connect-an-agent-running-in-linux)

55 -- [Docker](#connect-an-agent-running-in-docker)

56 -- [macOS](#connect-an-agent-running-in-macos)

57 -- [Kubernetes](#connect-a-kubernetes-clusters-parent-netdata-pod)

33 +- using the Netdata Cloud user interface (UI).

34 +- using the claiming script.

35

59 -This process can be repeated for each additional node you want to monitor in Netdata Cloud. You can add nodes during the

60 -initial onboarding process or afterward.

36 +#### Using the UI (recommended)

37

62 -### Manage Space or War Room area

38 +The UI method is the easiest and recommended way to connect your Agent. Here's how:

39

64 -Accessing Management screens:

40 +1. Open your Agent local UI.

41 +2. Sign in to your Netdata Cloud account.

42 +3. Click the "Connect to netdata" button.

43 +4. Follow the on-screen instructions to connect your Agent.

44

66 -- Space Management: Click the cogwheel icon in the bottom-left corner of the UI.

67 -- War Room Management: Click the cogwheel icon next to the War Room name at the top of the UI.

45 +#### Using claiming script

46

69 -Connecting a Node to a War Room:

47 +You can connect an Agent by running

48 +the [netdata-claim.sh](https://github.com/netdata/netdata/blob/master/src/claim/netdata-claim.sh.in) script directly.

49 +You can either run it with root privileges using `sudo` or as the user running the Agent (typically `netdata`).

50

71 -1. Select War Rooms: Choose which War Rooms you want to add the node to using the dropdown menu.

72 -2. Copy and Paste Script: Netdata Cloud will generate a script. Copy the entire script and paste it into your node's

73 - terminal window. Press Enter to initiate the connection process.

74 -

75 -> Note: When connecting from

76 -> the [Nodes tab](/docs/dashboards-and-charts/nodes-tab.md), the room parameter will

77 -> be

78 -> set to the current War Room.

79 -

80 -### Connect an Agent running in Linux

81 -

82 -Netdata Cloud provides a script called kickstart.sh to simplify the process of connecting your Linux node. This script

83 -performs two key actions:

84 -

85 -1. Installs the Netdata Agent (if needed): If the Netdata Agent isn't already installed on your Linux node, the script

86 - will take care of the installation process.

87 -2. Connects the Node to Netdata Cloud: The script will securely connect your node to Netdata Cloud, allowing you to

88 - monitor its performance.

89 -

90 -It should be similar to:

51 +The claiming script accepts options that control the connection process. You can specify these options using the

52 +following format:

53

54 ```bash

93 -wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud

55 +netdata-claim.sh -OPTION=VALUE ...

56 ```

57

96 -Copy and paste the entire script provided by Netdata Cloud into your terminal window and press Enter.

97 -

98 -If successful, you should see a message like "Agent was successfully claimed."

99 -

100 -If you encounter any errors during the process, or the node doesn't appear in your Space within 60 seconds, refer

101 -to the [troubleshooting information section](#troubleshooting).

102 -

103 -To run the script, you'll need either root privileges or to run it as the user that runs the Netdata Agent on your node.

104 -Refer to the [Connect an Agent without root privileges section](#connect-an-agent-without-root-privileges) for more

105 -details.

106 -

107 -For in-depth information about the optional parameters `--claim-token`, `--claim-rooms`, and `--claim-url`,

108 -see [Connect node to Netdata Cloud during installation](/packaging/installer/methods/kickstart.md#connect-node-to-netdata-cloud-during-installation).

109 -

110 -### Connect an Agent without root privileges

111 -

112 -If you don't have root access, you can still connect your node to Netdata Cloud by following these steps:

113 -

114 -1. Identify the Netdata Agent User: Use the `grep` command to search your `netdata.conf` file which is located at

115 - your [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory)

116 - and find the `run as user` setting. This will tell you which user is running the Netdata Agent.

117 - ```bash

118 - grep "run as user" /etc/netdata/netdata.conf

119 - # run as user = netdata

120 - ```

121 -2. Switch User: Use the `sudo su - username -s /bin/bash` command (replacing `username` with the identified user) to

122 - switch to the

123 - Netdata Agent user account. For example, if the `run as user` setting pointed to `netdata`, you would

124 - use `sudo su - netdata -s /bin/bash`.

125 -3. Run the Script: Once switched to the correct user, copy and paste the script provided by Netdata Cloud into the

126 - terminal and press Enter.

127 -

128 -### Connect an Agent running in Docker

129 -

130 -To ensure the **configuration and state information** needed for the Cloud connection is preserved across container

131 -restarts, the contents of the `/var/lib/netdata` directory must be persisted. See

132 -our [documentation](/packaging/docker/README.md#recommended-way) for

133 -details on using persistent volumes.

134 -

135 -<details>

136 -<summary>Known issues on older hosts with seccomp enabled</summary>

137 -

138 -The nodes running on the following hosts **cannot be claimed**:

58 +Claiming script options:

59

140 -- `libseccomp` version less than v2.3.3.

141 -- Docker version less than v18.04.0-ce.

142 -- The kernel is configured with CONFIG_SECCOMP enabled.

61 +|--------|--------------------------------------------------------------------|:--------:|:------------------------------------------------------|

62 +| token | The claiming token for your Netdata Cloud Space. | yes | |

64 +| id | The unique identifier of the Agent. | no | The Agent's MACHINE_GUID. |

65 +| proxy | The URL of a proxy server to use for the connection, if necessary. | no | |

66

144 -To check if your kernel supports `seccomp`:

145 -

146 -```cmd

147 -# grep CONFIG_SECCOMP= /boot/config-$(uname -r) 2>/dev/null || zgrep CONFIG_SECCOMP /proc/config.gz 2>/dev/null

148 -CONFIG_SECCOMP=y

149 -```

150 -

151 -To resolve the issue, do one of the following actions:

152 -

153 -- Update to a newer version of Docker and `libseccomp` (recommended).

154 -- Run without the default seccomp profile (unsafe, not recommended). You can

155 - pass [unconfined](https://docs.docker.com/engine/security/seccomp/#run-without-the-default-seccomp-profile) to run a

156 - container without the default seccomp profile.

157 -- Create a custom profile and pass it for the container.

158 - - Download the moby default seccomp profile and change `defaultAction` to `SCMP_ACT_TRACE` on line 2.

159 -

160 - ```cmd

161 - sudo wget https://raw.githubusercontent.com/moby/moby/master/profiles/seccomp/default.json -O /etc/docker/seccomp.json

162 - sudo sed -i '2s/SCMP_ACT_ERRNO/SCMP_ACT_TRACE/' /etc/docker/seccomp.json

163 - ```

164 - - Specify the new policy for the container explicitly.

165 - - When using `docker run`:

166 - ```cmd

167 - docker run -d --name=netdata \

168 - --security-opt=seccomp=/etc/docker/seccomp.json \

169 - ...

170 - ```

171 - - When using `docker-compose`:

172 - > :warning: The security_opt option is ignored when deploying a stack in swarm mode.

173 -

174 - ```yaml

175 - version: '3'

176 - services:

177 - netdata:

178 - security_opt:

179 - - seccomp:/etc/docker/seccomp.json

180 - ```

181 - - When using `docker stack deploy`: Change the default profile globally by

182 - adding `--seccomp-profile=/etc/docker/seccomp.json` to the options passed to

183 - dockerd on startup.

184 -

185 -</details>

186 -

187 -There are two main approaches to connect a Netdata Agent running inside a Docker container to Netdata Cloud:

188 -

189 -1. Connecting New Agents (Automatic):

190 - - This method is ideal for new container deployments.

191 - - You can configure the connection automatically during startup by setting specific environment variables within

192 - your Docker container.

193 -

194 -2. Connecting Existing Agents (Manual). This method is used for existing containers that haven't been connected yet:

195 - - Using the Agent UI: The Netdata Agent UI provides a "Connect to netdata" button. Click on it and follow the

196 - on-screen instructions.

197 - - Executing Claiming Script Directly (Advanced): For advanced users, you can connect an existing Agent by executing

198 - the claiming script directly within the container using the `docker exec` command.

199 -

200 -#### Using environment variables

201 -

202 -The Netdata Docker container looks for the following environment variables on startup:

203 -

204 -- `NETDATA_CLAIM_TOKEN`

205 -- `NETDATA_CLAIM_URL`

206 -- `NETDATA_CLAIM_ROOMS`

207 -- `NETDATA_CLAIM_PROXY`

208 -

209 -If the token and URL are specified in their corresponding variables _and_ the container is not already connected, it

210 -will use these values to attempt to connect to Netdata Cloud, automatically adding the node to the specified War Rooms.

211 -

212 -If a proxy is specified, it will be used for the connection process and for connecting to Netdata Cloud.

213 -

214 -These variables can be specified using any mechanism supported by your container tooling for setting environment

215 -variables inside containers.

216 -

217 -When using the `docker run` script, if you have an Agent container already running, it is important to know that there

218 -will be a short period of downtime. This is due to the process of recreating the new Agent container.

219 -

220 -The script to connect a new node to Netdata Cloud is:

67 +Example:

68

69 ```bash

223 -docker run -d --name=netdata \

224 - -p 19999:19999 \

225 - -v netdataconfig:/etc/netdata \

226 - -v netdatalib:/var/lib/netdata \

227 - -v netdatacache:/var/cache/netdata \

228 - -v /etc/passwd:/host/etc/passwd:ro \

229 - -v /etc/group:/host/etc/group:ro \

230 - -v /proc:/host/proc:ro \

231 - -v /sys:/host/sys:ro \

232 - -v /etc/os-release:/host/etc/os-release:ro \

233 - --restart unless-stopped \

234 - --cap-add SYS_PTRACE \

235 - --security-opt apparmor=unconfined \

236 - -e NETDATA_CLAIM_TOKEN=TOKEN \

237 - -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \

238 - -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \

239 - -e NETDATA_CLAIM_PROXY=PROXY \

240 - netdata/netdata

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

71 ```

72

243 -> Note: This command is suggested for connecting a new container. Using this command for an existing container recreates

244 -> the container, though data and configuration of the old container may be preserved.

245 ->

246 ->If you are claiming an existing container that can not be recreated, you can add the container by going to Netdata

247 -> Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and following the instructions

248 -> and

249 -> scripts provided, or by following the instructions in an [empty War Room](#empty-war-room).

250 -

251 -The output that would be seen from the connection process when using other methods will be present in the container

252 -logs.

73 +This command connects the Agent and adds it to the "room1" and "room2" War Rooms using your claiming token

74 +MYTOKEN1234567.

75

254 -Using the environment variables like this to handle the connection process is the preferred method of connecting Docker

255 -containers as it works in the widest variety of situations and simplifies configuration management.

76 +## Reconnect

77

257 -#### Using Docker compose

78 +### Linux based installations

79

259 -If you use `docker compose`, you can copy the config provided by Netdata Cloud, which should be same as the one below:

80 +To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory.

81

82 ```bash

262 -version: '3'

263 -services:

264 - netdata:

265 - image: netdata/netdata

266 - container_name: netdata

267 - hostname: example.com # set to fqdn of host

268 - ports:

269 - - 19999:19999

270 - restart: unless-stopped

271 - cap_add:

272 - - SYS_PTRACE

273 - security_opt:

274 - - apparmor:unconfined

275 - volumes:

276 - - netdataconfig:/etc/netdata

277 - - netdatalib:/var/lib/netdata

278 - - netdatacache:/var/cache/netdata

279 - - /etc/passwd:/host/etc/passwd:ro

280 - - /etc/group:/host/etc/group:ro

281 - - /proc:/host/proc:ro

282 - - /sys:/host/sys:ro

283 - - /etc/os-release:/host/etc/os-release:ro

284 - environment:

285 - - NETDATA_CLAIM_TOKEN=TOKEN

286 - - NETDATA_CLAIM_URL="https://app.netdata.cloud"

287 - - NETDATA_CLAIM_ROOMS=ROOM1,ROOM2

288 -

289 -volumes:

290 - netdataconfig:

291 - netdatalib:

292 - netdatacache:

83 +cd /var/lib/netdata # Replace with your Netdata library directory, if not /var/lib/netdata/

84 +sudo rm -rf cloud.d/

85 ```

86

295 -Then run the following command in the same directory as the `docker-compose.yml` file to start the container.

296 -

297 -```bash

298 -docker-compose up -d

299 -```

87 +This node no longer has access to the credentials it was used when connecting to Netdata Cloud via the ACLK. You will

88 +still be able to see this node in your War Rooms in an **unreachable** state.

89

301 -#### Using docker exec

90 +If you want to reconnect this node, you need to:

91

303 -In order to connect a _running Netdata Agent container_, where you don't want to recreate the existing container, append

304 -the script offered by Netdata Cloud to a `docker exec ...` command, replacing `netdata` with the name of your running

305 -container:

92 +1. Ensure that the `/var/lib/netdata/cloud.d` directory doesn't exist. In some installations, the path

93 + is `/opt/netdata/var/lib/netdata/cloud.d`

94 +2. Stop the Agent

95 +3. Ensure that the `uuidgen-runtime` package is installed. Run ```echo "$(uuidgen)"``` and validate you get back a UUID

96 +4. Copy the kickstart.sh command to add a node from your space and add to the end of it `--claim-id "$(uuidgen)"`. Run

97 + the command and look for the message `Node was successfully claimed.`

98 +5. Start the Agent

99

307 -```bash

308 -docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud

309 -```

100 +### Docker based installations

101

311 -The values for `ROOM1,ROOM2` can be found in any add-node screens, at the top of the tab. Click on them to reveal them

312 -and copy them to your clipboard.

102 +To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps:

103

314 -The script should return `Agent was successfully claimed.`. If the connection process returns errors, or if you don't

315 -see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).

104 +1. Enter the running container you wish to remove from your Space

105

317 -### Connect an Agent running in macOS

106 + ```bash

107 + docker exec -it CONTAINER_NAME sh

108 + ```

109

319 -To connect a node that is running on a macOS environment the script that will be provided to you by Netdata Cloud is

320 -the [kickstart](/packaging/installer/methods/macos.md#install-netdata-with-our-automatic-one-line-installation-script)

321 -script which will install the Netdata Agent on your node, if it isn't already installed, and connect the node to Netdata

322 -Cloud. It should be similar to:

110 + Replacing `CONTAINER_NAME` with either the container's name or ID.

111

324 -```bash

325 -curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud

326 -```

112 +2. Delete `/var/lib/netdata/cloud.d` and `/var/lib/netdata/registry/netdata.public.unique.id`

113

328 -> **Note**

329 ->

330 -> Hit **Enter**. The script should return `Agent was successfully claimed.`. If the process returns errors, or if you

331 -> don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).

114 + ```bash

115 + rm -rf /var/lib/netdata/cloud.d/

116 +

117 + rm /var/lib/netdata/registry/netdata.public.unique.id

118 + ```

119

333 -### Connect a Kubernetes cluster's parent Netdata pod

120 +3. Stop and remove the container

121

335 -Read

336 -our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#deploy-netdata-on-your-kubernetes-cluster)

337 -for details on connecting a cluster's parent Netdata pod.

122 + **Docker CLI:**

123

339 -### Connect through a proxy

124 + ```bash

125 + docker stop CONTAINER_NAME

126 +

127 + docker rm CONTAINER_NAME

128 + ```

129

341 -A Space's administrator can connect a node through HTTP(S) proxy.

130 + Replacing `CONTAINER_NAME` with either the container's name or ID.

131

343 -You should first configure the proxy in the `[cloud]` section of `netdata.conf`. The proxy settings you specify here

344 -will also be used to tunnel the ACLK. The default `proxy` setting is `none`.

132 + **Docker Compose:**

133 + Inside the directory that has the `docker-compose.yml` file, run:

134

346 -```conf

347 -[cloud]

348 - proxy = none

349 -```

135 + ```bash

136 + docker compose down

137 + ```

138

351 -The `proxy` setting can take one of the following values:

139 + **Docker Swarm:**

140 + Run the following, and replace `STACK` with your Stack's name:

141

353 -- `none`: Do not use a proxy, even if the system configured otherwise.

354 -- `env`: Try to read proxy settings from set environment variables `http_proxy`.

355 -- `http://[user:pass@]host:ip`: The ACLK and connection process will use the specified HTTP(S) proxy.

142 + ```bash

143 + docker stack rm STACK

144 + ```

145

357 -For example, a HTTP proxy setting may look like the following:

146 +4. Finally, go to your new Space, copy the installation command with the new claim token and run it.

147 + If you are using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token.

148 + The node should now appear online in that Space.

149

359 -```conf

360 -[cloud]

361 - proxy = http://203.0.113.0:1080 # With an IP address

362 - proxy = http://proxy.example.com:1080 # With a URL

363 -```

150 +## Regenerate Claiming Token

151

365 -You can now move on to connecting. When you connect with

366 -the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script)

367 -script, add the `--claim-proxy=` parameter and append the same proxy setting you added to `netdata.conf`.

152 +If in case of some security reason, or other, you need to revoke your previous claiming token and generate a new one you

153 +can achieve that from the Netdata Cloud UI.

154

369 -```bash

370 -wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud --claim-proxy http://[user:pass@]host:ip

371 -```

155 +On any screen where you see the connect the node to Netdata Cloud command you'll see above it, next to

156 +the [updates channel](/docs/netdata-agent/versions-and-platforms.md), a

157 +button to **Regenerate token**. This action will invalidate your previous token and generate a fresh new one.

158

373 -> **Note**

374 ->

375 -> Hit **Enter**. The script should return `Agent was successfully claimed.`. If the process returns errors, or if you

376 -> don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).

159 +Only the administrators of a Space in Netdata Cloud can trigger this action.

160

378 -### Troubleshooting

161 +## Troubleshoot

162

163 If you're having trouble connecting a node, this may be because

164 the [ACLK](/src/aclk/README.md) cannot connect to Cloud.

@@ -384,8 +167,8 @@ With the Netdata Agent running, visit `http://NODE:19999/api/v1/info` in your br

167 address or hostname of your Agent. The returned JSON contains four keys that will be helpful to diagnose any issues you

168 might be having with the ACLK or connection process.

169

387 -```json

388 - "cloud-enabled"

170 +```

171 +"cloud-enabled"

172 "cloud-available"

173 "agent-claimed"

174 "aclk-available"

@@ -408,7 +191,7 @@ Used Cloud Protocol: New

191

192 Use these keys and the information below to troubleshoot the ACLK.

193

411 -#### kickstart: unsupported Netdata installation

194 +### kickstart: unsupported Netdata installation

195

196 If you run the kickstart script and get the following

197 error `Existing install appears to be handled manually or through the system package manager.` you most probably

@@ -419,9 +202,9 @@ installed Netdata using an unsupported package.

202 > If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,

203 > please remove that package and reinstall using

204 >

422 -our [recommended kickstart script](/packaging/installer/README.md#install-on-linux-with-one-line-installer).

205 +our [recommended kickstart script](/packaging/installer/methods/kickstart.md).

206

424 -#### kickstart: Failed to write new machine GUID

207 +### kickstart: Failed to write new machine GUID

208

209 If you run the kickstart script but don't have privileges required for the actions done on the connecting to Netdata

210 Cloud process you will get the following error:

@@ -431,10 +214,9 @@ Failed to write new machine GUID. Please make sure you have rights to write to /

214 ```

215

216 For a successful execution you will need to run the script with root privileges or run it with the user that is running

434 -the Agent, more details on the [Connect an Agent without root privileges](#connect-an-agent-without-root-privileges)

435 -section.

217 +the Agent.

218

437 -#### bash: netdata-claim.sh: command not found

219 +### bash: netdata-claim.sh: command not found

220

221 If you run the claiming script and see a `command not found` error, you either installed Netdata in a non-standard

222 location or are using an unsupported package. If you installed Netdata in a non-standard path using

@@ -448,9 +230,9 @@ script.

230 > If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,

231 > please remove that package and reinstall using

232 >

451 -our [recommended kickstart script](/packaging/installer/README.md#install-on-linux-with-one-line-installer).

233 +our [recommended kickstart script](/packaging/installer/methods/kickstart.md).

234

453 -#### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)

235 +### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)

236

237 If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS

238 6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old

@@ -465,7 +247,7 @@ If you choose to continue using the outdated version of OpenSSL, your node will

247 with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to

248 man-in-the-middle attacks.

249

468 -#### cloud-enabled is false

250 +### cloud-enabled is false

251

252 If `cloud-enabled` is `false`, you probably ran the installer with `--disable-cloud` option.

253

@@ -480,7 +262,7 @@ To fix this issue, reinstall Netdata using

262 your [preferred method](/packaging/installer/README.md) and do not add

263 the `--disable-cloud` option.

264

483 -#### cloud-available is false / ACLK Available: No

265 +### cloud-available is false / ACLK Available: No

266

267 If `cloud-available` is `false` after you verified Cloud is enabled in the previous step, the most likely issue is that

268 Cloud features failed to build during installation.

@@ -520,108 +302,22 @@ If the installer's output does not help you enable Cloud features, contact us

302 by [creating an issue on GitHub](https://github.com/netdata/netdata/issues/new?assignees=&labels=bug%2Cneeds+triage&template=BUG_REPORT.yml&title=The+installer+failed+to+prepare+the+required+dependencies+for+Netdata+Cloud+functionality)

303 with details about your system and relevant output from `error.log`.

304

523 -#### agent-claimed is false / Claimed: No

305 +### agent-claimed is false / Claimed: No

306

525 -You must [connect your node](#how-to-connect-a-node).

307 +You must [connect your node](#connect).

308

527 -#### aclk-available is false / Online: No

309 +### aclk-available is false / Online: No

310

311 If `aclk-available` is `false` and all other keys are `true`, your Agent is having trouble connecting to the Cloud

312 through the ACLK. Please check your system's firewall.

313

532 -If your Agent needs to use a proxy to access the internet, you

533 -must [set up a proxy for connecting](#connect-through-a-proxy).

314 +If your Agent needs to use a proxy to access the internet, you must set up a proxy for connecting.

315

316 If you are certain firewall and proxy settings are not the issue, you should consult the Agent's `error.log`

317 at `/var/log/netdata/error.log` and contact us

318 by [creating an issue on GitHub](https://github.com/netdata/netdata/issues/new?assignees=&labels=bug%2Cneeds+triage&template=BUG_REPORT.yml&title=ACLK-available-is-false)

319 with details about your system and relevant output from `error.log`.

320

540 -### Remove and reconnect a node

541 -

542 -#### Linux based installations

543 -

544 -To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory.

545 -

546 -```bash

547 -cd /var/lib/netdata # Replace with your Netdata library directory, if not /var/lib/netdata/

548 -sudo rm -rf cloud.d/

549 -```

550 -

551 -This node no longer has access to the credentials it was used when connecting to Netdata Cloud via the ACLK. You will

552 -still be able to see this node in your War Rooms in an **unreachable** state.

553 -

554 -If you want to reconnect this node, you need to:

555 -

556 -1. Ensure that the `/var/lib/netdata/cloud.d` directory doesn't exist. In some installations, the path

557 - is `/opt/netdata/var/lib/netdata/cloud.d`

558 -2. Stop the Agent

559 -3. Ensure that the `uuidgen-runtime` package is installed. Run ```echo "$(uuidgen)"``` and validate you get back a UUID

560 -4. Copy the kickstart.sh command to add a node from your space and add to the end of it `--claim-id "$(uuidgen)"`. Run

561 - the command and look for the message `Node was successfully claimed.`

562 -5. Start the Agent

563 -

564 -#### Docker based installations

565 -

566 -To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps:

567 -

568 -1. Enter the running container you wish to remove from your Space

569 -

570 - ```bash

571 - docker exec -it CONTAINER_NAME sh

572 - ```

573 -

574 - Replacing `CONTAINER_NAME` with either the container's name or ID.

575 -

576 -2. Delete `/var/lib/netdata/cloud.d` and `/var/lib/netdata/registry/netdata.public.unique.id`

577 -

578 - ```bash

579 - rm -rf /var/lib/netdata/cloud.d/

580 -

581 - rm /var/lib/netdata/registry/netdata.public.unique.id

582 - ```

583 -

584 -3. Stop and remove the container

585 -

586 - **Docker CLI:**

587 -

588 - ```bash

589 - docker stop CONTAINER_NAME

590 -

591 - docker rm CONTAINER_NAME

592 - ```

593 -

594 - Replacing `CONTAINER_NAME` with either the container's name or ID.

595 -

596 - **Docker Compose:**

597 - Inside the directory that has the `docker-compose.yml` file, run:

598 -

599 - ```bash

600 - docker compose down

601 - ```

602 -

603 - **Docker Swarm:**

604 - Run the following, and replace `STACK` with your Stack's name:

605 -

606 - ```bash

607 - docker stack rm STACK

608 - ```

609 -

610 -4. Finally, go to your new Space, copy the install command with the new claim token and run it.

611 - If you are using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token.

612 - The node should now appear online in that Space.

613 -

614 -### Regenerate Claiming Token

615 -

616 -If in case of some security reason, or other, you need to revoke your previous claiming token and generate a new one you

617 -can achieve that from the Netdata Cloud UI.

618 -

619 -On any screen where you see the connect the node to Netdata Cloud command you'll see above it, next to

620 -the [updates channel](/docs/netdata-agent/versions-and-platforms.md), a

621 -button to **Regenerate token**. This action will invalidate your previous token and generate a fresh new one.

622 -

623 -Only the administrators of a Space in Netdata Cloud can trigger this action.

624 -

321 ## Connecting reference

322

323 In the sections below, you can find reference material for the kickstart script, claiming script, connecting via the

@@ -632,67 +328,10 @@ Agent's command line tool, and details about the files found in `cloud.d`.

328 This section defines how and whether your Agent connects to Netdata Cloud

329 using the [ACLK](/src/aclk/README.md).

330

635 -| setting | default | info |

636 -|:---------------|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

637 -| cloud base url | <https://app.netdata.cloud> | The URL for the Netdata Cloud web application. You should not change this. If you want to disable Cloud, change the `enabled` setting. |

638 -| enabled | yes | The runtime option to disable the [Agent-Cloud link](/src/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. |

639 -

640 -### Claiming script

641 -

642 -A Space's administrator can also connect an Agent by directly calling the `netdata-claim.sh` script either with root

643 -privileges

644 -using `sudo`, or as the user running the Agent (typically `netdata`), and passing the following arguments:

645 -

646 -```sh

647 --token=TOKEN

648 - where TOKEN is the Space's claiming token.

649 --rooms=ROOM1,ROOM2,...

650 - where ROOMX is the War Room this node should be added to. This list is optional.

651 --url=URL_BASE

652 - where URL_BASE is the Netdata Cloud endpoint base URL. By default, this is https://app.netdata.cloud.

653 --id=AGENT_ID

654 - where AGENT_ID is the unique identifier of the Agent. This is the Agent's MACHINE_GUID by default.

655 --hostname=HOSTNAME

656 - where HOSTNAME is the result of the hostname command by default.

657 --proxy=PROXY_URL

658 - where PROXY_URL is the endpoint of a HTTP or HTTPS proxy.

659 -```

660 -

661 -For example, the following command connects an Agent and adds it to rooms `room1` and `room2`:

662 -

663 -```sh

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

665 -```

666 -

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

668 -

669 -```sh

670 -netdatacli reload-claiming-state

671 -```

672 -

673 -This reloads the Agent connection state from disk.

674 -

675 -Our recommendation is to trigger the connection process using

676 -the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script)

677 -whenever possible.

678 -

679 -### Netdata Agent command line

680 -

681 -If a Netdata Agent is running, the Space's administrator can connect a node using the `netdata` service binary with

682 -additional command line parameters:

683 -

684 -```sh

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

686 -```

687 -

688 -For example:

689 -

690 -```sh

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

692 -```

693 -

694 -If need be, the user can override the Agent's defaults by providing additional arguments like those described

695 -[here](#claiming-script).

331 +| setting | default | info |

332 +|:---------------|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------------------|

333 +| cloud base url | <https://app.netdata.cloud> | The URL for the Netdata Cloud web application. You should not change this. If you want to disable Cloud, change the `enabled` setting. |

334 +| enabled | yes | The runtime option to disable the [Agent-Cloud link](/src/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. |

335

336 ### Connection directory

337

docs: simplify claiming readme part1 (#17771)