1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!--
title: "Configure the Netdata Agent"
description: "Netdata is zero-configuration for most users, but complex infrastructures may require you to tweak some of the Agent's granular settings."
custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/configure/nodes.md"
sidebar_label: "Configure the Netdata Agent"
learn_status: "Published"
learn_topic_type: "Concepts"
learn_rel_path: "Concepts"
-->
# Configure the Netdata Agent
Netdata's zero-configuration collection, storage, and visualization features work for many users, infrastructures, and
use cases, but there are some situations where you might want to configure the Netdata Agent running on your node(s),
which can be a physical or virtual machine (VM), container, cloud deployment, or edge/IoT device.
For example, you might want to increase metrics retention, configure a collector based on your infrastructure's unique
setup, or secure the local dashboard by restricting it to only connections from `localhost`.
Whatever the reason, Netdata users should know how to configure individual nodes to act decisively if an incident,
anomaly, or change in infrastructure affects how their Agents should perform.
## The Netdata config directory
On most Linux systems, using our [recommended one-line
installation](https://github.com/netdata/netdata/blob/master/docs/get-started.mdx#install-on-linux-with-one-line-installer), the **Netdata config
directory** is `/etc/netdata/`. The config directory contains several configuration files with the `.conf` extension, a
few directories, and a shell script named `edit-config`.
> Some operating systems will use `/opt/netdata/etc/netdata/` as the config directory. If you're not sure where yours
> is, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with the IP address or hostname of
> your node, and find the `# config directory = ` setting. The value listed is the config directory for your system.
All of Netdata's documentation assumes that your config directory is at `/etc/netdata`, and that you're running any
scripts from inside that directory.
## Netdata's configuration files
Upon installation, the Netdata config directory contains a few files and directories. It's okay if you don't see all
these files in your own Netdata config directory, as the next section describes how to edit any that might not already
exist.
- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. Read descriptions
for each in the [daemon config](https://github.com/netdata/netdata/blob/master/daemon/config/README.md) doc.
- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-configuration-files).
- Various configuration files ending in `.conf` for [configuring plugins or
collectors](https://github.com/netdata/netdata/blob/master/docs/collect/enable-configure.md#enable-a-collector-or-its-orchestrator) behave. Examples: `go.d.conf`,
`python.d.conf`, and `ebpf.d.conf`.
- Various directories ending in `.d`, which contain other configuration files, each ending in `.conf`, for [configuring
specific collectors](https://github.com/netdata/netdata/blob/master/docs/collect/enable-configure.md#configure-a-collector).
- `apps_groups.conf` is a configuration file for changing how applications/processes are grouped when viewing the
**Application** charts from [`apps.plugin`](https://github.com/netdata/netdata/blob/master/collectors/apps.plugin/README.md) or
[`ebpf.plugin`](https://github.com/netdata/netdata/blob/master/collectors/ebpf.plugin/README.md).
- `health.d/` is a directory that contains [health configuration files](https://github.com/netdata/netdata/blob/master/docs/monitor/configure-alarms.md).
- `health_alarm_notify.conf` enables and configures [alarm notifications](https://github.com/netdata/netdata/blob/master/docs/monitor/enable-notifications.md).
- `statsd.d/` is a directory for configuring Netdata's [statsd collector](https://github.com/netdata/netdata/blob/master/collectors/statsd.plugin/README.md).
- `stream.conf` configures [parent-child streaming](https://github.com/netdata/netdata/blob/master/streaming/README.md) between separate nodes running the Agent.
- `.environment` is a hidden file that describes the environment in which the Netdata Agent is installed, including the
`PATH` and any installation options. Useful for [reinstalling](https://github.com/netdata/netdata/blob/master/packaging/installer/REINSTALL.md) or
[uninstalling](https://github.com/netdata/netdata/blob/master/packaging/installer/UNINSTALL.md) the Agent.
The Netdata config directory also contains one symlink:
- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains stock configuration files. Stock
versions are copied into the config directory when opened with `edit-config`. _Do not edit the files in
`/usr/lib/netdata/conf.d`, as they are overwritten by updates to the Netdata Agent._
## Configure a Netdata docker container
See [configure agent containers](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#configure-agent-containers).
## Use `edit-config` to edit configuration files
The **recommended way to easily and safely edit Netdata's configuration** is with the `edit-config` script. This script
opens existing Netdata configuration files using your system's `$EDITOR`. If the file doesn't yet exist in your config
directory, the script copies the stock version from `/usr/lib/netdata/conf.d` and opens it for editing.
Run `edit-config` without any options to see details on its usage and a list of all the configuration files you can
edit.
```bash
./edit-config
USAGE:
./edit-config FILENAME
Copy and edit the stock config file named: FILENAME
if FILENAME is already copied, it will be edited as-is.
The EDITOR shell variable is used to define the editor to be used.
Stock config files at: '/usr/lib/netdata/conf.d'
User config files at: '/etc/netdata'
Available files in '/usr/lib/netdata/conf.d' to copy and edit:
./apps_groups.conf ./health.d/phpfpm.conf
./aws_kinesis.conf ./health.d/pihole.conf
./charts.d/ap.conf ./health.d/portcheck.conf
./charts.d/apcupsd.conf ./health.d/postgres.conf
...
```
To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevate your privileges with `sudo` or another
method for `edit-config` to write into the config directory. Use your `$EDITOR`, make your changes, and save the file.
> `edit-config` uses the `EDITOR` environment variable on your system to edit the file. On many systems, that is
> defaulted to `vim` or `nano`. Use `export EDITOR=` to change this temporarily, or edit your shell configuration file
> to change to permanently.
After you make your changes, you need to [restart the Agent](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) with `sudo systemctl
restart netdata` or the appropriate method for your system.
Here's an example of editing the node's hostname, which appears in both the local dashboard and in Netdata Cloud.
### Other configuration files
You can edit any Netdata configuration file using `edit-config`. A few examples:
```bash
./edit-config apps_groups.conf
./edit-config ebpf.d.conf
./edit-config health.d/load.conf
./edit-config go.d/prometheus.conf
```
The documentation for each of Netdata's components explains which file(s) to edit to achieve the desired behavior.
## See an Agent's running configuration
On start, the Netdata Agent daemon attempts to load `netdata.conf`. If that file is missing, incomplete, or contains
invalid settings, the daemon attempts to run sane defaults instead. In other words, the state of `netdata.conf` on your
filesystem may be different from the state of the Netdata Agent itself.
To see the _running configuration_, navigate to `http://NODE:19999/netdata.conf` in your browser, replacing `NODE` with
the IP address or hostname of your node. The file displayed here is exactly the settings running live in the Netdata
Agent.
If you're having issues with configuring the Agent, apply the running configuration to `netdata.conf` by downloading the
file to the Netdata config directory. Use `sudo` to elevate privileges.
```bash
wget -O /etc/netdata/netdata.conf http://localhost:19999/netdata.conf
# or
curl -o /etc/netdata/netdata.conf http://NODE:19999/netdata.conf
```
## What's next?
Learn more about [starting, stopping, or restarting](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) the Netdata daemon to apply
configuration changes.
Apply some [common configuration changes](https://github.com/netdata/netdata/blob/master/docs/configure/common-changes.md) to quickly tweak the Agent's behavior.
[Add security to your node](https://github.com/netdata/netdata/blob/master/docs/configure/secure-nodes.md) with what you've learned about the Netdata config directory
and `edit-config`. We put together a few security best practices based on how you use the Netdata.
You can also take what you've learned about node configuration to enable or enhance features:
- [Enable new collectors](https://github.com/netdata/netdata/blob/master/docs/collect/enable-configure.md) or tweak their behavior.
- [Configure existing health alarms](https://github.com/netdata/netdata/blob/master/docs/monitor/configure-alarms.md) or create new ones.
- [Enable notifications](https://github.com/netdata/netdata/blob/master/docs/monitor/enable-notifications.md) to receive updates about the health of your
infrastructure.
- Change [the long-term metrics retention period](https://github.com/netdata/netdata/blob/master/docs/store/change-metrics-storage.md) using the database engine.
### Related reference documentation
- [Netdata Agent · Daemon](https://github.com/netdata/netdata/blob/master/daemon/README.md)
- [Netdata Agent · Health monitoring](https://github.com/netdata/netdata/blob/master/health/README.md)
- [Netdata Agent · Notifications](https://github.com/netdata/netdata/blob/master/health/notifications/README.md)
[](<>)
|
