Netdata

13 minute read.

Last Modified 2024-12-11 15:57 EST

The TrueNAS Netdata app provides an easy way to install and access the Netdata infrastructure monitoring solution. TrueNAS deploys the Netdata app in a Docker container using Docker Compose. After successfully deploying the app, you can access the Netdata web portal from TrueNAS. The Netdata web portal opens on the local dashboard, and where you can create new dashboards, add plugins, metric databases, physical and virtual systems, containers, and other cloud deployments you want to monitor. The portal also provides access to the Netdata Cloud sign-in screen.

Before You Begin

Prepare TrueNAS before installing the app by:

Set a pool for applications to use if not already assigned.
You can use either an existing pool or create a new one. TrueNAS creates the ix-apps (hidden) dataset in the pool set as the application pool. This dataset is internally managed, so you cannot use this as the parent when you create required application datasets.
Figure 1: Choose A Pool for Apps
After setting the pool, the Installed Applications screen displays Apps Service Running on the top screen banner.

Locate the run-as user for the app.
Take note of the run-as user for the app, shown on the app information screen in the Run As Content widget and in the Application Metadata widget on the Installed applications screen after the app fully deploys. The run-as user(s) get added to the ACL permissions for each dataset used as a host path storage volume.

Create datasets for the storage volumes for the app.
Do not create encrypted datasets for apps if not required! Using an encrypted dataset can result in undesired behaviors after upgrading TrueNAS when pools and datasets are locked. When datasets for the containers are locked, the container does not mount, and the apps do not start. To resolve issues, unlock the dataset(s) by entering the passphrase/key to allow datasets to mount and apps to start.
Go to Datasets and select the pool or dataset where you want to place the dataset(s) for the app. For example, /tank/apps/appName.

Netdata uses three datasets: config, lib, and cache. Follow the instruction below in **Creating Datasets for Apps** to correctly set up these datasets.

Creating Datasets for Apps

When creating datasets for apps follow these steps:

Go to Datasets, select the location for the parent dataset if organizing required datasets under a parent dataset, then click Add Dataset. For example, select the root dataset of the pool, and click Add Dataset to create a new parent called apps or appName*, where appName is the name of the app.
Do not create the app datasets under the ix-applications or ix-apps dataset.
Enter the name of the dataset, then select Apps as the Dataset Preset. Creating the parent dataset with the preset set to Generic causes permissions issues when you try to create the datasets the app requires with the preset set to Apps.
Click Save. Return to dataset creation when prompted rather than configuring ACL permissions.
You can set up permissions (ACLs) for a dataset after adding it by selecting Go to ACL Manager to open the Edit ACL screen, or wait and use the app Install wizard ACL settings to add permissions. You can also edit permissions after installing the app using either method.
Select the parent dataset and then click Create Dataset to open the Add Dataset screen again.
Enter the name of a dataset required for the app, such as config, select Apps as the Dataset Preset, and then click Save. When prompted, return to creating datasets rather than setting up ACL permissions.
Repeat for remaining datasets required for the app.

(Optional) Create a Netdata account. The app install wizard allows you to create a new Netdata account when configuring the app in TrueNAS, or to configure it to use a preexisting account.

Installing Netdata in TrueNAS

This basic procedure covers the required Netdata app settings. For optional settings, see Understanding App Installation Wizard Settings.

You can have multiple deployments of the same app (for example, two or more from the stable or enterprise trains, or a combination of the stable and enterprise trains).

Naming Multiple App Deployments

Each deployment of the same app requires a unique name. App names can include numbers, dashes, or underscores (for example, syncthing2, syncthing-test, syncthing_1, minio2, etc.).

Use a consistent file-naming convention to avoid conflict situations where data does not or cannot synchronize because of file name conflicts. Path and file names in apps are case-sensitive. For example, a file named MyData.txt is not the same as the mydata.txt file in Syncthing.

Go to Apps, click on Discover Apps, and locate the app widget by either scrolling down to it or begin typing the name into the search field. For example, to locate the MinIO app widget, begin typing minIO into the search field to show app widgets matching the search input.

Figure 3: Example of Locating an App Widget

If this is the first application installed, TrueNAS displays a dialog about configuring apps.

Configuring Apps Dialog

Click Confirm then Agree to close the dialog and open the application details screen.

If not the first time installing apps the dialog does not show, click on the widget to open the app information screen.

Click Install to open the app installation wizard.

Application configuration settings are grouped into several sections, each explained below in Understanding App Installation Wizard Settings. To find specific fields begin typing in the Search Input Fields search field to show the section or field, scroll down to a particular section, or click on the section heading in the list of sections on the upper-right of the wizard screen.

Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.

Accept the default version number in Version. When a new version becomes available, the application shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.

The TrueNAS app is configured with all the required environment variables, but if you want to further customize the container, click Add to the right of Additional Environment Variables for each to enter the variable(s) and values(s). See Netdata Configuration below for more information.

Accept the default values in Network Configurations. The TrueNAS Netdata app uses the default port 20489 to communicate with Netdata and show the Netdata local dashboard. Accept the default settings in Advanced DNS Settings. See Network Configuration below for more information.

Add your Storage Configuration settings. Set Type for Netdata Config Storage to Host Path (Path that already exists on the system). Select Enable ACL, and then enter or browse to and select the config dataset to populate the Host Path field.

Figure 6: Add Netdata Config Storage ACL and ACE Settings

Click Add to the right of ACL Entries to show the block of permissions settings. Change ID Type to user, enter 0 in ID, and set Access to full control.

Next, select Force Flag.

Repeat the above for the lib and cache storage volumes.

Accept the defaults in Resources Configuration.

Click Install. A progress dialog displays before switching to the Installed applications screen. The system opens the Installed Applications screen with the Netdata app in the Deploying state. When the installation completes it changes to Running.

Click Web Portal on the Application Info widget to open the Netdata web interface showing the local dashboard.

Figure 9: Netdata Web Portal Local Dashboard

Refer to Netdata user guides and documentation for more information on configuring Netdata dashboards.

Understanding App Installation Wizard Settings

The following section provides more detailed explanations of the settings in each section of the Install Netdata wizard.

Application Name Settings

Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.

Netdata Configuration Settings

Accept defaults in the Netdata Configuration settings, or to customize the container deployment click Add to the right of Additional Environment Variables to show the Name and Value fields used to enter variables. Netdata does not require using environment variables to deploy the application but you can enter any you want to use to customize your container.

Figure 10: Netdata Configuration Add Environment Variable

Refer to Netdata user guides and documentation for information on configuring and customizing your app. Guides include GitHub Install Netdata with Docker, and Netdaa Deployment Guides. Netdata provides assistance through their community forums and Support site.

Network Configuration Settings

The TrueNAS Netdata app uses port 20489 to communicate with Netdata and open the web portal. Netdata documentation states it uses 19999 as the default port, but it recommends restricting access to this for security reasons.

All TrueNAS apps are assigned default port numbers. Accept the default port numbers, but if changing port number assignments, enter a number within the range 1-65535, however, 0-1024 might require the application to have elevated privileges. Before changing default ports, refer to the TrueNAS default port list for a list of assigned and available port numbers.

Host Network is selected by default, but we recommend disabling this as it binds to the host network. Select to allow auto-discovery to work. If not selected, enter the network settings for TrueNAS in the web portal for the application.

The app does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.

Storage Configuration Settings

TrueNAS provides two options for storage volumes: ixVolumes and host paths.

Netdata needs three datasets:

config
lib
cache

Create datasets before beginning the app installation process. Set the Dataset Preset to Apps before saving the datasets. If you group the required datasets under a parent dataset, for example, a dataset named netdata, set the Dataset Preset to Apps to avoid permissions error messages and issues that can block fully deploying the app. See Before You Begin for more information on adding these datasets.

You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings.

Setting Dataset ACL Permissions

You can configure ACL permissions for the required dataset in the Install Netdata wizard, or from the Datasets screen any time after adding the datasets.

Select Enable ACL to show the ACL and ACE Entries options.

Configuring ACE Entries

Enter or browse to select the dataset and populate Host Path.

Figure 11: Host Path ACL and ACE Settings

Next, click Add to the right of ACL Entries to show the permissions settings. Set ID Type to Entry is for a USER or Entry is for a GROUP. If you configured a group in TrueNAS that you want to give access to instead of a single user, set the ID to the group option and enter the GID for that group.

Enter the UID as one of the following:

The default app user:
- 568 for apps in all trains if the app can run as any non-root user.
- 999 for all postgres storage volumes.
- 0 if running as root.
- 473 for MinIO app in the stable train.
The run-as-user UID set as a default for the app. The run-as user shows on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys. You can refer to the tutorial for the app, or look in the questions.yaml file found in the GitHub repository for the application to find this UID/GID.
The user ID for the new or existing TrueNAS user added to serve as the administrator for the app.

If the app shows User and Group Configuration settings, the default UID shows on the screen. If not, choose the run-as user ID found in the Run As Content widget.

Use the default user ID 999 for all postgres storage volumes, not the run-as user.

If you created a new TrueNAS user to serve as the app administration user, add an entry record and enter the UID for this user in addition to the run-as user ID.

When adding the ACL entry for the run-as user, default user, and/or optional TrueNAS app administrator user, and postgres user ID, set the Access permissions level to FULL CONTROL.

Select Force Flag to apply the ACL even if the path has existing data. This allows you to update the app when an update is available.

Adding ACL Permissions from the Datasets Screen

First select the dataset row, and scroll down to the Permissions widget, and then click Edit to open the Edit ACL screen. Change the @owner and @group values from root to the administrative user for your TrueNAS system, and click apply for each. Next, add an ACL entry for the run-as user. For Netdata, the run-as users is 0 for root. Add a user entry for this user. Save the ACL before leaving the screen.

See Setting Up Permissions and Edit ACL Screen for more information.

TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.

Set Type an SMB/CIFS Share (Mounts a volume to a SMB share) to add an SMB share storage volume.

Select Read Only to make the storage volume read only.

Enter the path inside the container to mount the storage for the share volume in Mount Path.

Enter the server address for the SMB share in Server, the path to mount the SMB share in Path, and the share authentication user credentials in User and Password. (Optional) enter the share domain name in domain.

Permissions are currently limited to the permissions of the user that mounted the share.

Use the SMB option for data synchronization between a share and the app if the option shows on the screen. A present, only the Syncthing app includes this option.

Resources Configuration Settings

Figure 13: Install Netdata Resource Limits

Accept the default values in Resources Configuration or enter new CPU and memory values. By default, this application is limited to use no more than 2 CPU cores and 4096 Megabytes available memory. The application might use considerably less system resources.

To customize the CPU and memory allocated to the container (pod) the app uses, enter new CPU values as a plain integer value (letter suffix is not required). The default is 4096.

Accept the default value 8 (Gb) allocated memory or enter a new limit in bytes. Enter a plain integer without the measurement suffix, for example, 129 not 129M or 123MiB.

Using the Netdata Web Portal

After deploying the TrueNAS Netdata app click on Web Portal to open the Netdata agent local dashboard. This Netdata dashboard provides a system overview of CPU usage and other vital statistics for the TrueNAS server connecting to Netdata.

The Netdata System Overview dashboard displays a limited portion of the reporting capabilities. Scroll down to see more information or click on a listed metric on the right side of the screen to show the graph and reporting on that metric. Click the other tabs at the top left of the dashboard to view other dashboards for nodes, alerts, anomalies, functions, and events.

You can add your own Netdata dashboards using Netdata configuration documentation to guide you.

Click on the Nodes tab to better understand the differences between the Netdata agent and Netdata Cloud service reporting. The Netdata Cloud monitors your cloud storage providers added to Netdata.

Click Sign In to open the Netdata Cloud sign-in screen.

Use the Netdata-provided documentation to customize Netdata dashboards to suit your use case and monitoring needs.