Netdata is a high-performance, real-time monitoring agent that collects thousands of metrics per second with zero configuration. It tracks CPU, memory, disk I/O, network traffic, running processes, and application-specific metrics – all displayed through an interactive web dashboard. On FreeBSD, Netdata provides native support for FreeBSD-specific subsystems like ZFS, jails, and the pf firewall.
This guide covers installing and configuring Netdata on FreeBSD 14.4. We walk through package installation, service configuration, firewall rules, FreeBSD-specific monitoring, alert setup, and an Nginx reverse proxy for secure remote access.
Prerequisites
Before starting, make sure you have the following in place:
- A server or VM running FreeBSD 14.4 (or 14.x / 13.x)
- Root access or a user with
sudoprivileges - Network connectivity to install packages from FreeBSD repos
- Port 19999/TCP open for the Netdata dashboard (or 80/443 if using a reverse proxy)
All commands in this guide are run as root. If you are using a regular user, switch to root first:
su -Step 1: Install Netdata from FreeBSD Packages
The simplest way to install Netdata on FreeBSD is through the pkg package manager. The net-mgmt/netdata port is maintained in the FreeBSD ports tree and available as a prebuilt binary package.
Update the package index and install Netdata:
pkg update
pkg install -y netdataAfter installation finishes, confirm the installed version:
netdata -vThe output shows the Netdata version installed from the FreeBSD package repository:
netdata v2.8.5This installs Netdata along with all required dependencies – json-c, libuv, liblz4, curl, and Python. The package installs configuration files to /usr/local/etc/netdata/ and the binary to /usr/local/sbin/netdata.
Step 2: Install Netdata from Ports (Alternative)
If you need a newer version or want to compile Netdata with custom options, you can build from the FreeBSD ports tree. This method takes longer but gives full control over compile-time features.
First, make sure the ports tree is available. If you do not have it installed, fetch it with:
portsnap fetch extractIf the ports tree already exists, update it instead:
portsnap fetch updateNavigate to the Netdata port directory and compile:
cd /usr/ports/net-mgmt/netdata
make install cleanThe ports build system presents a configuration dialog where you can enable or disable optional features. The defaults work well for most deployments. Build time depends on your hardware – expect 5 to 15 minutes on a modern system.
Step 3: Configure Netdata
Netdata works out of the box with sensible defaults, but there are a few settings worth tuning for production use. The main configuration file is /usr/local/etc/netdata/netdata.conf.
Open the configuration file:
vi /usr/local/etc/netdata/netdata.confReview and adjust these key sections:
[global]
# Data collection frequency in seconds (1 = per-second metrics)
update every = 1
# How long to keep metrics in memory (3600 = 1 hour at 1-second resolution)
history = 3600
# Bind to all interfaces for remote access (default: 127.0.0.1)
# Change only if you need direct access without a reverse proxy
bind to = 0.0.0.0
[web]
# Dashboard port
default port = 19999
# Allow connections from specific networks (CIDR notation)
allow connections from = localhost 10.* 192.168.*
# Allow dashboard access from specific networks
allow dashboard from = localhost 10.* 192.168.*The bind to setting controls which network interfaces Netdata listens on. Keep it at 127.0.0.1 if you plan to use an Nginx reverse proxy (covered in Step 9). Set it to 0.0.0.0 only if you need direct access and have firewall rules in place.
The history value determines how many seconds of per-second data Netdata keeps in RAM. Set this based on available memory – each chart uses roughly 16 bytes per second of history. For 3600 seconds (1 hour) with the default ~200 charts, expect around 50 MB of RAM usage.
Step 4: Start and Enable the Netdata Service
Enable Netdata to start automatically at boot using FreeBSD’s rc.conf system:
sysrc netdata_enable="YES"The sysrc command adds netdata_enable="YES" to /etc/rc.conf. Now start the service:
service netdata startVerify the service is running:
service netdata statusYou should see a running process with the Netdata PID:
netdata is running as pid 1234.You can also confirm Netdata is listening on port 19999:
sockstat -4 -l | grep 19999The output confirms Netdata is bound and listening:
netdata netdata 1234 5 tcp4 *:19999 *:*Step 5: Access the Netdata Dashboard
Netdata provides a built-in web dashboard that displays all collected metrics in real time. Open your browser and navigate to:
http://YOUR_SERVER_IP:19999Replace YOUR_SERVER_IP with the actual IP address of your FreeBSD server. The dashboard loads immediately and starts showing live metrics – CPU usage, memory, disk I/O, network interfaces, and hundreds more.
The dashboard is fully interactive. You can zoom into any time window, pan across the timeline, pause data collection, and drill into individual metrics. Every chart updates in real time at 1-second granularity by default.
If you are running Netdata on a remote server and the dashboard does not load, check that port 19999 is open in your firewall (covered in the next step) and that bind to is set to 0.0.0.0 in the config.
Step 6: Configure Firewall Rules (pf / ipfw)
FreeBSD supports two built-in firewalls – pf (Packet Filter, ported from OpenBSD) and ipfw (the native FreeBSD firewall). Choose the one your server uses.
Option A: pf Firewall
If you use pf, add a rule to allow TCP traffic on port 19999. Open the pf configuration:
vi /etc/pf.confAdd this rule to allow Netdata dashboard access from your management network:
# Allow Netdata dashboard access
pass in on egress proto tcp from 192.168.1.0/24 to any port 19999Reload the pf ruleset to apply the changes:
pfctl -f /etc/pf.confVerify the rule is loaded:
pfctl -sr | grep 19999Option B: ipfw Firewall
For servers using ipfw, add a rule to permit TCP connections on port 19999:
ipfw add allow tcp from 192.168.1.0/24 to me 19999To make this rule persistent across reboots, add it to your ipfw rules script. The default location is /etc/ipfw.rules or wherever your firewall_script variable points in /etc/rc.conf.
Restrict the source network to your management subnet – never expose the Netdata dashboard to the public internet without authentication. If you need remote access, use the Nginx reverse proxy with basic authentication covered in Step 9.
Step 7: Monitor FreeBSD-Specific Metrics
Netdata automatically detects and monitors several FreeBSD-specific subsystems. These collectors activate without any configuration if the relevant services are running.
ZFS Monitoring
If your FreeBSD server uses ZFS (the default filesystem since FreeBSD 13), Netdata automatically collects ZFS metrics including ARC (Adaptive Replacement Cache) hit rates, pool I/O, compression ratios, and dataset usage. These appear under the ZFS section in the dashboard.
Key ZFS metrics tracked by Netdata:
- ARC size and hit rate – how effectively ZFS caches data in RAM
- Pool read/write operations – I/O throughput per pool
- L2ARC statistics – secondary cache performance (if configured)
- Dataset space usage – used, available, and referenced space per dataset
Verify ZFS metrics are being collected by checking the dashboard or querying the API:
curl -s http://localhost:19999/api/v1/charts | python3 -m json.tool | grep zfsFreeBSD Jails Monitoring
If you run FreeBSD jails for container-like isolation, Netdata can monitor resource usage per jail. Jail metrics include CPU time, memory consumption, and network I/O for each active jail.
List running jails to confirm they are active:
jlsNetdata picks up running jails automatically. The metrics appear in the dashboard under the system section grouped by jail name.
Network and Disk Metrics
Netdata monitors all network interfaces (including lo0, em0, vtnet0) with per-interface bandwidth, packets, errors, and drops. Disk metrics cover all mounted filesystems and physical devices with read/write IOPS, throughput, and latency. If you use Grafana alongside Netdata, you can build custom dashboards for deeper analysis of these metrics.
Step 8: Configure Netdata Alerts
Netdata ships with hundreds of preconfigured health alerts covering CPU, memory, disk space, network errors, and application-specific checks. These alerts work out of the box and trigger notifications when thresholds are crossed.
View the default health configuration:
ls /usr/local/etc/netdata/health.d/Each file in this directory contains alert definitions for a specific subsystem. To customize alerts, create override files in the same directory rather than editing the defaults (so upgrades do not overwrite your changes).
Here is an example custom alert that triggers when disk space usage exceeds 85% on any mounted filesystem. Create a custom health config file:
vi /usr/local/etc/netdata/health.d/custom-disk.confAdd the following alert definition:
alarm: disk_space_warning
on: disk.space
lookup: average -1m percentage of used
units: %
every: 1m
warn: $this > 85
crit: $this > 95
info: Disk space usage is highThis alert checks disk usage every minute and triggers a warning at 85% and a critical alert at 95%.
To enable email notifications, configure the alarm notification script. Open the notification config:
vi /usr/local/etc/netdata/health_alarm_notify.confSet the email recipient and sender:
# Email notifications
SEND_EMAIL="YES"
DEFAULT_RECIPIENT_EMAIL="[email protected]"
EMAIL_SENDER="[email protected]"Netdata also supports notifications through Slack, PagerDuty, Telegram, Discord, and many other services. Check the official Netdata documentation for the full list of notification integrations.
After making changes to health configuration, reload Netdata to apply:
service netdata restartVerify alerts are active through the dashboard by navigating to the Alerts tab, or check from the command line:
curl -s http://localhost:19999/api/v1/alarms | python3 -m json.tool | head -30Step 9: Set Up Nginx Reverse Proxy for Netdata
Running Netdata behind an Nginx reverse proxy adds TLS encryption and HTTP basic authentication – both essential for production servers accessible over the network. This setup lets you access the dashboard on port 80/443 instead of 19999.
Install Nginx if it is not already present:
pkg install -y nginxEnable and start Nginx:
sysrc nginx_enable="YES"
service nginx startCreate a password file for basic authentication. Install the apache24 package to get the htpasswd utility, or use a standalone tool:
pkg install -y apache24
htpasswd -c /usr/local/etc/nginx/.htpasswd adminEnter a strong password when prompted. Now create the Nginx server block configuration:
vi /usr/local/etc/nginx/conf.d/netdata.confAdd the following reverse proxy configuration:
upstream netdata_backend {
server 127.0.0.1:19999;
keepalive 64;
}
server {
listen 80;
server_name netdata.example.com;
auth_basic "Netdata Monitoring";
auth_basic_user_file /usr/local/etc/nginx/.htpasswd;
location / {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://netdata_backend;
proxy_http_version 1.1;
proxy_pass_request_headers on;
proxy_set_header Connection "keep-alive";
proxy_store off;
}
}Make sure the Nginx main config includes files from the conf.d directory. Open the main config:
vi /usr/local/etc/nginx/nginx.confAdd this line inside the http block if it is not already present:
include /usr/local/etc/nginx/conf.d/*.conf;Create the conf.d directory if it does not exist:
mkdir -p /usr/local/etc/nginx/conf.dTest the Nginx configuration and reload:
nginx -t
service nginx reloadThe output should confirm the configuration is valid:
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successfulNow change Netdata to bind only to localhost since Nginx handles external connections. Edit /usr/local/etc/netdata/netdata.conf and set:
[global]
bind to = 127.0.0.1Restart Netdata to apply the binding change:
service netdata restartAccess the dashboard through Nginx at http://netdata.example.com. You are prompted for the username and password configured in the .htpasswd file. For production use, add TLS with Nginx and a Let’s Encrypt certificate to encrypt traffic between clients and the reverse proxy.
Conclusion
Netdata is now running on your FreeBSD server, collecting per-second metrics across CPU, memory, disk, network, ZFS, and application layers. The interactive dashboard gives immediate visibility into server performance, and the built-in alert system notifies you before small issues become outages.
For production hardening, bind Netdata to localhost and serve it exclusively through the Nginx reverse proxy with TLS and authentication. Consider connecting your Netdata agent to Netdata Cloud for centralized monitoring across multiple servers, or pair it with Prometheus for long-term metric storage and advanced alerting.
