Securing Agents section docs cleanup (#19053)

Co-authored-by: ilyam8 <ilya@netdata.cloud>

docs/netdata-agent/securing-netdata-agents.md

@@ -1,112 +1,85 @@
 # Securing Netdata Agents
 
-Netdata is a monitoring system. It should be protected, the same way you protect all your admin apps. We assume Netdata
-will be installed privately, for your eyes only.
+By default, the Agent exposes its **local dashboard** on port `19999`. If the node has a public IP address, the dashboard and metrics are accessible to anyone at `http://NODE:19999`.
 
-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.
+Protect your Agents by implementing any of these security measures:
 
-Viewers will be able to get some information about the system Netdata is running. This information is everything the dashboard
-provides. The dashboard includes a list of the services each system runs (the legends of the charts under the `Systemd Services`
-section), the applications running (the legends of the charts under the `Applications` section), the disks of the system and
-their names, the user accounts of the system that are running processes (the `Users` and `User Groups` section of the dashboard),
-the network interfaces and their names (not the IPs) and detailed information about the performance of the system and its applications.
+**Recommended**:
 
-This information is not sensitive (meaning that it is not your business data), but **it is important for possible attackers**.
-It will give them clues on what to check, what to try and in the case of DDoS against your applications, they will know if they’re doing it right or not.
+- [Disable the local dashboard](#disable-the-local-dashboard): Best for users who monitor their systems through Netdata Cloud dashboards.
+- [Use Netdata Parents as Web Application Firewalls](#use-netdata-parents-as-web-application-firewalls): Deploy Parent nodes as border gateways to isolate production systems from direct internet exposure, even when using Netdata Cloud.
 
-Also, viewers could use Netdata itself to stress your servers. Although the Netdata daemon runs unprivileged, with the minimum
-process priority (scheduling priority `idle` - lower than nice 19) and adjusts its OutOfMemory (OOM) score to 1000 (so that it
-will be first to be killed by the kernel if the system starves for memory), some pressure can be applied on your systems if
-someone attempts a DDoS against Netdata.
+**Alternative Approaches**:
 
-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.
-
-- [Expose Netdata only in a private LAN](#expose-netdata-only-in-a-private-lan). Simplest and recommended method for those who don’t use Netdata Cloud.
-
-- [Fine-grained access control](#fine-grained-access-control): 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 (authenticating web server in proxy mode)](#use-an-authenticating-web-server-in-proxy-mode): Password-protect
-  a local dashboard and enable TLS to secure it. Full support for Netdata Cloud.
-
-- [Use Netdata parents as Web Application Firewalls](#use-netdata-parents-as-web-application-firewalls)
-
-- [Other methods](#other-methods) list some less common methods of protecting Netdata.
+- [Restrict dashboard access to private LAN](#restrict-dashboard-access-to-private-lan): Suitable for accessing the local dashboard via a LAN connection.
+- [Configure granular access control](#configure-granular-access-control): Limit local dashboard access to specific IP addresses, such as trusted static IPs or management LAN connections.
+- [Deploy a reverse proxy](#deploy-a-reverse-proxy): Secure your dashboard with password protection and TLS encryption.
 
 ## 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 Room Overview, Nodes tab, and Cloud dashboards.
+Secure your nodes by disabling local dashboard access while maintaining Cloud monitoring capabilities:
 
-You can disable the local dashboard (and API) but retain the encrypted Agent-Cloud link
-([ACLK](/src/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.
+- Eliminates public exposure of metrics and system information.
+- Maintains secure metrics viewing through Netdata Cloud via [ACLK](/src/aclk/README.md).
 
-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`.
+Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script:
 
 ```text
 [web]
     mode = none
 ```
 
-Save and close the editor, then [restart your Agent](/docs/netdata-agent/start-stop-restart.md). 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.
+Restart your Agent to apply changes. After restart, the local dashboard (http://NODE:19999) will no longer be accessible, but all metrics remain available through Netdata Cloud.
+
+> **Note**
+>
+> For Docker deployments, set `NETDATA_HEALTHCHECK_TARGET=cli` in your environment variables.
+
+## Use Netdata Parents as Web Application Firewalls
+
+Enhance security by deploying Parent nodes as border gateways, eliminating the need for direct internet access from production Agents. Parent nodes:
 
-> See the [configuration basics doc](/docs/netdata-agent/configuration/README.md) for details on how to find
-`netdata.conf` and use
-> `edit-config`.
+- Act as application firewalls.
+- Receive metrics from Child Agents securely.
+- Serve dashboard requests using local data.
+- Maintain Netdata Cloud connectivity through encrypted connection.
 
-If you’re using Netdata with Docker, make sure to set the `NETDATA_HEALTHCHECK_TARGET` environment variable to `cli`.
+For more information, see [Observability Centralization Points](/docs/observability-centralization-points/README.md).
 
-## Expose Netdata only in a private LAN
+## Restrict dashboard access to private LAN
 
-If your organization has a private administration and management LAN, you can bind Netdata on this network interface on all your servers.
-This is done in `Netdata.conf` with these settings:
+Enhance security by binding the Agent to your organization's private management network interface. This limits dashboard access to your administrative LAN only.
+
+Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script:
 
 ```text
 [web]
     bind to = 10.1.1.1:19999 localhost:19999
 ```
 
-You can bind Netdata to multiple IPs and ports. If you use hostnames, Netdata will resolve them and use all the IPs
-(in the above example `localhost` usually resolves to both `127.0.0.1` and `::1`).
+The Agent supports binding to multiple IPs and ports. When using hostnames, all resolved IPs will be used (for example, `localhost` typically resolves to both `127.0.0.1` and `::1`).
+
+<details><summary>More info for cloud-based installations</summary>
+
+For cloud environments without private LAN capabilities or multi-cloud deployments, you can create a virtual management network using mesh VPN tools like `tincd` or `gvpe`. These tools enable secure, private communication between servers while allowing administration stations to access management functions across your cloud infrastructure.
 
-**This is the best and the suggested way to protect Netdata**. Your systems **should** have a private administration and management
-LAN, so that all management tasks are performed without any possibility of them being exposed on the internet.
+For `gvpe` specifically, we maintain a [deployment tool](https://github.com/netdata/netdata-demo-site/tree/master/gvpe) that includes:
 
-For Cloud-based installations, if your cloud provider doesn’t provide such a private LAN (or if you use multiple providers),
-you can create a virtual management and administration LAN with tools like `tincd` or `gvpe`. These tools create a mesh VPN
-allowing all servers to communicate securely and privately. Your administration stations join this mesh VPN to get access to
-management and administration tasks on all your cloud servers.
+- Pre-compiled binaries for Linux and FreeBSD.
+- macOS compilation script.
+- Configuration templates.
 
-For `gvpe` we have developed a [simple provisioning tool](https://github.com/netdata/netdata-demo-site/tree/master/gvpe) you
-may find handy (it includes statically compiled `gvpe` binaries for Linux and FreeBSD, and also a script to compile `gvpe`
-on your macOS system). We use this to create a management and administration LAN for all Netdata demo sites (spread all over
-the internet using multiple hosting providers).
+We use this tool to manage our Netdata demo sites across multiple hosting providers.
 
-## Fine-grained access control
+</details>
 
-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](/src/web/server/README.md#access-lists). This method also fully
-retains the ability to stream metrics
-on-demand through Netdata Cloud.
+## Configure granular access control
 
-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.
+Restrict access to your local dashboard while maintaining Netdata Cloud connectivity by using [access lists](/src/web/server/README.md#access-lists).
 
-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](/src/libnetdata/simple_pattern/README.md).
+Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script.
+
+Use the `allow connections from` setting to permit specific IP addresses or hostnames:
 
 ```text
 [web]
@@ -120,8 +93,9 @@ patterns](/src/libnetdata/simple_pattern/README.md).
     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 in more detail if you want:
+The default setting `localhost *` allows both localhost and all external connections. You can customize this using Netdata's [simple patterns](/src/libnetdata/simple_pattern/README.md).
+
+While `allow connections from` globally controls access to all Netdata services, you can set specific permissions for individual features:
 
 ```text
 [web]
@@ -133,42 +107,24 @@ The `allow connections from` setting is global and restricts access to the dashb
     allow management from = localhost
 ```
 
-See the [web server](/src/web/server/README.md#access-lists) docs for additional details about access lists. You can take access lists one step further by [enabling SSL](/src/web/server/README.md#enable-httpstls-support) to encrypt data from local
-dashboard in transit. The connection to Netdata Cloud is always secured with TLS.
-
-## Use an authenticating web server in proxy mode
-
-Use one web server to provide authentication in front of **all your Netdata servers**. So, you will be accessing all your Netdata with
-URLs like `http://{HOST}/netdata/{NETDATA_HOSTNAME}/` and authentication will be shared among all of them (you will sign in once for all your servers).
-Instructions are provided on how to set the proxy configuration to have Netdata run behind
-[nginx](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md),
-[HAproxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md),
-[Apache](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md),
-[lighthttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md),
-[caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md), and
-[H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md).
-
-## Use Netdata parents as Web Application Firewalls
-
-The Netdata Agents you install on your production systems don’t need direct access to the Internet. Even when you use
-Netdata Cloud, you can appoint one or more Netdata Parents to act as border gateways or application firewalls, isolating
-your production systems from the rest of the world. Netdata
-Parents receive metric data from Netdata Agents or other Netdata Parents on one side, and serve most queries using their own
-copy of the data to satisfy dashboard requests on the other side.
+For additional security:
 
-For more information, see [Streaming and replication](/docs/observability-centralization-points/README.md).
+- Review detailed access list options in the [Web Server documentation](/src/web/server/README.md#access-lists).
+- Consider [enabling SSL](/src/web/server/README.md#enable-httpstls-support) to encrypt local dashboard traffic (Netdata Cloud connections are always TLS-encrypted).
 
-## Other methods
+## Deploy a reverse proxy
 
-Of course, there are many more methods you could use to protect Netdata:
+Secure multiple Agents using a single authenticating web server as a reverse proxy. This provides:
 
-- Bind Netdata to localhost and use `ssh -L 19998:127.0.0.1:19999 remote.netdata.ip` to forward connections of local port 19998 to remote port 19999.
-  This way you can ssh to a Netdata server and then use `http://127.0.0.1:19998/` on your computer to access the remote Netdata dashboard.
+- Unified access through URLs like `http://{HOST}/netdata/{NETDATA_HOSTNAME}/`.
+- Single sign-on across all Agents.
+- Optional TLS encryption.
 
-- If you’re always under a static IP, you can use the script given above to allow direct access to your Netdata servers without authentication,
-  from all your static IPs.
+We provide detailed configuration guides for popular web servers:
 
-- Install all your Netdata in **headless data collector** mode, forwarding all metrics in real-time to a parent
-  Netdata server, which will be protected with authentication using a nginx server running locally at the parent
-  Netdata server. This requires more resources (you will need a bigger parent Netdata server), but doesn’t require
-  any firewall changes, since all the child Netdata servers will not be listening for incoming connections.
+- [nginx](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md)
+- [HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md)
+- [Apache](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md)
+- [Lighttpd](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md)
+- [Caddy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md)
+- [H2O](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md)

src/web/server/README.md

@@ -1,15 +1,14 @@
-# Web server
+# Web Server
 
-The Netdata web server is `static-threaded`, with a fixed, configurable number of threads.
+The Netdata Web Server is `static-threaded`, with a fixed, configurable number of threads.
 
-All the threads are concurrently listening for web requests on the same sockets, and the kernel distributes the incoming
-requests to them. Each thread uses non-blocking I/O so it can serve any number of web requests in parallel.
+All the threads are concurrently listening for web requests on the same sockets, and the kernel distributes the incoming requests to them. Each thread uses non-blocking I/O so it can serve any number of web requests in parallel.
 
-This web server respects the `keep-alive` HTTP header to serve multiple HTTP requests via the same connection.
+It respects the `keep-alive` HTTP header to serve multiple HTTP requests via the same connection.
 
 ## Configuration
 
-Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md)
+Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)
 
 Scroll down to the `[web]` section to find the following settings.
 
@@ -17,24 +16,24 @@ Scroll down to the `[web]` section to find the following settings.
 
 | Setting                            | Default                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                              |
 |:-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `ssl key`                          | `/etc/netdata/ssl/key.pem`                                                                                                                                                             | Declare the location of an SSL key to [enable HTTPS](#enable-httpstls-support).                                                                                                                                                                                                                                                                                                                          |
-| `ssl certificate`                  | `/etc/netdata/ssl/cert.pem`                                                                                                                                                            | Declare the location of an SSL certificate to [enable HTTPS](#enable-httpstls-support).                                                                                                                                                                                                                                                                                                                  |
+| `ssl key`                          | `/etc/netdata/ssl/key.pem`                                                                                                                                                             | Declare the location of an SSL key to enable HTTPS.                                                                                                                                                                                                                                                                                                                                                      |
+| `ssl certificate`                  | `/etc/netdata/ssl/cert.pem`                                                                                                                                                            | Declare the location of an SSL certificate to enable HTTPS.                                                                                                                                                                                                                                                                                                                                              |
 | `tls version`                      | `1.3`                                                                                                                                                                                  | Choose which TLS version to use. While all versions are allowed (`1` or `1.0`, `1.1`, `1.2` and `1.3`), we recommend `1.3` for the most secure encryption. If left blank, Netdata uses the highest available protocol version on your system.                                                                                                                                                            |
 | `tls ciphers`                      | `none`                                                                                                                                                                                 | Choose which TLS cipher to use. Options include `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, and `TLS_AES_128_GCM_SHA256`. If left blank, Netdata uses the default cipher list for that protocol provided by your TLS implementation.                                                                                                                                                       |
 | `ses max window`                   | `15`                                                                                                                                                                                   | See [single exponential smoothing](/src/web/api/queries/ses/README.md).                                                                                                                                                                                                                                                                                                                                  |
 | `des max window`                   | `15`                                                                                                                                                                                   | See [double exponential smoothing](/src/web/api/queries/des/README.md).                                                                                                                                                                                                                                                                                                                                  |
-| `mode`                             | `static-threaded`                                                                                                                                                                      | Turns on (`static-threaded` or off (`none`) the static-threaded web server. See the [example](#disable-the-web-server) to turn off the web server and disable the dashboard.                                                                                                                                                                                                                             |
+| `mode`                             | `static-threaded`                                                                                                                                                                      | Turns on (`static-threaded`) or off (`none`) the static-threaded Web Server. See the [example](#disable-the-web-server) to turn off the Web Server and disable the dashboard.                                                                                                                                                                                                                            |
 | `listen backlog`                   | `4096`                                                                                                                                                                                 | The port backlog. Check `man 2 listen`.                                                                                                                                                                                                                                                                                                                                                                  |
-| `default port`                     | `19999`                                                                                                                                                                                | The listen port for the static web server.                                                                                                                                                                                                                                                                                                                                                               |
+| `default port`                     | `19999`                                                                                                                                                                                | The listen port for the static Web Server.                                                                                                                                                                                                                                                                                                                                                               |
 | `web files owner`                  | `netdata`                                                                                                                                                                              | The user that owns the web static files. Netdata will refuse to serve a file that is not owned by this user, even if it has read access to that file. If the user given is not found, Netdata will only serve files owned by user given in `run as user`.                                                                                                                                                |
 | `web files group`                  | `netdata`                                                                                                                                                                              | If this is set, Netdata will check if the file is owned by this group and refuse to serve the file if it's not.                                                                                                                                                                                                                                                                                          |
 | `disconnect idle clients after`    | `1m`                                                                                                                                                                                   | The time in seconds to disconnect web clients after being totally idle.                                                                                                                                                                                                                                                                                                                                  |
 | `timeout for first request`        | `1m`                                                                                                                                                                                   | How long to wait for a client to send a request before closing the socket. Prevents slow request attacks.                                                                                                                                                                                                                                                                                                |
-| `accept a streaming request every` | `off`                                                                                                                                                                                  | Can be used to set a limit on how often a parent node will accept streaming requests from child nodes in a [streaming and replication setup](/src/streaming/README.md).                                                                                                                                                                                                                                  |
+| `accept a streaming request every` | `off`                                                                                                                                                                                  | Can be used to set a limit on how often a Parent will accept streaming requests from Children in a [streaming and replication setup](/src/streaming/README.md).                                                                                                                                                                                                                                          |
 | `respect do not track policy`      | `no`                                                                                                                                                                                   | If set to `yes`, Netdata will respect the user's browser preferences for [Do Not Track](https://www.eff.org/issues/do-not-track) (DNT) and storing cookies. If DNT is _enabled_ in the browser, and this option is set to `yes`, nodes will not connect to any [registry](/src/registry/README.md). For certain browsers, users must disable DNT and change this option to `yes` for full functionality. |
 | `x-frame-options response header`  | ``                                                                                                                                                                                     | Avoid [clickjacking attacks](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options), by ensuring that the content is not embedded into other sites.                                                                                                                                                                                                                                  |
-| `allow connections from`           | `localhost *`                                                                                                                                                                          | Declare which IP addresses or full-qualified domain names (FQDNs) are allowed to connect to the web server, including the [dashboard](/docs/dashboards-and-charts/README.md) or [HTTP API](/src/web/api/README.md). This is a global setting with higher priority to any of the ones below.                                                                                                              |
-| `allow connections by dns`         | `heuristic`                                                                                                                                                                            | See the [access list examples](#access-lists) for details on using `allow` settings.                                                                                                                                                                                                                                                                                                                     |
+| `allow connections from`           | `localhost *`                                                                                                                                                                          | Declare which IP addresses or full-qualified domain names (FQDNs) are allowed to connect to the Web Server, including the [dashboard](/docs/dashboards-and-charts/README.md) or [HTTP API](/src/web/api/README.md). This is a global setting with higher priority to any of the ones below.                                                                                                              |
+| `allow connections by dns`         | `heuristic`                                                                                                                                                                            | See the [access list section](#access-lists) for details on using `allow` settings.                                                                                                                                                                                                                                                                                                                      |
 | `allow dashboard from`             | `localhost *`                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `allow dashboard by dns`           | `heuristic`                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `allow badges from`                | `*`                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -52,19 +51,84 @@ Scroll down to the `[web]` section to find the following settings.
 | `web server max sockets`           | ``                                                                                                                                                                                     | Available sockets. The default is system-specific, automatically adjusted to 50% of the max number of open files Netdata is allowed to use (via `/etc/security/limits.conf` or systemd), to allow enough file descriptors to be available for data collection.                                                                                                                                           |
 | `custom dashboard_info.js`         | ``                                                                                                                                                                                     | Specifies the location of a custom `dashboard.js` file. See [customizing the standard dashboard](/docs/developer-and-contributor-corner/customize.md#customize-the-standard-dashboard) for details.                                                                                                                                                                                                      |
 
+## Access lists
+
+Netdata supports access lists in `netdata.conf`:
+
+```text
+[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
+```
+
+`*` does string matches on the IPs or FQDNs of the clients.
+
+- `allow connections from` matches anyone that connects on the Netdata port(s).
+  So, if someone is not allowed, it will be connected and disconnected immediately, without reading even
+  a single byte from its connection. This is a global setting with higher priority to any of the ones below.
+
+- `allow dashboard from` receives the request and examines if it is a static dashboard file or an API call the
+  dashboards do.
+
+- `allow badges from` checks if the API request is for a badge. Badges aren’t matched by `allow dashboard from`.
+
+- `allow streaming from` checks if the child willing to stream metrics to this Netdata is allowed.
+  This can be controlled per API KEY and MACHINE GUID in `stream.conf`.
+  The setting in `netdata.conf` is checked before the ones in `stream.conf`.
+
+- `allow netdata.conf from` checks the IP to allow `http://netdata.host:19999/netdata.conf`.
+  The IPs listed are all the private IPv4 addresses, including link-local IPv6 addresses. Keep in mind that connections to Netdata API ports are filtered by `allow connections from`. So, IPs allowed by `allow netdata.conf from` should also be allowed by `allow connections from`.
+
+- `allow management from` checks the IPs to allow API management calls. Management via the API is currently supported for [health](/src/web/api/health/README.md#health-management-api)
+
+To check the FQDN of the connection without opening the Netdata Agent to DNS-spoofing, a reverse-dns record must be setup for the connecting host. At connection time, the reverse-dns of the peer IP address is resolved, and a forward DNS resolution is made to validate the IP address against the name-pattern.
+
+Please note that this process can be expensive on a machine that is serving many connections. Each access list has an associated configuration option to turn off DNS-based patterns completely to avoid incurring this cost at run-time:
+
+```text
+    allow connections by dns = heuristic
+    allow dashboard by dns = heuristic
+    allow badges by dns = heuristic
+    allow streaming by dns = heuristic
+    allow netdata.conf by dns = no
+    allow management by dns = heuristic
+```
+
+The three possible values for each of these options are `yes`, `no` and `heuristic`. The `heuristic` option disables the check when the pattern only contains IPv4/IPv6 addresses or `localhost`, and enables it when wildcards are present that may match DNS FQDNs.
+
+## DDoS protection
+
+If you publish your Netdata web server to the internet, you may want to apply some protection against DDoS:
+
+1. Use the `static-threaded` web server (it is the default)
+2. Use reasonable `[web].web server max sockets` (e.g default)
+3. Don't use all your CPU cores for Netdata (lower `[web].web server threads`)
+4. Run the `netdata` process with a low process scheduling priority (the default is the lowest)
+5. If possible, proxy Netdata via a full-featured web server (Nginx, Apache, etc.)
+
 ## Examples
 
-### Disable the web server
+### Disable the Web Server
 
-Disable the web server by editing `netdata.conf` and setting:
+<details><summary>details</summary>
+
+Edit `netdata.conf` using the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)
 
 ```text
 [web]
     mode = none
 ```
 
+</details>
+
 ### Change the number of threads
 
+<details><summary>details</summary>
+
 Control the number of threads and sockets with the following settings:
 
 ```text
@@ -73,8 +137,12 @@ Control the number of threads and sockets with the following settings:
     web server max sockets = 512
 ```
 
+</details>
+
 ### Binding Netdata to multiple ports
 
+<details><summary>details</summary>
+
 Netdata can bind to multiple IPs and ports, offering access to different services on each. Up to 100 sockets can be used (increase it at compile time with `CFLAGS="-DMAX_LISTEN_FDS=200" ./netdata-installer.sh ...`).
 
 The ports to bind are controlled via `[web].bind to`, like this:
@@ -90,25 +158,30 @@ Using the above, Netdata will bind to:
 - IPv4 127.0.0.1 at port 19999 (port was used from `default port`). Only the UI (dashboard) and the read API will be accessible on this port. Both HTTP and HTTPS requests will be accepted.
 - IPv4 10.1.1.1 at port 19998. The management API and `netdata.conf` will be accessible on this port.
 - All the IPs `hostname` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19997. Only badges will be accessible on this port.
-- All IPv6 IPs at port 19996. Only metric streaming requests from other Netdata Agents will be accepted on this port. Only encrypted streams will be allowed (i.e. child nodes also need to be [configured for TLS](/src/streaming/README.md).
-- All the IPs `localhost` resolves to (both IPv4 and IPv6 depending the resolved IPs) at port 19996. This port will only accept registry API requests.
+- All IPv6 IPs at port 19996. Only metric streaming requests from other Netdata Agents will be accepted on this port. Only encrypted streams will be allowed (i.e., Children also need to be [configured for TLS](/src/streaming/README.md)).
+- All the IPs `localhost` resolves to (both IPv4 and IPv6 depending on the resolved IPs) at port 19996. This port will only accept registry API requests.
 - All IPv4 and IPv6 IPs at port `http` as set in `/etc/services`. Only the UI (dashboard) and the read API will be accessible on this port.
 - Unix domain socket `/run/netdata/netdata.sock`. All requests are serviceable on this socket. Note that in some OSs like Fedora, every service sees a different `/tmp`, so don't create a Unix socket under `/tmp`. `/run` or `/var/run` is suggested.
 
-The option `[web].default port` is used when an entries in `[web].bind to` do not specify a port.
+The option `[web].default port` is used when entries in `[web].bind to` do not specify a port.
+
+As shown in the example above, these permissions are optional, with the default permitting all request types on the specified port.
 
-Note that the access permissions specified with the `=request type|request type|...` format are available from version 1.12 onwards.
-As shown in the example above, these permissions are optional, with the default being to permit all request types on the specified port.
 The request types are strings identical to the `allow X from` directives of the access lists, i.e. `dashboard`, `streaming`, `registry`, `netdata.conf`, `badges` and `management`.
 The access lists themselves and the general setting `allow connections from` in the next section are applied regardless of the ports that are configured to provide these services.
+
 The API requests are serviced as follows:
 
 - `dashboard` gives access to the UI, the read API and badges API calls.
-- `badges` gives access only to the badges API calls.
+- `badges` gives access only to the badge API calls.
 - `management` gives access only to the management API calls.
 
+</details>
+
 ### Enable HTTPS/TLS support
 
+<details><summary>details</summary>
+
 Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data to a
 parent from its child nodes, via the TLS protocol.
 
@@ -127,7 +200,7 @@ To enable TLS, provide the path to your certificate and private key in the `[web
     ssl certificate = /etc/netdata/ssl/cert.pem
 ```
 
-Both files must be readable by the `netdata` user. If either of these files do not exist or are unreadable, Netdata will fall back to HTTP. For a parent-child connection, only the parent needs these settings.
+Both files must be readable by the `netdata` user. If any of these files are missing or can’t be read, Netdata will fall back to using HTTP. For a parent-child connection, only the parent needs these settings.
 
 For test purposes, generate self-signed certificates with the following command:
 
@@ -136,15 +209,19 @@ openssl req -newkey rsa:2048 -nodes -sha512 -x509 -days 365 -keyout key.pem -out
 ```
 
 > If you use 4096 bits for your key and the certificate, Netdata will need more CPU to process the communication.
-> `rsa4096` can be up to 4 times slower than `rsa2048`, so we recommend using 2048 bits. Verify the difference
+> `rsa4096` can be up to four times slower than `rsa2048`, so we recommend using 2048 bits. Verify the difference
 > by running:
 >
 > ```sh
 > openssl speed rsa2048 rsa4096
 > ```
 
+</details>
+
 ### Select TLS version
 
+<details><summary>details</summary>
+
 Beginning with version `v1.21.0`, specify the TLS version and the ciphers that you want to use:
 
 ```text
@@ -153,7 +230,7 @@ Beginning with version `v1.21.0`, specify the TLS version and the ciphers that y
     tls ciphers = TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
 ```
 
-If you do not specify these options, Netdata will use the highest available protocol version on your system and the default cipher list for that protocol provided by your TLS implementation.
+If you don’t specify these options, Netdata will use the highest available protocol version on your system and the default cipher list for that protocol provided by your TLS implementation.
 
 #### TLS/SSL enforcement
 
@@ -162,7 +239,7 @@ When the certificates are defined and unless any other options are provided, a N
 - Redirect all incoming HTTP web server requests to HTTPS. Applies to the dashboard, the API, `netdata.conf` and badges.
 - Allow incoming child connections to use both unencrypted and encrypted communications for streaming.
 
-To change this behavior, you need to modify the `bind to` setting in the `[web]` section of `netdata.conf`. At the end of each port definition, append `^SSL=force` or `^SSL=optional`. What happens with these settings differs, depending on whether the port is used for HTTP/S requests, or for streaming.
+To change this behavior, you need to modify the `bind to` setting in the `[web]` section of `netdata.conf`. At the end of each port definition, append `^SSL=force` or `^SSL=optional`. What happens with these settings differs, depending on whether the port is used for HTTP/S requests or for streaming.
 
 | SSL setting |    HTTP requests    | HTTPS requests | Unencrypted Streams | Encrypted Streams |
 |:-----------:|:-------------------:|:--------------:|:-------------------:|:------------------|
@@ -179,7 +256,7 @@ Example:
 
 For information how to configure the child to use TLS, check [securing the communication](/src/streaming/README.md#securing-streaming-with-tlsssl) in the streaming documentation. There you will find additional details on the expected behavior for client and server nodes, when their respective TLS options are enabled.
 
-When we define the use of SSL in a Netdata Agent for different ports,  Netdata will apply the behavior specified on each port. For example, using the configuration line below:
+When we define the use of SSL in a Netdata Agent for different ports, Netdata will apply the behavior specified on each port. For example, using the configuration line below:
 
 ```text
 [web]
@@ -199,68 +276,4 @@ When you start using Netdata with TLS, you may find errors in the Netdata log, w
 
 Most of the time, these errors are due to incompatibilities between your browser's options related to TLS/SSL protocols and Netdata's internal configuration. The most common error is `error:00000006:lib(0):func(0):EVP lib`.
 
-In the near future, Netdata will allow our users to change the internal configuration to avoid similar errors. Until then, we're recommending only the most common and safe encryption protocols listed above.
-
-### Access lists
-
-Netdata supports access lists in `netdata.conf`:
-
-```text
-[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
-```
-
-`*` does string matches on the IPs or FQDNs of the clients.
-
-- `allow connections from` matches anyone that connects on the Netdata port(s).
-     So, if someone is not allowed, it will be connected and disconnected immediately, without reading even
-     a single byte from its connection. This is a global setting with higher priority to any of the ones below.
-
-- `allow dashboard from` receives the request and examines if it is a static dashboard file or an API call the
-     dashboards do.
-
-- `allow badges from` checks if the API request is for a badge. Badges are not matched by `allow dashboard from`.
-
-- `allow streaming from` checks if the child willing to stream metrics to this Netdata is allowed.
-     This can be controlled per API KEY and MACHINE GUID in `stream.conf`.
-     The setting in `netdata.conf` is checked before the ones in `stream.conf`.
-
-- `allow netdata.conf from` checks the IP to allow `http://netdata.host:19999/netdata.conf`.
-     The IPs listed are all the private IPv4 addresses, including link local IPv6 addresses. Keep in mind that connections to Netdata API ports are filtered by `allow connections from`. So, IPs allowed by `allow netdata.conf from` should also be allowed by `allow connections from`.
-
-- `allow management from` checks the IPs to allow API management calls. Management via the API is currently supported for [health](/src/web/api/health/README.md#health-management-api)
-
-In order to check the FQDN of the connection without opening the Netdata Agent to DNS-spoofing, a reverse-dns record
-must be setup for the connecting host. At connection time the reverse-dns of the peer IP address is resolved, and
-a forward DNS resolution is made to validate the IP address against the name-pattern.
-
-Please note that this process can be expensive on a machine that is serving many connections. Each access list has an
-associated configuration option to turn off DNS-based patterns completely to avoid incurring this cost at run-time:
-
-```text
-    allow connections by dns = heuristic
-    allow dashboard by dns = heuristic
-    allow badges by dns = heuristic
-    allow streaming by dns = heuristic
-    allow netdata.conf by dns = no
-    allow management by dns = heuristic
-```
-
-The three possible values for each of these options are `yes`, `no` and `heuristic`. The `heuristic` option disables
-the check when the pattern only contains IPv4/IPv6 addresses or `localhost`, and enables it when wildcards are
-present that may match DNS FQDNs.
-
-## DDoS protection
-
-If you publish your Netdata web server to the internet, you may want to apply some protection against DDoS:
-
-1. Use the `static-threaded` web server (it is the default)
-2. Use reasonable `[web].web server max sockets` (the default is)
-3. Don't use all your CPU cores for Netdata (lower `[web].web server threads`)
-4. Run the `netdata` process with a low process scheduling priority (the default is the lowest)
-5. If possible, proxy Netdata via a full featured web server (Nginx, Apache, etc)
+</details>