diff options
| author | Joel Hans <joel@netdata.cloud> | 2021-01-04 10:49:00 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-01-04 10:49:00 -0700 |
| commit | 8d11dad2a85505a7563eb164a0be7aedae6b9589 (patch) | |
| tree | 2499e4c6c1b3d57c2ce46bc497929d4f751a1fcd /docs | |
| parent | b4201dc7965e2a04daefad476c36b7346315d5d7 (diff) | |
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
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration-guide.md | 213 | ||||
| -rw-r--r-- | docs/configure/common-changes.md | 204 | ||||
| -rw-r--r-- | docs/configure/nodes.md | 93 | ||||
| -rw-r--r-- | docs/configure/secure-nodes.md | 9 | ||||
| -rw-r--r-- | docs/configure/start-stop-restart.md | 98 | ||||
| -rw-r--r-- | docs/guides/configure/performance.md | 16 | ||||
| -rw-r--r-- | docs/store/change-metrics-storage.md | 4 |
7 files changed, 390 insertions, 247 deletions
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md deleted file mode 100644 index 6af45dfd1e..0000000000 --- a/docs/configuration-guide.md +++ /dev/null @@ -1,213 +0,0 @@ -<!-- ---- -title: "Configuration guide" -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configuration-guide.md ---- ---> - -# Configuration guide - -No configuration is required to run Netdata, but you will find plenty of options to tweak, so that you can adapt it to -your particular needs. - -<details markdown="1"><summary>Configuration files are placed in `/etc/netdata`.</summary> -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> - -Under that directory you will see the following: - -- `netdata.conf` is [the main configuration file](/daemon/config/README.md#daemon-configuration) -- `edit-config` is an sh script that you can use to easily and safely edit the configuration. Just run it to see its - usage. -- Other directories, initially empty, where your custom configurations for alarms and collector plugins/modules will - be copied from the stock configuration, if and when you customize them using `edit-config`. -- `orig` is a symbolic link to the directory `/usr/lib/netdata/conf.d`, which contains the stock configurations for - everything not included in `netdata.conf`: - - `health_alarm_notify.conf` is where you configure how and to who Netdata will send [alarm - notifications](/health/notifications/README.md#netdata-alarm-notifications). - - `health.d` is the directory that contains the alarm triggers for [health - monitoring](/health/README.md#health-monitoring). It contains one .conf file per collector. - - The [modular plugin orchestrators](/collectors/plugins.d/README.md#external-plugins-overview) have: - - One config file each, mainly to turn their modules on and off: `python.d.conf` for - [python](/collectors/python.d.plugin/README.md#pythondplugin), `node.d.conf` for - [nodejs](/collectors/node.d.plugin/README.md#nodedplugin) and `charts.d.conf` for - [bash](/collectors/charts.d.plugin/README.md#chartsdplugin) modules. - - One directory each, where the module-specific configuration files can be found. - - `stream.conf` is where you configure [streaming and - replication](/streaming/README.md#streaming-and-replication) - - `stats.d` is a directory under which you can add .conf files to add [synthetic - charts](/collectors/statsd.plugin/README.md#synthetic-statsd-charts). - - Individual collector plugin config files, such as `fping.conf` for the [fping - plugin](/collectors/fping.plugin/) and `apps_groups.conf` for the [apps plugin](/collectors/apps.plugin/) - -So there are many configuration files to control every aspect of Netdata's behavior. It can be overwhelming at first, -but you won't have to deal with any of them, unless you have specific things you need to change. The following HOWTO -will guide you on how to customize your Netdata, based on what you want to do. - -## How to - -### Persist my configuration - -In `http://localhost:19999/netdata.conf`, you will see the following two parameters: - -```bash - # config directory = /etc/netdata - # stock config directory = /usr/lib/netdata/conf.d -``` - -To persist your configurations, don't edit the files under the `stock config directory` directly. Use the `sudo [config -directory]/edit-config` command, or copy the stock config file to its proper place under the `config directory` and edit -it there. - -### Change what I see - -#### Increase the long-term metrics retention period - -Increase the values for the `page cache size` and `dbengine disk space` settings in the [`[global]` -section](/daemon/config/README.md#global-section-options) of `netdata.conf`. Read our guide on [increasing -long-term metrics storage](/docs/guides/longer-metrics-storage.md) and the [memory requirements for the database -engine](/database/engine/README.md#memory-requirements). - -#### Reduce the data collection frequency - -Increase `update every` in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options). This is another -way to increase your metrics retention period, but at a lower resolution than the default 1s. - -#### Modify how a chart is displayed - -In `netdata.conf` under `# Per chart configuration` you will find several [\[CHART_NAME\] -sections](/daemon/config/README.md#per-chart-configuration), where you can control all aspects of a specific chart. - -#### Disable a collector - -Entire plugins can be turned off from the [netdata.conf \[plugins\]](/daemon/config/README.md#plugins-section-options) -section. To disable specific modules of a plugin orchestrator, you need to edit one of the following: - -- `python.d.conf` for [python](/collectors/python.d.plugin/README.md) -- `node.d.conf` for [nodejs](/collectors/node.d.plugin/README.md) -- `charts.d.conf` for [bash](/collectors/charts.d.plugin/README.md) - -#### Show charts with zero metrics - -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. - -### Modify alarms and notifications - -#### Add a new alarm - -You can add a new alarm definition either by editing an existing stock alarm config file under `health.d` (e.g. -`/etc/netdata/edit-config health.d/load.conf`), or by adding a new `.conf` file under `/etc/netdata/health.d`. The -documentation on how to define an alarm is in [health monitoring](/health/README.md). It is -suggested to look at some of the stock alarm definitions, so you can ensure you understand how the various options work. - -#### Turn off all alarms and notifications - -Just set `enabled = no` in the [netdata.conf \[health\]](/daemon/config/README.md#health-section-options) section - -#### Modify or disable a specific alarm - -The `health.d` directory that contains the alarm triggers for [health monitoring](/health/README.md). It has -one .conf file per collector. You can easily find the .conf file you will need to modify, by looking for the "source" -line on the table that appears on the right side of an alarm on the Netdata gui. - -For example, if you click on Alarms and go to the tab 'All', the default Netdata installation will show you at the top -the configured alarm for `10 min cpu usage` (it's the name of the badge). Looking at the table on the right side, you -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 -to run `/etc/netdata/edit-config health.d/cpu.conf` and look for alarm at line 4 of the conf file. - -As stated at the top of the .conf file, **you can disable an alarm notification by setting the 'to' line to: silent**. -To modify how the alarm gets triggered, we suggest that you go through the guide on [health -monitoring](/health/README.md#health-monitoring). - -#### Receive notifications using my preferred method - -You only need to configure `health_alarm_notify.conf`. To learn how to do it, read first [alarm -notifications](/health/notifications/README.md#netdata-alarm-notifications) and then open the submenu `Supported -Notifications` under `Alarm notifications` in the documentation to find the specific page on your preferred notification -method. - -### Make security-related customizations - -#### Change the Netdata web server access lists - -You have several options under the [netdata.conf \[web\]](/web/server/README.md#access-lists) section. - -#### Stop sending info to registry.my-netdata.io - -You will need to configure the `[registry]` section in `netdata.conf`. First read the [registry -documentation](/registry/). In it, are instructions on how to [run your own -registry](/registry/README.md#run-your-own-registry). - -#### Change the IP address/port Netdata listens to - -The settings are under the `[web]` section. Look at the [web server -documentation](/web/server/README.md#binding-netdata-to-multiple-ports) for more info. - -### System resource usage - -#### Reduce the resources Netdata uses - -The [Netdata performance guide](/docs/guides/configure/performance.md) outlines many ways to reduce the Netdata -CPU/disk/RAM utilization to levels suitable even for the weakest [IoT devices](/docs/netdata-for-IoT.md). - -#### Change when Netdata saves metrics to disk - -[netdata.conf \[global\]](/daemon/config/README.md#global-section-options): `memory mode` - -#### Prevent Netdata from getting immediately killed when my server runs out of memory - -You can change the Netdata [OOM score](/daemon/README.md#oom-score) in `[global]`. - -### Other - -#### Move Netdata directories - -The various directory paths are in [netdata.conf \[global\]](/daemon/config/README.md#global-section-options). - -## How Netdata configuration works - -The configuration files are `name = value` dictionaries with `[sections]`. Write whatever you like there as long as it -follows this simple format. - -Netdata loads this dictionary and then when the code needs a value from it, it just looks up the `name` in the -dictionary at the proper `section`. In all places, in the code, there are both the `names` and their `default values`, -so if something is not found in the configuration file, the default is used. The lookup is made using B-Trees and hashes -(no string comparisons), so they are super fast. Also the `names` of the settings can be `my super duper setting that -once set to yes, will turn the world upside down = no` - so goodbye to most of the documentation involved. - -Next, Netdata can generate a valid configuration for the user to edit. No need to remember anything. Just get the -configuration from the server (`/netdata.conf` on your Netdata server), edit it and save it. - -Last, what about options you believe you have set, but you misspelled?When you get the configuration file from the -server, there will be a comment above all `name = value` pairs the server does not use. So you know that whatever you -wrote there, is not used. - -## Netdata simple patterns - -Unix prefers regular expressions. But they are just too hard, too cryptic to use, write and understand. - -So, Netdata supports [simple patterns](/libnetdata/simple_pattern/README.md). - -## Netdata labels - -Beginning with 1.20, Netdata accepts user-defined **host labels**. These labels are defined in the section `[host -labels]`. - -Read more about how these labels work and why they're an effective way to organize complex infrasturctures in our -guide: [Use host labels to organize systems, metrics, and alarms](/docs/guides/using-host-labels.md). - -To define a label inside this section, some rules needs to be followed, or Netdata will reject the label. The following -restrictions are applied for label names: - -- Names cannot start with `_`, but it can be present in other parts of the name. -- Names only accept alphabet letters, numbers, dots, and dashes. - -The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes -(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alarms and -templates. - -[](<>) diff --git a/docs/configure/common-changes.md b/docs/configure/common-changes.md new file mode 100644 index 0000000000..79faae9876 --- /dev/null +++ b/docs/configure/common-changes.md @@ -0,0 +1,204 @@ +<!-- +title: "Common configuration changes" +description: "See the most popular configuration changes to make to the Netdata Agent, including longer metrics retention, reduce sampling, and more." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/common-changes.md +--> + +# Common configuration changes + +The Netdata Agent requires no configuration upon installation to collect thousands of per-second metrics from most +systems, containers, and applications, but there are hundreds of settings to tweak if you want to exercise more control +over your monitoring platform. + +This document assumes familiarity with using [`edit-config`](/docs/configure/nodes.md) from the Netdata config +directory. + +## Change dashboards and visualizations + +The Netdata Agent's [local dashboard](/web/gui/README.md), accessible at `http://NODE:19999` is highly configurable. If +you use Netdata Cloud for [infrastructure monitoring](/docs/quickstart/infrastructure.md), you will see many of these +changes reflected in those visualizations due to the way Netdata Cloud proxies metric data and metadata to your browser. + +### Increase the long-term metrics retention period + +Increase the values for the `page cache size` and `dbengine multihost disk space` settings in the [`[global]` +section](/daemon/config/README.md#global-section-options) of `netdata.conf`. + +```conf +[global] + page cache size = 128 # 128 MiB of memory for metrics storage + dbengine multihost disk space = 4096 # 4GiB of disk space for metrics storage +``` + +Read our doc on [increasing long-term metrics storage](/docs/store/change-metrics-storage.md) for details, including a +[calculator](/docs/store/change-metrics-storage.md#calculate-the-system-resources-RAM-disk-space-needed-to-store-metrics) +to help you determine the exact settings for your desired retention period. + +### Reduce the data collection frequency + +Change `update every` in the [`[global]` section](/daemon/config/README.md#global-section-options) of `netdata.conf` so +that it is greater than `1`. An `update every` of `5` means the Netdata Agent enforces a _minimum_ collection frequency +of 5 seconds. + +```conf +[global] + update every = 5 +``` + +Every collector and plugin has its own `update every` setting, which you can also change in the `go.d.conf`, +`python.d.conf`, `node.d.conf`, or `charts.d.conf` files, or in individual collector configuration files. If the `update +every` for an individual collector is less than the global, the Netdata Agent uses the global setting. See the [enable +or configure a collector](/docs/collect/enable-configure.md) doc for details. + +### Disable a collector or plugin + +Turn off entire plugins in the [`[plugins]` section](/daemon/config/README.md#plugins-section-options) of +`netdata.conf`. + +To disable specific collectors, open `go.d.conf`, `python.d.conf`, `node.d.conf`, or `charts.d.conf` and find the line +for that specific module. Uncomment the line and change its value to `no`. + +## Modify alarms and notifications + +Netdata's health monitoring watchdog uses hundreds of preconfigured health entities, with intelligent thresholds, to +generate warning and critical alarms for most production systems and their applications without configuration. However, +each alarm and notification method is completely customizable. + +### Add a new alarm + +To create a new alarm configuration file, initiate an empty file, with a filename that ends in `.conf`, in the +`health.d/` directory. The Netdata Agent loads any valid alarm configuration file ending in `.conf` in that directory. +Next, edit the new file with `edit-config`. For example, with a file called `ram-usage.conf`. + +```bash +sudo touch health.d/ram-usage.conf +sudo ./edit-config health.d/ram-usage.conf +``` + +Or, append your new alarm to an existing file by editing a relevant existing file in the `health.d/` directory. + +Read more about [configuring alarms](/docs/monitor/configure-alarms.md) to get started, and see the [health monitoring +reference](/health/REFERENCE.md) for a full listing of options available in health entities. + +### Configure a specific alarm + +Tweak existing alarms by editing files in the `health.d/` directory. For example, edit `health.d/cpu.conf` to change how +the Agent responds to anomalies related to CPU utilization. + +To see which configuration file you need to edit to configure a specific alarm, [view your active +alarms](/docs/monitor/view-active-alarms.md) in Netdata Cloud or the local Agent dashboard and look for the **source** +line. For example, it might read `source 4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. Because the source path contains +`health.d/cpu.conf`, you now you that you should run `sudo edit-config health.d/cpu.conf` to configure that alarm. + +### Disable a specific alarm + +Open the configuration file for that alarm and set the `to` line to `silent`. + +### Turn of all alarms and notifications + +Set `enabled` to `no` in the [`[health]` section](/daemon/config/README.md#health-section-options) section of +`netdata.conf`. + +### Enable alarm notifications + +Open `health_alarm_notify.conf` for editing. First, read the [enabling +notifications](/docs/monitor/enable-notifications.md#netdata-agent) doc for an example of the process using Slack, then +click on the link to your preferred notification method to find documentation for that specific endpoint. + +## Improve node security + +While the Netdata Agent is both [open and secure by design](https://www.netdata.cloud/blog/netdata-agent-dashboard/), we +recommend every user take some action to administer and secure their nodes. + +Learn more about a few of the following changes in the [node security doc](/docs/configure/secure-nodes.md). + +### Disable the local Agent dashboard (`http://NODE:19999`) + +If you use Netdata Cloud to visualize metrics, stream metrics to a parent node, or otherwise don't need the local Agent +dashboard, disabling it reduces the Agent's resource utilization and improves security. + +Change the `mode` setting to `none` in the [`[web]` section](/web/server/README.md#configuration) of `netdata.conf`. + +```conf +[web] + mode = none +``` + +### Use access lists to restrict access to specific assets + +Allow access from only specific IP addresses, ranges of IP addresses, or hostnames using [access +lists](/web/server/README.md#access-lists) and [simple patterns](/libnetdata/simple_pattern/README.md). + +See a quickstart to access lists in the [node security +doc](/docs/configure/secure-nodes.md#restrict-access-to-the-local-dashboard). + +### Stop sending anonymous statistics to Google Analytics + +Create a file called `.opt-out-from-anonymous-statistics` inside of your Netdata config directory to immediately stop +the statistics script. + +```bash +sudo touch .opt-out-from-anonymous-statistics +``` + +Learn more about [why we collect anonymous statistics](/docs/anonymous-statistics.md). + +### Change the IP address/port Netdata listens to + +Change the `default port` setting in the `[web]` section to a port other than `19999`. + +```conf +[web] + default port = 39999 +``` + +Use the `bind to` setting to the ports other assets, such as the [running `netdata.conf` +configuration](/docs/configure/nodes.md#see-an-agents-running-configuration), API, or streaming requests listen to. + +## Reduce resource usage + +Read our [performance optimization guide](/docs/guides/configure/performance.md) for a long list of specific changes +that can reduce the Netdata Agent's CPU/memory footprint and IO requirements. + +## Organize nodes with host labels + +Beginning with v1.20, Netdata accepts user-defined **host labels**. These labels are sent during streaming, exporting, +and as metadata to Netdata Cloud, and help you organize the metrics coming from complex infrastructure. Host labels are +defined in the section `[host labels]`. + +For a quick introduction, read the [host label guide](/docs/guides/using-host-labels.md). + +The following restrictions apply to host label names: + +- Names cannot start with `_`, but it can be present in other parts of the name. +- Names only accept alphabet letters, numbers, dots, and dashes. + +The policy for values is more flexible, but you can not use exclamation marks (`!`), whitespaces (` `), single quotes +(`'`), double quotes (`"`), or asterisks (`*`), because they are used to compare label values in health alarms and +templates. + +## What's next? + +If you haven't already, learn how to [secure your nodes](/docs/configure/secure-nodes.md). + +As mentioned at the top, there are plenty of other + +You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features: + +- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior. +- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones. +- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your + infrastructure. +- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine. + +### Related reference documentation + +- [Netdata Agent · Daemon](/health/README.md) +- [Netdata Agent · Daemon configuration](/daemon/config/README.md) +- [Netdata Agent · Web server](/web/server/README.md) +- [Netdata Agent · Local Agent dashboard](/web/gui/README.md) +- [Netdata Agent · Health monitoring](/health/REFERENCE.md) +- [Netdata Agent · Notifications](/health/notifications/README.md) +- [Netdata Agent · Simple patterns](/libnetdata/simple_pattern/README.md) + +[](<>) diff --git a/docs/configure/nodes.md b/docs/configure/nodes.md index 89aa760a69..2e4bef6408 100644 --- a/docs/configure/nodes.md +++ b/docs/configure/nodes.md @@ -14,7 +14,7 @@ For example, you might want to increase metrics retention, configure a collector 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 peform. +anomaly, or change in infrastructure affects how their Agents should perform. ## The Netdata config directory @@ -31,20 +31,36 @@ scripts from inside that directory. ## Netdata's configuration files -Upon installation, the Netdata config directory contains a few files and directories. - -- `netdata.conf` is the main configuration file. This is where you'll find most configuration options. This doc won't - go into exhaustive detail about each setting. You can read descriptions for each in the [daemon config - doc](/daemon/config/README.md). -- `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._ -- `edit-config` is a shell script used for [editing configuration files](#use-edit-config-to-edit-netdataconf). -- `go.d/`, `python.d/`, `charts.d/`, `node.d`/, and `custom-plugins.d/`, which are directories for each of Netdata's - [orchestrators](/collectors/plugins.d/README.md). These directories can each contain additional `.conf` files for - configuring specific collectors. - -## Use `edit-config` to edit `netdata.conf` +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](/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](/docs/collect/enable-configure.md#enable-a-collector-or-its-orchestrator) behave. Examples: `go.d.conf`, + `python.d.conf`, and `ebpf.conf`. +- Various directories ending in `.d`, which contain other configuration files, each ending in `.conf`, for [configuring + specific collectors](/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`](/collectors/apps.plugin/README.md) or + [`ebpf.plugin`](/collectors/ebpf.plugin/README.md). +- `health.d/` is a directory that contains [health configuration files](/docs/monitor/configure-alarms.md). +- `health_alarm_notify.conf` enables and configures [alarm notifications](/docs/monitor/enable-notifications.md). +- `statsd.d/` is a directory for configuring Netdata's [statsd collector](/collectors/statsd.plugin/README.md). +- `stream.conf` configures [parent-child streaming](/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](/packaging/installer/REINSTALL.md) or + [uninstalling](/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._ + +## 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 @@ -79,11 +95,11 @@ To edit `netdata.conf`, run `./edit-config netdata.conf`. You may need to elevat 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`. To change this variable for the current session (it will revert to the default when you -> reboot), export a new value: `export EDITOR=nano`. Or, [make the change -> permanent](https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux). +> 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 `service netdata restart`. +After you make your changes, you need to [restart the Agent](/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. @@ -103,13 +119,36 @@ 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 `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? -Take advantage of this newfound understanding of node configuration to [add security to your -node](/docs/configure/secure-nodes.md). We have a few best practices based on how you use the Netdata Agent and Netdata -Cloud. +Learn more about [starting, stopping, or restarting](/docs/configure/start-stop-restart.md) the Netdata daemon to apply +configuration changes. + +Apply some [common configuration changes](/docs/configure/common-changes.md) to quickly tweak the Agent's behavior. -You can also take what you've learned about node configuration to tweak the Agent's behavior or enable new features: +[Add security to your node](/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](/docs/collect/enable-configure.md) or tweak their behavior. - [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 infrastructure. - Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine. -[](<>) +### Related reference documentation + +- [Netdata Agent · Daemon](/health/README.md) +- [Netdata Agent · Health monitoring](/health/README.md) +- [Netdata Agent · Notifications](/health/notifications/README.md) + +[](<>) diff --git a/docs/configure/secure-nodes.md b/docs/configure/secure-nodes.md index e58102401d..704db35a33 100644 --- a/docs/configure/secure-nodes.md +++ b/docs/configure/secure-nodes.md @@ -50,8 +50,9 @@ static-threaded` setting, and change it to `none`. mode = none ``` -Save and close the editor, then restart your Agent using `service netdata restart`. If you try to visit the local -dashboard to `http://NODE:19999` again, the connection will fail because that node no longer serves its local dashboard. +Save and close the editor, then [restart your Agent](/docs/configure/start-stop-restart.md) using `sudo systemctl +restart netdata`. If you try to visit the local dashboard to `http://NODE:19999` again, the connection will fail because +that node no longer serves its local dashboard. > See the [configuration basics doc](/docs/configure/nodes.md) for details on how to find `netdata.conf` and use > `edit-config`. @@ -112,7 +113,9 @@ We also have guides for [Apache](/docs/Running-behind-apache.md), [Lighttpd](/do ## What's next? -If you haven't already, be sure to read about [Netdata's security design](/docs/netdata-security.md). +Read about [Netdata's security design](/docs/netdata-security.md) and our [blog +post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) about why the local Agent dashboard is both open and +secure by design. Next up, learn about [collectors](/docs/collect/how-collectors-work.md) to ensure you're gathering every essential metric about your node, its applications, and your infrastructure at large. diff --git a/docs/configure/start-stop-restart.md b/docs/configure/start-stop-restart.md new file mode 100644 index 0000000000..4967fff087 --- /dev/null +++ b/docs/configure/start-stop-restart.md @@ -0,0 +1,98 @@ +<!-- +title: "Start, stop, or restart the Netdata Agent" +description: "Manage the Netdata Agent daemon, load configuration changes, and troubleshoot stuck processes on systemd and non-systemd nodes." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/configure/start-stop-restart.md +--> + +# Start, stop, or restart the Netdata Agent + +When you install the Netdata Agent, the [daemon](/daemon/README.md) is configured to start at boot and stop and +restart/shutdown. + +You will most often need to _restart_ the Agent to load new or editing configuration files. [Health +configuration](#reload-health-configuration) files are the only exception, as they can be reloaded without restarting +the entire Agent. + +Stopping or restarting the Netdata Agent will cause gaps in stored metrics until the `netdata` process initiates +collectors and the database engine. + +## Using `systemctl`, `service`, or `init.d` + +This is the recommended way to start, stop, or restart the Netdata daemon. + +- To **start** Netdata, run `sudo systemctl start netdata`. +- To **stop** Netdata, run `sudo systemctl stop netdata`. +- To **restart** Netdata, run `sudo systemctl restart netdata`. + +If the above commands fail, or you know that you're using a non-systemd system, try using the `service` command: + +- **service**: `sudo service netdata start`, `sudo service netdata stop`, `sudo service netdata restart` + +## Using `netdata` + +Use the `netdata` command, typically located at `/usr/sbin/netdata`, to start the Netdata daemon. + +```bash +sudo netdata +``` + +If you start the daemon this way, close it with `sudo killall netdata`. + +## Using `netdatacli` + +The Netdata Agent also comes with a [CLI tool](/cli/README.md) capable of performing shutdowns. Start the Agent back up +using your preferred method listed above. + +```bash +sudo netdatacli shutdown-agent +``` + +## Reload health configuration + +You do not need to restart the Netdata Agent between changes to health configuration files, such as specific health +entities. Instead, use [`netdatacli`](#using-netdatacli) and the `reload-health` option to prevent gaps in metrics +collection. + +```bash +sudo netdatacli reload-health +``` + +If `netdatacli` doesn't work on your system, send a `SIGUSR2` signal to the daemon, which reloads health configuration +without restarting the entire process. + +```bash +killall -USR2 netdata +``` + +## Force stop stalled or unresponsive `netdata` processes + +In rare cases, the Netdata Agent may stall or not properly close sockets, preventing a new process from starting. In +these cases, try the following three commands: + +```bash +sudo systemctl stop netdata +sudo killall netdata +ps aux| grep netdata +``` + +The output of `ps aux` should show no `netdata` or associated processes running. You can now start the Netdata Agent +again with `service netdata start`, or the appropriate method for your system. + +## What's next? + +Learn more about [securing the Netdata Agent](/docs/configure/secure-nodes.md). + +You can also use the restart/reload methods described above to enable new features: + +- [Enable new collectors](/docs/collect/enable-configure.md) or tweak their behavior. +- [Configure existing health alarms](/docs/monitor/configure-alarms.md) or create new ones. +- [Enable notifications](/docs/monitor/enable-notifications.md) to receive updates about the health of your + infrastructure. +- Change [the long-term metrics retention period](/docs/store/change-metrics-storage.md) using the database engine. + +### Related reference documentation + +- [Netdata Agent · Daemon](/daemon/README.md) +- [Netdata Agent · Netdata CLI](/cli/README.md) + +[](<>) diff --git a/docs/guides/configure/performance.md b/docs/guides/configure/performance.md index 95 |