diff options
Diffstat (limited to 'claim/README.md')
| -rw-r--r-- | claim/README.md | 64 |
1 files changed, 34 insertions, 30 deletions
diff --git a/claim/README.md b/claim/README.md index 3731d2004..f1d893eb2 100644 --- a/claim/README.md +++ b/claim/README.md @@ -1,17 +1,21 @@ <!-- 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 +custom_edit_url: "https://github.com/netdata/netdata/edit/master/claim/README.md" +sidebar_label: "Connect Agent to Cloud" +learn_status: "Published" +learn_topic_type: "Tasks" +learn_rel_path: "Setup" --> # Connect Agent to Cloud 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). +(ACLK)](https://github.com/netdata/netdata/blob/master/aclk/README.md). 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 +Cloud](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx) guide for a walkthrough of the process and simplified instructions. 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. @@ -22,13 +26,13 @@ Netdata Cloud. > 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 connecting a node, you opt-in to sending data from your Agent to Netdata Cloud via the [ACLK](/aclk/README.md). This +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/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 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). +Nodes** in the [Spaces management area](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx#manage-spaces). There are two important notes regarding connecting nodes: @@ -42,7 +46,7 @@ There will be three main flows from where you might want to connect a node to Ne * 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 +* when you are on the [Nodes view page](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow 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. @@ -66,11 +70,11 @@ finished onboarding. 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. +When coming from [Nodes view page](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) 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/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: +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: ``` wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud @@ -80,7 +84,7 @@ the node in your Space after 60 seconds, see the [troubleshooting information](# 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.md#connect-node-to-netdata-cloud-during-installation). +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). ### Connect an agent without root privileges @@ -114,7 +118,7 @@ connected on startup or restart. 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. +examples](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#create-a-new-netdata-agent-container) for details. #### Known issues on older hosts with seccomp enabled @@ -285,17 +289,17 @@ you don't see the node in your Space after 60 seconds, see the [troubleshooting ### Connect an agent running in macOS -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.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: +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: ```bash -curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud +curl https://my-netdata.io/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://api.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-your-kubernetes-cluster-to-netdata-cloud) +Read our [Kubernetes installation](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/kubernetes.md#connect-your-kubernetes-cluster-to-netdata-cloud) for details on connecting a parent Netdata pod. ### Connect through a proxy @@ -324,7 +328,7 @@ For example, a HTTP proxy setting may look like the following: proxy = http://proxy.example.com:1080 # With a URL ``` -You can now move on to connecting. When you connect with the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script) script, add the `--claim-proxy=` parameter and +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 append the same proxy setting you added to `netdata.conf`. ```bash @@ -336,7 +340,7 @@ you don't see the node in your Space after 60 seconds, see the [troubleshooting ### Troubleshooting -If you're having trouble connecting 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](https://github.com/netdata/netdata/blob/master/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 @@ -369,7 +373,7 @@ If you run the kickstart script and get the following error `Existing install ap 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). +script](https://github.com/netdata/netdata/blob/master/docs/get-started.mdx#install-on-linux-with-one-line-installer). #### kickstart: Failed to write new machine GUID @@ -382,14 +386,14 @@ For a successful execution you will need to run the script with root privileges #### bash: netdata-claim.sh: command not found -If you run the claiming script and see a `command not found` error, you either installed Netdata in a non-standard -location or are using an unsupported package. If you installed Netdata in a non-standard path using the `--install` -option, you need to update your `$PATH` or run `netdata-claim.sh` using the full path. For example, if you installed -Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script. +If you run the claiming script and see a `command not found` error, you either installed Netdata in a +non-standard location or are using an unsupported package. If you installed Netdata in a non-standard path using the +`--install-prefix` option, you need to update your `$PATH` or run `netdata-claim.sh` using the full path. For example, +if you installed Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script. 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). +script](https://github.com/netdata/netdata/blob/master/docs/get-started.mdx#install-on-linux-with-one-line-installer). #### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6) @@ -398,7 +402,7 @@ If you're running an older Linux distribution or one that has reached EOL, such versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which helps securely encrypt SSL connections. -We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart.md#static-builds), which uses an +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 up-to-date version of OpenSSL with hostname validation enabled. If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit @@ -416,7 +420,7 @@ Additionally, check that the `enabled` setting in `var/lib/netdata/cloud.d/cloud enabled = true ``` -To fix this issue, reinstall Netdata using your [preferred method](/packaging/installer/README.md) and do not add the +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 `--disable-cloud` option. #### cloud-available is false / ACLK Available: No @@ -506,20 +510,20 @@ tool, and details about the files found in `cloud.d`. ### The `cloud.conf` file -This section defines how and whether your Agent connects to [Netdata Cloud](https://learn.netdata.cloud/docs/cloud/) -using the [ACLK](/aclk/README.md). +This section defines how and whether your Agent connects to [Netdata Cloud](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx) +using the [ACLK](https://github.com/netdata/netdata/blob/master/aclk/README.md). | setting | default | info | |:-------------- |:------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------- | | cloud base url | https://api.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. | +| enabled | yes | The runtime option to disable the [Agent-Cloud link](https://github.com/netdata/netdata/blob/master/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/README.md#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. +The best way to install Netdata and connect your nodes to Netdata Cloud is with our automatic one-line installation script, [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#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: -* most Linux distributions, see [Netdata's platform support policy](/packaging/PLATFORM_SUPPORT.md) +* most Linux distributions, see [Netdata's platform support policy](https://github.com/netdata/netdata/blob/master/packaging/PLATFORM_SUPPORT.md) * 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. @@ -538,7 +542,7 @@ wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/ **macOS** ```bash -curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install /usr/local/ +curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ ``` ### Claiming script @@ -574,7 +578,7 @@ netdatacli reload-claiming-state This reloads the Agent connection state from disk. -Our recommendation is to trigger the connection process using the [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script) whenever possible. +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. ### Netdata Agent command line |