Adding upstream version 1.37.1.upstream/1.37.1upstream

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

4 files changed, 605 insertions, 0 deletions

diff --git a/docs/configure/common-changes.md b/docs/configure/common-changes.md
new file mode 100644
index 0000000..93b12d2
--- /dev/null
+++ b/docs/configure/common-changes.md
@@ -0,0 +1,214 @@
+<!--
+title: "Common configuration changes"
+description: "See the most popular configuration changes to make to the Netdata Agent, including longer metrics retention, reduce sampling, and more."
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/common-changes.md
+-->
+
+# Common configuration changes
+
+The Netdata Agent requires no configuration upon installation to collect thousands of per-second metrics from most
+systems, containers, and applications, but there are hundreds of settings to tweak if you want to exercise more control
+over your monitoring platform.
+
+This document assumes familiarity with using [`edit-config`](/docs/configure/nodes.md) from the Netdata config
+directory.
+
+## Change dashboards and visualizations
+
+The Netdata Agent's [local dashboard](/web/gui/README.md), accessible at `http://NODE:19999` is highly configurable. If
+you use Netdata Cloud for [infrastructure monitoring](/docs/quickstart/infrastructure.md), you will see many of these
+changes reflected in those visualizations due to the way Netdata Cloud proxies metric data and metadata to your browser.
+
+### Increase the long-term metrics retention period
+
+Increase the values for the `page cache size` and `dbengine multihost disk space` settings in the [`[global]`
+section](/daemon/config/README.md#global-section-options) of `netdata.conf`.
+
+```conf
+[global]
+    page cache size = 128   # 128 MiB of memory for metrics storage
+    dbengine multihost disk space = 4096   # 4GiB of disk space for metrics storage
+```
+
+Read our doc on [increasing long-term metrics storage](/docs/store/change-metrics-storage.md) for details, including a
+[calculator](/docs/store/change-metrics-storage.md#calculate-the-system-resources-ram-disk-space-needed-to-store-metrics)
+to help you determine the exact settings for your desired retention period.
+
+### Reduce the data collection frequency
+
+Change `update every` in the [`[global]` section](/daemon/config/README.md#global-section-options) of `netdata.conf` so
+that it is greater than `1`. An `update every` of `5` means the Netdata Agent enforces a _minimum_ collection frequency
+of 5 seconds.
+
+```conf
+[global]
+    update every = 5
+```
+
+Every collector and plugin has its own `update every` setting, which you can also change in the `go.d.conf`,
+`python.d.conf` or `charts.d.conf` files, or in individual collector configuration files. If the `update
+every` for an individual collector is less than the global, the Netdata Agent uses the global setting. See the [enable
+or configure a collector](/docs/collect/enable-configure.md) doc for details.
+
+### Disable a collector or plugin
+
+Turn off entire plugins in the [`[plugins]` section](/daemon/config/README.md#plugins-section-options) of
+`netdata.conf`.
+
+To disable specific collectors, open `go.d.conf`, `python.d.conf` or `charts.d.conf` and find the line
+for that specific module. Uncomment the line and change its value to `no`.
+
+## Modify alarms and notifications
+
+Netdata's health monitoring watchdog uses hundreds of preconfigured health entities, with intelligent thresholds, to
+generate warning and critical alarms for most production systems and their applications without configuration. However,
+each alarm and notification method is completely customizable.
+
+### Add a new alarm
+
+To create a new alarm configuration file, initiate an empty file, with a filename that ends in `.conf`, in the
+`health.d/` directory. The Netdata Agent loads any valid alarm configuration file ending in `.conf` in that directory.
+Next, edit the new file with `edit-config`. For example, with a file called `example-alarm.conf`.
+
+```bash
+sudo touch health.d/example-alarm.conf
+sudo ./edit-config health.d/example-alarm.conf
+```
+
+Or, append your new alarm to an existing file by editing a relevant existing file in the `health.d/` directory.
+
+Read more about [configuring alarms](/docs/monitor/configure-alarms.md) to get started, and see the [health monitoring
+reference](/health/REFERENCE.md) for a full listing of options available in health entities.
+
+### Configure a specific alarm
+
+Tweak existing alarms by editing files in the `health.d/` directory. For example, edit `health.d/cpu.conf` to change how
+the Agent responds to anomalies related to CPU utilization.
+
+To see which configuration file you need to edit to configure a specific alarm, [view your active
+alarms](/docs/monitor/view-active-alarms.md) in Netdata Cloud or the local Agent dashboard and look for the **source**
+line. For example, it might read `source  4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. 
+
+Because the source path contains `health.d/cpu.conf`, run `sudo edit-config health.d/cpu.conf` to configure that alarm.
+
+### Disable a specific alarm
+
+Open the configuration file for that alarm and set the `to` line to `silent`.
+
+```conf
+template: disk_fill_rate
+       on: disk.space
+   lookup: max -1s at -30m unaligned of avail
+     calc: ($this - $avail) / (30 * 60)
+    every: 15s
+       to: silent
+```
+
+### Turn of all alarms and notifications
+
+Set `enabled` to `no` in the [`[health]` section](/daemon/config/README.md#health-section-options) section of
+`netdata.conf`.
+
+### Enable alarm notifications
+
+Open `health_alarm_notify.conf` for editing. First, read the [enabling
+notifications](/docs/monitor/enable-notifications.md#netdata-agent) doc for an example of the process using Slack, then
+click on the link to your preferred notification method to find documentation for that specific endpoint.
+
+## Improve node security
+
+While the Netdata Agent is both [open and secure by design](https://www.netdata.cloud/blog/netdata-agent-dashboard/), we
+recommend every user take some action to administer and secure their nodes.
+
+Learn more about a few of the following changes in the [node security doc](/docs/configure/secure-nodes.md).
+
+### Disable the local Agent dashboard (`http://NODE:19999`)
+
+If you use Netdata Cloud to visualize metrics, stream metrics to a parent node, or otherwise don't need the local Agent
+dashboard, disabling it reduces the Agent's resource utilization and improves security.
+
+Change the `mode` setting to `none` in the [`[web]` section](/web/server/README.md#configuration) of `netdata.conf`.
+
+```conf
+[web]
+    mode = none
+```
+
+### Use access lists to restrict access to specific assets
+
+Allow access from only specific IP addresses, ranges of IP addresses, or hostnames using [access
+lists](/web/server/README.md#access-lists) and [simple patterns](/libnetdata/simple_pattern/README.md).
+
+See a quickstart to access lists in the [node security
+doc](/docs/configure/secure-nodes.md#restrict-access-to-the-local-dashboard).
+
+### Stop sending anonymous statistics to Google Analytics
+
+Create a file called `.opt-out-from-anonymous-statistics` inside of your Netdata config directory to immediately stop
+the statistics script.
+
+```bash
+sudo touch .opt-out-from-anonymous-statistics
+```
+
+Learn more about [why we collect anonymous statistics](/docs/anonymous-statistics.md).
+
+### Change the IP address/port Netdata listens to
+
+Change the `default port` setting in the `[web]` section to a port other than `19999`.
+
+```conf
+[web]
+   default port = 39999
+```
+
+Use the `bind to` setting to the ports other assets, such as the [running `netdata.conf`
+configuration](/docs/configure/nodes.md#see-an-agents-running-configuration), API, or streaming requests listen to.
+
+## Reduce resource usage
+
+Read our [performance optimization guide](/docs/guides/configure/performance.md) for a long list of specific changes
+that can reduce the Netdata Agent's CPU/memory footprint and IO requirements.
+
+## Organize nodes with host labels
+
+Beginning with v1.20, Netdata accepts user-defined **host labels**. These labels are sent during streaming, exporting,
+and as metadata to Netdata Cloud, and help you organize the metrics coming from complex infrastructure. Host labels are
+defined in the section `[host labels]`. 
+
+For a quick introduction, read the [host label guide](/docs/guides/using-host-labels.md).
+
+The following restrictions apply to host label names: 
+ 
+-   Names cannot start with `_`, but it can be present in other parts of the name.
+-   Names only accept alphabet letters, numbers, dots, and dashes.
+
+The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes
+(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alarms and
+templates.
+
+## What's next?
+
+If you haven't already, learn how to [secure your nodes](/docs/configure/secure-nodes.md).
+
+As mentioned at the top, there are plenty of other 
+
+You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features:
+
+- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
+- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
+- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your
+  infrastructure.
+- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
+
+### Related reference documentation
+
+- [Netdata Agent · Daemon](/health/README.md)
+- [Netdata Agent · Daemon configuration](/daemon/config/README.md)
+- [Netdata Agent · Web server](/web/server/README.md)
+- [Netdata Agent · Local Agent dashboard](/web/gui/README.md)
+- [Netdata Agent · Health monitoring](/health/REFERENCE.md)
+- [Netdata Agent · Notifications](/health/notifications/README.md)
+- [Netdata Agent · Simple patterns](/libnetdata/simple_pattern/README.md)
+
+[![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%2Fdocs%2Fconfigure%2Fcommon-changes&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)
diff --git a/docs/configure/nodes.md b/docs/configure/nodes.md
new file mode 100644
index 0000000..841419a
--- /dev/null
+++ b/docs/configure/nodes.md
@@ -0,0 +1,170 @@
+<!--
+title: "Configure the Netdata Agent"
+description: "Netdata is zero-configuration for most users, but complex infrastructures may require you to tweak some of the Agent's granular settings."
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/nodes.md
+-->
+
+# Configure the Netdata Agent
+
+Netdata's zero-configuration collection, storage, and visualization features work for many users, infrastructures, and
+use cases, but there are some situations where you might want to configure the Netdata Agent running on your node(s),
+which can be a physical or virtual machine (VM), container, cloud deployment, or edge/IoT device.
+
+For example, you might want to increase metrics retention, configure a collector based on your infrastructure's unique
+setup, or secure the local dashboard by restricting it to only connections from `localhost`.
+
+Whatever the reason, Netdata users should know how to configure individual nodes to act decisively if an incident,
+anomaly, or change in infrastructure affects how their Agents should perform.
+
+## The Netdata config directory
+
+On most Linux systems, using our [recommended one-line
+installation](/docs/get-started.mdx#install-on-linux-with-one-line-installer), the **Netdata config
+directory** is `/etc/netdata/`. The config directory contains several configuration files with the `.conf` extension, a
+few directories, and a shell script named `edit-config`.
+
+> Some operating systems will use `/opt/netdata/etc/netdata/` as the config directory. If you're not sure where yours
+> is, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with the IP address or hostname of
+> your node, and find the `# config directory = ` setting. The value listed is the config directory for your system.
+
+All of Netdata's documentation assumes that your config directory is at `/etc/netdata`, and that you're running any
+scripts from inside that directory.
+
+## Netdata's configuration files
+
+Upon installation, the Netdata config directory contains a few files and directories. It's okay if you don't see all
+these files in your own Netdata config directory, as the next section describes how to edit any that might not already
+exist.
+
+- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. Read descriptions
+  for each in the [daemon config](/daemon/config/README.md) doc.
+- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-configuration-files).
+- Various configuration files ending in `.conf` for [configuring plugins or
+  collectors](/docs/collect/enable-configure.md#enable-a-collector-or-its-orchestrator) behave. Examples: `go.d.conf`,
+  `python.d.conf`, and `ebpf.d.conf`.
+- Various directories ending in `.d`, which contain other configuration files, each ending in `.conf`, for [configuring
+  specific collectors](/docs/collect/enable-configure.md#configure-a-collector).
+- `apps_groups.conf` is a configuration file for changing how applications/processes are grouped when viewing the
+  **Application** charts from [`apps.plugin`](/collectors/apps.plugin/README.md) or
+  [`ebpf.plugin`](/collectors/ebpf.plugin/README.md).
+- `health.d/` is a directory that contains [health configuration files](/docs/monitor/configure-alarms.md).
+- `health_alarm_notify.conf` enables and configures [alarm notifications](/docs/monitor/enable-notifications.md).
+- `statsd.d/` is a directory for configuring Netdata's [statsd collector](/collectors/statsd.plugin/README.md).
+- `stream.conf` configures [parent-child streaming](/streaming/README.md) between separate nodes running the Agent.
+- `.environment` is a hidden file that describes the environment in which the Netdata Agent is installed, including the
+  `PATH` and any installation options. Useful for [reinstalling](/packaging/installer/REINSTALL.md) or
+  [uninstalling](/packaging/installer/UNINSTALL.md) the Agent.
+
+The Netdata config directory also contains one symlink:
+
+- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files. Stock
+  versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in
+  `/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._
+
+## Configure a Netdata docker container
+
+See [configure agent containers](/packaging/docker/README.md#configure-agent-containers).
+
+## Use `edit-config` to edit configuration files
+
+The **recommended way to easily and safely edit Netdata's configuration** is with the `edit-config` script. This script
+opens existing Netdata configuration files using your system's `$EDITOR`. If the file doesn't yet exist in your config
+directory, the script copies the stock version from `/usr/lib/netdata/conf.d` and opens it for editing.
+
+Run `edit-config` without any options to see details on its usage and a list of all the configuration files you can
+edit.
+
+```bash
+./edit-config
+USAGE:
+  ./edit-config FILENAME
+
+  Copy and edit the stock config file named: FILENAME
+  if FILENAME is already copied, it will be edited as-is.
+
+  The EDITOR shell variable is used to define the editor to be used.
+
+  Stock config files at: '/usr/lib/netdata/conf.d'
+  User  config files at: '/etc/netdata'
+
+  Available files in '/usr/lib/netdata/conf.d' to copy and edit:
+
+./apps_groups.conf                  ./health.d/phpfpm.conf
+./aws_kinesis.conf                  ./health.d/pihole.conf
+./charts.d/ap.conf                  ./health.d/portcheck.conf
+./charts.d/apcupsd.conf             ./health.d/postgres.conf
+...
+```
+
+To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevate your privileges with `sudo` or another
+method for `edit-config` to write into the config directory. Use your `$EDITOR`, make your changes, and save the file.
+
+> `edit-config` uses the `EDITOR` environment variable on your system to edit the file. On many systems, that is
+> defaulted to `vim` or `nano`. Use `export EDITOR=` to change this temporarily, or edit your shell configuration file
+> to change to permanently.
+
+After you make your changes, you need to [restart the Agent](/docs/configure/start-stop-restart.md) with `sudo systemctl
+restart netdata` or the appropriate method for your system.
+
+Here's an example of editing the node's hostname, which appears in both the local dashboard and in Netdata Cloud.
+
+![Animated GIF of editing the hostname option in
+netdata.conf](https://user-images.githubusercontent.com/1153921/80994808-1c065300-8df2-11ea-81af-d28dc3ba27c8.gif)
+
+### Other configuration files
+
+You can edit any Netdata configuration file using `edit-config`. A few examples:
+
+```bash
+./edit-config apps_groups.conf
+./edit-config ebpf.d.conf
+./edit-config health.d/load.conf
+./edit-config go.d/prometheus.conf
+```
+
+The documentation for each of Netdata's components explains which file(s) to edit to achieve the desired behavior.
+
+## See an Agent's running configuration
+
+On start, the Netdata Agent daemon attempts to load `netdata.conf`. If that file is missing, incomplete, or contains
+invalid settings, the daemon attempts to run sane defaults instead. In other words, the state of `netdata.conf` on your
+filesystem may be different from the state of the Netdata Agent itself.
+
+To see the _running configuration_, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with
+the IP address or hostname of your node. The file displayed here is exactly the settings running live in the Netdata
+Agent.
+
+If you're having issues with configuring the Agent, apply the running configuration to `netdata.conf` by downloading the
+file to the Netdata config directory. Use `sudo` to elevate privileges.
+
+```bash
+wget -O /etc/netdata/netdata.conf http://localhost:19999/netdata.conf
+# or
+curl -o /etc/netdata/netdata.conf http://NODE:19999/netdata.conf
+```
+
+## What's next?
+
+Learn more about [starting, stopping, or restarting](/docs/configure/start-stop-restart.md) the Netdata daemon to apply
+configuration changes.
+
+Apply some [common configuration changes](/docs/configure/common-changes.md) to quickly tweak the Agent's behavior.
+
+[Add security to your node](/docs/configure/secure-nodes.md) with what you've learned about the Netdata config directory
+and `edit-config`. We put together a few security best practices based on how you use the Netdata.
+
+You can also take what you've learned about node configuration to enable or enhance features:
+
+-   [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
+-   [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
+-   [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your
+    infrastructure.
+-   Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
+
+### Related reference documentation
+
+- [Netdata Agent · Daemon](/daemon/README.md)
+- [Netdata Agent · Health monitoring](/health/README.md)
+- [Netdata Agent · Notifications](/health/notifications/README.md)
+
+[![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%2Fdocs%2Fconfigure%2Fnodes&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)
diff --git a/docs/configure/secure-nodes.md b/docs/configure/secure-nodes.md
new file mode 100644
index 0000000..02057ab
--- /dev/null
+++ b/docs/configure/secure-nodes.md
@@ -0,0 +1,123 @@
+<!--
+title: "Secure your nodes"
+description: "Your data and systems are safe with Netdata, but we recommend a few easy ways to improve the security of your infrastructure."
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/secure-nodes.md
+-->
+
+# Secure your nodes
+
+Upon installation, the Netdata Agent serves the **local dashboard** at port `19999`. If the node is accessible to the
+internet at large, anyone can access the dashboard and your node's metrics at `http://NODE:19999`. We made this decision
+so that the local dashboard was immediately accessible to users, and so that we don't dictate how professionals set up
+and secure their infrastructures. 
+
+Despite this design decision, your [data](/docs/netdata-security.md#your-data-is-safe-with-netdata) and your
+[systems](/docs/netdata-security.md#your-systems-are-safe-with-netdata) are safe with Netdata. Netdata is read-only,
+cannot do anything other than present metrics, and runs without special/`sudo` privileges. Also, the local dashboard
+only exposes chart metadata and metric values, not raw data.
+
+While Netdata is secure by design, we believe you should [protect your
+nodes](/docs/netdata-security.md#why-netdata-should-be-protected). If left accessible to the internet at large, the
+local dashboard could reveal sensitive information about your infrastructure. For example, an attacker can view which
+applications you run (databases, webservers, and so on), or see every user account on a node. 
+
+Instead of dictating how to secure your infrastructure, we give you many options to establish security best practices
+that align with your goals and your organization's standards.
+
+-   [Disable the local dashboard](#disable-the-local-dashboard): **Simplest and recommended method** for those who have
+    added nodes to Netdata Cloud and view dashboards and metrics there.
+-   [Restrict access to the local dashboard](#restrict-access-to-the-local-dashboard): Allow local dashboard access from
+    only certain IP addresses, such as a trusted static IP or connections from behind a management LAN. Full support for
+    Netdata Cloud.
+-   [Use a reverse proxy](#use-a-reverse-proxy): Password-protect a local dashboard and enable TLS to secure it. Full
+    support for Netdata Cloud.
+
+## Disable the local dashboard
+
+This is the _recommended method for those who have connected their nodes to Netdata Cloud_ and prefer viewing real-time
+metrics using the War Room Overview, Nodes view, and Cloud dashboards.
+
+You can disable the local dashboard (and API) but retain the encrypted Agent-Cloud link ([ACLK](/aclk/README.md)) that
+allows you to stream metrics on demand from your nodes via the Netdata Cloud interface. This change mitigates all
+concerns about revealing metrics and system design to the internet at large, while keeping all the functionality you
+need to view metrics and troubleshoot issues with Netdata Cloud.
+
+Open `netdata.conf` with `./edit-config netdata.conf`. Scroll down to the `[web]` section, and find the `mode =
+static-threaded` setting, and change it to `none`.
+
+```conf
+[web]
+    mode = none
+```
+
+Save and close the editor, then [restart your Agent](/docs/configure/start-stop-restart.md) using `sudo systemctl
+restart netdata`. If you try to visit the local dashboard to `http://NODE:19999` again, the connection will fail because
+that node no longer serves its local dashboard.
+
+> See the [configuration basics doc](/docs/configure/nodes.md) for details on how to find `netdata.conf` and use
+> `edit-config`.
+
+## Restrict access to the local dashboard
+
+If you want to keep using the local dashboard, but don't want it exposed to the internet, you can restrict access with
+[access lists](/web/server/README.md#access-lists). This method also fully retains the ability to stream metrics
+on-demand through Netdata Cloud.
+
+The `allow connections from` setting helps you allow only certain IP addresses or FQDN/hostnames, such as a trusted
+static IP, only `localhost`, or connections from behind a management LAN. 
+
+By default, this setting is `localhost *`. This setting allows connections from `localhost` in addition to _all_
+connections, using the `*` wildcard. You can change this setting using Netdata's [simple
+patterns](/libnetdata/simple_pattern/README.md).
+
+```conf
+[web]
+    # Allow only localhost connections
+    allow connections from = localhost
+
+    # Allow only from management LAN running on `10.X.X.X`
+    allow connections from = 10.*
+
+    # Allow connections only from a specific FQDN/hostname
+    allow connections from = example*
+```
+
+The `allow connections from` setting is global and restricts access to the dashboard, badges, streaming, API, and
+`netdata.conf`, but you can also set each of those access lists more granularly if you choose:
+
+```conf
+[web]
+    allow connections from = localhost *
+    allow dashboard from = localhost *
+    allow badges from = *
+    allow streaming from = *
+    allow netdata.conf from = localhost fd* 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22.* 172.23.* 172.24.* 172.25.* 172.26.* 172.27.* 172.28.* 172.29.* 172.30.* 172.31.*
+    allow management from = localhost
+```
+
+See the [web server](/web/server/README.md#access-lists) docs for additional details about access lists. You can take
+access lists one step further by [enabling SSL](/web/server/README.md#enabling-tls-support) to encrypt data from local
+dashboard in transit. The connection to Netdata Cloud is always secured with TLS.
+
+## Use a reverse proxy
+
+You can also put Netdata behind a reverse proxy for additional security while retaining the functionality of both the
+local dashboard and Netdata Cloud dashboards. You can use a reverse proxy to password-protect the local dashboard and
+enable HTTPS to encrypt metadata and metric values in transit.
+
+We recommend Nginx, as it's what we use for our [demo server](https://london.my-netdata.io/), and we have a guide
+dedicated to [running Netdata behind Nginx](/docs/Running-behind-nginx.md).
+
+We also have guides for [Apache](/docs/Running-behind-apache.md), [Lighttpd](/docs/Running-behind-lighttpd.md),
+[HAProxy](/docs/Running-behind-haproxy.md), and [Caddy](/docs/Running-behind-caddy.md).
+
+## What's next?
+
+Read about [Netdata's security design](/docs/netdata-security.md) and our [blog
+post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) about why the local Agent dashboard is both open and
+secure by design.
+
+Next up, learn about [collectors](/docs/collect/how-collectors-work.md) to ensure you're gathering every essential
+metric about your node, its applications, and your infrastructure at large.
+
+[![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%2Fdocs%2Fconfigure%2Fsecure-nodesa&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)
diff --git a/docs/configure/start-stop-restart.md b/docs/configure/start-stop-restart.md
new file mode 100644
index 0000000..4967fff
--- /dev/null
+++ b/docs/configure/start-stop-restart.md
@@ -0,0 +1,98 @@
+<!--
+title: "Start, stop, or restart the Netdata Agent"
+description: "Manage the Netdata Agent daemon, load configuration changes, and troubleshoot stuck processes on systemd and non-systemd nodes."
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/start-stop-restart.md
+-->
+
+# Start, stop, or restart the Netdata Agent
+
+When you install the Netdata Agent, the [daemon](/daemon/README.md) is configured to start at boot and stop and
+restart/shutdown.
+
+You will most often need to _restart_ the Agent to load new or editing configuration files. [Health
+configuration](#reload-health-configuration) files are the only exception, as they can be reloaded without restarting
+the entire Agent.
+
+Stopping or restarting the Netdata Agent will cause gaps in stored metrics until the `netdata` process initiates
+collectors and the database engine.
+
+## Using `systemctl`, `service`, or `init.d`
+
+This is the recommended way to start, stop, or restart the Netdata daemon.
+
+- To **start** Netdata, run `sudo systemctl start netdata`.
+- To **stop** Netdata, run `sudo systemctl stop netdata`.
+- To **restart** Netdata, run `sudo systemctl restart netdata`.
+
+If the above commands fail, or you know that you're using a non-systemd system, try using the `service` command:
+
+- **service**: `sudo service netdata start`, `sudo service netdata stop`, `sudo service netdata restart`
+
+## Using `netdata`
+
+Use the `netdata` command, typically located at `/usr/sbin/netdata`, to start the Netdata daemon. 
+
+```bash
+sudo netdata
+```
+
+If you start the daemon this way, close it with `sudo killall netdata`.
+
+## Using `netdatacli`
+
+The Netdata Agent also comes with a [CLI tool](/cli/README.md) capable of performing shutdowns. Start the Agent back up
+using your preferred method listed above.
+
+```bash
+sudo netdatacli shutdown-agent
+```
+
+## Reload health configuration
+
+You do not need to restart the Netdata Agent between changes to health configuration files, such as specific health
+entities. Instead, use [`netdatacli`](#using-netdatacli) and the `reload-health` option to prevent gaps in metrics
+collection.
+
+```bash
+sudo netdatacli reload-health
+```
+
+If `netdatacli` doesn't work on your system, send a `SIGUSR2` signal to the daemon, which reloads health configuration
+without restarting the entire process.
+
+```bash
+killall -USR2 netdata
+```
+
+## Force stop stalled or unresponsive `netdata` processes
+
+In rare cases, the Netdata Agent may stall or not properly close sockets, preventing a new process from starting. In
+these cases, try the following three commands:
+
+```bash
+sudo systemctl stop netdata
+sudo killall netdata
+ps aux| grep netdata
+```
+
+The output of `ps aux` should show no `netdata` or associated processes running. You can now start the Netdata Agent
+again with `service netdata start`, or the appropriate method for your system.
+
+## What's next?
+
+Learn more about [securing the Netdata Agent](/docs/configure/secure-nodes.md).
+
+You can also use the restart/reload methods described above to enable new features:
+
+- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
+- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
+- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your
+  infrastructure.
+- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
+
+### Related reference documentation
+
+- [Netdata Agent · Daemon](/daemon/README.md)
+- [Netdata Agent · Netdata CLI](/cli/README.md)
+
+[![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%2Fdocs%2Fconfigure%2Fstart-stop-restart&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)