Docs: Update with go-live claiming and ACLK information (#8859) (#8960)

* Restore docs from naughty PR

* Address Andrew's comments

* Ini to conf

* Changes based on meeting with Andrew

* Tweak text around claiming

* Some grammar/typo fixes

* Add /var/lib/netdata to Docker instructions on README

* Added a few more ACLK links per Chris

Co-authored-by: Joel Hans <joel@netdata.cloud>

4 files changed, 177 insertions, 68 deletions

diff --git a/README.md b/README.md
index f3cbac6b1a..93325a79be 100644
--- a/README.md
+++ b/README.md
@@ -156,11 +156,14 @@ To try Netdata in a Docker container, run this:
 ```sh
 docker run -d --name=netdata \
   -p 19999:19999 \
+  -v netdatalib:/var/lib/netdata \
+  -v netdatacache:/var/cache/netdata \
   -v /etc/passwd:/host/etc/passwd:ro \
   -v /etc/group:/host/etc/group:ro \
   -v /proc:/host/proc:ro \
   -v /sys:/host/sys:ro \
-  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -v /etc/os-release:/host/etc/os-release:ro \
+  --restart unless-stopped \
   --cap-add SYS_PTRACE \
   --security-opt apparmor=unconfined \
   netdata/netdata
diff --git a/aclk/README.md b/aclk/README.md
index c2823fe362..e5529dd52c 100644
--- a/aclk/README.md
+++ b/aclk/README.md
@@ -2,28 +2,31 @@
 ---
 title: "Agent-Cloud link (ACLK)"
 description: "The Agent-Cloud link (ACLK) is the mechanism responsible for connecting a Netdata agent to Netdata Cloud."
-date: 2020-04-15
+date: 2020-04-30
 custom_edit_url: https://github.com/netdata/netdata/edit/master/aclk/README.md
 ---
 -->
 
 # Agent-cloud link (ACLK)
 
-The Agent-Cloud link (ACLK) is the mechanism responsible for connecting a Netdata Agent to Netdata Cloud. The ACLK uses
-[MQTT](https://en.wikipedia.org/wiki/MQTT) over secure websockets to first create, persist, encrypt the connection, and
-then enable the features found in Netdata Cloud. _No data is exchanged with Netdata Cloud until you claim a node._
+The Agent-Cloud link (ACLK) is the mechanism responsible for securely connecting a Netdata Agent to your web browser
+through Netdata Cloud. The ACLK is encrypted, safe, and _does not exchange data with Netdata Cloud until you claim a
+node_.
 
-Read our [claiming documentation](/claim/README.md) for a guide for claiming a node using the ACLK and additional
-troubleshooting and reference information.
+For a guide to claiming a node using the ACLK, plus additional troubleshooting and reference information, read our [get
+started with Cloud](https://learn.netdata.cloud/docs/cloud/get-started) guide or the full [claiming
+documentation](/claim/README.md).
 
 ## Enable and configure the ACLK
 
-The ACLK is enabled by default and automatically configured if the prerequisites installed correctly. You can see this
-in the `[cloud]` section of `netdata.conf`.
+The ACLK is enabled by default, with its settings automatically configured and stored in the Agent's memory. No file is
+created at `var/lib/netdata/cloud.d/cloud.conf` until you either claim a node or create it yourself. The default
+configuration uses two settings:
 
 ```conf
-[cloud]
-    cloud base url = https://app.netdata.cloud
+[global]
+  enabled = yes
+  cloud base url = https://app.netdata.cloud
 ```
 
 If your Agent needs to use a proxy to access the internet, you must [set up a proxy for
@@ -31,18 +34,81 @@ claiming](/claim/README.md#claim-through-a-proxy).
 
 ## Disable the ACLK
 
-You have two options if you prefer to disable the ACLK and not use Netdata Cloud:
+You have two options if you prefer to disable the ACLK and not use Netdata Cloud.
+
+### Disable at installation
+
+You can pass the `--disable-cloud` parameter to the Agent installation when using a kickstart script
+([kickstart.sh](/packaging/installer/methods/kickstart.md) or
+[kickstart-static64.sh](/packaging/installer/methods/kickstart-64.md)), or a [manual installation from
+Git](/packaging/installer/methods/manual.md).
 
-1.  Pass `--disable-cloud` to `netdata-installer.sh` during installation. When you pass this parameter, the installer
-    does not download or compile any extra libraries, and the Agent behaves as though the ACLK, and thus Netdata Cloud,
-    does not exist. ACLK functionality is available in the Agent but remains fully inactive.
+When you pass this parameter, the installer does not download or compile any extra libraries. Once running, the Agent
+kills the thread responsible for the ACLK and claiming behavior, and behaves as though the ACLK, and thus Netdata Cloud,
+does not exist.
 
-2.  Change a runtime setting in your `netdata.conf` file. This setting only stops the Agent from attempting any
-    connection via the ACLK, but does not prevent the installer from downloading and compiling the ACLK's dependencies.
+### Disable at runtime
+
+You can change a runtime setting in your `cloud.conf` file to disable the ACLK. This setting only stops the Agent from
+attempting any connection via the ACLK, but does not prevent the installer from downloading and compiling the ACLK's
+dependencies.
+
+The file typically exists at `/var/lib/netdata/cloud.d/cloud.conf`, but can change if you set a prefix during
+installation. To disable the ACLK, open that file and change the `enabled` setting to `no`:
 
 ```conf
 [global]
-    netdata cloud = disable
+    enabled = no
 ```
 
+If the file at `/var/lib/netdata/cloud.d/cloud.conf` doesn't exist, you need to create it. 
+
+Copy and paste the first two lines from below, which will change your prompt to `cat`.
+
+```bash
+cd /var/lib/netdata/cloud.d
+cat > cloud.conf << EOF
+```
+
+Copy and paste in lines 3-6, and after the final `EOF`, hit **Enter**. The final line must contain only `EOF`. Hit **Enter** again to return to your normal prompt with the newly-created file.
+
+To get your normal prompt back, the final line
+must contain only `EOF`.
+
+```bash
+[global]
+    enabled = no
+    cloud base url = https://app.netdata.cloud
+EOF
+```
+
+You also need to change the file's permissions. Use `grep "run as user" /etc/netdata/netdata.conf` to figure out which
+user your Agent runs as (typically `netdata`), and replace `netdata:netdata` as shown below if necessary:
+
+```bash
+sudo chmod 0770 cloud.conf
+sudo chown netdata:netdata cloud.conf
+```
+
+Restart your Agent to disable the ACLK.
+
+### Re-enable the ACLK
+
+If you first disable the ACLK and any Cloud functionality and then decide you would like to use Cloud, you must either
+reinstall Netdata with Cloud enabled or change the runtime setting in your `cloud.conf` file.
+
+If you passed `--disable-cloud` to `netdata-installer.sh` during installation, you must reinstall your Agent. Use the
+same method as before, but pass `--require-cloud` to the installer. When installation finishes you can [claim your
+node](/claim/README.md#claim-a-node).
+
+If you changed the runtime setting in your `var/lib/netdata/cloud.d/cloud.conf` file, edit the file again and change
+`enabled` to `yes`:
+
+```conf
+[global]
+    enabled = yes
+```
+
+Restart your Agent and [claim your node](/claim/README.md#claim-a-node).
+
 [![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Faclk%2FREADME&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)
diff --git a/claim/README.md b/claim/README.md
index 2743851e33..5fa1b30bcc 100644
--- a/claim/README.md
+++ b/claim/README.md
@@ -2,7 +2,7 @@
 ---
 title: "Agent claiming"
 description: "Agent claiming allows a Netdata Agent, running on a distributed node, to securely connect 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."
-date: 2020-04-15
+date: 2020-04-30
 custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md
 ---
 -->
@@ -13,6 +13,10 @@ Agent claiming allows a Netdata Agent, running on a distributed node, to securel
 administrator creates a **claiming token**, which is used to add an Agent to their Space via the [Agent-Cloud link
 (ACLK)](/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
+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
@@ -24,41 +28,58 @@ Netdata Cloud.
 > The claiming 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. This data is encrypted by
-TLS while it is in transit. We use the 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 from Agents to the
-browser, we do not store or log it.
-
-## How to claim a node
+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
+from Agents to the browser, we do not store or log it.
 
 You can claim a node during the Cloud onboarding process, or after you created a Space by clicking on the **USER's
-Space** dropdown, then **Manage Claimed Nodes**.
+Space** dropdown, then **Manage claimed nodes**.
 
-> Only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script generated by
-> Netdata Cloud.
+There are two important notes regarding claiming:
 
-To claim a node, copy the script given by Cloud. **You must run this script as the user running the** `netdata`
-**service**, which is usually the `netdata` user. You have two options: Switch to the appropriate user yourself, or run
-the command using `sudo` to automatically manage permissions.
+-   _You can only claim any given node in a single Space_. You can, however, add that claimed 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.
 
-By switching to the `netdata` user:
+## How to claim 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**.
 
 ```bash
-sudo su -s /bin/bash netdata
-netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
+sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
 ```
 
-With `sudo`:
+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.
+
+Repeat this process with every node you want to add to Cloud during onboarding. You can also add more nodes once you've
+finished onboarding.
+
+### Claim an agent without root privileges
+
+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.
+
+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:
 
 ```bash
-sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
+grep "run as user" /etc/netdata/netdata.conf 
+    # run as user = netdata
 ```
 
-Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, see
-the [troubleshooting information](#troubleshooting).
+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.
 
-> Your node may need up to 60 seconds to connect to Netdata Cloud after finishing the claiming process. Please be
-> patient!
+```bash
+netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
+```
+
+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). 
 
 ### Claim an Agent running in Docker
 
@@ -68,14 +89,15 @@ and immediately claim it.
 
 #### Running Agent containers
 
-Claim a _running Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing `netdata` with the name of your running container:
+Claim a _running Agent container_ by appending the script offered by 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 script should return `Agent was successfully claimed.`. If the claiming script returns errors, see the
-[troubleshooting information](#troubleshooting).
+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).
 
 #### New/ephemeral Agent containers
 
@@ -88,11 +110,14 @@ Cloud.
 ```bash
 docker run -d --name=netdata \
   -p 19999:19999 \
+  -v netdatalib:/var/lib/netdata \
+  -v netdatacache:/var/cache/netdata \
   -v /etc/passwd:/host/etc/passwd:ro \
   -v /etc/group:/host/etc/group:ro \
   -v /proc:/host/proc:ro \
   -v /sys:/host/sys:ro \
   -v /etc/os-release:/host/etc/os-release:ro \
+  --restart unless-stopped \
   --cap-add SYS_PTRACE \
   --security-opt apparmor=unconfined \
   netdata/netdata \
@@ -114,7 +139,7 @@ A Space's administrator can claim 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`.
 
-```ini
+```conf
 [cloud]
     proxy = none
 ```
@@ -134,25 +159,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. Be sure to switch to the `netdata` user or use `sudo` as explained in the [step
-above](#how-to-claim-a-node).
-
-When you claim with the `netdata-claim.sh` script, add the `-proxy=` parameter and append the same proxy setting you
-added to `netdata.conf`.
+You can now move on to claiming. When you claim with the `netdata-claim.sh` script, add the `-proxy=` parameter and
+append the same proxy setting you added to `netdata.conf`.
 
 ```bash
-netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 -url=https://app.netdata.cloud -proxy=socks5h://203.0.113.0:1080
+sudo netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 -url=https://app.netdata.cloud -proxy=socks5h://203.0.113.0:1080
 ```
 
-Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, see
-the [troubleshooting information](#troubleshooting).
+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).
 
 ### Troubleshooting
 
-If you're having trouble claiming a node, this may be because the ACLK cannot connect to Cloud.
+If you're having trouble claiming a node, this may be because the [ACLK](/aclk/README.md) cannot connect to Cloud.
 
-With the Netdata Agent running, visit `http://localhost:19999/api/v1/info` in your browser. The returned JSON contains
-four keys that will be helpful to diagnose any issues you might be having with the ACLK or claiming process.
+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.
 
 ```json
 	"cloud-enabled"
@@ -169,7 +192,7 @@ If `cloud-enabled` is `false`, you probably ran the installer with `--disable-cl
 
 Additionally, check that the `enabled` setting in `var/lib/netdata/cloud.d/cloud.conf` is set to `true`:
 
-```ini
+```conf
 [global]
     enabled = true
 ```
@@ -199,6 +222,12 @@ You may see one of the following error messages during installation:
     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` and OpenSSL, including the `devel` package.
@@ -221,7 +250,7 @@ You must [claim your node](#how-to-claim-a-node).
 
 #### aclk-available is false
 
-If `aclk-available` is `false` and all other keys are `true`, your Agent is having trouble connection to the Cloud
+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
@@ -239,23 +268,31 @@ Netdata library directory.
 
 ```bash
 cd /var/lib/netdata   # Replace with your Netdata library directory, if not /var/lib/netdata/
-rm -rf cloud.d/
+sudo rm -rf cloud.d/
 ```
 
-> You may need to use `sudo` or another method of elevating your privileges.
-
 Once you delete the `cloud.d/` directory, the ACLK will not connect to Cloud the next time the Agent starts, and Cloud
-will then remove it from the interface.
+will show it as **unreachable**. You can then remove it from your War Rooms.
 
 ## Claiming reference
 
 In the sections below, you can find reference material for the claiming script, claiming 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](https://learn.netdata.cloud/docs/cloud/)
+using the [ACLK](/aclk/README.md).
+
+| setting        | default                   | info                                                                                                                                   |
+|:-------------- |:------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.         |
+
 ### Claiming script
 
-A Space's administrator can claim an Agent by directly calling the `netdata-claim.sh` script **as the `netdata` user**
-and passing the following arguments:
+A Space's administrator can claim 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
 -token=TOKEN
@@ -306,12 +343,12 @@ If need be, the user can override the Agent's defaults by providing additional a
 
 ### Claiming directory
 
-Netdata stores the agent claiming-related state in the Netdata library directory under `cloud.d`, e.g. in
-`/var/lib/netdata/cloud.d`. The user can put files in this directory to provide defaults to the `-token` and `-rooms`
-arguments. These files should be owned **by the `netdata` user**.
+Netdata stores the Agent's claiming-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.
+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.
diff --git a/daemon/README.md b/daemon/README.md
index 9c571099aa..18c5e50b06 100644
--- a/daemon/README.md
+++ b/daemon/README.md
@@ -1,6 +1,7 @@
 <!--
 ---
 title: "Netdata daemon"
+date: 2020-04-29
 custom_edit_url: https://github.com/netdata/netdata/edit/master/daemon/README.md
 ---
 -->
@@ -184,6 +185,8 @@ The command line options of the Netdata 1.10.0 version are the following:
   -W simple-pattern pattern string
                            Check if string matches pattern and exit.
 
+  -W "claim -token=TOKEN -rooms=ROOM1,ROOM2 url=https://app.netdata.cloud"
+                           Claim the agent to the workspace rooms pointed to by TOKEN and ROOM*.
 
  Signals netdata handles: