Improve configuration docs with common changes and start/stop/restart directions (#10415)
* Finish new common config doc, delete old one * Small tweak to blockquote * Add new files * Fix broken links * Fix one more broken link * Copyedits and improvements * Fix broken link * Re-add common config doc * service -> systemctl * Reverse systemctl order * Add mention of .conf files in health.d * Add mention of minimum global update every
Joel Hans committed
Jan 4, 2021 at 10:49 UTC
8d11dad2a85505a7563eb164a0be7aedae6b9589
8 files changed
+392
-248
daemon/config/README.md
+2
-1
@@ -67,7 +67,8 @@ Please note that your data history will be lost if you have modified `history` p
67
| 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.|||
68
| memory mode | `dbengine` | `dbengine`: The default for long-term metrics storage with efficient RAM and disk usage. Can be extended with `page cache size` and `dbengine disk space`. <br />`save`: Netdata will save its round robin database on exit and load it on startup. <br />`map`: Cache files will be updated in real-time. Not ideal for systems with high load or slow disks (check `man mmap`). <br />`ram`: The round-robin database will be temporary and it will be lost when Netdata exits. <br />`none`: Disables the database at this host, and disables health monitoring entirely, as that requires a database of metrics. |
69
| page cache size | 32 | Determines the amount of RAM in MiB that is dedicated to caching Netdata metric values. |||
70
-| dbengine disk space | 256 | Determines the amount of disk space in MiB that is dedicated to storing Netdata metric values and all related metadata describing them |||
70
+| dbengine disk space | 256 | Determines the amount of disk space in MiB that is dedicated to storing Netdata metric values and all related metadata describing them. |||
71
+| dbengine multihost disk space | 256 | Same functionality as `dbengine disk space`, but includes support for storing metrics streamed to a parent node by its children. Can be used in single-node environments as well. |||
72
| 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).|
73
| 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/README.md#ksm)|||
74
| TZ environment variable|`:/etc/localtime`|Where to find the timezone|||
docs/configuration-guide.md
deleted
-213
@@ -1,213 +0,0 @@
1
-<!--
2
----
3
-title: "Configuration guide"
4
-custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configuration-guide.md
5
----
6
--->
7
-
8
-# Configuration guide
9
-
10
-No configuration is required to run Netdata, but you will find plenty of options to tweak, so that you can adapt it to
11
-your particular needs.
12
-
13
-<details markdown="1"><summary>Configuration files are placed in `/etc/netdata`.</summary>
14
-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>
15
-
16
-Under that directory you will see the following:
17
-
18
-- `netdata.conf` is [the main configuration file](/daemon/config/README.md#daemon-configuration)
19
-- `edit-config` is an sh script that you can use to easily and safely edit the configuration. Just run it to see its
20
- usage.
21
-- Other directories, initially empty, where your custom configurations for alarms and collector plugins/modules will
22
- be copied from the stock configuration, if and when you customize them using `edit-config`.
23
-- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains the stock configurations for
24
- everything not included in `netdata.conf`:
25
- - `health_alarm_notify.conf` is where you configure how and to who Netdata will send [alarm
26
- notifications](/health/notifications/README.md#netdata-alarm-notifications).
27
- - `health.d` is the directory that contains the alarm triggers for [health
28
- monitoring](/health/README.md#health-monitoring). It contains one .conf file per collector.
29
- - The [modular plugin orchestrators](/collectors/plugins.d/README.md#external-plugins-overview) have:
30
- - One config file each, mainly to turn their modules on and off: `python.d.conf` for
31
- [python](/collectors/python.d.plugin/README.md#pythondplugin), `node.d.conf` for
32
- [nodejs](/collectors/node.d.plugin/README.md#nodedplugin) and `charts.d.conf` for
33
- [bash](/collectors/charts.d.plugin/README.md#chartsdplugin) modules.
34
- - One directory each, where the module-specific configuration files can be found.
35
- - `stream.conf` is where you configure [streaming and
36
- replication](/streaming/README.md#streaming-and-replication)
37
- - `stats.d` is a directory under which you can add .conf files to add [synthetic
38
- charts](/collectors/statsd.plugin/README.md#synthetic-statsd-charts).
39
- - Individual collector plugin config files, such as `fping.conf` for the [fping
40
- plugin](/collectors/fping.plugin/) and `apps_groups.conf` for the [apps plugin](/collectors/apps.plugin/)
41
-
42
-So there are many configuration files to control every aspect of Netdata's behavior. It can be overwhelming at first,
43
-but you won't have to deal with any of them, unless you have specific things you need to change. The following HOWTO
44
-will guide you on how to customize your Netdata, based on what you want to do.
45
-
46
-## How to
47
-
48
-### Persist my configuration
49
-
50
-In `http://localhost:19999/netdata.conf`, you will see the following two parameters:
51
-
52
-```bash
53
- # config directory = /etc/netdata
54
- # stock config directory = /usr/lib/netdata/conf.d
55
-```
56
-
57
-To persist your configurations, don't edit the files under the `stock config directory` directly. Use the `sudo [config
58
-directory]/edit-config` command, or copy the stock config file to its proper place under the `config directory` and edit
59
-it there.
60
-
61
-### Change what I see
62
-
63
-#### Increase the long-term metrics retention period
64
-
65
-Increase the values for the `page cache size` and `dbengine disk space` settings in the [`[global]`
66
-section](/daemon/config/README.md#global-section-options) of `netdata.conf`. Read our guide on [increasing
67
-long-term metrics storage](/docs/guides/longer-metrics-storage.md) and the [memory requirements for the database
68
-engine](/database/engine/README.md#memory-requirements).
69
-
70
-#### Reduce the data collection frequency
71
-
72
-Increase `update every` in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options). This is another
73
-way to increase your metrics retention period, but at a lower resolution than the default 1s.
74
-
75
-#### Modify how a chart is displayed
76
-
77
-In `netdata.conf` under `# Per chart configuration` you will find several [\[CHART_NAME\]
78
-sections](/daemon/config/README.md#per-chart-configuration), where you can control all aspects of a specific chart.
79
-
80
-#### Disable a collector
81
-
82
-Entire plugins can be turned off from the [netdata.conf \[plugins\]](/daemon/config/README.md#plugins-section-options)
83
-section. To disable specific modules of a plugin orchestrator, you need to edit one of the following:
84
-
85
-- `python.d.conf` for [python](/collectors/python.d.plugin/README.md)
86
-- `node.d.conf` for [nodejs](/collectors/node.d.plugin/README.md)
87
-- `charts.d.conf` for [bash](/collectors/charts.d.plugin/README.md)
88
-
89
-#### Show charts with zero metrics
90
-
91
-By default, Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they
92
-are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected
93
-and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear
94
-though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also
95
-set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all
96
-internal Netdata plugins.
97
-
98
-### Modify alarms and notifications
99
-
100
-#### Add a new alarm
101
-
102
-You can add a new alarm definition either by editing an existing stock alarm config file under `health.d` (e.g.
103
-`/etc/netdata/edit-config health.d/load.conf`), or by adding a new `.conf` file under `/etc/netdata/health.d`. The
104
-documentation on how to define an alarm is in [health monitoring](/health/README.md). It is
105
-suggested to look at some of the stock alarm definitions, so you can ensure you understand how the various options work.
106
-
107
-#### Turn off all alarms and notifications
108
-
109
-Just set `enabled = no` in the [netdata.conf \[health\]](/daemon/config/README.md#health-section-options) section
110
-
111
-#### Modify or disable a specific alarm
112
-
113
-The `health.d` directory that contains the alarm triggers for [health monitoring](/health/README.md). It has
114
-one .conf file per collector. You can easily find the .conf file you will need to modify, by looking for the "source"
115
-line on the table that appears on the right side of an alarm on the Netdata gui.
116
-
117
-For example, if you click on Alarms and go to the tab 'All', the default Netdata installation will show you at the top
118
-the configured alarm for `10 min cpu usage` (it's the name of the badge). Looking at the table on the right side, you
119
-will see a row that says: `source 4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. This way, you know that you will need
120
-to run `/etc/netdata/edit-config health.d/cpu.conf` and look for alarm at line 4 of the conf file.
121
-
122
-As stated at the top of the .conf file, **you can disable an alarm notification by setting the 'to' line to: silent**.
123
-To modify how the alarm gets triggered, we suggest that you go through the guide on [health
124
-monitoring](/health/README.md#health-monitoring).
125
-
126
-#### Receive notifications using my preferred method
127
-
128
-You only need to configure `health_alarm_notify.conf`. To learn how to do it, read first [alarm
129
-notifications](/health/notifications/README.md#netdata-alarm-notifications) and then open the submenu `Supported
130
-Notifications` under `Alarm notifications` in the documentation to find the specific page on your preferred notification
131
-method.
132
-
133
-### Make security-related customizations
134
-
135
-#### Change the Netdata web server access lists
136
-
137
-You have several options under the [netdata.conf \[web\]](/web/server/README.md#access-lists) section.
138
-
139
-#### Stop sending info to registry.my-netdata.io
140
-
141
-You will need to configure the `[registry]` section in `netdata.conf`. First read the [registry
142
-documentation](/registry/). In it, are instructions on how to [run your own
143
-registry](/registry/README.md#run-your-own-registry).
144
-
145
-#### Change the IP address/port Netdata listens to
146
-
147
-The settings are under the `[web]` section. Look at the [web server
148
-documentation](/web/server/README.md#binding-netdata-to-multiple-ports) for more info.
149
-
150
-### System resource usage
151
-
152
-#### Reduce the resources Netdata uses
153
-
154
-The [Netdata performance guide](/docs/guides/configure/performance.md) outlines many ways to reduce the Netdata
155
-CPU/disk/RAM utilization to levels suitable even for the weakest [IoT devices](/docs/netdata-for-IoT.md).
156
-
157
-#### Change when Netdata saves metrics to disk
158
-
159
-[netdata.conf \[global\]](/daemon/config/README.md#global-section-options): `memory mode`
160
-
161
-#### Prevent Netdata from getting immediately killed when my server runs out of memory
162
-
163
-You can change the Netdata [OOM score](/daemon/README.md#oom-score) in `[global]`.
164
-
165
-### Other
166
-
167
-#### Move Netdata directories
168
-
169
-The various directory paths are in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options).
170
-
171
-## How Netdata configuration works
172
-
173
-The configuration files are `name = value` dictionaries with `[sections]`. Write whatever you like there as long as it
174
-follows this simple format.
175
-
176
-Netdata loads this dictionary and then when the code needs a value from it, it just looks up the `name` in the
177
-dictionary at the proper `section`. In all places, in the code, there are both the `names` and their `default values`,
178
-so if something is not found in the configuration file, the default is used. The lookup is made using B-Trees and hashes
179
-(no string comparisons), so they are super fast. Also the `names` of the settings can be `my super duper setting that
180
-once set to yes, will turn the world upside down = no` - so goodbye to most of the documentation involved.
181
-
182
-Next, Netdata can generate a valid configuration for the user to edit. No need to remember anything. Just get the
183
-configuration from the server (`/netdata.conf` on your Netdata server), edit it and save it.
184
-
185
-Last, what about options you believe you have set, but you misspelled?When you get the configuration file from the
186
-server, there will be a comment above all `name = value` pairs the server does not use. So you know that whatever you
187
-wrote there, is not used.
188
-
189
-## Netdata simple patterns
190
-
191
-Unix prefers regular expressions. But they are just too hard, too cryptic to use, write and understand.
192
-
193
-So, Netdata supports [simple patterns](/libnetdata/simple_pattern/README.md).
194
-
195
-## Netdata labels
196
-
197
-Beginning with 1.20, Netdata accepts user-defined **host labels**. These labels are defined in the section `[host
198
-labels]`.
199
-
200
-Read more about how these labels work and why they're an effective way to organize complex infrasturctures in our
201
-guide: [Use host labels to organize systems, metrics, and alarms](/docs/guides/using-host-labels.md).
202
-
203
-To define a label inside this section, some rules needs to be followed, or Netdata will reject the label. The following
204
-restrictions are applied for label names:
205
-
206
-- Names cannot start with `_`, but it can be present in other parts of the name.
207
-- Names only accept alphabet letters, numbers, dots, and dashes.
208
-
209
-The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes
210
-(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alarms and
211
-templates.
212
-
213
-[](<>)
docs/configure/common-changes.md
new
+204
@@ -0,0 +1,204 @@
1
+<!--
2
+title: "Common configuration changes"
3
+description: "See the most popular configuration changes to make to the Netdata Agent, including longer metrics retention, reduce sampling, and more."
4
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/common-changes.md
5
+-->
6
+
7
+# Common configuration changes
8
+
9
+The Netdata Agent requires no configuration upon installation to collect thousands of per-second metrics from most
10
+systems, containers, and applications, but there are hundreds of settings to tweak if you want to exercise more control
11
+over your monitoring platform.
12
+
13
+This document assumes familiarity with using [`edit-config`](/docs/configure/nodes.md) from the Netdata config
14
+directory.
15
+
16
+## Change dashboards and visualizations
17
+
18
+The Netdata Agent's [local dashboard](/web/gui/README.md), accessible at `http://NODE:19999` is highly configurable. If
19
+you use Netdata Cloud for [infrastructure monitoring](/docs/quickstart/infrastructure.md), you will see many of these
20
+changes reflected in those visualizations due to the way Netdata Cloud proxies metric data and metadata to your browser.
21
+
22
+### Increase the long-term metrics retention period
23
+
24
+Increase the values for the `page cache size` and `dbengine multihost disk space` settings in the [`[global]`
25
+section](/daemon/config/README.md#global-section-options) of `netdata.conf`.
26
+
27
+```conf
28
+[global]
29
+ page cache size = 128 # 128 MiB of memory for metrics storage
30
+ dbengine multihost disk space = 4096 # 4GiB of disk space for metrics storage
31
+```
32
+
33
+Read our doc on [increasing long-term metrics storage](/docs/store/change-metrics-storage.md) for details, including a
34
+[calculator](/docs/store/change-metrics-storage.md#calculate-the-system-resources-RAM-disk-space-needed-to-store-metrics)
35
+to help you determine the exact settings for your desired retention period.
36
+
37
+### Reduce the data collection frequency
38
+
39
+Change `update every` in the [`[global]` section](/daemon/config/README.md#global-section-options) of `netdata.conf` so
40
+that it is greater than `1`. An `update every` of `5` means the Netdata Agent enforces a _minimum_ collection frequency
41
+of 5 seconds.
42
+
43
+```conf
44
+[global]
45
+ update every = 5
46
+```
47
+
48
+Every collector and plugin has its own `update every` setting, which you can also change in the `go.d.conf`,
49
+`python.d.conf`, `node.d.conf`, or `charts.d.conf` files, or in individual collector configuration files. If the `update
50
+every` for an individual collector is less than the global, the Netdata Agent uses the global setting. See the [enable
51
+or configure a collector](/docs/collect/enable-configure.md) doc for details.
52
+
53
+### Disable a collector or plugin
54
+
55
+Turn off entire plugins in the [`[plugins]` section](/daemon/config/README.md#plugins-section-options) of
56
+`netdata.conf`.
57
+
58
+To disable specific collectors, open `go.d.conf`, `python.d.conf`, `node.d.conf`, or `charts.d.conf` and find the line
59
+for that specific module. Uncomment the line and change its value to `no`.
60
+
61
+## Modify alarms and notifications
62
+
63
+Netdata's health monitoring watchdog uses hundreds of preconfigured health entities, with intelligent thresholds, to
64
+generate warning and critical alarms for most production systems and their applications without configuration. However,
65
+each alarm and notification method is completely customizable.
66
+
67
+### Add a new alarm
68
+
69
+To create a new alarm configuration file, initiate an empty file, with a filename that ends in `.conf`, in the
70
+`health.d/` directory. The Netdata Agent loads any valid alarm configuration file ending in `.conf` in that directory.
71
+Next, edit the new file with `edit-config`. For example, with a file called `ram-usage.conf`.
72
+
73
+```bash
74
+sudo touch health.d/ram-usage.conf
75
+sudo ./edit-config health.d/ram-usage.conf
76
+```
77
+
78
+Or, append your new alarm to an existing file by editing a relevant existing file in the `health.d/` directory.
79
+
80
+Read more about [configuring alarms](/docs/monitor/configure-alarms.md) to get started, and see the [health monitoring
81
+reference](/health/REFERENCE.md) for a full listing of options available in health entities.
82
+
83
+### Configure a specific alarm
84
+
85
+Tweak existing alarms by editing files in the `health.d/` directory. For example, edit `health.d/cpu.conf` to change how
86
+the Agent responds to anomalies related to CPU utilization.
87
+
88
+To see which configuration file you need to edit to configure a specific alarm, [view your active
89
+alarms](/docs/monitor/view-active-alarms.md) in Netdata Cloud or the local Agent dashboard and look for the **source**
90
+line. For example, it might read `source 4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. Because the source path contains
91
+`health.d/cpu.conf`, you now you that you should run `sudo edit-config health.d/cpu.conf` to configure that alarm.
92
+
93
+### Disable a specific alarm
94
+
95
+Open the configuration file for that alarm and set the `to` line to `silent`.
96
+
97
+### Turn of all alarms and notifications
98
+
99
+Set `enabled` to `no` in the [`[health]` section](/daemon/config/README.md#health-section-options) section of
100
+`netdata.conf`.
101
+
102
+### Enable alarm notifications
103
+
104
+Open `health_alarm_notify.conf` for editing. First, read the [enabling
105
+notifications](/docs/monitor/enable-notifications.md#netdata-agent) doc for an example of the process using Slack, then
106
+click on the link to your preferred notification method to find documentation for that specific endpoint.
107
+
108
+## Improve node security
109
+
110
+While the Netdata Agent is both [open and secure by design](https://www.netdata.cloud/blog/netdata-agent-dashboard/), we
111
+recommend every user take some action to administer and secure their nodes.
112
+
113
+Learn more about a few of the following changes in the [node security doc](/docs/configure/secure-nodes.md).
114
+
115
+### Disable the local Agent dashboard (`http://NODE:19999`)
116
+
117
+If you use Netdata Cloud to visualize metrics, stream metrics to a parent node, or otherwise don't need the local Agent
118
+dashboard, disabling it reduces the Agent's resource utilization and improves security.
119
+
120
+Change the `mode` setting to `none` in the [`[web]` section](/web/server/README.md#configuration) of `netdata.conf`.
121
+
122
+```conf
123
+[web]
124
+ mode = none
125
+```
126
+
127
+### Use access lists to restrict access to specific assets
128
+
129
+Allow access from only specific IP addresses, ranges of IP addresses, or hostnames using [access
130
+lists](/web/server/README.md#access-lists) and [simple patterns](/libnetdata/simple_pattern/README.md).
131
+
132
+See a quickstart to access lists in the [node security
133
+doc](/docs/configure/secure-nodes.md#restrict-access-to-the-local-dashboard).
134
+
135
+### Stop sending anonymous statistics to Google Analytics
136
+
137
+Create a file called `.opt-out-from-anonymous-statistics` inside of your Netdata config directory to immediately stop
138
+the statistics script.
139
+
140
+```bash
141
+sudo touch .opt-out-from-anonymous-statistics
142
+```
143
+
144
+Learn more about [why we collect anonymous statistics](/docs/anonymous-statistics.md).
145
+
146
+### Change the IP address/port Netdata listens to
147
+
148
+Change the `default port` setting in the `[web]` section to a port other than `19999`.
149
+
150
+```conf
151
+[web]
152
+ default port = 39999
153
+```
154
+
155
+Use the `bind to` setting to the ports other assets, such as the [running `netdata.conf`
156
+configuration](/docs/configure/nodes.md#see-an-agents-running-configuration), API, or streaming requests listen to.
157
+
158
+## Reduce resource usage
159
+
160
+Read our [performance optimization guide](/docs/guides/configure/performance.md) for a long list of specific changes
161
+that can reduce the Netdata Agent's CPU/memory footprint and IO requirements.
162
+
163
+## Organize nodes with host labels
164
+
165
+Beginning with v1.20, Netdata accepts user-defined **host labels**. These labels are sent during streaming, exporting,
166
+and as metadata to Netdata Cloud, and help you organize the metrics coming from complex infrastructure. Host labels are
167
+defined in the section `[host labels]`.
168
+
169
+For a quick introduction, read the [host label guide](/docs/guides/using-host-labels.md).
170
+
171
+The following restrictions apply to host label names:
172
+
173
+- Names cannot start with `_`, but it can be present in other parts of the name.
174
+- Names only accept alphabet letters, numbers, dots, and dashes.
175
+
176
+The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes
177
+(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alarms and
178
+templates.
179
+
180
+## What's next?
181
+
182
+If you haven't already, learn how to [secure your nodes](/docs/configure/secure-nodes.md).
183
+
184
+As mentioned at the top, there are plenty of other
185
+
186
+You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features:
187
+
188
+- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
189
+- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
190
+- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your
191
+ infrastructure.
192
+- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
193
+
194
+### Related reference documentation
195
+
196
+- [Netdata Agent · Daemon](/health/README.md)
197
+- [Netdata Agent · Daemon configuration](/daemon/config/README.md)
198
+- [Netdata Agent · Web server](/web/server/README.md)
199
+- [Netdata Agent · Local Agent dashboard](/web/gui/README.md)
200
+- [Netdata Agent · Health monitoring](/health/REFERENCE.md)
201
+- [Netdata Agent · Notifications](/health/notifications/README.md)
202
+- [Netdata Agent · Simple patterns](/libnetdata/simple_pattern/README.md)
203
+
204
+[](<>)
docs/configure/nodes.md
+69
-24
@@ -14,7 +14,7 @@ For example, you might want to increase metrics retention, configure a collector
14
setup, or secure the local dashboard by restricting it to only connections from `localhost`.
15
16
Whatever the reason, Netdata users should know how to configure individual nodes to act decisively if an incident,
17
-anomaly, or change in infrastructure affects how their Agents should peform.
17
+anomaly, or change in infrastructure affects how their Agents should perform.
18
19
## The Netdata config directory
20
@@ -31,20 +31,36 @@ scripts from inside that directory.
31
32
## Netdata's configuration files
33
34
-Upon installation, the Netdata config directory contains a few files and directories.
35
-
36
-- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. This doc won't
37
- go into exhaustive detail about each setting. You can read descriptions for each in the [daemon config
38
- doc](/daemon/config/README.md).
39
-- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files.
40
- Stock versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in
41
- `/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._
42
-- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-netdataconf).
43
-- `go.d/`, `python.d/`, `charts.d/`, `node.d`/, and `custom-plugins.d/`, which are directories for each of Netdata's
44
- [orchestrators](/collectors/plugins.d/README.md). These directories can each contain additional `.conf` files for
45
- configuring specific collectors.
46
-
47
-## Use `edit-config` to edit `netdata.conf`
34
+Upon installation, the Netdata config directory contains a few files and directories. It's okay if you don't see all
35
+these files in your own Netdata config directory, as the next section describes how to edit any that might not already
36
+exist.
37
+
38
+- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. Read descriptions
39
+ for each in the [daemon config](/daemon/config/README.md) doc.
40
+- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-configuration-files).
41
+- Various configuration files ending in `.conf` for [configuring plugins or
42
+ collectors](/docs/collect/enable-configure.md#enable-a-collector-or-its-orchestrator) behave. Examples: `go.d.conf`,
43
+ `python.d.conf`, and `ebpf.conf`.
44
+- Various directories ending in `.d`, which contain other configuration files, each ending in `.conf`, for [configuring
45
+ specific collectors](/docs/collect/enable-configure.md#configure-a-collector).
46
+- `apps_groups.conf` is a configuration file for changing how applications/processes are grouped when viewing the
47
+ **Application** charts from [`apps.plugin`](/collectors/apps.plugin/README.md) or
48
+ [`ebpf.plugin`](/collectors/ebpf.plugin/README.md).
49
+- `health.d/` is a directory that contains [health configuration files](/docs/monitor/configure-alarms.md).
50
+- `health_alarm_notify.conf` enables and configures [alarm notifications](/docs/monitor/enable-notifications.md).
51
+- `statsd.d/` is a directory for configuring Netdata's [statsd collector](/collectors/statsd.plugin/README.md).
52
+- `stream.conf` configures [parent-child streaming](/streaming/README.md) between separate nodes running the Agent.
53
+- `.environment` is a hidden file that describes the environment in which the Netdata Agent is installed, including the
54
+ `PATH` and any installation options. Useful for [reinstalling](/packaging/installer/REINSTALL.md) or
55
+ [uninstalling](/packaging/installer/UNINSTALL.md) the Agent.
56
+
57
+The Netdata config directory also contains one symlink:
58
+
59
+- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files. Stock
60
+ versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in
61
+ `/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._
62
+
63
+## Use `edit-config` to edit configuration files
64
65
The **recommended way to easily and safely edit Netdata's configuration** is with the `edit-config` script. This script
66
opens existing Netdata configuration files using your system's `$EDITOR`. If the file doesn't yet exist in your config
@@ -79,11 +95,11 @@ To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevat
95
method for `edit-config` to write into the config directory. Use your `$EDITOR`, make your changes, and save the file.
96
97
> `edit-config` uses the `EDITOR` environment variable on your system to edit the file. On many systems, that is
82
-> defaulted to `vim` or `nano`. To change this variable for the current session (it will revert to the default when you
83
-> reboot), export a new value: `export EDITOR=nano`. Or, [make the change
84
-> permanent](https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux).
98
+> defaulted to `vim` or `nano`. Use `export EDITOR=` to change this temporarily, or edit your shell configuration file
99
+> to change to permanently.
100
86
-After you make your changes, you need to restart the Agent with `service netdata restart`.
101
+After you make your changes, you need to [restart the Agent](/docs/configure/start-stop-restart.md) with `sudo systemctl
102
+restart netdata` or the appropriate method for your system.
103
104
Here's an example of editing the node's hostname, which appears in both the local dashboard and in Netdata Cloud.
105
@@ -103,13 +119,36 @@ You can edit any Netdata configuration file using `edit-config`. A few examples:
119
120
The documentation for each of Netdata's components explains which file(s) to edit to achieve the desired behavior.
121
122
+## See an Agent's running configuration
123
+
124
+On start, the Netdata Agent daemon attempts to load `netdata.conf`. If that file is missing, incomplete, or contains
125
+invalid settings, the daemon attempts to run sane defaults instead. In other words, the state of `netdata.conf` on your
126
+filesystem may be different from the state of the Netdata Agent itself.
127
+
128
+To see the _running configuration_, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with
129
+the IP address or hostname of your node. The file displayed here is exactly the settings running live in the Netdata
130
+Agent.
131
+
132
+If you're having issues with configuring the Agent, apply the running configuration to `netdata.conf` by downloading the
133
+file to the Netdata config directory. Use `sudo` to elevate privileges.
134
+
135
+```bash
136
+wget -O /etc/netdata/netdata.conf http://localhost:19999/netdata.conf
137
+# or
138
+curl -o /etc/netdata/netdata.conf http://NODE:19999/netdata.conf
139
+```
140
+
141
## What's next?
142
108
-Take advantage of this newfound understanding of node configuration to [add security to your
109
-node](/docs/configure/secure-nodes.md). We have a few best practices based on how you use the Netdata Agent and Netdata
110
-Cloud.
143
+Learn more about [starting, stopping, or restarting](/docs/configure/start-stop-restart.md) the Netdata daemon to apply
144
+configuration changes.
145
+
146
+Apply some [common configuration changes](/docs/configure/common-changes.md) to quickly tweak the Agent's behavior.
147
112
-You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features:
148
+[Add security to your node](/docs/configure/secure-nodes.md) with what you've learned about the Netdata config directory
149
+and `edit-config`. We put together a few security best practices based on how you use the Netdata.
150
+
151
+You can also take what you've learned about node configuration to enable or enhance features:
152
153
- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
154
- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
@@ -117,4 +156,10 @@ You can also take what you've learned about node configuration to tweak the Agen
156
infrastructure.
157
- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
158
120
-[](<>)
159
+### Related reference documentation
160
+
161
+- [Netdata Agent · Daemon](/health/README.md)
162
+- [Netdata Agent · Health monitoring](/health/README.md)
163
+- [Netdata Agent · Notifications](/health/notifications/README.md)
164
+
165
+[](<>)
docs/configure/secure-nodes.md
+6
-3
@@ -50,8 +50,9 @@ static-threaded` setting, and change it to `none`.
50
mode = none
51
```
52
53
-Save and close the editor, then restart your Agent using `service netdata restart`. If you try to visit the local
54
-dashboard to `http://NODE:19999` again, the connection will fail because that node no longer serves its local dashboard.
53
+Save and close the editor, then [restart your Agent](/docs/configure/start-stop-restart.md) using `sudo systemctl
54
+restart netdata`. If you try to visit the local dashboard to `http://NODE:19999` again, the connection will fail because
55
+that node no longer serves its local dashboard.
56
57
> See the [configuration basics doc](/docs/configure/nodes.md) for details on how to find `netdata.conf` and use
58
> `edit-config`.
@@ -112,7 +113,9 @@ We also have guides for [Apache](/docs/Running-behind-apache.md), [Lighttpd](/do
113
114
## What's next?
115
115
-If you haven't already, be sure to read about [Netdata's security design](/docs/netdata-security.md).
116
+Read about [Netdata's security design](/docs/netdata-security.md) and our [blog
117
+post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) about why the local Agent dashboard is both open and
118
+secure by design.
119
120
Next up, learn about [collectors](/docs/collect/how-collectors-work.md) to ensure you're gathering every essential
121
metric about your node, its applications, and your infrastructure at large.
docs/configure/start-stop-restart.md
new
+98
@@ -0,0 +1,98 @@
1
+<!--
2
+title: "Start, stop, or restart the Netdata Agent"
3
+description: "Manage the Netdata Agent daemon, load configuration changes, and troubleshoot stuck processes on systemd and non-systemd nodes."
4
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/start-stop-restart.md
5
+-->
6
+
7
+# Start, stop, or restart the Netdata Agent
8
+
9
+When you install the Netdata Agent, the [daemon](/daemon/README.md) is configured to start at boot and stop and
10
+restart/shutdown.
11
+
12
+You will most often need to _restart_ the Agent to load new or editing configuration files. [Health
13
+configuration](#reload-health-configuration) files are the only exception, as they can be reloaded without restarting
14
+the entire Agent.
15
+
16
+Stopping or restarting the Netdata Agent will cause gaps in stored metrics until the `netdata` process initiates
17
+collectors and the database engine.
18
+
19
+## Using `systemctl`, `service`, or `init.d`
20
+
21
+This is the recommended way to start, stop, or restart the Netdata daemon.
22
+
23
+- To **start** Netdata, run `sudo systemctl start netdata`.
24
+- To **stop** Netdata, run `sudo systemctl stop netdata`.
25
+- To **restart** Netdata, run `sudo systemctl restart netdata`.
26
+
27
+If the above commands fail, or you know that you're using a non-systemd system, try using the `service` command:
28
+
29
+- **service**: `sudo service netdata start`, `sudo service netdata stop`, `sudo service netdata restart`
30
+
31
+## Using `netdata`
32
+
33
+Use the `netdata` command, typically located at `/usr/sbin/netdata`, to start the Netdata daemon.
34
+
35
+```bash
36
+sudo netdata
37
+```
38
+
39
+If you start the daemon this way, close it with `sudo killall netdata`.
40
+
41
+## Using `netdatacli`
42
+
43
+The Netdata Agent also comes with a [CLI tool](/cli/README.md) capable of performing shutdowns. Start the Agent back up
44
+using your preferred method listed above.
45
+
46
+```bash
47
+sudo netdatacli shutdown-agent
48
+```
49
+
50
+## Reload health configuration
51
+
52
+You do not need to restart the Netdata Agent between changes to health configuration files, such as specific health
53
+entities. Instead, use [`netdatacli`](#using-netdatacli) and the `reload-health` option to prevent gaps in metrics
54
+collection.
55
+
56
+```bash
57
+sudo netdatacli reload-health
58
+```
59
+
60
+If `netdatacli` doesn't work on your system, send a `SIGUSR2` signal to the daemon, which reloads health configuration
61
+without restarting the entire process.
62
+
63
+```bash
64
+killall -USR2 netdata
65
+```
66
+
67
+## Force stop stalled or unresponsive `netdata` processes
68
+
69
+In rare cases, the Netdata Agent may stall or not properly close sockets, preventing a new process from starting. In
70
+these cases, try the following three commands:
71
+
72
+```bash
73
+sudo systemctl stop netdata
74
+sudo killall netdata
75
+ps aux| grep netdata
76
+```
77
+
78
+The output of `ps aux` should show no `netdata` or associated processes running. You can now start the Netdata Agent
79
+again with `service netdata start`, or the appropriate method for your system.
80
+
81
+## What's next?
82
+
83
+Learn more about [securing the Netdata Agent](/docs/configure/secure-nodes.md).
84
+
85
+You can also use the restart/reload methods described above to enable new features:
86
+
87
+- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior.
88
+- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones.
89
+- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your
90
+ infrastructure.
91
+- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine.
92
+
93
+### Related reference documentation
94
+
95
+- [Netdata Agent · Daemon](/daemon/README.md)
96
+- [Netdata Agent · Netdata CLI](/cli/README.md)
97
+
98
+[](<>)
docs/guides/configure/performance.md
+11
-5
@@ -54,20 +54,26 @@ The fastest way to improve the Agent's resource utilization is to reduce how oft
54
55
## Global
56
57
-If you don't need per-second metrics, or if the Agent uses a lot of CPU even when no one is viewing that node's
57
+If you don't need per-second metrics, or if the Netdata Agent uses a lot of CPU even when no one is viewing that node's
58
dashboard, configure the Agent to collect metrics less often.
59
60
-Open `netdata.conf` and edit the `update every` setting. The default is `1`, meaning that the Agent updates every
61
-second.
60
+Open `netdata.conf` and edit the `update every` setting. The default is `1`, meaning that the Agent collects metrics
61
+every second.
62
63
-If you change this to `2`, Netdata collects metrics every other second, which will effectively halve the CPU utilization
64
-dedicated for metrics collection. Set this to `5` or `10` to collect metrics every 5 or 10 seconds, respectively.
63
+If you change this to `2`, Netdata enforces a minimum `update every` setting of 2 seconds, and collects metrics every
64
+other second, which will effectively halve CPU utilization. Set this to `5` or `10` to collect metrics every 5 or 10
65
+seconds, respectively.
66
67
```conf
68
[global]
69
update every: 5
70
```
71
72
+Every collector and plugin has its own `update every` setting, which you can also change in the `go.d.conf`,
73
+`python.d.conf`, `node.d.conf`, or `charts.d.conf` files, or in individual collector configuration files. If the `update
74
+every` for an individual collector is less than the global, the Netdata Agent uses the global setting. See the [enable
75
+or configure a collector](/docs/collect/enable-configure.md) doc for details.
76
+
77
## Specific plugin or collector
78
79
If you did not [reduce the global collection frequency](#global) but find that a specific plugin/collector uses too many
docs/store/change-metrics-storage.md
+2
-2
@@ -46,8 +46,8 @@ want to store more metrics _specifically in memory_, you can increase the cache
46
## Edit `netdata.conf` with recommended database engine settings
47
48
Now that you have a recommended setting for `dbengine multihost disk space`, open `netdata.conf` with
49
-[`edit-config`](/docs/configure/nodes.md#use-edit-config-to-edit-netdataconf) and look for the `dbengine multihost disk
50
-space` setting. Change it to the value recommended above. For example:
49
+[`edit-config`](/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) and look for the `dbengine
50
+multihost disk space` setting. Change it to the value recommended above. For example:
51
52
```conf
53
[global]