Skip to main content

Daemon configuration

The daemon configuration file is read from /etc/netdata/netdata.conf.

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

This config file is not needed by default. Netdata works fine out of the box without it. But it does allow you to adapt the general behavior of Netdata, in great detail. You can find all these settings, with their default values, by accessing the URL https://netdata.server.hostname:19999/netdata.conf. For example check the configuration file of HTTP access to this file is limited by default to private IPs, via the web server access lists.

netdata.conf has sections stated with [section]. You will see the following sections:

  1. [global] to configure the Netdata daemon.
  2. [db] to configure the database of Netdata.
  3. [directories] to configure the directories used by Netdata.
  4. [logs] to configure the Netdata logging.
  5. [environment variables] to configure the environment variables used Netdata.
  6. [sqlite] to configure the Netdata daemon SQLite settings.
  7. [ml] to configure settings for machine learning.
  8. [health] to configure general settings for health monitoring.
  9. [web] to configure the web server.
  10. [registry] for the Netdata registry.
  11. [global statistics] for the Netdata registry.
  12. [statsd] for the general settings of the stats.d.plugin.
  13. [plugins] to configure which collectors to use and PATH settings.
  14. [plugin:NAME] sections for each collector plugin, under the comment Per plugin configuration.

The configuration file is a name = value dictionary. Netdata will not complain if you set options unknown to it. When you check the running configuration by accessing the URL /netdata.conf on your Netdata server, Netdata will add a comment on settings it does not currently use.

Applying changes

After netdata.conf has been modified, Netdata needs to be restarted for changes to apply:

sudo systemctl restart netdata

If the above does not work, try the following:

sudo killall netdata; sleep 10; sudo netdata

Please note that your data history will be lost if you have modified history parameter in section [global].


[global] section options

process scheduling policykeepSee Netdata process scheduling policy
OOM score0
glibc malloc arena max for plugins1See Virtual memory.
glibc malloc arena max for Netdata1See Virtual memory.
hostnameauto-detectedThe hostname of the computer running Netdata.
host access prefixemptyThis 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.
timezoneauto-detectedThe timezone retrieved from the environment variable
run as usernetdataThe user Netdata will run as.
pthread stack sizeauto-detected

[db] section options

modedbenginedbengine: The default for long-term metrics storage with efficient RAM and disk usage. Can be extended with dbengine page cache size MB and dbengine disk space MB.
ram: The round-robin database will be temporary and it will be lost when Netdata exits.
alloc: Similar to ram, but can significantly reduce memory usage, when combined with a low retention and does not support KSM.
none: Disables the database at this host, and disables health monitoring entirely, as that requires a database of metrics. Not to be used together with streaming.
retention3600Used with mode = ram/alloc, not the default mode = dbengine. This number reflects the number of entries the netdata daemon will by default keep in memory for each chart dimension. Check Memory Requirements for more information.
storage tiers3The number of storage tiers you want to have in your dbengine. Check the tiering mechanism in the dbengine's reference. You can have up to 5 tiers of data (including the Tier 0). This number ranges between 1 and 5.
dbengine page cache size MB32Determines the amount of RAM in MiB that is dedicated to caching for Tier 0 Netdata metric values.
dbengine tier N page cache size MB32Determines the amount of RAM in MiB that is dedicated for caching Netdata metric values of the N tier.
N belongs to [1..4]
dbengine disk space MB256Determines the amount of disk space in MiB that is dedicated to storing Tier 0 Netdata metric values and all related metadata describing them. This option is available only for legacy configuration (Agent v1.23.2 and prior).
dbengine multihost disk space MB256Same functionality as dbengine disk space MB, but includes support for storing metrics streamed to a parent node by its children. Can be used in single-node environments as well. This setting is only for Tier 0 metrics.
dbengine tier N multihost disk space MB256Same functionality as dbengine multihost disk space MB, but stores metrics of the N tier (both parent node and its children). Can be used in single-node environments as well.
N belongs to [1..4]
update every1The frequency in seconds, for data collection. For more information see the performance guide. These metrics stored as Tier 0 data. Explore the tiering mechanism in the dbengine's reference.
dbengine tier N update every iterations60The down sampling value of each tier from the previous one. For each Tier, the greater by one Tier has N (equal to 60 by default) less data points of any metric it collects. This setting can take values from 2 up to 255.
N belongs to [1..4]
dbengine tier N back fillNewSpecifies the strategy of recreating missing data on each Tier from the exact lower Tier.
New: Sees the latest point on each Tier and save new points to it only if the exact lower Tier has available points for it's observation window (dbengine tier N update every iterations window).
none: No back filling is applied.
N belongs to [1..4]
memory deduplication (ksm)yesWhen set to yes, Netdata will offer its in-memory round robin database and the dbengine page cache to kernel same page merging (KSM) for deduplication. For more information check Memory Deduplication - Kernel Same Page Merging - KSM
cleanup obsolete charts after secs3600See monitoring ephemeral containers, also sets the timeout for cleaning up obsolete dimensions
gap when lost iterations above1
cleanup orphan hosts after secs3600How long to wait until automatically removing from the DB a remote Netdata host (child) that is no longer sending data.
enable zero metricsnoSet to yes to show charts when all their metrics are zero.


The multiplication of all the enabled tiers dbengine tier N update every iterations values must be less than 65535.

[directories] section options

config/etc/netdataThe directory configuration files are kept.
stock config/usr/lib/netdata/conf.d
log/var/log/netdataThe directory in which the log files are kept.
web/usr/share/netdata/webThe directory the web static files are kept.
cache/var/cache/netdataThe directory the memory database will be stored if and when Netdata exits. Netdata will re-read the database when it will start again, to continue from the same point.
lib/var/lib/netdataContains the alert log and the Netdata instance GUID.
home/var/cache/netdataContains the db files for the collected metrics.
lock/var/lib/netdata/lockContains the data collectors lock files.
plugins"/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.
health config/etc/netdata/health.dThe directory containing the user alert configuration files, to override the stock configurations
stock health config/usr/lib/netdata/conf.d/health.dContains the stock alert configuration files for each collector
registry/opt/netdata/var/lib/netdata/registryContains the registry database and GUID that uniquely identifies each Netdata Agent

[logs] section options

debug flags0x0000000000000000Bitmap of debug options to enable. For more information check Tracing Options.
debug/var/log/netdata/debug.logThe filename to save debug information. This file will not be created if debugging is not enabled. You can also set it to syslog to send the debug messages to syslog, or none to disable this log. For more information check Tracing Options.
error/var/log/netdata/error.logThe filename to save error messages for Netdata daemon and all plugins (stderr is sent here for all Netdata programs, including the plugins). You can also set it to syslog to send the errors to syslog, or none to disable this log.
access/var/log/netdata/access.logThe filename to save the log of web clients accessing Netdata charts. You can also set it to syslog to send the access log to syslog, or none to disable this log.
facilitydaemonA facility keyword is used to specify the type of system that is logging the message.
errors flood protection period1200Length of period (in sec) during which the number of errors should not exceed the errors to trigger flood protection.
errors to trigger flood protection200Number of errors written to the log in errors flood protection period sec before flood protection is activated.
severity levelinfoControls which log messages are logged, with error being the most important. Supported values: info and error.

[environment variables] section options

TZ:/etc/localtimeWhere to find the timezone
PATHauto-detectedSpecifies the directories to be searched to find a command
PYTHONPATHUsed to set a custom python path

[sqlite] section options

auto vacuumINCREMENTALThe auto-vacuum status in the database
synchronousNORMALThe setting of the "synchronous" flag
journal modeWALThe journal mode for databases
temp storeMEMORYUsed to determine where temporary tables and indices are stored
journal size limit16777216Used to set a new limit in bytes for the database
cache size-2000Used to suggest the maximum number of database disk pages that SQLite will hold in memory at once per open database file

[health] section options

This section controls the general behavior of the health monitoring capabilities of Netdata.

Specific alerts are configured in per-collector config files under the health.d directory. For more info, see health monitoring.

Alert notifications are configured in health_alarm_notify.conf.

enabledyesSet to no to disable all alerts and notifications
in memory max health log entries1000Size of the alert history held in RAM
script to execute on alarm/usr/libexec/netdata/plugins.d/alarm-notify.shThe script that sends alert notifications. Note that in versions before 1.16, the plugins.d directory may be installed in a different location in certain OSs (e.g. under /usr/lib/netdata).
run at least every seconds10Controls how often all alert conditions should be evaluated.
postpone alarms during hibernation for seconds60Prevents false alerts. May need to be increased if you get alerts during hibernation.
health log history432000Specifies the history of alert events (in seconds) kept in the agent's sqlite database.
enabled alarms*Defines which alerts to load from both user and stock directories. This is a simple pattern list of alert or template names. Can be used to disable specific alerts. For example, enabled alarms = !oom_kill * will load all alerts except oom_kill.

[web] section options

Refer to the web server documentation

[plugins] section options

In this section you will see be a boolean (yes/no) option for each plugin (e.g. tc, cgroups, apps, proc etc.). Note that the configuration options in this section for the orchestrator plugins python.d and charts.d control all the modules written for that orchestrator. For instance, setting python.d = no means that all Python modules under collectors/python.d.plugin will be disabled.

Additionally, there will be the following options:

enable running new pluginsyesWhen set to yes, Netdata will enable detected plugins, even if they are not configured explicitly. Setting this to no will only enable plugins explicitly configured in this file with a yes
check for new plugins every60The time in seconds to check for new plugins in the plugins directory. This allows having other applications dynamically creating plugins for Netdata.
checksnoThis is a debugging plugin for the internal latency

[registry] section options

To understand what this section is and how it should be configured, please refer to the registry documentation.

Per-plugin configuration

The configuration options for plugins appear in sections following the pattern [plugin:NAME].

Internal plugins

Most internal plugins will provide additional options. Check Internal Plugins for more information.

Please note, that by default Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use yes instead of auto in plugin configuration sections to enable these charts permanently. You can also set the enable zero metrics option to yes in the [global] section which enables charts with zero metrics for all internal Netdata plugins.

External plugins

External plugins will have only 2 options at netdata.conf:

update everythe value of [global].update every settingThe frequency in seconds the plugin should collect values. For more information check the performance guide.
command options-Additional command line options to pass to the plugin.

External plugins that need additional configuration may support a dedicated file in /etc/netdata. Check their documentation.

Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.