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
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, the Netdata config
/etc/netdata/. The config directory contains several configuration files with the
.conf extension, a
few directories, and a shell script named
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.confin your browser, replacing
NODEwith 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.confis the main configuration file. This is where you'll find most configuration options. Read descriptions for each in the daemon config doc.
edit-configis a shell script used for editing configuration files.
- Various configuration files ending in
.conffor configuring plugins or collectors behave. Examples:
- Various directories ending in
.d, which contain other configuration files, each ending in
.conf, for configuring specific collectors.
apps_groups.confis a configuration file for changing how applications/processes are grouped when viewing the Application charts from
health.d/is a directory that contains health configuration files.
health_alarm_notify.confenables and configures alarm notifications.
statsd.d/is a directory for configuring Netdata's statsd collector.
stream.confconfigures parent-child streaming between separate nodes running the Agent.
.environmentis a hidden file that describes the environment in which the Netdata Agent is installed, including the
PATHand any installation options. Useful for reinstalling or uninstalling the Agent.
The Netdata config directory also contains one symlink:
origis 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.
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 (or wherever the symlink
orig under the config directory leads to)
to the proper place in the config directory and opens the copy for editing.
If you have trouble running the script, you can manually copy the file and edit the copy.
cp /usr/lib/netdata/conf.d/go.d/bind.conf /etc/netdata/go.d/bind.conf; vi /etc/netdata/go.d/bind.conf
edit-config without options, to see details on its usage, or
edit-config --list to see a list of all the configuration
files you can edit.
./edit-config [options] FILENAME
Copy and edit the stock config file named: FILENAME
if FILENAME is already copied, it will be edited as-is.
Stock config files at: '/etc/netdata/../../usr/lib/netdata/conf.d'
User config files at: '/etc/netdata'
The editor to use can be specified either by setting the EDITOR
environment variable, or by using the --editor option.
The file to edit can also be specified using the --file option.
For a list of known config files, run './edit-config --list'
./edit-config netdata.conf. You may need to elevate your privileges with
sudo or another
edit-config to write into the config directory. Use your
$EDITOR, make your changes, and save the file.
EDITORenvironment variable on your system to edit the file. On many systems, that is defaulted to
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 with
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:
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
the IP address or hostname of your node. The file displayed here is exactly the settings running live in the Netdata
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.
wget -O /etc/netdata/netdata.conf http://localhost:19999/netdata.conf
curl -o /etc/netdata/netdata.conf http://NODE:19999/netdata.conf
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.