diff options
Diffstat (limited to 'src/claim/README.md')
| -rw-r--r-- | src/claim/README.md | 250 |
1 files changed, 69 insertions, 181 deletions
diff --git a/src/claim/README.md b/src/claim/README.md index 51e2a9ebe..a0af190b9 100644 --- a/src/claim/README.md +++ b/src/claim/README.md @@ -11,8 +11,7 @@ features like centralized monitoring and easier collaboration. There are two places in the UI where you can add/connect your Node: - **Space/Room settings**: Click the cogwheel (the bottom-left corner or next to the Room name at the top) and - select "Nodes." Click the "+" button to add - a new node. + select "Nodes." Click the "+" button to add a new node. - [**Nodes tab**](/docs/dashboards-and-charts/nodes-tab.md): Click on the "Add nodes" button. Netdata Cloud will generate a command that you can execute on your Node to install and claim the Agent. The command is @@ -28,12 +27,13 @@ Once you've chosen your installation method, follow the provided instructions to ### Connect an Existing Agent -There are two methods to connect an already installed Netdata Agent to your Netdata Cloud Space: +There are three methods to connect an already installed Netdata Agent to your Netdata Cloud Space: -- using the Netdata Cloud user interface (UI). -- using the claiming script. +- Manually, via the UI +- Automatically, via a provisioning system (or the command line) +- Automatically, via environment variables (e.g. kubernetes, docker, etc) -#### Using the UI (recommended) +#### Manually, via the UI The UI method is the easiest and recommended way to connect your Agent. Here's how: @@ -42,36 +42,52 @@ The UI method is the easiest and recommended way to connect your Agent. Here's h 3. Click the "Connect" button. 4. Follow the on-screen instructions to connect your Agent. -#### Using claiming script +#### Automatically, via a provisioning system or the command line -You can connect an Agent by running -the [netdata-claim.sh](https://github.com/netdata/netdata/blob/master/src/claim/netdata-claim.sh.in) script directly. -You can either run it with root privileges using `sudo` or as the user running the Agent (typically `netdata`). - -The claiming script accepts options that control the connection process. You can specify these options using the -following format: +Netdata Agents can be connected to Netdata Cloud by creating the file `/etc/netdata/claim.conf` +(or `/opt/netdata/etc/netdata/claim.conf` depending on your installation), like this: ```bash -netdata-claim.sh -OPTION=VALUE ... +[global] + url = The Netdata Cloud base URL (optional, defaults to `https://app.netdata.cloud`) + token = The claiming token for your Netdata Cloud Space (required) + rooms = A comma-separated list of Rooms to add the Agent to (optional) + proxy = The URL of a proxy server to use for the connection, or none, or env (optional, defaults to env) + insecure = Either yes or no (optional) ``` -Claiming script options: +- `proxy` can get anything libcurl accepts as a proxy, or the `none` and `env` keywords. `none` (or just an empty value) disables proxy configuration, while `env` tells libcurl to use the environment to determine the proxy configuration (usually the `https_proxy` environment variable). +- `insecure` is a boolean (either `yes`, or `no`) and when set to `yes` it instructs libcurl to disable host verification. -| Option | Description | Required | Default value | -|--------|--------------------------------------------------------------------|:--------:|:------------------------------------------------------| -| token | The claiming token for your Netdata Cloud Space. | yes | | -| rooms | A comma-separated list of Rooms to add the Agent to. | no | The Agent will be added to the "All nodes" Room only. | -| id | The unique identifier of the Agent. | no | The Agent's MACHINE_GUID. | -| proxy | The URL of a proxy server to use for the connection, if necessary. | no | | - -Example: +example: ```bash -netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 +[global] + url = https://app.netdata.cloud + token = NETDATA_CLOUD_SPACE_TOKEN + rooms = ROOM_KEY1,ROOM_KEY2,ROOM_KEY3 + proxy = http://username:password@myproxy:8080 + insecure = no ``` -This command connects the Agent and adds it to the "room1" and "room2" Rooms using your claiming token -MYTOKEN1234567. +If the agent is already running, you can either run `netdatacli reload-claiming-state` or restart the agent. +Otherwise, the agent will be claimed when it starts. + +If the claiming process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v2/info`. + +#### Automatically, via environment variables + +Netdata will use the following environment variables: + +- `NETDATA_CLAIM_URL`: The Netdata Cloud base URL (optional, defaults to `https://app.netdata.cloud`) +- `NETDATA_CLAIM_TOKEN`: The claiming token for your Netdata Cloud Space (required) +- `NETDATA_CLAIM_ROOMS`: A comma-separated list of Rooms to add the Agent to (optional) +- `NETDATA_CLAIM_PROXY`: The URL of a proxy server to use for the connection (optional) +- `NETDATA_EXTRA_CLAIM_OPTS`, may contain a space separated list of options. The option `-insecure` is the only currently used. + +The `NETDATA_CLAIM_TOKEN` alone is enough for triggering the claiming process. + +If the claiming process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v2/info`. ## Reconnect @@ -84,22 +100,16 @@ cd /var/lib/netdata # Replace with your Netdata library directory, if not /var sudo rm -rf cloud.d/ ``` +> **IMPORTANT** +> +> Keep in mind that the Agent will be **re-claimed automatically** if the environment variables or `claim.conf` exist when the agent is restarted. + 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 Rooms in an **unreachable** state. -If you want to reconnect this node, you need to: - -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` -2. Stop the Agent -3. Ensure that the `uuidgen-runtime` package is installed. Run ```echo "$(uuidgen)"``` and validate you get back a UUID -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.` -5. Start the Agent - ### Docker based installations -To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps: +To remove a node from your Space in Netdata Cloud and connect it to another Space, follow these steps: 1. Enter the running container you wish to remove from your Space @@ -113,7 +123,6 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac ```bash rm -rf /var/lib/netdata/cloud.d/ - rm /var/lib/netdata/registry/netdata.public.unique.id ``` @@ -123,7 +132,6 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac ```bash docker stop CONTAINER_NAME - docker rm CONTAINER_NAME ``` @@ -144,35 +152,31 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac ``` 4. Finally, go to your new Space, copy the installation command with the new claim token and run it. - If you are using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token. + If you’re using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token. The node should now appear online in that Space. ## Regenerate Claiming Token -If in case of some security reason, or other, you need to revoke your previous claiming token and generate a new one you -can achieve that from the Netdata Cloud UI. +There may be situations where you need to revoke your previous Netdata Cloud claiming token and generate a new one for security reasons. Here's how to do it: + +**Requirements**: + +- Only administrators of Space in Netdata Cloud can regenerate tokens. -On any screen where you see the connect the node to Netdata Cloud command you'll see above it, next to -the [updates channel](/docs/netdata-agent/versions-and-platforms.md), a -button to **Regenerate token**. This action will invalidate your previous token and generate a fresh new one. +**Steps**: -Only the administrators of a Space in Netdata Cloud can trigger this action. +1. Navigate to any screen within the Netdata Cloud UI where you see the "Connect the node to Netdata Cloud" command. +2. Look above this command, near the [Updates channel](/docs/netdata-agent/versions-and-platforms.md). You should see a button that says "Regenerate token." +3. Click the "Regenerate token" button. This action will invalidate your previous token and generate a new one. ## Troubleshoot If you're having trouble connecting a node, this may be because the [ACLK](/src/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 connection process. - -``` -"cloud-enabled" -"cloud-available" -"agent-claimed" -"aclk-available" -``` +With the Netdata Agent running, visit `http://NODE:19999/api/v2/info` in your browser, replacing `NODE` with the IP +address or hostname of your Agent. The returned JSON contains a section called `cloud` with helpful information to +diagnose any issues you might be having with the ACLK or connection process. > **Note** > @@ -199,149 +203,33 @@ installed Netdata using an unsupported package. > **Note** > -> If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution, +> If you’re 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](/packaging/installer/methods/kickstart.md). ### 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: +You might encounter this error if you run the Netdata kickstart script without sufficient permissions: ```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. - -### bash: netdata-claim.sh: command not found +To resolve this issue, you have two options: -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. +1. Run the script with root privileges. +2. Run the script with the user that runs the Netdata Agent. -For example, if you installed Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming -script. - -> **Note** -> -> 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](/packaging/installer/methods/kickstart.md). - -### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6) +### Connecting to Cloud 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 -versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which -helps securely encrypt SSL connections. +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 up-to-date version of OpenSSL with hostname validation enabled. +We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart.md#install-type), 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 with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to man-in-the-middle attacks. - -### cloud-enabled is false - -If `cloud-enabled` is `false`, you probably ran the installer with `--disable-cloud` option. - -Additionally, check that the `enabled` setting in `var/lib/netdata/cloud.d/cloud.conf` is set to `true`: - -```conf -[global] - enabled = true -``` - -To fix this issue, reinstall Netdata using -your [preferred method](/packaging/installer/README.md) and do not add -the `--disable-cloud` option. - -### cloud-available is false / ACLK Available: No - -If `cloud-available` is `false` after you verified Cloud is enabled in the previous step, the most likely issue is that -Cloud features failed to build during installation. - -If Cloud features fail to build, the installer continues and finishes the process without Cloud functionality as opposed -to failing the installation altogether. - -We do this to ensure the Agent will always finish installing. - -If you can't see an explicit error in the installer's output, you can run the installer with the `--require-cloud` -option. This option causes the installation to fail if Cloud functionality can't be built and enabled, and the -installer's output should give you more error details. - -You may see one of the following error messages during installation: - -- `Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud.` -- `Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud.` -- `Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud.` -- `Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud.` -- `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.` -- `Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud support will be disabled.` -- `Failed to build JSON-C. Netdata Cloud support will be disabled.` -- `Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled.` - -One common cause of the installer failing to build Cloud features is not having one of the following dependencies on -your system: `cmake`, `json-c` and `OpenSSL`, including corresponding `devel` packages. - -You can also look for error messages in `/var/log/netdata/error.log`. Try one of the following two commands to search -for ACLK-related errors. - -```bash -less /var/log/netdata/error.log -grep -i ACLK /var/log/netdata/error.log -``` - -If the installer's output does not help you enable Cloud features, contact us -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) -with details about your system and relevant output from `error.log`. - -### agent-claimed is false / Claimed: No - -You must [connect your node](#connect). - -### aclk-available is false / Online: No - -If `aclk-available` is `false` and all other keys are `true`, your Agent is having trouble connecting to the Cloud -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 connecting. - -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?assignees=&labels=bug%2Cneeds+triage&template=BUG_REPORT.yml&title=ACLK-available-is-false) -with details about your system and relevant output from `error.log`. - -## 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 - -This section defines how and whether your Agent connects to Netdata Cloud using -the [Agent-Cloud link](/src/aclk/README.md)(ACLK). - -| setting | default | info | -|:---------------|:----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| -| enabled | yes | Controls whether the ACLK is active. Set to no to prevent the Agent from connecting to Netdata Cloud. | -| cloud base url | <https://app.netdata.cloud> | The URL for the Netdata Cloud web application. Typically, this should not be changed. | -| proxy | env | Specifies the proxy setting for the ACLK. Options: none (no proxy), env (use environment's proxy), or a URL (e.g., `http://proxy.example.com:1080`). | - -### Connection directory - -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. - -The `cloud.d/token` file should contain the claiming-token and the `cloud.d/rooms` file should contain the list of War -Rooms you added that node to. - -The user can also put the Cloud endpoint's full certificate chain in `cloud.d/cloud_fullchain.pem` so that the Agent -can trust the endpoint if necessary. |