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, 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 doc.
edit-config is a shell script used for editing configuration files.
Various configuration files ending in .conf for configuring plugins or collectors 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.
apps_groups.conf is a configuration file for changing how applications/processes are grouped when viewing the Application charts from apps.plugin or ebpf.plugin.
health.d/ is a directory that contains health configuration files.
health_alarm_notify.conf enables and configures alarm notifications.
statsd.d/ is a directory for configuring Netdata's statsd collector.
stream.conf configures parent-child streaming 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 or uninstalling 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.

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.

./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 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:

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

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 the Netdata daemon to apply configuration changes.

Apply some common configuration changes to quickly tweak the Agent's behavior.

Add security to your node 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 or tweak their behavior.
Configure existing health alarms or create new ones.
Enable notifications to receive updates about the health of your infrastructure.
Change the long-term metrics retention period using the database engine.

9.1 KiB Raw Permalink Blame History