Merging upstream version 1.12.0.

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

1 files changed, 100 insertions, 129 deletions

diff --git a/daemon/config/README.md b/daemon/config/README.md
index 5cd7844a2..64f8564cc 100755..100644
--- a/daemon/config/README.md
+++ b/daemon/config/README.md
@@ -1,175 +1,146 @@
-# Configuration Guide
+# Daemon configuration
 
-Configuration files are placed in `/etc/netdata`.
 
-## Netdata Daemon
+<details markdown="1"><summary>The daemon configuration file is read from `/etc/netdata/netdata.conf`.</summary>
+Depending on your installation method, Netdata will have been installed either directly under `/`, or under `/opt/netdata`. The paths mentioned here and in the documentation in general assume that your installation is under `/`. If it is not, you will find the exact same paths under `/opt/netdata` as well. (i.e. `/etc/netdata` will be `/opt/netdata/etc/netdata`).</details>
 
-The daemon configuration file is read from `/etc/netdata/netdata.conf`.
+This config file **is not needed by default**. Netdata works fine out of the box without it. But it does allow you to adapt the general behavior of Netdata, in great detail. You can find all these settings, with their default values, by accessing the URL `https://netdata.server.hostname:19999/netdata.conf`. For example check the configuration file of [netdata.firehol.org](http://netdata.firehol.org/netdata.conf). HTTP access to this file is limited by default to private IPs, via the [web server access lists](../../web/server/#access-lists).
 
-In this file you can configure all aspects of netdata. Netdata provides configuration settings for plugins and charts found when started. You can find all these settings, with their default values, by accessing the URL `https://netdata.server.hostname:19999/netdata.conf`. For example check the configuration file of [netdata.firehol.org](http://netdata.firehol.org/netdata.conf).
+`netdata.conf` has sections stated with `[section]`. You will see the following sections:
 
-The configuration file has sections stated with `[section]`. There will be the following sections:
-
-1. `[global]` for global netdata daemon options
-2. `[plugins]` for controlling which plugins the netdata will use
-3. `[plugin:NAME]` one such section for each plugin enabled
-4. `[CHART_NAME]` once such section for each chart defined
+1. `[global]` to [configure](#global-section-options) the [netdata daemon](../).
+2. `[web]` to [configure the web server](../../web/server).
+3. `[plugins]` to [configure](#plugins-section-options) which [collectors](../../collectors) to use and PATH settings.
+4. `[health]` to [configure](#health-section-options) general settings for [health monitoring](../../health)
+5. `[registry]` for the [netdata registry](../../registry). 
+6. `[backend]` to set up [streaming and replication](../../streaming) options.
+7. `[statsd]` for the general settings of the [stats.d.plugin](../../collectors/statsd.plugin). 
+8. `[plugin:NAME]` sections for each collector plugin, under the comment [Per plugin configuration](#per-plugin-configuration).
+9. `[CHART_NAME]` sections for each chart defined, under the comment [Per chart configuration](#per-chart-configuration).
 
 The configuration file is a `name = value` dictionary. Netdata will not complain if you set options unknown to it. When you check the running configuration by accessing the URL `/netdata.conf` on your netdata server, netdata will add a comment on settings it does not currently use.
 
-### [global] section options
-
-
-setting | default | info
-:------:|:-------:|:----
-hostname|auto-detected|The hostname of the computer running netdata.
-history|3600|The number of entries the netdata daemon will by default keep in memory for each chart dimension. This setting can also be configured per chart. Check [Memory Requirements](../../database/#netdata-database) for more information.
-config directory|`/etc/netdata`|The directory configuration files are kept.
-plugins directory|`/usr/libexec/netdata/plugins.d`|The directory plugin programs are kept. This setting supports multiple directories, space separated. If any directory path contains spaces, enclose it in single or double quotes.
-web files directory|`/usr/share/netdata/web`|The directory the web static files are kept.
-cache directory|`/var/cache/netdata`|The directory the memory database will be stored if and when netdata exits. Netdata will re-read the database when it will start again, to continue from the same point.
-log directory|`/var/log/netdata`|The directory in which the [log files](../#log-files) are kept.
-host access prefix|*empty*|This is used in docker environments where /proc, /sys, etc have to be accessed via another path. You may also have to set SYS_PTRACE capability on the docker for this work. Check [issue 43](https://github.com/netdata/netdata/issues/43).
-debug flags|0x00000000|Bitmap of debug options to enable. For more information check [Tracing Options](../#debugging).
-memory deduplication (ksm)|yes|When set to `yes`, netdata will offer its in-memory round robin database to kernel same page merging (KSM) for deduplication. For more information check [[Memory Deduplication - Kernel Same Page Merging - KSM]]
-debug log|`/var/log/netdata/debug.log`|The filename to save debug information. This file will not be created is debugging is not enabled. You can also set it to `syslog` to send the debug messages to syslog, or `none` to disable this log. For more information check [Tracing Options](../#debugging).
-error log|`/var/log/netdata/error.log`|The filename to save error messages for netdata daemon and all plugins (`stderr` is sent here for all netdata programs, including the plugins). You can also set it to `syslog` to send the errors to syslog, or `none` to disable this log.
-access log|`/var/log/netdata/access.log`|The filename to save the log of web clients accessing netdata charts. You can also set it to `syslog` to send the access log to syslog, or `none` to disable this log.
-memory mode|save|When set to `save` netdata will save its round robin database on exit and load it on startup. When set to `map` the cache files will be updated in real time (check `man mmap` - do not set this on systems with heavy load or slow disks - the disks will continuously sync the in-memory database of netdata). When set to `ram` the round robin database will be temporary and it will be lost when netdata exits.
-update every|1|The frequency in seconds, for data collection. For more information see [Performance](../../doc/Performance.md#netdata-performance).
-run as user|`netdata`|The user netdata will run as.
-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`.
-http port listen backlog|100|The port backlog. Check `man 2 listen`.
-default port|19999|The default port to listen for web clients.
-bind to|`*`|The IP address and port to listen to. This is a space separated list of IPv4 or IPv6 address and ports. The default will bind to all IP addresses. Example: `bind to = 127.0.0.1:19999 10.11.12.1:19998 [::1]:19999`.
-disconnect idle web clients after seconds|60|The time in seconds to disconnect web clients after being totally idle.
-enable web responses gzip compression|yes|When set to `yes`, netdata web responses will be GZIP compressed, if the web client accepts such responses.
-
-##### netdata process priority
-
-By default, netdata runs with the `idle` process scheduler, which assigns CPU resources to netdata, only when the system has such resources to spare.
-
-The following `netdata.conf` settings control this:
-
-```
-[global]
-    process scheduling policy = idle
-    process scheduling priority = 0
-    process nice level = 19
-```
-
-The policies supported by netdata are `idle` (the netdata default), `other` (also as `nice`), `batch`, `rr`, `fifo`. netdata also recognizes `keep` and `none` to keep the current settings without changing them.
-
-For `other`, `nice` and `batch`, the setting `process nice level = 19` is activated to configure the nice level of netdata. Nice gets values -20 (highest) to 19 (lowest).
-
-For `rr` and `fifo`, the setting `process scheduling priority = 0` is activated to configure the priority of the relative scheduling policy. Priority gets values 1 (lowest) to 99 (highest).
-
-For the details of each scheduler, see `man sched_setscheduler` and `man sched`.
+## Applying changes
 
-When netdata is running under systemd, it can only lower its priority (the default is `other` with `nice level = 0`). If you want to make netdata to get more CPU than that, you will need to set in `netdata.conf`:
+After `netdata.conf` has been modified, netdata needs to be restarted for changes to apply:
 
-```
-[global]
-    process scheduling policy = keep
+```bash
+sudo service netdata restart
 ```
 
-and edit `/etc/systemd/system/netdata.service` and add:
+If the above does not work, try the following:
 
-```
-CPUSchedulingPolicy=other | batch | idle | fifo | rr
-CPUSchedulingPriority=99
-Nice=-10
+```bash
+sudo killall netdata; sleep 10; sudo netdata
 ```
 
+Please note that your data history will be lost if you have modified `history` parameter in section `[global]`.
 
-### [plugins] section options
+## Sections
 
-In this section there will be a boolean (`yes`/`no`) option for each plugin. Additionally, there will be the following options:
+### [global] section options
 
 setting | default | info
 :------:|:-------:|:----
-checks|no|This is a debugging plugin for the internal latency of netdata.
-enable running new plugins|yes|When set to `yes`, netdata will enable plugins not configured specifically for them. Setting this to `no` will disable all plugins you have not set to `yes` explicitly.
-check for new plugins every|60|The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for netdata.
-
-## Netdata Plugins
-
-The configuration options for plugins appear in sections following the pattern `[plugin:NAME]`.
-
-### Internal Plugins
-
-Most internal plugins will provide additional options. Check [Internal Plugins](../../collectors/) for more information.
+process scheduling policy | `keep` |  See [netdata process scheduling policy](../#netdata-process-scheduling-policy)
+OOM score | `1000` |  See [OOM score](../#oom-score)
+glibc malloc arena max for plugins | `1` |  See [Virtual memory](../#virtual-memory).
+glibc malloc arena max for netdata | `1` |  See [Virtual memory](../#virtual-memory).
+hostname | auto-detected | The hostname of the computer running netdata. 
+history | `3996` | The number of entries the netdata daemon will by default keep in memory for each chart dimension. This setting can also be configured per chart. Check [Memory Requirements](../../database/#database) for more information. 
+update every | `1` | The frequency in seconds, for data collection. For more information see [Performance](../../docs/Performance.md#performance). 
+config directory | `/etc/netdata` | The directory configuration files are kept. 
+stock config directory | `/usr/lib/netdata/conf.d` |  
+log directory | `/var/log/netdata` | The directory in which the [log files](../#log-files) are kept. 
+web files directory | `/usr/share/netdata/web` | The directory the web static files are kept. 
+cache directory | `/var/cache/netdata` | The directory the memory database will be stored if and when netdata exits. Netdata will re-read the database when it will start again, to continue from the same point. 
+lib directory | `/var/lib/netdata` | Contains the alarm log and the netdata instance guid.
+home directory | `/var/cache/netdata` | Contains the db files for the collected metrics
+plugins directory | `"/usr/libexec/netdata/plugins.d" "/etc/netdata/custom-plugins.d"` | The directory plugin programs are kept. This setting supports multiple directories, space separated. If any directory path contains spaces, enclose it in single or double quotes. 
+memory mode | `save` | When set to `save` netdata will save its round robin database on exit and load it on startup. When set to `map` the cache files will be updated in real time (check `man mmap` - do not set this on systems with heavy load or slow disks - the disks will continuously sync the in-memory database of netdata). When set to `ram` the round robin database will be temporary and it will be lost when netdata exits. `none` disables the database at this host. This also disables health monitoring (there cannot be health monitoring without a database). host access prefix | | This is used in docker environments where /proc, /sys, etc have to be accessed via another path. You may also have to set SYS_PTRACE capability on the docker for this work. Check [issue 43](https://github.com/netdata/netdata/issues/43). 
+memory deduplication (ksm) | `yes` | When set to `yes`, netdata will offer its in-memory round robin database to kernel same page merging (KSM) for deduplication. For more information check [Memory Deduplication - Kernel Same Page Merging - KSM](../../database/#ksm) 
+TZ environment variable | `:/etc/localtime` | Where to find the timezone 
+timezone | auto-detected | The timezone retrieved from the environment variable 
+debug flags | `0x0000000000000000` | Bitmap of debug options to enable. For more information check [Tracing Options](../#debugging). 
+debug log | `/var/log/netdata/debug.log` | The filename to save debug information. This file will not be created is debugging is not enabled. You can also set it to `syslog` to send the debug messages to syslog, or `none` to disable this log. For more information check [Tracing Options](../#debugging). 
+error log | `/var/log/netdata/error.log` | The filename to save error messages for netdata daemon and all plugins (`stderr` is sent here for all netdata programs, including the plugins). You can also set it to `syslog` to send the errors to syslog, or `none` to disable this log. 
+access log | `/var/log/netdata/access.log` | The filename to save the log of web clients accessing netdata charts. You can also set it to `syslog` to send the access log to syslog, or `none` to disable this log. 
+errors flood protection period | `1200` | UNUSED - Length of period (in sec) during which the number of errors should not exceed the `errors to trigger flood protection`.
+errors to trigger flood protection | `200` |  UNUSED - Number of errors written to the log in `errors flood protection period` sec before flood protection is activated.
+run as user | `netdata` | The user netdata will run as. 
+pthread stack size | auto-detected |  
+cleanup obsolete charts after seconds | `3600` |  See [monitoring ephemeral containers](../../collectors/cgroups.plugin/#monitoring-ephemeral-containers)
+gap when lost iterations above | `1` |  
+cleanup orphan hosts after seconds | `3600` |  How long to wait until automatically removing from the DB a remote netdata host (slave) that is no longer sending data.
+delete obsolete charts files | `yes` |  See [monitoring ephemeral containers](../../collectors/cgroups.plugin/#monitoring-ephemeral-containers)
+delete orphan hosts files | `yes` |  Set to `no` to disable non-responsive host removal.
+
+### [web] section options
+
+Refer to the [web server documentation](../../web/server)
 
+### [plugins] section options
 
-### External Plugins
+In this section you will see be a boolean (`yes`/`no`) option for each plugin (e.g. tc, cgroups, apps, proc etc.). Note that the configuration options in this section for the orchestrator plugins `python.d`, `charts.d` and `node.d` control **all the modules** written for that orchestrator. For instance, setting `python.d = no` means that all Python modules under `collectors/python.d.plugin` will be disabled.  
 
-External plugins will have only 2 options at `netdata.conf`:
+Additionally, there will be the following options:
 
 setting | default | info
 :------:|:-------:|:----
-update every|the value of `[global].update every` setting|The frequency in seconds the plugin should collect values. For more information check [Performance](../../doc/Performance.md#netdata-performance).
-command options|*empty*|Additional command line options to pass to the plugin. 
-
-External plugins that need additional configuration may support a dedicated file in `/etc/netdata`. Check their documentation.
-
----
-
-## A note about netdata.conf
-
-This config file is not needed by default. You can just touch it (to be empty) to get rid of the error message displayed when missing.
-
-The whole idea came up when I was evaluating the documentation involved in maintaining a complex configuration system. My intention was to give configuration options for everything imaginable. But then, documenting all these options would require a tremendous amount of time, users would have to search through endless pages for the option they need, etc.
+PATH environment variable | `auto-detected` | 
+PYTHONPATH environment variable | | Used to set a custom python path
+enable running new plugins | `yes` | When set to `yes`, netdata will enable detected plugins, even if they are not configured explicitly. Setting this to `no` will only enable plugins explicitly configirued in this file with a `yes` 
+check for new plugins every | 60 | The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for netdata.
+checks | `no` | This is a debugging plugin for the internal latency 
 
-I concluded then that configuring software like that is a waste for time and effort. Of course there must be plenty of configuration options, but the implementation itself should require a lot less effort for both the devs and the users.
+### [health] section options
 
-So, I did this:
+This section controls the general behavior of the health monitoring capabilities of Netdata. 
 
-1. No configuration is required to run netdata
-2. There are plenty of options to tweak
-3. There is minimal documentation (or no at all)
+Specific alarms are configured in per-collector config files under the `health.d` directory. For more info, see [health monitoring](../../health/#health-monitoring). 
 
-### Why this works?
+[Alarm notifications](../../health/notifications/#netdata-alarm-notifications) are configured in `health_alarm_notify.conf`. 
 
-The configuration file is a `name = value` dictionary with `[sections]`. Write whatever you like there as long as it follows this simple format.
-
-Netdata loads this dictionary and then when the code needs a value from it, it just looks up the `name` in the dictionary at the proper `section`. In all places, in the code, there are both the `names` and their `default values`, so if something is not found in the configuration file, the default is used. The lookup is made using B-Trees and hashes (no string comparisons), so they are super fast. Also the `names` of the settings can be `my super duper setting that once set to yes, will turn the world upside down = no` - so goodbye to most of the documentation involved.
-
-Next, netdata can generate a valid configuration for the user to edit. No need to remember anything. Just get the configuration from the server (`/netdata.conf` on your netdata server), edit it and save it.
-
-Last, what about options you believe you have set, but you misspelled? When you get the configuration file from the server, there will be a comment above all `name = value` pairs the server does not use. So you know that whatever you wrote there, is not used.
+setting | default | info
+:------:|:-------:|:----
+enabled | `yes` | Set to `no` to disable all alarms and notifications
+in memory max health log entries | 1000 | Size of the alarm history held in RAM
+script to execute on alarm | `/usr/libexec/netdata/plugins.d/alarm-notify.sh` | The script that sends alarm notifications. 
+stock health configuration directory | `/usr/lib/netdata/conf.d/health.d` | Contains the stock alarm configuration files for each collector
+health configuration directory | `/etc/netdata/health.d` | The directory containing the user alarm configuration files, to override the stock configurations
+run at least every seconds | `10` | Controls how often all alarm conditions should be evaluated. 
+postpone alarms during hibernation for seconds | `60` | Prevents false alarms. May need to be increased if you get alarms during hibernation.
+rotate log every lines | 2000 | Controls the number of alarm log entries stored in `<lib directory>/health-log.db`, where <lib directory> is the one configured in the [[global] section](#global-section-options)
 
-### limiting access to netdata.conf
+### [registry] section options
 
-netdata v1.9+ limit by default access to `http://your.netdata.ip:19999/netdata.conf` to private IP addresses. This is controlled by this settings:
+To understand what this section is and how it should be configured, please refer to the [registry documentation](../../registry). 
 
-```
-[web]
-	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.*
-```
+### [backend]
 
-The IPs listed are all the private IPv4 addresses, including link local IPv6 addresses.
+Refer to the [streaming and replication](../../streaming) documentation.
 
-> Keep in mind that connections to netdata API ports are filtered by `[web].allow connections from`. So, IPs allowed by `[web].allow netdata.conf from` should also be allowed by `[web].allow connections from`.
+### Per plugin configuration
 
+The configuration options for plugins appear in sections following the pattern `[plugin:NAME]`.
 
-## netdata simple patterns
+#### Internal plugins
 
-Unix prefers regular expressions. But they are just too hard, too cryptic to use, write and understand.
+Most internal plugins will provide additional options. Check [Internal Plugins](../../collectors/) for more information.
 
-So, netdata supports [simple patterns](../../libnetdata/simple_pattern/). 
+#### External plugins
 
-## Applying changes
+External plugins will have only 2 options at `netdata.conf`:
 
-After `netdata.conf` has been modified, netdata needs to be restarted for changes to apply:
+setting | default | info
+:------:|:-------:|:----
+update every|the value of `[global].update every` setting|The frequency in seconds the plugin should collect values. For more information check [Performance](../../docs/Performance.md#performance).
+command options|*empty*|Additional command line options to pass to the plugin. 
 
-```bash
-sudo service netdata restart
-```
+External plugins that need additional configuration may support a dedicated file in `/etc/netdata`. Check their documentation.
 
-If the above does not work, try the following:
+### Per chart configuration
 
-```bash
-sudo killall netdata; sleep 10; sudo netdata
-```
+In this section you will a separate subsection for each chart shown on the dashboard. You can control all aspects of a specific chart here. You can understand what each option does by reading [how charts are defined](../../collectors/plugins.d/#chart). If you don't know how to find the name of a chart, you can learn about it [here](../../docs/Charts.md).
 
-Please note that your data history will be lost if you have modified `history` parameter in section `[global]`.
+[![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%2Fdaemon%2Fconfig%2FREADME&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]()