@cryptotaxi247 / netdata-1 / commits / 2c64795b7

Change streaming terminology to parent/child in docs (#9312)

* Intial pass through docs * Dash instead of slash * To parent/child * Child nodes * Change diagrams * Allowlist * Fixes for Andrew * Remove from build_external * Change in proc

Joel Hans committed Jun 12, 2020 at 09:42 UTC 2c64795b7cc4e21a9382f863ae354b137b367b45

18 files changed +210 -195

backends/README.md

+2 -2

@@ -179,8 +179,8 @@ from your Netdata):

179 of times within each pattern). The patterns are checked against the hostname (the localhost is always checked as

180 `localhost`), allowing us to filter which hosts will be sent to the backend when this Netdata is a central Netdata

181 aggregating multiple hosts. A pattern starting with `!` gives a negative match. So to match all hosts named `*db*`

182 - except hosts containing `*slave*`, use `!*slave* *db*` (so, the order is important: the first pattern matching the

183 - hostname will be used - positive or negative).

182 + except hosts containing `*child*`, use `!*child* *db*` (so, the order is important: the first pattern

183 + matching the hostname will be used - positive or negative).

184

185 - `send charts matching = *` includes one or more space separated patterns, using `*` as wildcard (any number of times

186 within each pattern). The patterns are checked against both chart id and chart name. A pattern starting with `!`

backends/prometheus/README.md

+1 -1

@@ -356,7 +356,7 @@ For more information check prometheus documentation.

356

357 ### Streaming data from upstream hosts

358

359 -The `format=prometheus` parameter only exports the host's Netdata metrics. If you are using the master/slave

359 +The `format=prometheus` parameter only exports the host's Netdata metrics. If you are using the parent-child

360 functionality of Netdata this ignores any upstream hosts - so you should consider using the below in your

361 **prometheus.yml**:

362

build_external/README.md

+10 -9

@@ -10,10 +10,11 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/build_external/R

11 This wraps the build-system in Docker so that the host system and the target system are

12 decoupled. This allows:

13 -* Cross-compilation (e.g. linux development from macOS)

14 -* Cross-distro (e.g. using CentOS user-land while developing on Debian)

15 -* Multi-host scenarios (e.g. master/slave configurations)

16 -* Bleeding-edge sceneraios (e.g. using the ACLK (**currently for internal-use only**))

13 +

14 +- Cross-compilation (e.g. linux development from macOS)

15 +- Cross-distro (e.g. using CentOS user-land while developing on Debian)

16 +- Multi-host scenarios (e.g. parent-child configurations)

17 +- Bleeding-edge sceneraios (e.g. using the ACLK (**currently for internal-use only**))

19 The advantage of these scenarios is that they allow **reproducible** builds and testing

20 for developers. This is the first iteration of the build-system to allow the team to use

@@ -97,19 +98,19 @@ Note: it is possible to run multiple copies of the agent using the `--scale` opt

98 Distro=debian Version=10 docker-compose -f projects/only-agent/docker-compose.yml up --scale agent=3

99 ```

100

100 -3. A simple master-slave scenario

101 +3. A simple parent-child scenario

102

103 ```bash

103 -# Need to call clean-install on the configs used in the master/slave containers

104 -docker-compose -f master-slaves/docker-compose.yml up --scale agent_slave1=2

104 +# Need to call clean-install on the configs used in the parent-child containers

105 +docker-compose -f parent-child/docker-compose.yml up --scale agent_child1=2

106 ```

107

108 Note: this is not production ready yet, but it is left in so that we can see how it behaves

109 and improve it. Currently it produces the following problems:

110 * Only the base-configuration in the compose without scaling works.

111 * The containers are hard-coded in the compose.

111 - * There is no way to separate the agent configurations, so running multiple agent slaves

112 - wth the same GUID kills the master which exits with a fatal condition.

112 + * There is no way to separate the agent configurations, so running multiple agent child nodes with the same GUID kills

113 + the parent which exits with a fatal condition.

114

115 4. The ACLK

116

collectors/proc.plugin/README.md

+3 -3

@@ -86,8 +86,8 @@ By default, Netdata will enable monitoring metrics only when they are not zero.

87 Netdata categorizes all block devices in 3 categories:

89 -1. physical disks (i.e. block devices that does not have slaves and are not partitions)

90 -2. virtual disks (i.e. block devices that have slaves - like RAID devices)

89 +1. physical disks (i.e. block devices that do not have child devices and are not partitions)

90 +2. virtual disks (i.e. block devices that have child devices - like RAID devices)

91 3. disk partitions (i.e. block devices that are part of a physical disk)

93 Performance metrics are enabled by default for all disk devices, except partitions and not-mounted virtual disks. Of course, you can enable/disable monitoring any block device by editing the Netdata configuration file.

@@ -325,7 +325,7 @@ By default Netdata will enable monitoring metrics only when they are not zero. I

325

326 There are several alarms defined in `health.d/net.conf`.

327

328 -The tricky ones are `inbound packets dropped` and `inbound packets dropped ratio`. They have quite a strict policy so that they warn users about possible issues. These alarms can be annoying for some network configurations. It is especially true for some bonding configurations if an interface is a slave or a bonding interface itself. If it is expected to have a certain number of drops on an interface for a certain network configuration, a separate alarm with different triggering thresholds can be created or the existing one can be disabled for this specific interface. It can be done with the help of the [families](/health/REFERENCE.md#alarm-line-families) line in the alarm configuration. For example, if you want to disable the `inbound packets dropped` alarm for `eth0`, set `families: !eth0 *` in the alarm definition for `template: inbound_packets_dropped`.

328 +The tricky ones are `inbound packets dropped` and `inbound packets dropped ratio`. They have quite a strict policy so that they warn users about possible issues. These alarms can be annoying for some network configurations. It is especially true for some bonding configurations if an interface is a child or a bonding interface itself. If it is expected to have a certain number of drops on an interface for a certain network configuration, a separate alarm with different triggering thresholds can be created or the existing one can be disabled for this specific interface. It can be done with the help of the [families](/health/REFERENCE.md#alarm-line-families) line in the alarm configuration. For example, if you want to disable the `inbound packets dropped` alarm for `eth0`, set `families: !eth0 *` in the alarm definition for `template: inbound_packets_dropped`.

329

330 #### configuration

331

daemon/config/README.md

+1 -1

@@ -82,7 +82,7 @@ Please note that your data history will be lost if you have modified `history` p

82 | pthread stack size|auto-detected||||

83 | cleanup obsolete charts after seconds|`3600`|See [monitoring ephemeral containers](/collectors/cgroups.plugin/README.md#monitoring-ephemeral-containers), also sets the timeout for cleaning up obsolete dimensions|||

84 | gap when lost iterations above|`1`||||

85 -| 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.|||

85 +| cleanup orphan hosts after seconds|`3600`|How long to wait until automatically removing from the DB a remote Netdata host (child) that is no longer sending data.|||

86 | delete obsolete charts files|`yes`|See [monitoring ephemeral containers](/collectors/cgroups.plugin/README.md#monitoring-ephemeral-containers), also affects the deletion of files for obsolete dimensions|||

87 | delete orphan hosts files|`yes`|Set to `no` to disable non-responsive host removal.|||

88 | enable zero metrics|`no`|Set to `yes` to show charts when all their metrics are zero.|||

database/engine/README.md

+13 -13

@@ -46,18 +46,18 @@ The `dbengine disk space` option determines the amount of disk space in **MiB**

46 metric values and all related metadata describing them.

48 Use the [**database engine calculator**](https://learn.netdata.cloud/docs/agent/database/calculator) to correctly set

49 -`dbengine disk space` based on your needs. The calculator gives an accurate estimate based on how many slave nodes you

50 -have, how many metrics your Agent collects, and more.

49 +`dbengine disk space` based on your needs. The calculator gives an accurate estimate based on how many child nodes

50 +you have, how many metrics your Agent collects, and more.

52 ### Streaming metrics to the database engine

54 -When streaming metrics, the Agent on the master node creates one instance of the database engine for itself, and another

55 -instance for every slave node it receives metrics from. If you have four streaming nodes, you will have five instances

56 -in total (`1 master + 4 slaves = 5 instances`).

54 +When streaming metrics, the Agent on the parent node creates one instance of the database engine for itself, and another

55 +instance for every child node it receives metrics from. If you have four streaming nodes, you will have five instances

56 +in total (`1 parent + 4 child nodes = 5 instances`).

58 The Agent allocates resources for each instance separately using the `dbengine disk space` setting. If `dbengine disk

59 space` is set to the default `256`, each instance is given 256 MiB in disk space, which means the total disk space

60 -required to store all instances is, roughly, `256 MiB * 1 master * 4 slaves = 1280 MiB`.

60 +required to store all instances is, roughly, `256 MiB * 1 parent * 4 child nodes = 1280 MiB`.

62 See the [database engine calculator](https://learn.netdata.cloud/docs/agent/database/calculator) to help you correctly

63 set `dbengine disk space` and undertand the toal disk space required based on your streaming setup.

@@ -90,14 +90,14 @@ validate the memory requirements for your particular system(s) and configuration

91 ### File descriptor requirements

93 -The Database Engine may keep a **significant** amount of files open per instance (e.g. per streaming slave or master

94 -server). When configuring your system you should make sure there are at least 50 file descriptors available per

93 +The Database Engine may keep a **significant** amount of files open per instance (e.g. per streaming child or

94 +parent server). When configuring your system you should make sure there are at least 50 file descriptors available per

95 `dbengine` instance.

97 Netdata allocates 25% of the available file descriptors to its Database Engine instances. This means that only 25% of

98 the file descriptors that are available to the Netdata service are accessible by dbengine instances. You should take

99 that into account when configuring your service or system-wide file descriptor limits. You can roughly estimate that the

100 -Netdata service needs 2048 file descriptors for every 10 streaming slave hosts when streaming is configured to use

100 +Netdata service needs 2048 file descriptors for every 10 streaming child hosts when streaming is configured to use

101 `memory mode = dbengine`.

102

103 If for example one wants to allocate 65536 file descriptors to the Netdata service on a systemd system one needs to

@@ -173,10 +173,10 @@ traffic so as to create the minimum possible interference with other application

173

174 ## Evaluation

175

176 -We have evaluated the performance of the `dbengine` API that the netdata daemon uses internally. This is **not** the

177 -web API of netdata. Our benchmarks ran on a **single** `dbengine` instance, multiple of which can be running in a

178 -netdata master server. We used a server with an AMD Ryzen Threadripper 2950X 16-Core Processor and 2 disk drives, a

179 -Seagate Constellation ES.3 2TB magnetic HDD and a SAMSUNG MZQLB960HAJR-00007 960GB NAND Flash SSD.

176 +We have evaluated the performance of the `dbengine` API that the netdata daemon uses internally. This is **not** the web

177 +API of netdata. Our benchmarks ran on a **single** `dbengine` instance, multiple of which can be running in a Netdata

178 +parent node. We used a server with an AMD Ryzen Threadripper 2950X 16-Core Processor and 2 disk drives, a Seagate

179 +Constellation ES.3 2TB magnetic HDD and a SAMSUNG MZQLB960HAJR-00007 960GB NAND Flash SSD.

180

181 For our workload, we defined 32 charts with 128 metrics each, giving us a total of 4096 metrics. We defined 1 worker

182 thread per chart (32 threads) that generates new data points with a data generation interval of 1 second. The time axis

docs/guides/longer-metrics-storage.md

+1 -1

@@ -57,7 +57,7 @@ metrics. The default settings retain about two day's worth of metris on a system

58 [**See our database engine calculator**](https://learn.netdata.cloud/docs/agent/database/calculator) to help you

59 correctly set `dbengine disk space` based on your needs. The calculator gives an accurate estimate based on how many

60 -slave nodes you have, how many metrics your Agent collects, and more.

60 +child nodes you have, how many metrics your Agent collects, and more.

62 With the database engine active, you can back up your `/var/cache/netdata/dbengine/` folder to another location for

63 redundancy.

docs/guides/monitor-hadoop-cluster.md

+1 -1

@@ -96,7 +96,7 @@ al-9866",

96 If Netdata can't access the `/jmx` endpoint for either a NameNode or DataNode, it will not be able to auto-detect and

97 collect metrics from your HDFS implementation.

99 -Zookeeper auto-detection relies on an accessible client port and a whitelisted `mntr` command. For more details on

99 +Zookeeper auto-detection relies on an accessible client port and a allow-listed `mntr` command. For more details on

100 `mntr`, see Zookeeper's documentation on [cluster

101 options](https://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_clusterOptions) and [Zookeeper

102 commands](https://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_zkCommands).

docs/guides/step-by-step/step-09.md

+1 -1

@@ -53,7 +53,7 @@ every second.

54 [**See our database engine calculator**](https://learn.netdata.cloud/docs/agent/database/calculator) to help you

55 correctly set `dbengine disk space` based on your needs. The calculator gives an accurate estimate based on how many

56 -slave nodes you have, how many metrics your Agent collects, and more.

56 +child nodes you have, how many metrics your Agent collects, and more.

58 ```conf

59 [global]

docs/guides/using-host-labels.md

+16 -16

@@ -7,7 +7,7 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/usin

8 When you use Netdata to monitor and troubleshoot an entire infrastructure, whether that's dozens or hundreds of systems,

9 you need sophisticated ways of keeping everything organized. You need alarms that adapt to the system's purpose, or

10 -whether the `master` or `slave` in a streaming setup. You need properly-labeled metrics archiving so you can sort,

10 +whether the parent or child in a streaming setup. You need properly-labeled metrics archiving so you can sort,

11 correlate, and mash-up your data to your heart's content. You need to keep tabs on ephemeral Docker containers in a

12 Kubernetes cluster.

@@ -50,7 +50,7 @@ read the status of your agent. For example, from a VPS system running Debian 10:

50 {

51 ...

52 "host_labels": {

53 - "_is_master": "false",

53 + "_is_parent": "false",

54 "_virt_detection": "systemd-detect-virt",

55 "_container_detection": "none",

56 "_container": "unknown",

@@ -73,7 +73,7 @@ You may have noticed a handful of labels that begin with an underscore (`_`). Th

74 When Netdata starts, it captures relevant information about the system and converts them into automatically-generated

75 host labels. You can use these to logically organize your systems via health entities, exporting metrics,

76 -streaming/master status, and more.

76 +parent-child status, and more.

78 They capture the following:

@@ -82,29 +82,29 @@ They capture the following:

82 - CPU architecture, system cores, CPU frequency, RAM, and disk space

83 - Whether Netdata is running inside of a container, and if so, the OS and hardware details about the container's host

84 - What virtualization layer the system runs on top of, if any

85 -- Whether the system is a streaming master or slave

85 +- Whether the system is a streaming parent or child

87 If you want to organize your systems without manually creating host tags, try the automatic labels in some of the

88 features below.

90 ## Host labels in streaming

92 -You may have noticed the `_is_master` and `_is_slave` automatic labels from above. Host labels are also now streamed

93 -from a slave to its master agent, which concentrates an entire infrastructure's OS, hardware, container, and

94 -virtualization information in one place: the master.

92 +You may have noticed the `_is_parent` and `_is_child` automatic labels from above. Host labels are also now

93 +streamed from a child to its parent node, which concentrates an entire infrastructure's OS, hardware, container,

94 +and virtualization information in one place: the parent.

96 -Now, if you'd like to remind yourself of how much RAM a certain slave system has, you can simply access

97 -`http://localhost:19999/host/SLAVE_NAME/api/v1/info` and reference the automatically-generated host labels from the

98 -slave system. It's a vastly simplified way of accessing critical information about your infrastructure.

96 +Now, if you'd like to remind yourself of how much RAM a certain child node has, you can access

97 +`http://localhost:19999/host/CHILD_HOSTNAME/api/v1/info` and reference the automatically-generated host labels from the

98 +child system. It's a vastly simplified way of accessing critical information about your infrastructure.

100 -> ⚠️ Because automatic labels for slave nodes are accessible via API calls, and contain sensitive information like

100 +> ⚠️ Because automatic labels for child nodes are accessible via API calls, and contain sensitive information like

101 > kernel and operating system versions, you should secure streaming connections with SSL. See the [streaming

102 > documentation](/streaming/README.md#securing-streaming-communications) for details. You may also want to use

103 > [access lists](/web/server/README.md#access-lists) or [expose the API only to LAN/localhost

104 > connections](/docs/netdata-security.md#expose-netdata-only-in-a-private-lan).

105

106 -You can also use `_is_master`, `_is_slave`, and any other host labels in both health entities and metrics exporting.

107 -Speaking of which...

106 +You can also use `_is_parent`, `_is_child`, and any other host labels in both health entities and metrics

107 +exporting. Speaking of which...

108

109 ## Host labels in health entities

110

@@ -138,11 +138,11 @@ Or, by using one of the automatic labels, for only webserver systems running a s

138 host labels: _os_name = Debian*

139 ```

140

141 -In a streaming configuration where a master agent is triggering alarms for its slaves, you could create health entities

142 -that apply only to slaves:

141 +In a streaming configuration where a parent node is triggering alarms for its child nodes, you could create health

142 +entities that apply only to child nodes:

143

144 ```yaml

145 - host labels: _is_slave = true

145 + host labels: _is_child = true

146 ```

147

148 Or when ephemeral Docker nodes are involved:

docs/netdata-security.md

+8 -2

@@ -40,7 +40,10 @@ There are a few cases however that raw source data are only exposed to processes

41 So, Netdata **plugins**, even those running with escalated capabilities or privileges, perform a **hard coded data collection job**. They do not accept commands from Netdata. The communication is strictly **unidirectional**: from the plugin towards the Netdata daemon. The original application data collected by each plugin do not leave the process they are collected, are not saved and are not transferred to the Netdata daemon. The communication from the plugins to the Netdata daemon includes only chart metadata and processed metric values.

43 -Netdata slaves streaming metrics to upstream Netdata servers, use exactly the same protocol local plugins use. The raw data collected by the plugins of slave Netdata servers are **never leaving the host they are collected**. The only data appearing on the wire are chart metadata and metric values. This communication is also **unidirectional**: slave Netdata servers never accept commands from master Netdata servers.

43 +Child nodes use the same protocol when streaming metrics to their parent nodes. The raw data collected by the plugins of

44 +child Netdata servers are **never leaving the host they are collected**. The only data appearing on the wire are chart

45 +metadata and metric values. This communication is also **unidirectional**: child nodes never accept commands from

46 +parent Netdata servers.

48 ## Netdata is read-only

@@ -190,7 +193,10 @@ Of course, there are many more methods you could use to protect Netdata:

193

194 - If you are 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.

195

193 -- install all your Netdata in **headless data collector** mode, forwarding all metrics in real-time to a master Netdata server, which will be protected with authentication using an nginx server running locally at the master Netdata server. This requires more resources (you will need a bigger master Netdata server), but does not require any firewall changes, since all the slave Netdata servers will not be listening for incoming connections.

196 +- install all your Netdata in **headless data collector** mode, forwarding all metrics in real-time to a parent

197 + Netdata server, which will be protected with authentication using an nginx server running locally at the parent

198 + Netdata server. This requires more resources (you will need a bigger parent Netdata server), but does not require

199 + any firewall changes, since all the child Netdata servers will not be listening for incoming connections.

200

201 ## Anonymous Statistics

202

exporting/README.md

+2 -2

@@ -233,8 +233,8 @@ Options:

233 of times within each pattern). The patterns are checked against the hostname (the localhost is always checked as

234 `localhost`), allowing us to filter which hosts will be sent to the external database when this Netdata is a central

235 Netdata aggregating multiple hosts. A pattern starting with `!` gives a negative match. So to match all hosts named

236 - `*db*` except hosts containing `*slave*`, use `!*slave* *db*` (so, the order is important: the first pattern

237 - matching the hostname will be used - positive or negative).

236 + `*db*` except hosts containing `*child*`, use `!*child* *db*` (so, the order is important: the first

237 + pattern matching the hostname will be used - positive or negative).

238

239 - `send charts matching = *` includes one or more space separated patterns, using `*` as wildcard (any number of times

240 within each pattern). The patterns are checked against both chart id and chart name. A pattern starting with `!`

exporting/prometheus/README.md

+1 -1

@@ -357,7 +357,7 @@ For more information check Prometheus documentation.

357

358 ### Streaming data from upstream hosts

359

360 -The `format=prometheus` parameter only exports the host's Netdata metrics. If you are using the master/slave

360 +The `format=prometheus` parameter only exports the host's Netdata metrics. If you are using the parent-child

361 functionality of Netdata this ignores any upstream hosts - so you should consider using the below in your

362 **prometheus.yml**:

363

packaging/DISTRIBUTIONS.md

+3 -1

@@ -125,7 +125,9 @@ This is the brand new database engine capability of netdata. It is a mandatory f

125

126 #### Encryption Support (HTTPS)

127

128 -This is Netdata's TLS capability that incorporates encryption on the web server and the APIs between master and slaves. Also a mandatory facility for Netdata, but remains optional for users who are limited or not interested in tight security

128 +This is Netdata's TLS capability that incorporates encryption on the web server and the APIs between parent and child

129 +nodes. Also a mandatory facility for Netdata, but remains optional for users who are limited or not interested in tight

130 +security

131

133 |:---------------:|:------------------:|:----------:|:-------------------:|:----------:|:-----------:|:-----------:|

packaging/installer/methods/cloud-providers.md

+1 -1

@@ -9,7 +9,7 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/instal

10 Netdata is fully compatible with popular cloud providers like Google Cloud Platform (GCP), Amazon Web Services (AWS),

11 Azure, and others. You can install Netdata on cloud instances to monitor the apps/services running there, or use

12 -multiple instances in a [master/slave streaming](../../../streaming/README.md) configuration.

12 +multiple instances in a [parent-child streaming](/streaming/README.md) configuration.

14 In some cases, using Netdata on these cloud providers requires unique installation or configuration steps. This page

15 aims to document some of those steps for popular cloud providers.

packaging/installer/methods/macos.md

+2 -2

@@ -9,8 +9,8 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/instal

10 Netdata works on macOS, albeit with some limitations. The number of charts displaying system metrics is limited, but you

11 can use any of Netdata's [external plugins](../../../collectors/plugins.d/README.md) to monitor any services you might

12 -have installed on your macOS system. You could also use a macOS system as the master node in a [streaming

13 -configuration](../../../streaming/README.md).

12 +have installed on your macOS system. You could also use a macOS system as the parent node in a [streaming

13 +configuration](/streaming/README.md).

15 We recommend installing Netdata with the community-created and -maintained [**Homebrew

16 package**](#install-netdata-with-the-homebrew-package).

streaming/README.md

+135 -130

@@ -1,64 +1,70 @@

1 <!--

2 ----

2 title: "Streaming and replication"

3 +description: "Replicate and mirror Netdata's metrics through real-time streaming from child to parent nodes. Then combine, correlate, and export."

4 custom_edit_url: https://github.com/netdata/netdata/edit/master/streaming/README.md

5 ----

5 -->

7 # Streaming and replication

9 Each Netdata is able to replicate/mirror its database to another Netdata, by streaming collected

10 metrics, in real-time to it. This is quite different to [data archiving to third party time-series

12 -databases](/backends/README.md).

11 +databases](/exporting/README.md).

14 -When Netdata streams metrics to another Netdata, the receiving one is able to perform everything a Netdata instance is capable of:

13 +When Netdata streams metrics to another Netdata, the receiving one is able to perform everything a Netdata instance is

14 +capable of:

16 -- visualize them with a dashboard

17 -- run health checks that trigger alarms and send alarm notifications

18 -- archive metrics to a backend time-series database

16 +- Visualize metrics with a dashboard

17 +- Run health checks that trigger alarms and send alarm notifications

18 +- Export metrics to a external time-series database

19 +

20 +The nodes that send metrics are called **child** nodes, and the nodes that receive metrics are called **parent** nodes.

21 +There are also **proxies**, which collects metrics from a child and sends it to a parent.

23 ## Supported configurations

25 ### Netdata without a database or web API (headless collector)

24 -Local Netdata (`slave`), **without any database or alarms**, collects metrics and sends them to

25 -another Netdata (`master`).

27 +Local Netdata (child), **without any database or alarms**, collects metrics and sends them to another Netdata

28 +(parent).

27 -The node menu shows a list of all "databases streamed to" the master. Clicking one of those links allows the user to view the full dashboard of the `slave` Netdata. The URL has the form `http://master-host:master-port/host/slave-host/`.

30 +The node menu shows a list of all "databases streamed to" the parent. Clicking one of those links allows the user to

31 +view the full dashboard of the child node. The URL has the form

32 +`http://parent-host:parent-port/host/child-host/`.

29 -Alarms for the `slave` are served by the `master`.

34 +Alarms for the child are served by the parent.

31 -In this mode the `slave` is just a plain data collector. It spawns all external plugins, but instead

32 -of maintaining a local database and accepting dashboard requests, it streams all metrics to the

33 -`master`. The memory footprint is reduced significantly, to between 6 MiB and 40 MiB, depending on the enabled plugins. To reduce the memory usage as much as possible, refer to [running Netdata in embedded devices](/docs/Performance.md#running-netdata-in-embedded-devices).

36 +In this mode the child is just a plain data collector. It spawns all external plugins, but instead of maintaining a

37 +local database and accepting dashboard requests, it streams all metrics to the parent. The memory footprint is reduced

38 +significantly, to between 6 MiB and 40 MiB, depending on the enabled plugins. To reduce the memory usage as much as

39 +possible, refer to [running Netdata in embedded devices](/docs/Performance.md#running-netdata-in-embedded-devices).

35 -The same `master` can collect data for any number of `slaves`.

41 +The same parent can collect data for any number of child nodes.

43 ### Database Replication

39 -Local Netdata (`slave`), **with a local database (and possibly alarms)**, collects metrics and

40 -sends them to another Netdata (`master`).

45 +Local Netdata (child), **with a local database (and possibly alarms)**, collects metrics and

46 +sends them to another Netdata (parent).

42 -The user can use all the functions **at both** `http://slave-ip:slave-port/` and

43 -`http://master-host:master-port/host/slave-host/`.

48 +The user can use all the functions **at both** `http://child-ip:child-port/` and

49 +`http://parent-host:parent-port/host/child-host/`.

45 -The `slave` and the `master` may have different data retention policies for the same metrics.

51 +The child and the parent may have different data retention policies for the same metrics.

47 -Alarms for the `slave` are triggered by **both** the `slave` and the `master` (and actually

53 +Alarms for the child are triggered by **both** the child and the parent (and actually

54 each can have different alarms configurations or have alarms disabled).

50 -Take a note, that custom chart names, configured on the `slave`, should be in the form `type.name` to work correctly. The `master` will truncate the `type` part and substitute the original chart `type` to store the name in the database.

56 +Take a note, that custom chart names, configured on the child, should be in the form `type.name` to work correctly. The parent will truncate the `type` part and substitute the original chart `type` to store the name in the database.

58 ### Netdata proxies

54 -Local Netdata (`slave`), with or without a database, collects metrics and sends them to another

55 -Netdata (`proxy`), which may or may not maintain a database, which forwards them to another

56 -Netdata (`master`).

60 +Local Netdata (child), with or without a database, collects metrics and sends them to another

61 +Netdata (**proxy**), which may or may not maintain a database, which forwards them to another

62 +Netdata (parent).

58 -Alarms for the slave can be triggered by any of the involved hosts that maintains a database.

64 +Alarms for the child can be triggered by any of the involved hosts that maintains a database.

66 Any number of daisy chaining Netdata servers are supported, each with or without a database and

61 -with or without alarms for the `slave` metrics.

67 +with or without alarms for the child metrics.

69 ### mix and match with backends

@@ -96,7 +102,9 @@ monitoring (there cannot be health monitoring without a database).

102 `[web].mode = none` disables the API (Netdata will not listen to any ports).

103 This also disables the registry (there cannot be a registry without an API).

104

99 -`accept a streaming request every seconds` can be used to set a limit on how often a master Netdata server will accept streaming requests from the slaves. 0 sets no limit, 1 means maximum once every second. If this is set, you may see error log entries "... too busy to accept new streaming request. Will be allowed in X secs".

105 +`accept a streaming request every seconds` can be used to set a limit on how often a parent node will accept streaming

106 +requests from its child nodes. 0 sets no limit, 1 means maximum once every second. If this is set, you may see error log

107 +entries "... too busy to accept new streaming request. Will be allowed in X secs".

108

109 ```

110 [backend]

@@ -126,7 +134,7 @@ sending-receiving Netdata.

134

135 This is the section for the sending Netdata. On the receiving node, `[stream].enabled` can be `no`.

136 If it is `yes`, the receiving node will also stream the metrics to another node (i.e. it will be

129 -a `proxy`).

137 +a proxy).

138

139 ```

140 [stream]

@@ -144,7 +152,7 @@ This is an overview of how these options can be combined:

154

147 -For the options to encrypt the data stream between the slave and the master, refer to [securing the communication](#securing-streaming-communications)

155 +For the options to encrypt the data stream between the child and the parent, refer to [securing the communication](#securing-streaming-communications)

156

157 ##### options for the receiving node

158

@@ -166,7 +174,7 @@ all hosts pushed with this API key.

174 You can also add sections like this:

175

176 ```sh

169 -# replace MACHINE_GUID with the slave /var/lib/netdata/registry/netdata.public.unique.id

177 +# replace MACHINE_GUID with the child /var/lib/netdata/registry/netdata.public.unique.id

178 [MACHINE_GUID]

179 enabled = yes

180 history = 3600

@@ -175,7 +183,7 @@ You can also add sections like this:

183 allow from = *

184 ```

185

178 -The above is the receiver configuration of a single host, at the receiver end. `MACHINE_GUID` is

186 +The above is the parent configuration of a single host, at the parent end. `MACHINE_GUID` is

187 the unique id the Netdata generating the metrics (i.e. the Netdata that originally collects

188 them `/var/lib/netdata/registry/netdata.unique.id`). So, metrics for Netdata `A` that pass through

189 any number of other Netdata, will have the same `MACHINE_GUID`.

@@ -195,7 +203,7 @@ important: left to right, the first positive or negative match is used.

203

204 ##### tracing

205

198 -When a `slave` is trying to push metrics to a `master` or `proxy`, it logs entries like these:

206 +When a child is trying to push metrics to a parent or proxy, it logs entries like these:

207

208 ```

209 2017-02-25 01:57:44: netdata: ERROR: Failed to connect to '10.11.12.1', port '19999' (errno 111, Connection refused)

@@ -207,7 +215,7 @@ When a `slave` is trying to push metrics to a `master` or `proxy`, it logs entri

215 2017-02-25 01:58:14: netdata: INFO : STREAM costa-pc [send]: ready - sending metrics...

216 ```

217

210 -The receiving end (`proxy` or `master`) logs entries like these:

218 +The receiving end (proxy or parent) logs entries like these:

219

220 ```

221 2017-02-25 01:58:04: netdata: INFO : STREAM [receive from [10.11.12.11]:33554]: new client connection.

@@ -221,14 +229,14 @@ For Netdata v1.9+, streaming can also be monitored via `access.log`.

229

230 ### Securing streaming communications

231

224 -Netdata does not activate TLS encryption by default. To encrypt streaming connections, you first need to [enable TLS support](/web/server/README.md#enabling-tls-support) on the master. With encryption enabled on the receiving side, you need to instruct the slave to use TLS/SSL as well. On the slave's `stream.conf`, configure the destination as follows:

232 +Netdata does not activate TLS encryption by default. To encrypt streaming connections, you first need to [enable TLS support](/web/server/README.md#enabling-tls-support) on the parent. With encryption enabled on the receiving side, you need to instruct the child to use TLS/SSL as well. On the child's `stream.conf`, configure the destination as follows:

233

234 ```

235 [stream]

236 destination = host:port:SSL

237 ```

238

231 -The word `SSL` appended to the end of the destination tells the slave that connections must be encrypted.

239 +The word `SSL` appended to the end of the destination tells the child that connections must be encrypted.

240

241 > While Netdata uses Transport Layer Security (TLS) 1.2 to encrypt communications rather than the obsolete SSL protocol,

242 > it's still common practice to refer to encrypted web connections as `SSL`. Many vendors, like Nginx and even Netdata

@@ -237,7 +245,7 @@ The word `SSL` appended to the end of the destination tells the slave that conne

245

246 #### Certificate verification

247

240 -When TLS/SSL is enabled on the slave, the default behavior will be to not connect with the master unless the server's certificate can be verified via the default chain. In case you want to avoid this check, add the following to the slave's `stream.conf` file:

248 +When TLS/SSL is enabled on the child, the default behavior will be to not connect with the parent unless the server's certificate can be verified via the default chain. In case you want to avoid this check, add the following to the child's `stream.conf` file:

249

250 ```

251 [stream]

@@ -252,15 +260,15 @@ Given these known issues, you have two options. If you trust your certificate, y

260

261 For more details about these options, you can read about [verify locations](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_load_verify_locations.html).

262

255 -Before you changed your streaming configuration, you need to copy your trusted certificate to your slave system and add the certificate to OpenSSL's list.

263 +Before you changed your streaming configuration, you need to copy your trusted certificate to your child system and add the certificate to OpenSSL's list.

264

265 On most Linux distributions, the `update-ca-certificates` command searches inside the `/usr/share/ca-certificates` directory for certificates. You should double-check by reading the `update-ca-certificate` manual (`man update-ca-certificate`), and then change the directory in the below commands if needed.

266

259 -If you have `sudo` configured on your slave system, you can use that to run the following commands. If not, you'll have to log in as `root` to complete them.

267 +If you have `sudo` configured on your child system, you can use that to run the following commands. If not, you'll have to log in as `root` to complete them.

268

269 ```

270 # mkdir /usr/share/ca-certificates/netdata

263 -# cp master_cert.pem /usr/share/ca-certificates/netdata/master_cert.crt

271 +# cp parent_cert.pem /usr/share/ca-certificates/netdata/parent_cert.crt

272 # chown -R netdata.netdata /usr/share/ca-certificates/netdata/

273 ```

274

@@ -269,7 +277,7 @@ First, you create a new directory to store your certificates for Netdata. Next,

277 Next, edit the file `/etc/ca-certificates.conf` and add the following line:

278

279 ```

272 -netdata/master_cert.crt

280 +netdata/parent_cert.crt

281 ```

282

283 Now you update the list of certificates running the following, again either as `sudo` or `root`:

@@ -281,32 +289,32 @@ Now you update the list of certificates running the following, again either as `

289 > Some Linux distributions have different methods of updating the certificate list. For more details, please read this

290 > guide on [addding trusted root certificates](https://github.com/Busindre/How-to-Add-trusted-root-certificates).

291

284 -Once you update your certificate list, you can set the stream parameters for Netdata to trust the master certificate. Open `stream.conf` for editing and change the following lines:

292 +Once you update your certificate list, you can set the stream parameters for Netdata to trust the parent certificate. Open `stream.conf` for editing and change the following lines:

293

294 ```

295 [stream]

296 CApath = /etc/ssl/certs/

289 - CAfile = /etc/ssl/certs/master_cert.pem

297 + CAfile = /etc/ssl/certs/parent_cert.pem

298 ```

299

292 -With this configuration, the `CApath` option tells Netdata to search for trusted certificates inside `/etc/ssl/certs`. The `CAfile` option specifies the Netdata master certificate is located at `/etc/ssl/certs/master_cert.pem`. With this configuration, you can skip using the system's entire list of certificates and use Netdata's master certificate instead.

300 +With this configuration, the `CApath` option tells Netdata to search for trusted certificates inside `/etc/ssl/certs`. The `CAfile` option specifies the Netdata parent certificate is located at `/etc/ssl/certs/parent_cert.pem`. With this configuration, you can skip using the system's entire list of certificates and use Netdata's parent certificate instead.

301

302 #### Expected behaviors

303

296 -With the introduction of TLS/SSL, the master-slave communication behaves as shown in the table below, depending on the following configurations:

304 +With the introduction of TLS/SSL, the parent-child communication behaves as shown in the table below, depending on the following configurations:

305

298 -- **Master TLS (Yes/No)**: Whether the `[web]` section in `netdata.conf` has `ssl key` and `ssl certificate`.

299 -- **Master port TLS (-/force/optional)**: Depends on whether the `[web]` section `bind to` contains a `^SSL=force` or `^SSL=optional` directive on the port(s) used for streaming.

300 -- **Slave TLS (Yes/No)**: Whether the destination in the slave's `stream.conf` has `:SSL` at the end.

301 -- **Slave TLS Verification (yes/no)**: Value of the slave's `stream.conf` `ssl skip certificate verification` parameter (default is no).

306 +- **Parent TLS (Yes/No)**: Whether the `[web]` section in `netdata.conf` has `ssl key` and `ssl certificate`.

307 +- **Parent port TLS (-/force/optional)**: Depends on whether the `[web]` section `bind to` contains a `^SSL=force` or `^SSL=optional` directive on the port(s) used for streaming.

308 +- **Child TLS (Yes/No)**: Whether the destination in the child's `stream.conf` has `:SSL` at the end.

309 +- **Child TLS Verification (yes/no)**: Value of the child's `stream.conf` `ssl skip certificate verification` parameter (default is no).

310

312 |:----------------:|:-------------:|:-------:|:------------:|:-------|

305 -| No|-|No|no|Legacy behavior. The master-slave stream is unencrypted.|

306 -| Yes|force|No|no|The master rejects the slave connection.|

307 -| Yes|-/optional|No|no|The master-slave stream is unencrypted (expected situation for legacy slaves and newer masters)|

308 -| Yes|-/force/optional|Yes|no|The master-slave stream is encrypted, provided that the master has a valid TLS/SSL certificate. Otherwise, the slave refuses to connect.|

309 -| Yes|-/force/optional|Yes|yes|The master-slave stream is encrypted.|

313 +| No|-|No|no|Legacy behavior. The parent-child stream is unencrypted.|

314 +| Yes|force|No|no|The parent rejects the child connection.|

315 +| Yes|-/optional|No|no|The parent-child stream is unencrypted (expected situation for legacy child nodes and newer parent nodes)|

316 +| Yes|-/force/optional|Yes|no|The parent-child stream is encrypted, provided that the parent has a valid TLS/SSL certificate. Otherwise, the child refuses to connect.|

317 +| Yes|-/force/optional|Yes|yes|The parent-child stream is encrypted.|

318

319 ## Viewing remote host dashboards, using mirrored databases

320

@@ -323,9 +331,7 @@ Auto-scaling is probably the most trendy service deployment strategy these days.

331

332 Auto-scaling detects the need for additional resources and boots VMs on demand, based on a template. Soon after they start running the applications, a load balancer starts distributing traffic to them, allowing the service to grow horizontally to the scale needed to handle the load. When demands falls, auto-scaling starts shutting down VMs that are no longer needed.

333

326 -

327 -<img src="https://cloud.githubusercontent.com/assets/2662304/23627426/65a9074a-02b9-11e7-9664-cd8f258a00af.png"/>

328 -

334 +![Monitoring ephemeral nodes with Netdata](https://cloud.githubusercontent.com/assets/2662304/23627426/65a9074a-02b9-11e7-9664-cd8f258a00af.png)

335

336 What a fantastic feature for controlling infrastructure costs! Pay only for what you need for the time you need it!

337

@@ -348,84 +354,83 @@ Following the Netdata way of monitoring, we wanted:

354

355 All monitoring solutions, including Netdata, work like this:

356

351 -1. `collect metrics`, from the system and the running applications

352 -2. `store metrics`, in a time-series database

353 -3. `examine metrics` periodically, for triggering alarms and sending alarm notifications

354 -4. `visualize metrics`, so that users can see what exactly is happening

357 +1. Collect metrics from the system and the running applications

358 +2. Store metrics in a time-series database

359 +3. Examine metrics periodically, for triggering alarms and sending alarm notifications

360 +4. Visualize metrics so that users can see what exactly is happening

361

362 Netdata used to be self-contained, so that all these functions were handled entirely by each server. The changes we made, allow each Netdata to be configured independently for each function. So, each Netdata can now act as:

363

358 -- a `self contained system`, much like it used to be.

359 -- a `data collector`, that collects metrics from a host and pushes them to another Netdata (with or without a local database and alarms).

360 -- a `proxy`, that receives metrics from other hosts and pushes them immediately to other Netdata servers. Netdata proxies can also be `store and forward proxies` meaning that they are able to maintain a local database for all metrics passing through them (with or without alarms).

361 -- a `time-series database` node, where data are kept, alarms are run and queries are served to visualise the metrics.

364 +- A self-contained system, much like it used to be.

365 +- A data collector that collects metrics from a host and pushes them to another Netdata (with or without a local database and alarms).

366 +- A proxy, which receives metrics from other hosts and pushes them immediately to other Netdata servers. Netdata proxies can also be `store and forward proxies` meaning that they are able to maintain a local database for all metrics passing through them (with or without alarms).

367 +- A time-series database node, where data are kept, alarms are run and queries are served to visualise the metrics.

368

369 ### Configuring an auto-scaling setup

370

365 -

366 -<img src="https://cloud.githubusercontent.com/assets/2662304/23627468/96daf7ba-02b9-11e7-95ac-1f767dd8dab8.png"/>

367 -

371 +![A diagram of an auto-scaling setup with Netdata](https://user-images.githubusercontent.com/1153921/84290043-0c1c1600-aaf8-11ea-9757-dd8dd8a8ec6c.png)

372

369 -You need a Netdata `master`. This node should not be ephemeral. It will be the node where all ephemeral nodes (let's call them `slaves`) will be sending their metrics.

373 +You need a Netdata parent. This node should not be ephemeral. It will be the node where all ephemeral child

374 +nodes will send their metrics.

375

371 -The master will need to authorize the slaves for accepting their metrics. This is done with an API key.

376 +The parent will need to authorize child nodes to receive their metrics. This is done with an API key.

377

378 #### API keys

379

375 -API keys are just random GUIDs. Use the Linux command `uuidgen` to generate one. You can use the same API key for all your `slaves`, or you can configure one API for each of them. This is entirely your decision.

380 +API keys are just random GUIDs. Use the Linux command `uuidgen` to generate one. You can use the same API key for all your child nodes, or you can configure one API for each of them. This is entirely your decision.

381

382 We suggest to use the same API key for each ephemeral node template you have, so that all replicas of the same ephemeral node will have exactly the same configuration.

383

384 I will use this API_KEY: `11111111-2222-3333-4444-555555555555`. Replace it with your own.

385

381 -#### Configuring the `master`

386 +#### Configuring the parent

387

383 -On the master, edit `/etc/netdata/stream.conf` (to edit it on your system run `/etc/netdata/edit-config stream.conf`) and set these:

388 +On the parent, edit `/etc/netdata/stream.conf` (to edit it on your system run `/etc/netdata/edit-config stream.conf`) and set these:

389

390 ```bash

391 [11111111-2222-3333-4444-555555555555]

392 # enable/disable this API key

393 enabled = yes

394

390 - # one hour of data for each of the slaves

395 + # one hour of data for each of the child nodes

396 default history = 3600

397

393 - # do not save slave metrics on disk

398 + # do not save child metrics on disk

399 default memory = ram

400

396 - # alarms checks, only while the slave is connected

401 + # alarms checks, only while the child is connected

402 health enabled by default = auto

403 ```

404

400 -_`stream.conf` on master, to enable receiving metrics from slaves using the API key._

405 +_`stream.conf` on the parent, to enable receiving metrics from its child ndoes using the API key._

406

407 If you used many API keys, you can add one such section for each API key.

408

404 -When done, restart Netdata on the `master` node. It is now ready to receive metrics.

409 +When done, restart Netdata on the parent node. It is now ready to receive metrics.

410

406 -Note that `health enabled by default = auto` will still trigger `last_collected` alarms, if a connected slave does not exit gracefully. If the `netdata` process running on the slave is

407 -stopped, it will close the connection to the master, ensuring that no `last_collected` alarms are triggered. For example, a proper container restart would first terminate

408 -the `netdata` process, but a system power issue would leave the connection open on the master side. In the second case, you will still receive alarms.

411 +Note that `health enabled by default = auto` will still trigger `last_collected` alarms, if a connected child does not exit gracefully. If the `netdata` process running on the child is

412 +stopped, it will close the connection to the parent, ensuring that no `last_collected` alarms are triggered. For example, a proper container restart would first terminate

413 +the `netdata` process, but a system power issue would leave the connection open on the parent side. In the second case, you will still receive alarms.

414

410 -#### Configuring the `slaves`

415 +#### Configuring the child nodes

416

412 -On each of the slaves, edit `/etc/netdata/stream.conf` (to edit it on your system run `/etc/netdata/edit-config stream.conf`) and set these:

417 +On each of the child nodes, edit `/etc/netdata/stream.conf` (to edit it on your system run `/etc/netdata/edit-config stream.conf`) and set these:

418

419 ```bash

420 [stream]

421 # stream metrics to another Netdata

422 enabled = yes

423

419 - # the IP and PORT of the master

424 + # the IP and PORT of the parent

425 destination = 10.11.12.13:19999

426

427 # the API key to use

428 api key = 11111111-2222-3333-4444-555555555555

429 ```

430

426 -_`stream.conf` on slaves, to enable pushing metrics to master at `10.11.12.13:19999`._

431 +_`stream.conf` on child nodes, to enable pushing metrics to their parent at `10.11.12.13:19999`._

432

428 -Using just the above configuration, the `slaves` will be pushing their metrics to the `master` Netdata, but they will still maintain a local database of the metrics and run health checks. To disable them, edit `/etc/netdata/netdata.conf` and set:

433 +Using just the above configuration, the child nodes will be pushing their metrics to the parent Netdata, but they will still maintain a local database of the metrics and run health checks. To disable them, edit `/etc/netdata/netdata.conf` and set:

434

435 ```bash

436 [global]

@@ -437,9 +442,9 @@ Using just the above configuration, the `slaves` will be pushing their metrics t

442 enabled = no

443 ```

444

440 -_`netdata.conf` configuration on slaves, to disable the local database and health checks._

445 +_`netdata.conf` configuration on child nodes, to disable the local database and health checks._

446

442 -Keep in mind that setting `memory mode = none` will also force `[health].enabled = no` (health checks require access to a local database). But you can keep the database and disable health checks if you need to. You are however sending all the metrics to the master server, which can handle the health checking (`[health].enabled = yes`)

447 +Keep in mind that setting `memory mode = none` will also force `[health].enabled = no` (health checks require access to a local database). But you can keep the database and disable health checks if you need to. You are however sending all the metrics to the parent node, which can handle the health checking (`[health].enabled = yes`)

448

449 #### Netdata unique id

450

@@ -449,15 +454,15 @@ The file `/var/lib/netdata/registry/netdata.public.unique.id` contains a random

454

455 #### Troubleshooting metrics streaming

456

452 -Both the sender and the receiver of metrics log information at `/var/log/netdata/error.log`.

457 +Both parent and child nodes log information at `/var/log/netdata/error.log`.

458

454 -On both master and slave do this:

459 +Run the following on both the parent and child nodes:

460

461 ```

462 tail -f /var/log/netdata/error.log | grep STREAM

463 ```

464

460 -If the slave manages to connect to the master you will see something like (on the master):

465 +If the child manages to connect to the parent you will see something like (on the parent):

466

467 ```

468 2017-03-09 09:38:52: netdata: INFO : STREAM [receive from [10.11.12.86]:38564]: new client connection.

@@ -467,7 +472,7 @@ If the slave manages to connect to the master you will see something like (on th

472 2017-03-09 09:38:52: netdata: INFO : STREAM xxx [receive from [10.11.12.86]:38564]: receiving metrics...

473 ```

474

470 -and something like this on the slave:

475 +and something like this on the child:

476

477 ```

478 2017-03-09 09:38:28: netdata: INFO : STREAM xxx [send to box:19999]: connecting...

@@ -478,7 +483,8 @@ and something like this on the slave:

483

484 ### Archiving to a time-series database

485

481 -The `master` Netdata node can also archive metrics, for all `slaves`, to a time-series database. At the time of this writing, Netdata supports:

486 +The parent Netdata node can also archive metrics, for all its child nodes, to a time-series database. At the time of

487 +this writing, Netdata supports:

488

489 - graphite

490 - opentsdb

@@ -486,13 +492,12 @@ The `master` Netdata node can also archive metrics, for all `slaves`, to a time-

492 - json document DBs

493 - all the compatibles to the above (e.g. kairosdb, influxdb, etc)

494

489 -Check the Netdata [backends documentation](/backends/README.md) for configuring this.

495 +Check the Netdata [exporting documentation](/docs/export/README.md) for configuring this.

496

497 This is how such a solution will work:

498

493 -

494 -<img src="https://cloud.githubusercontent.com/assets/2662304/23627295/e3569adc-02b8-11e7-9d55-4014bf98c1b3.png"/>

495 -

499 +![Diagram showing an example configuration for archiving to a time-series

500 +database](https://user-images.githubusercontent.com/1153921/84291308-c2ccc600-aaf9-11ea-98a9-89ccbf3a62dd.png)

501

502 ### An advanced setup

503

@@ -522,93 +527,93 @@ For a practical example see [Monitoring ephemeral nodes](#monitoring-ephemeral-n

527

528 ## Troubleshooting streaming connections

529

525 -This section describes the most common issues you might encounter when connecting slave and master Netdata agents.

530 +This section describes the most common issues you might encounter when connecting parent and child nodes.

531

527 -### Slow connections between slave and master

532 +### Slow connections between parent and child

533

529 -When you have a slow connection between master and slave, Netdata raises a few different errors. Most of the errors will

530 -appear in the slave's `error.log`.

534 +When you have a slow connection between parent and child, Netdata raises a few different errors. Most of the

535 +errors will appear in the child's `error.log`.

536

532 -```

533 -netdata ERROR : STREAM_SENDER[SLAVE HOSTNAME] : STREAM SLAVE HOSTNAME [send to MASTER IP:MASTER PORT]: too many data pending - buffer is X bytes long,

537 +```bash

538 +netdata ERROR : STREAM_SENDER[CHILD HOSTNAME] : STREAM CHILD HOSTNAME [send to PARENT IP:PARENT PORT]: too many data pending - buffer is X bytes long,

539 Y unsent - we have sent Z bytes in total, W on this connection. Closing connection to flush the data.

540 ```

541

537 -On the master side, you may see various error messages, most commonly the following:

542 +On the parent side, you may see various error messages, most commonly the following:

543

544 ```

540 -netdata ERROR : STREAM_RECEIVER[SLAVE HOSTNAME,[SLAVE IP]:SLAVE PORT] : read failed: end of file

545 +netdata ERROR : STREAM_PARENT[CHILD HOSTNAME,[CHILD IP]:CHILD PORT] : read failed: end of file

546 ```

547

543 -Another common problem in slow connections is the slave sending a partial message to the master. In this case, the

544 -master will write the following in its `error.log`:

548 +Another common problem in slow connections is the CHILD sending a partial message to the parent. In this case,

549 +the parent will write the following in its `error.log`:

550

551 ```

547 -ERROR : STREAM_RECEIVER[SLAVE HOSTNAME,[SLAVE IP]:SLAVE PORT] : sent command 'B' which is not known by netdata, for host 'HOSTNAME'. Disabling it.

552 +ERROR : STREAM_RECEIVER[CHILD HOSTNAME,[CHILD IP]:CHILD PORT] : sent command 'B' which is not known by netdata, for host 'HOSTNAME'. Disabling it.

553 ```

554

555 In this example, `B` was part of a `BEGIN` message that was cut due to connection problems.

556

552 -Slow connections can also cause problems when the master misses a message and then recieves a command related to the

553 -missed message. For example, a master might miss a message containing the slave's charts, and then doesn't know what to

554 -do with the `SET` message that follows. When that happens, the master will show a message like this:

557 +Slow connections can also cause problems when the parent misses a message and then recieves a command related to the

558 +missed message. For example, a parent might miss a message containing the child's charts, and then doesn't know

559 +what to do with the `SET` message that follows. When that happens, the parent will show a message like this:

560

561 ```

557 -ERROR : STREAM_RECEIVER[SLAVE HOSTNAME,[SLAVE IP]:SLAVE PORT] : requested a SET on chart 'CHART NAME' of host 'HOSTNAME', without a dimension. Disabling it.

562 +ERROR : STREAM_RECEIVER[CHILD HOSTNAME,[CHILD IP]:CHILD PORT] : requested a SET on chart 'CHART NAME' of host 'HOSTNAME', without a dimension. Disabling it.

563 ```

564

560 -### Slave cannot connect to master

565 +### child cannot connect to parent

566

562 -When the slave can't connect to a master for any reason (misconfiguration, networking, firewalls, master down), you will

563 -see the following in the slave's `error.log`.

567 +When the child can't connect to a parent for any reason (misconfiguration, networking, firewalls, parent

568 +down), you will see the following in the child's `error.log`.

569

570 ```

566 -ERROR : STREAM_SENDER[HOSTNAME] : Failed to connect to 'MASTER IP', port 'MASTER PORT' (errno 113, No route to host)

571 +ERROR : STREAM_SENDER[HOSTNAME] : Failed to connect to 'PARENT IP', port 'PARENT PORT' (errno 113, No route to host)

572 ```

573

574 ### 'Is this a Netdata?'

575

576 This question can appear when Netdata starts the stream and receives an unexpected response. This error can appear when

572 -the master is using SSL and the slave tries to connect using plain text. You will also see this message when Netdata

573 -connects to another server that isn't Netdata. The complete error message will look like this:

577 +the parent is using SSL and the child tries to connect using plain text. You will also see this message when

578 +Netdata connects to another server that isn't Netdata. The complete error message will look like this:

579

580 ```

576 -ERROR : STREAM_SENDER[SLAVE HOSTNAME] : STREAM SLAVE HOSTNAME [send to MASTER HOSTNAME:MASTER PORT]: server is not replying properly (is it a netdata?).

581 +ERROR : STREAM_SENDER[CHILD HOSTNAME] : STREAM child HOSTNAME [send to PARENT HOSTNAME:PARENT PORT]: server is not replying properly (is it a netdata?).

582 ```

583

584 ### Stream charts wrong

585

581 -Chart data needs to be consistent between slave and master agents. If there are differences between chart data on a

582 -master and a slave, such as gaps in metrics collection, it most often means your slave's `memory mode` does not match

583 -the master's. To learn more about the different ways Netdata can store metrics, and thus keep chart data consistent,

584 -read our [memory mode documentation](/database/README.md).

586 +Chart data needs to be consistent between child and parent nodes. If there are differences between chart data on

587 +a parent and a child, such as gaps in metrics collection, it most often means your child's `memory mode`

588 +does not match the parent's. To learn more about the different ways Netdata can store metrics, and thus keep chart

589 +data consistent, read our [memory mode documentation](/database/README.md).

590

591 ### Forbidding access

592

593 You may see errors about "forbidding access" for a number of reasons. It could be because of a slow connection between

589 -the master and slave nodes, but it could also be due to other failures. Look in your master's `error.log` for errors

594 +the parent and child nodes, but it could also be due to other failures. Look in your parent's `error.log` for errors

595 that look like this:

596

597 ```

593 -STREAM [receive from [SLAVE HOSTNAME]:SLAVE IP]: `MESSAGE`. Forbidding access."

598 +STREAM [receive from [child HOSTNAME]:child IP]: `MESSAGE`. Forbidding access."

599 ```

600

601 `MESSAGE` will have one of the following patterns:

602

603 - `request without KEY` : The message received is incomplete and the KEY value can be API, hostname, machine GUID.

599 -- `API key 'VALUE' is not valid GUID`: The UUID received from slave does not have the format defined in [RFC 4122]

604 +- `API key 'VALUE' is not valid GUID`: The UUID received from child does not have the format defined in [RFC 4122]

605 (https://tools.ietf.org/html/rfc4122)

606 - `machine GUID 'VALUE' is not GUID.`: This error with machine GUID is like the previous one.

607 - `API key 'VALUE' is not allowed`: This stream has a wrong API key.

603 -- `API key 'VALUE' is not permitted from this IP`: The IP is not allowed to use STREAM with this master.

608 +- `API key 'VALUE' is not permitted from this IP`: The IP is not allowed to use STREAM with this parent.

609 - `machine GUID 'VALUE' is not allowed.`: The GUID that is trying to send stream is not allowed.

610 - `Machine GUID 'VALUE' is not permitted from this IP. `: The IP does not match the pattern or IP allowed to connect

611 to use stream.

612

613 ### Netdata could not create a stream

614

610 -The connection between master and slave is a stream. When the master can't convert the initial connection into a stream,

611 -it will write the following message inside `error.log`:

615 +The connection between parent and child is a stream. When the parent can't convert the initial connection into

616 +a stream, it will write the following message inside `error.log`:

617

618 ```

619 file descriptor given is not a valid stream

web/server/README.md

+9 -8

@@ -48,7 +48,7 @@ Using the above, Netdata will bind to:

48 - 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.

49 - IPv4 10.1.1.1 at port 19998. The management API and `netdata.conf` will be accessible on this port.

50 - 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.

51 -- 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. slaves also need to be [configured for TLS](/streaming/README.md).

51 +- 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](/streaming/README.md).

52 - 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.

53 - 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.

54 - 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.

@@ -67,7 +67,8 @@ The API requests are serviced as follows:

68 ### Enabling TLS support

70 -Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data between a slave and its master, via the TLS protocol.

70 +Since v1.16.0, Netdata supports encrypted HTTP connections to the web server, plus encryption of streaming data to a

71 +parent from its child nodes, via the TLS protocol.

73 Inbound unix socket connections are unaffected, regardless of the TLS settings.

@@ -84,7 +85,7 @@ To enable TLS, provide the path to your certificate and private key in the `[web

85 ssl certificate = /etc/netdata/ssl/cert.pem

86 ```

87 -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 master/slave connection, only the master needs these settings.

88 +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.

90 For test purposes, you can generate self-signed certificates with the following command:

@@ -119,7 +120,7 @@ While Netdata accepts all the TLS version as arguments (`1` or `1.0`, `1.1`, `1.

120 When the certificates are defined and unless any other options are provided, a Netdata server will:

121

122 - Redirect all incoming HTTP web server requests to HTTPS. Applies to the dashboard, the API, `netdata.conf` and badges.

122 -- Allow incoming slave connections to use both unencrypted and encrypted communications for streaming.

123 +- Allow incoming child connections to use both unencrypted and encrypted communications for streaming.

124

125 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, you can 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.

126

@@ -136,7 +137,7 @@ Example:

138 ```

139

139 -For information how to configure the slaves to use TLS, check [securing the communication](/streaming/README.md#securing-streaming-communications) 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.

140 +For information how to configure the child to use TLS, check [securing the communication](/streaming/README.md#securing-streaming-communications) 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.

141

142 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:

143

@@ -148,7 +149,7 @@ When we define the use of SSL in a Netdata agent for different ports, Netdata w

149 Netdata will:

150

151 - Force all HTTP requests to the default port to be redirected to HTTPS (same port).

151 -- Refuse unencrypted streaming connections from slaves on the default port.

152 +- Refuse unencrypted streaming connections from child nodes on the default port.

153 - Allow both HTTP and HTTPS requests to port 20000 for `netdata.conf`

154 - Force HTTP requests to port 20001 to be redirected to HTTPS (same port). Only allow requests for the dashboard, the read API and the registry on port 20001.

155

@@ -185,7 +186,7 @@ Netdata supports access lists in `netdata.conf`:

186

187 - `allow badges from` checks if the API request is for a badge. Badges are not matched by `allow dashboard from`.

188

188 -- `allow streaming from` checks if the slave willing to stream metrics to this Netdata is allowed.

189 +- `allow streaming from` checks if the child willing to stream metrics to this Netdata is allowed.

190 This can be controlled per API KEY and MACHINE GUID in `stream.conf`.

191 The setting in `netdata.conf` is checked before the ones in `stream.conf`.

192

@@ -225,7 +226,7 @@ present that may match DNS FQDNs.

226 |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.|

227 |disconnect idle clients after seconds|`60`|The time in seconds to disconnect web clients after being totally idle.|

228 |timeout for first request|`60`|How long to wait for a client to send a request before closing the socket. Prevents slow request attacks.|

228 -|accept a streaming request every seconds|`0`|Can be used to set a limit on how often a master Netdata server will accept streaming requests from the slaves in a [streaming and replication setup](/streaming/README.md)|

229 +|accept a streaming request every seconds|`0`|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](/streaming/README.md)|

230 |respect do not track policy|`no`|If set to `yes`, will respect the client's browser preferences on storing cookies.|

231 |x-frame-options response header||[Avoid clickjacking attacks, by ensuring that the content is not embedded into other sites](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options).|

232 |enable gzip compression|`yes`|When set to `yes`, Netdata web responses will be GZIP compressed, if the web client accepts such responses.|