7c9dfe1f0 · cryptotaxi247/netdata-1

@@ -1,119 +1,139 @@

1 # Connect Agent to Cloud

2

3 -This page will guide you through connecting a Netdata Agent to Netdata Cloud securely, via the encrypted Agent-Cloud link (ACLK).

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](https://github.com/netdata/netdata/blob/master/src/aclk/README.md)).

5

5 -You can securely connect a Netdata Agent, running on a distributed node, to Netdata Cloud. A Space's

6 -administrator creates a **claiming token**, which is used to add an Agent to their Space via the [Agent-Cloud link

7 -(ACLK)](https://github.com/netdata/netdata/blob/master/src/aclk/README.md).

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.

10

9 -Are you just getting started with Netdata Cloud? You can find simplified instructions in the [Install Netdata documentation](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#get-started)

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

11 -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.

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

13 -Only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script generated by

14 -Netdata Cloud.

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

20

16 -> The connection process ensures no third party can add your node, and then view your node's metrics, in a Cloud account,

17 -> Space, or War Room that you did not authorize.

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

19 -By connecting a node, you opt-in to sending data from your Agent to Netdata Cloud via the [ACLK](https://github.com/netdata/netdata/blob/master/src/aclk/README.md). This

20 -data is encrypted by TLS while it is in transit. We use the RSA keypair created during the connection process to authenticate the

21 -identity of the Netdata Agent when it connects to the Cloud. While the data does flow through Netdata Cloud servers on its way

22 -from Agents to the browser, we do not store or log it.

23 -

24 -You can connect a node during the Netdata Cloud onboarding process, or after you created a Space by clicking on **Connect

25 -Nodes** in the [Spaces management area](https://github.com/netdata/netdata/blob/master/docs/cloud/manage/organize-your-infrastrucutre-invite-your-team.md#netdata-cloud-spaces#manage-spaces).

26 -

27 -There are two important notes regarding connecting nodes:

28 -

29 -- _You can only connect any given node in a single Space_. You can, however, add that connected node to multiple War Rooms

30 - within that one Space.

31 -- You must repeat the connection process on every node you want to add to Netdata Cloud.

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.

30

31 ## How to connect a node

32

35 -There will be three main flows from where you might want to connect a node to Netdata Cloud.

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

34

37 -- when you are on a [War Room](#empty-war-room) and you want to connect your first node

38 -- 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

39 -- when you are on the [Nodes tab](https://github.com/netdata/netdata/blob/master/docs/dashboard/nodes-tab.md) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow

40 -

41 -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.

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](https://github.com/netdata/netdata/blob/master/docs/dashboard/nodes-tab.md): While you can see

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

41

42 ### Empty War Room

43

45 -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:

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

45

47 -- connect a new node to Netdata Cloud and add it to the War Room

48 -- add a previously connected node to the War Room

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.

51

50 -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:

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

53

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)

58

57 -Repeat this process with every node you want to add to Netdata Cloud during onboarding. You can also add more nodes once you've

58 -finished onboarding.

59 -

60 -### Manage Space or War Room

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.

61

62 -To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script

63 -given by Netdata Cloud into your node's terminal.

62 +### Manage Space or War Room area

63

65 -When coming from the [Nodes tab](https://github.com/netdata/netdata/blob/master/docs/dashboard/nodes-tab.md) the room parameter is already defined to current War Room.

64 +Accessing Management screens:

65

67 -### Connect an agent running in Linux

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.

68

69 -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](https://github.com/netdata/netdata/blob/master/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:

69 +Connecting a Node to a War Room:

70

71 -```bash

72 -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

73 -```

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 -The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see

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

75 +> Note: When connecting from

76 +> the [Nodes tab](https://github.com/netdata/netdata/blob/master/docs/dashboard/nodes-tab.md), the room parameter will

77 +> be

78 +> set to the current War Room.

79

78 -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.

80 +### Connect an Agent running in Linux

81

80 -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](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kickstart.md#connect-node-to-netdata-cloud-during-installation).

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

82 -### Connect an agent without root privileges

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

84 -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,

85 -switch to that user, and run the script.

86 -

87 -Use `grep` to search your `netdata.conf` file, which is typically located at `/etc/netdata/netdata.conf`, for the `run

88 -as user` setting. For example:

89 -To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script

90 -given by Netdata Cloud into your node's terminal.

90 +It should be similar to:

91

92 ```bash

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

94 - # run as user = netdata

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

94 ```

95

97 -The default user is `netdata`. Yours may be different, so pay attention to the output from `grep`. Switch to that user

98 -and run the script.

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

97

100 -```bash

101 -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

102 -```

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

104 -### Connect an agent running in Docker

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](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kickstart.md#connect-node-to-netdata-cloud-during-installation).

109

106 -To connect an instance of the Netdata Agent running inside of a Docker container, it is recommended that you follow

107 -the instructions and use the commands provided either in the `Nodes` tab of an [empty War Room](#empty-war-room) on Netdata Cloud or

108 -in the shelf that appears when you click **Connect Nodes** and select **Docker**.

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](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration.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

110 -However, users can also claim a new node by claiming environment variables in the container to have it automatically

111 -connected on startup or restart.

128 +### Connect an Agent running in Docker

129

113 -For the connection process to work, the contents of `/var/lib/netdata` _must_ be preserved across container

114 -restarts using a persistent volume. See our [recommended `docker run` and Docker Compose examples](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.

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](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#recommended-way) for

133 +details on using persistent volumes.

134

116 -#### Known issues on older hosts with seccomp enabled

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**:

139

@@ -131,48 +151,51 @@ CONFIG_SECCOMP=y

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.

135 -- Run [without the default seccomp profile](https://docs.docker.com/engine/security/seccomp/#run-without-the-default-seccomp-profile) (unsafe, not recommended).

136 -

137 -<details>

138 -<summary>See how to create a custom profile</summary>

139 -

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

141 -

142 - ```cmd

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

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

145 - ```

146 -

147 -2. Specify the new policy for the container explicitly.

148 -

149 - - When using `docker run`:

150 -

151 - ```cmd

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

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

154 - ...

155 - ```

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

157 - - When using `docker-compose`:

158 -

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

160 -

161 - ```yaml

162 - version: '3'

163 - services:

164 - netdata:

165 - security_opt:

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

167 - ...

168 - ```

185 +</details>

186

170 - - When using `docker stack deploy`:

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

188

172 - Change the default profile globally by adding `--seccomp-profile=/etc/docker/seccomp.json` to the options passed to

173 - dockerd on startup.

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

175 -</details>

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

@@ -183,16 +206,18 @@ The Netdata Docker container looks for the following environment variables on st

206 - `NETDATA_CLAIM_ROOMS`

207 - `NETDATA_CLAIM_PROXY`

208

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

187 -it will use these values to attempt to connect the container, automatically adding the node to the specified War

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

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

193 -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.

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

195 -The command to connect a new node to Netdata Cloud is:

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

221

222 ```bash

223 docker run -d --name=netdata \

@@ -215,15 +240,19 @@ docker run -d --name=netdata \

240 netdata/netdata

241 ```

242

218 ->Note: This command is suggested for connecting a new container. Using this command for an existing container recreates the container, though data

219 -and configuration of the old container may be preserved. If you are claiming an existing container that can not be recreated,

220 -you can add the container by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and following

221 -the instructions and commands provided or by following the instructions in an [empty War Room](#empty-war-room).

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

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

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

252 +logs.

253

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

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

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.

256

257 #### Using Docker compose

258

@@ -271,33 +300,41 @@ docker-compose up -d

300

301 #### Using docker exec

302

274 -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

275 -`netdata` with the name of your running container:

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:

306

307 ```bash

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

309 ```

310

281 -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.

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.

313

283 -The script should return `Agent was successfully claimed.`. If the connection process returns errors, or if

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

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).

316

286 -### Connect an agent running in macOS

317 +### Connect an Agent running in macOS

318

288 -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](https://github.com/netdata/netdata/blob/master/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:

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](https://github.com/netdata/netdata/blob/master/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:

323

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 ```

327

294 -The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see

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

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).

332

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

334

299 -Read our [Kubernetes installation](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kubernetes.md#connect-your-kubernetes-cluster-to-netdata-cloud)

300 -for details on connecting a parent Netdata pod.

335 +Read

336 +our [Kubernetes installation](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kubernetes.md#deploy-netdata-on-your-kubernetes-cluster)

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

338

339 ### Connect through a proxy

340

@@ -325,19 +362,23 @@ For example, a HTTP proxy setting may look like the following:

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

363 ```

364

328 -You can now move on to connecting. When you connect with the [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-one-line-installation-script) script, add the `--claim-proxy=` parameter and

329 -append the same proxy setting you added to `netdata.conf`.

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

366 +the [kickstart](https://github.com/netdata/netdata/blob/master/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`.

368

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 ```

372

335 -Hit **Enter**. The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if

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

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).

377

378 ### Troubleshooting

379

340 -If you're having trouble connecting a node, this may be because the [ACLK](https://github.com/netdata/netdata/blob/master/src/aclk/README.md) cannot connect to Cloud.

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

381 +the [ACLK](https://github.com/netdata/netdata/blob/master/src/aclk/README.md) cannot connect to Cloud.

382

383 With the Netdata Agent running, visit `http://NODE:19999/api/v1/info` in your browser, replacing `NODE` with the IP

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

@@ -345,12 +386,15 @@ might be having with the ACLK or connection process.

386

387 ```json

388 "cloud-enabled"

348 - "cloud-available"

349 - "agent-claimed"

350 - "aclk-available"

389 +"cloud-available"

390 +"agent-claimed"

391 +"aclk-available"

392 ```

393

353 -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:

394 +> **Note**

395 +>

396 +> On Netdata Agent version `1.32` (`netdata -v` to find your version) and newer, `sudo netdatacli aclk-state` can be

397 +> used to get some diagnostic information about ACLK. Sample output:

398

399 ```bash

400 ACLK Available: Yes

@@ -366,32 +410,45 @@ Use these keys and the information below to troubleshoot the ACLK.

410

411 #### kickstart: unsupported Netdata installation

412

369 -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.

413 +If you run the kickstart script and get the following

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

415 +installed Netdata using an unsupported package.

416

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

372 -please remove that package and reinstall using our [recommended kickstart

373 -script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer).

417 +> **Note**

418 +>

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

420 +> please remove that package and reinstall using

421 +>

422 +our [recommended kickstart script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer).

423

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

425

377 -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:

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

427 +Cloud process you will get the following error:

428

429 ```bash

430 Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id.

431 ```

432

383 -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.

433 +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.

436

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

438

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

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

389 -`--install-prefix` option, you need to update your `$PATH` or run `netdata-claim.sh` using the full path. For example,

390 -if you installed Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script.

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

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

441 +the `--install-prefix` option, you need to update your `$PATH` or run `netdata-claim.sh` using the full path.

442 +

443 +For example, if you installed Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming

444 +script.

445

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

393 -please remove that package and reinstall using our [recommended kickstart

394 -script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer).

446 +> **Note**

447 +>

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

449 +> please remove that package and reinstall using

450 +>

451 +our [recommended kickstart script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer).

452

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

454

@@ -400,8 +457,9 @@ If you're running an older Linux distribution or one that has reached EOL, such

457 versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which

458 helps securely encrypt SSL connections.

459

403 -We recommend you reinstall Netdata with a [static build](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kickstart.md#static-builds), which uses an

404 -up-to-date version of OpenSSL with hostname validation enabled.

460 +We recommend you reinstall Netdata with

461 +a [static build](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kickstart.md#static-builds),

462 +which uses an up-to-date version of OpenSSL with hostname validation enabled.

463

464 If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit

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

@@ -418,8 +476,9 @@ Additionally, check that the `enabled` setting in `var/lib/netdata/cloud.d/cloud

476 enabled = true

477 ```

478

421 -To fix this issue, reinstall Netdata using your [preferred method](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md) and do not add the

422 -`--disable-cloud` option.

479 +To fix this issue, reinstall Netdata using

480 +your [preferred method](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md) and do not add

481 +the `--disable-cloud` option.

482

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

484

@@ -427,7 +486,9 @@ If `cloud-available` is `false` after you verified Cloud is enabled in the previ

486 Cloud features failed to build during installation.

487

488 If Cloud features fail to build, the installer continues and finishes the process without Cloud functionality as opposed

430 -to failing the installation altogether. We do this to ensure the Agent will always finish installing.

489 +to failing the installation altogether.

490 +

491 +We do this to ensure the Agent will always finish installing.

492

493 If you can't see an explicit error in the installer's output, you can run the installer with the `--require-cloud`

494 option. This option causes the installation to fail if Cloud functionality can't be built and enabled, and the

@@ -435,20 +496,14 @@ installer's output should give you more error details.

496

497 You may see one of the following error messages during installation:

498

438 -- Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to

439 - Netdata Cloud.

440 -- Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect

441 - this node to Netdata Cloud.

442 -- Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to

443 - Netdata Cloud.

444 -- Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect

445 - this node to Netdata Cloud.

446 -- Could not find cmake, which is required to build libwebsockets. The install process will continue, but you may not

447 - be able to connect this node to Netdata Cloud.

448 -- Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud

449 - support will be disabled.

450 -- Failed to build JSON-C. Netdata Cloud support will be disabled.

451 -- Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled.

499 +- `Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud.`

500 +- `Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud.`

501 +- `Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud.`

502 +- `Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud.`

503 +- `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.`

504 +- `Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud support will be disabled.`

505 +- `Failed to build JSON-C. Netdata Cloud support will be disabled.`

506 +- `Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled.`

507

508 One common cause of the installer failing to build Cloud features is not having one of the following dependencies on

509 your system: `cmake`, `json-c` and `OpenSSL`, including corresponding `devel` packages.

@@ -461,8 +516,8 @@ less /var/log/netdata/error.log

516 grep -i ACLK /var/log/netdata/error.log

517 ```

518

464 -If the installer's output does not help you enable Cloud features, contact us by [creating an issue on

465 -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)

519 +If the installer's output does not help you enable Cloud features, contact us

520 +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)

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

522

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

@@ -474,12 +529,12 @@ You must [connect your node](#how-to-connect-a-node).

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

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

531

477 -If your Agent needs to use a proxy to access the internet, you must [set up a proxy for

478 -connecting](#connect-through-a-proxy).

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).

534

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

481 -`/var/log/netdata/error.log` and contact us by [creating an issue on

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

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

536 +at `/var/log/netdata/error.log` and contact us

537 +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)

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

539

540 ### Remove and reconnect a node

@@ -493,16 +548,18 @@ cd /var/lib/netdata # Replace with your Netdata library directory, if not /var

548 sudo rm -rf cloud.d/

549 ```

550

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

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

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

501 -1. 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`.

502 -2. Stop the agent.

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

504 -4. 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 message `Node was successfully claimed.`

505 -5. Start the agent

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

@@ -526,7 +583,7 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac

583

584 3. Stop and remove the container

585

529 - **Docker CLI:**

586 + **Docker CLI:**

587

588 ```bash

589 docker stop CONTAINER_NAME

@@ -534,55 +591,56 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac

591 docker rm CONTAINER_NAME

592 ```

593

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

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

595

539 - **Docker Compose:**

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

596 + **Docker Compose:**

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

598

599 ```bash

600 docker compose down

601 ```

602

546 - **Docker Swarm:**

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

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.

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

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

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

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

560 -one you can achieve that from the Netdata Cloud UI.

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

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

563 -[updates channel](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/versions-and-platforms.md), a

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](https://github.com/netdata/netdata/blob/master/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

625 ## Connecting reference

626

570 -In the sections below, you can find reference material for the kickstart script, claiming script, connecting via the Agent's command line

571 -tool, and details about the files found in `cloud.d`.

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

628 +Agent's command line tool, and details about the files found in `cloud.d`.

629

630 ### The `cloud.conf` file

631

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

633 using the [ACLK](https://github.com/netdata/netdata/blob/master/src/aclk/README.md).

634

578 -| setting | default | info |

579 -|:-------------- |:------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------- |

580 -| 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. |

581 -| enabled | yes | The runtime option to disable the [Agent-Cloud link](https://github.com/netdata/netdata/blob/master/src/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. |

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](https://github.com/netdata/netdata/blob/master/src/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. |

639

640 ### Claiming script

641

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

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

@@ -614,7 +672,9 @@ netdatacli reload-claiming-state

672

673 This reloads the Agent connection state from disk.

674

617 -Our recommendation is to trigger the connection process using the [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-one-line-installation-script) whenever possible.

675 +Our recommendation is to trigger the connection process using

676 +the [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-one-line-installation-script)

677 +whenever possible.

678

679 ### Netdata Agent command line

680

Update the claim readme (#17646)