Merging upstream version 1.32.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 218 insertions, 81 deletions

diff --git a/claim/README.md b/claim/README.md
index b3ebb8221..bbccaac19 100644
--- a/claim/README.md
+++ b/claim/README.md
@@ -1,12 +1,12 @@
 <!--
-title: "Agent claiming"
-description: "Agent claiming allows a Netdata Agent, running on a distributed node, to securely connect to Netdata Cloud via the encrypted Agent-Cloud link (ACLK)."
+title: "Connect Agent to Cloud"
+description: "Connecting a Netdata Agent, running on a distributed node, to Netdata Cloud securely via the encrypted Agent-Cloud link (ACLK)."
 custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md
 -->
 
-# Agent claiming
+# Connect Agent to Cloud
 
-Agent claiming allows a Netdata Agent, running on a distributed node, to securely connect to Netdata Cloud. A Space's
+You can securely connect a Netdata Agent, running on a distributed node, to Netdata Cloud. A Space's
 administrator creates a **claiming token**, which is used to add an Agent to their Space via the [Agent-Cloud link
 (ACLK)](/aclk/README.md).
 
@@ -14,54 +14,83 @@ Are you just starting out with Netdata Cloud? See our [get started with
 Cloud](https://learn.netdata.cloud/docs/cloud/get-started) guide for a walkthrough of the process and simplified
 instructions.
 
-Claiming nodes is a security feature in Netdata Cloud. Through the process of claiming, you demonstrate in a few ways
-that you have administrative access to that node and the configuration settings for its Agent. By logging into the node,
-you prove you have access, and by using the claiming script or the Netdata command line, you prove you have write access
-and administrative privileges.
+When connecting an agent (also referred to as a node) to Netdata Cloud, you must complete a verification process that proves you have some level of authorization to manage the node itself. This verification is a security feature that helps prevent unauthorized users from seeing the data on your node.
 
 Only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script generated by
 Netdata Cloud.
 
-> The claiming process ensures no third party can add your node, and then view your node's metrics, in a Cloud account,
+> The connection process ensures no third party can add your node, and then view your node's metrics, in a Cloud account,
 > Space, or War Room that you did not authorize.
 
-By claiming a node, you opt-in to sending data from your Agent to Netdata Cloud via the [ACLK](/aclk/README.md). This
-data is encrypted by TLS while it is in transit. We use the RSA keypair created during claiming to authenticate the
-identity of the Agent when it connects to the Cloud. While the data does flow through Netdata Cloud servers on its way
+By connecting a node, you opt-in to sending data from your Agent to Netdata Cloud via the [ACLK](/aclk/README.md). This
+data is encrypted by TLS while it is in transit. We use the RSA keypair created during the connection process to authenticate the
+identity of the Netdata Agent when it connects to the Cloud. While the data does flow through Netdata Cloud servers on its way
 from Agents to the browser, we do not store or log it.
 
-You can claim a node during the Netdata Cloud onboarding process, or after you created a Space by clicking on **Claim
+You can connect a node during the Netdata Cloud onboarding process, or after you created a Space by clicking on **Connect
 Nodes** in the [Spaces management area](https://learn.netdata.cloud/docs/cloud/spaces#manage-spaces).
 
-There are two important notes regarding claiming:
+There are two important notes regarding connecting nodes:
 
--   _You can only claim any given node in a single Space_. You can, however, add that claimed node to multiple War Rooms
+-   _You can only connect any given node in a single Space_. You can, however, add that connected node to multiple War Rooms
     within that one Space.
--   You must repeat the claiming process on every node you want to add to Netdata Cloud.
+-   You must repeat the connection process on every node you want to add to Netdata Cloud.
 
-## How to claim a node
+## How to connect a node
 
-To claim a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script
-given by Cloud into your node's terminal. Hit **Enter**.
+There will be three main flows from where you might want to connect a node to Netdata Cloud.
+* when you are on an [
+War Room](#empty-war-room) and you want to connect your first node
+* when you are at the [Manage Space](#manage-space-or-war-room) area and you select **Connect Nodes** to connect a node, coming from Manage Space or Manage War Room
+* when you are on the [Nodes view page](https://learn.netdata.cloud/docs/cloud/visualize/nodes) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow
 
-```bash
-sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
-```
+Please note that only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script, generated by Netdata Cloud, to trigger the connection process.
+
+### Empty War Room
+
+Either at your first sign in or following ones, when you enter Netdata Cloud and are at a War Room that doesn’t have any node added to it, you will be able to:
+* connect a new node to Netdata Cloud and add it to the War Room 
+* add a previously connected node to the War Room 
 
-The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if you don't see
-the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting). If you prefer not to
-use root privileges via `sudo` to run the claiming script, see the next section.
+If your case is to connect a new node and add it to the War Room, you will need to tell us what environment the node is running on (Linux, Docker, macOS, Kubernetes) and then we will provide you with a script to initiate the connection process. You just will need to copy and paste it into your node's terminal. See one of the following sections depending on your case:
+* [Linux](#connect-an-agent-running-in-linux)
+* [Docker](#connect-an-agent-running-in-docker)
+* [macOS](#connect-an-agent-running-in-macos)
+* [Kubernetes](#connect-a-kubernetes-clusters-parent-netdata-pod)
 
-Repeat this process with every node you want to add to Cloud during onboarding. You can also add more nodes once you've
+Repeat this process with every node you want to add to Netdata Cloud during onboarding. You can also add more nodes once you've
 finished onboarding.
 
-### Claim an agent without root privileges
+### Manage Space or War Room
+
+To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script
+given by Netdata Cloud into your node's terminal.
+
+When coming from  [Nodes view page](https://learn.netdata.cloud/docs/cloud/visualize/nodes) the room parameter is already defined to current War Room.
+
+### Connect an agent running in Linux
+
+If you want to connect a node that is running on a Linux environment, the script that will be provided to you by Netdata Cloud is the [kickstart](/packaging/installer/#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:
 
-If you don't want to run the claiming script with root privileges, you can discover which user is running the Agent,
-switch to that user, and run the claiming script.
+```
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
+```
+The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see
+the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
+
+Please note that to run it you will either need to have root privileges or run it with the user that is running the agent, more details on the [Connect an agent without root privileges](#connect-an-agent-without-root-privileges) section.
+
+For more details on what are the extra parameters `claim-token`, `claim-rooms` and `claim-url` please refer to [Connect node to Netdata Cloud during installation](/packaging/installer/methods/kickstart#connect-node-to-netdata-cloud-during-installation).
+
+### Connect an agent without root privileges
+
+If you don't want to run the installation script to connect your nodes to Netdata Cloud with root privileges, you can discover which user is running the Agent,
+switch to that user, and run the script.
 
 Use `grep` to search your `netdata.conf` file, which is typically located at `/etc/netdata/netdata.conf`, for the `run
 as user` setting. For example:
+To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script
+given by Netdata Cloud into your node's terminal.
 
 ```bash
 grep "run as user" /etc/netdata/netdata.conf 
@@ -69,22 +98,21 @@ grep "run as user" /etc/netdata/netdata.conf
 ```
 
 The default user is `netdata`. Yours may be different, so pay attention to the output from `grep`. Switch to that user
-and run the claiming script.
+and run the script.
 
 ```bash
-netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
 ```
+### Connect an agent running in Docker
 
-Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
-you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting). 
+To connect an instance of the Netdata Agent running inside of a Docker container, it is recommended that you follow
+the instructions and use the commands provided either in the `Nodes` tab of an [empty War Room](#empty-war-room) on Netdata Cloud or 
+in the shelf that appears when you click **Connect Nodes** and select **Docker**. 
 
-### Claim an Agent running in Docker
+However, users can also claim a new node by claiming environment variables in the container to have it automatically 
+connected on startup or restart.
 
-To claim an instance of the Netdata Agent running inside of a Docker container, either set claiming environment
-variables in the container to have it automatically claimed on startup or restart, or use `docker exec` to manually
-claim an already running container.
-
-For claiming to work, the contents of `/var/lib/netdata` _must_ be preserved across container
+For the connection process to work, the contents of `/var/lib/netdata` _must_ be preserved across container
 restarts using a persistent volume.  See our [recommended `docker run` and Docker Compose
 examples](/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.
 
@@ -97,17 +125,21 @@ The Netdata Docker container looks for the following environment variables on st
 - `NETDATA_CLAIM_ROOMS`
 - `NETDATA_CLAIM_PROXY`
 
-If the token and URL are specified in their corresponding variables _and_ the container is not already claimed,
-it will use these values to attempt to claim the container, automatically adding the node to the specified War
-Rooms. If a proxy is specified, it will be used for the claiming process and for connecting to Netdata Cloud.
+If the token and URL are specified in their corresponding variables _and_ the container is not already connected,
+it will use these values to attempt to connect the container, automatically adding the node to the specified War
+Rooms. If a proxy is specified, it will be used for the connection process and for connecting to Netdata Cloud.
 
 These variables can be specified using any mechanism supported by your container tooling for setting environment
-variables inside containers. For example, when creating a new Netdata continer using `docker run`, the following
-modified version of the command can be used to set the variables:
+variables inside containers. 
 
-```bash
+When using the `docker run` command, if you have an agent container already running, it is important to know that there will be a short period of downtime. This is due to the process of recreating the new agent container.
+
+The command to connect a new node to Netdata Cloud is:
+
+```bash 
 docker run -d --name=netdata \
   -p 19999:19999 \
+  -v netdataconfig:/etc/netdata \
   -v netdatalib:/var/lib/netdata \
   -v netdatacache:/var/cache/netdata \
   -v /etc/passwd:/host/etc/passwd:ro \
@@ -115,40 +147,99 @@ docker run -d --name=netdata \
   -v /proc:/host/proc:ro \
   -v /sys:/host/sys:ro \
   -v /etc/os-release:/host/etc/os-release:ro \
-  -e NETDATA_CLAIM_TOKEN=TOKEN \
-  -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \
-  -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \
   --restart unless-stopped \
   --cap-add SYS_PTRACE \
   --security-opt apparmor=unconfined \
-  netdata/netdata
+  -e NETDATA_CLAIM_TOKEN=TOKEN \
+  -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \
+  -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \
+  -e NETDATA_CLAIM_PROXY=PROXY \
+ netdata/netdata
 ```
+>Note: This command is suggested for connecting a new container. Using this command for an existing container recreates the container, though data 
+and configuration of the old container may be preserved.  If you are claiming an existing container that can not be recreated, 
+you can add the container by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and following
+the instructions and commands provided or by following the instructions in an [empty War Room](#empty-war-room). 
 
-Output that would be seen from the claiming script when using other methods will be present in the container logs.
+The output that would be seen from the connection process when using other methods will be present in the container logs.
 
-Using the environment variables like this to handle claiming is the preferred method of claiming Docker containers
+Using the environment variables like this to handle the connection process is the preferred method of connecting Docker containers
 as it works in the widest variety of situations and simplifies configuration management.
 
+#### Using Docker compose
+
+If you use `docker compose`, you can copy the config provided by Netdata Cloud, which should be same as the one below:
+
+```bash
+version: '3'
+services:
+  netdata:
+    image: netdata/netdata
+    container_name: netdata
+  hostname: example.com # set to fqdn of host
+  ports:
+    - 19999:19999
+  restart: unless-stopped
+  cap_add:
+    - SYS_PTRACE
+  security_opt:
+    - apparmor:unconfined
+  volumes:
+    - netdataconfig:/etc/netdata
+    - netdatalib:/var/lib/netdata
+    - netdatacache:/var/cache/netdata
+    - /etc/passwd:/host/etc/passwd:ro
+    - /etc/group:/host/etc/group:ro
+    - /proc:/host/proc:ro
+    - /sys:/host/sys:ro
+    - /etc/os-release:/host/etc/os-release:ro
+  environment:
+    - NETDATA_CLAIM_TOKEN=TOKEN
+    - NETDATA_CLAIM_URL="https://app.netdata.cloud"
+    - NETDATA_CLAIM_ROOMS=ROOM1,ROOM2
+
+volumes:
+  netdataconfig:
+  netdatalib:
+  netdatacache:
+```
+
+Then run the following command in the same directory as the `docker-compose.yml` file to start the container.
+
+```bash
+docker-compose up -d
+```
 #### Using docker exec
 
-Claim a _running Netdata Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing
+Connect a _running Netdata Agent container_, where you don't want to recreate the existing container, append the script offered by Netdata Cloud to a `docker exec ...` command, replacing
 `netdata` with the name of your running container:
 
 ```bash
 docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
 ```
+The values for `ROOM1,ROOM2` can be found by by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and copying the `rooms=` value in the command provided. 
 
-The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
+The script should return `Agent was successfully claimed.`. If the connection process returns errors, or if
 you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
 
-### Claim a Kubernetes cluster's parent Netdata pod
+### Connect an agent running in macOS
 
-Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#claim-a-kubernetes-clusters-parent-pod)
-for details on claiming a parent Netdata pod.
+To connect a node that is running on a macOS environment the script that will be provided to you by Netdata Cloud is the [kickstart](/packaging/installer/methods/macos#install-netdata-with-kickstart) 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:
 
-### Claim through a proxy
+```bash
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --install /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
+```
+The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see
+the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
+
+### Connect a Kubernetes cluster's parent Netdata pod
+
+Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#connect-a-kubernetes-clusters-parent-pod)
+for details on connecting a parent Netdata pod.
 
-A Space's administrator can claim a node through a SOCKS5 or HTTP(S) proxy.
+### Connect through a proxy
+
+A Space's administrator can connect a node through a SOCKS5 or HTTP(S) proxy.
 
 You should first configure the proxy in the `[cloud]` section of `netdata.conf`. The proxy settings you specify here
 will also be used to tunnel the ACLK. The default `proxy` setting is `none`.
@@ -162,8 +253,8 @@ The `proxy` setting can take one of the following values:
 
 -   `none`: Do not use a proxy, even if the system configured otherwise.
 -   `env`: Try to read proxy settings from set environment variables `http_proxy`/`socks_proxy`.
--   `socks5[h]://[user:pass@]host:ip`: The ACLK and claiming will use the specified SOCKS5 proxy.
--   `http://[user:pass@]host:ip`: The ACLK and claiming will use the specified HTTP(S) proxy.
+-   `socks5[h]://[user:pass@]host:ip`: The ACLK and connection process will use the specified SOCKS5 proxy.
+-   `http://[user:pass@]host:ip`: The ACLK and connection process will use the specified HTTP(S) proxy.
 
 For example, a SOCKS5 proxy setting may look like the following:
 
@@ -173,23 +264,23 @@ For example, a SOCKS5 proxy setting may look like the following:
     proxy = socks5h://proxy.example.com:1080 # With a URL
 ```
 
-You can now move on to claiming. When you claim with the `netdata-claim.sh` script, add the `-proxy=` parameter and
+You can now move on to connecting. When you connect with the [kickstart](/packaging/installer/#automatic-one-line-installation-script) script, add the `--claim-proxy=` parameter and
 append the same proxy setting you added to `netdata.conf`.
 
 ```bash
-sudo netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 -url=https://app.netdata.cloud -proxy=socks5h://203.0.113.0:1080
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud --claim-proxy socks5h://203.0.113.0:1080
 ```
 
-Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
+Hit **Enter**. The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if
 you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
 
 ### Troubleshooting
 
-If you're having trouble claiming a node, this may be because the [ACLK](/aclk/README.md) cannot connect to Cloud.
+If you're having trouble connecting a node, this may be because the [ACLK](/aclk/README.md) cannot connect to Cloud.
 
 With the Netdata Agent running, visit `http://NODE:19999/api/v1/info` in your browser, replacing `NODE` with the IP
 address or hostname of your Agent. The returned JSON contains four keys that will be helpful to diagnose any issues you
-might be having with the ACLK or claiming process.
+might be having with the ACLK or connection process.
 
 ```json
 	"cloud-enabled"
@@ -200,6 +291,23 @@ might be having with the ACLK or claiming process.
 
 Use these keys and the information below to troubleshoot the ACLK.
 
+#### kickstart: unsupported Netdata installation
+
+If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package. 
+
+If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,
+please remove that package and reinstall using our [recommended kickstart
+script](/docs/get-started.mdx#install-on-linux-with-one-line-installer-recommended).
+
+#### kickstart: Failed to write new machine GUID
+
+If you run the kickstart script but don't have privileges required for the actions done on the connecting to Netdata Cloud process you will get the following error:
+
+```bash
+Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id.
+```
+For a successful execution you will need to run the script with root privileges or run it with the user that is running the agent, more details on the [Connect an agent without root privileges](#connect-an-agent-without-root-privileges) section.
+
 #### bash: netdata-claim.sh: command not found
 
 If you run the claiming script and see a `command not found` error, you either installed Netdata in a non-standard
@@ -211,7 +319,7 @@ If you are using an unsupported package, such as a third-party `.deb`/`.rpm` pac
 please remove that package and reinstall using our [recommended kickstart
 script](/docs/get-started.mdx#install-on-linux-with-one-line-installer-recommended).
 
-#### Claiming on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)
+#### 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
@@ -285,7 +393,7 @@ with details about your system and relevant output from `error.log`.
 
 #### agent-claimed is false
 
-You must [claim your node](#how-to-claim-a-node).
+You must [connect your node](#how-to-connect-a-node).
 
 #### aclk-available is false
 
@@ -293,14 +401,14 @@ If `aclk-available` is `false` and all other keys are `true`, your Agent is havi
 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
-claiming](#claim-through-a-proxy).
+connecting](#connect-through-a-proxy).
 
 If you are certain firewall and proxy settings are not the issue, you should consult the Agent's `error.log` at
 `/var/log/netdata/error.log` and contact us by [creating an issue on
 GitHub](https://github.com/netdata/netdata/issues/new?labels=bug%2C+needs+triage%2C+ACLK&template=bug_report.md&title=ACLK-available-is-false)
 with details about your system and relevant output from `error.log`.
 
-### Remove and reclaim a node
+### Remove and reconnect a node
 
 To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory.
 
@@ -309,11 +417,13 @@ cd /var/lib/netdata   # Replace with your Netdata library directory, if not /var
 sudo rm -rf cloud.d/
 ```
 
-This node no longer has access to the credentials it was claimed with and cannot connect to Netdata Cloud via the ACLK.
+This node no longer has access to the credentials it was used when connecting to Netdata Cloud via the ACLK.
 You will still be able to see this node in your War Rooms in an **unreachable** state.
 
-If you want to reclaim this node into a different Space, you need to create a new identity by adding `-id=$(uuidgen)` to
-the claiming script parameters. Make sure that you have the `uuidgen-runtime` package installed, as it is used to run the command `uuidgen`. For example, using the default claiming script:
+If you want to reconnect this node, you need to create a new identity by adding `-id=$(uuidgen)` to
+the claiming script parameters (not yet supported on the kickstart script). Make sure that you have the `uuidgen-runtime` package installed, as it is used to run the command `uuidgen`. For example:
+
+**Claiming script**
 
 ```bash
 sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud -id=$(uuidgen)
@@ -321,9 +431,8 @@ sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.c
 
 The agent _must be restarted_ after this change.
 
-## Claiming reference
-
-In the sections below, you can find reference material for the claiming script, claiming via the Agent's command line
+## 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
@@ -336,9 +445,35 @@ using the [ACLK](/aclk/README.md).
 | 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. |
 | enabled        | yes                       | The runtime option to disable the [Agent-Cloud link](/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud.         |
 
+### kickstart script
+
+The best way to install Netdata and connect your nodes to Netdata Cloud is with our automatic one-line installation script, [kickstart](/packaging/installer/#automatic-one-line-installation-script). This script will install the Netdata Agent, in case it isn't already installed, and connect your node to Netdata Cloud. 
+
+This  works with:
+* all Linux distributions, see [Netdata distribution support matrix](https://learn.netdata.cloud/docs/agent/packaging/distributions)
+* macOS
+
+For details on how to run this script please check [How to connect a node](#how-to-connect-a-node) and choose your environment.
+
+In case Netdata Agent is already installed and you run this script to connect a node to Netdata Cloud it will not upgrade your agent automatically. If you also want to upgrade the Agent installation you'll need to run the script again without the connection options. 
+
+Our suggestion is to first run kickstart to upgrade your agent by running the command below and the run the [How to connect a node]
+(#how-to-connect-a-node).
+
+**Linux**
+
+```bash
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
+```
+
+**macOS**
+
+```bash
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --install /usr/local/
+```
 ### Claiming script
 
-A Space's administrator can claim an Agent by directly calling the `netdata-claim.sh` script either with root privileges
+A Space's administrator can also connect an Agent by directly calling the `netdata-claim.sh` script either with root privileges
 using `sudo`, or as the user running the Agent (typically `netdata`), and passing the following arguments:
 
 ```sh
@@ -356,7 +491,7 @@ using `sudo`, or as the user running the Agent (typically `netdata`), and passin
     where PROXY_URL is the endpoint of a SOCKS5 proxy.
 ```
 
-For example, the following command claims an Agent and adds it to rooms `room1` and `room2`:
+For example, the following command connects an Agent and adds it to rooms `room1` and `room2`:
 
 ```sh
 netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2
@@ -368,11 +503,13 @@ You should then update the `netdata` service about the result with `netdatacli`:
 netdatacli reload-claiming-state
 ```
 
-This reloads the Agent claiming state from disk.
+This reloads the Agent connection state from disk.
+
+Our recommendation is to trigger the connection process using the [kickstart](/packaging/installer/#automatic-one-line-installation-script) whenever possible.
 
 ### Netdata Agent command line
 
-If a Netdata Agent is running, the Space's administrator can claim a node using the `netdata` service binary with
+If a Netdata Agent is running, the Space's administrator can connect a node using the `netdata` service binary with
 additional command line parameters:
 
 ```sh
@@ -388,9 +525,9 @@ For example:
 If need be, the user can override the Agent's defaults by providing additional arguments like those described
 [here](#claiming-script).
 
-### Claiming directory
+### Connection directory
 
-Netdata stores the Agent's claiming-related state in the Netdata library directory under `cloud.d`. For a default
+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.