Monitor Your Server with Netdata
Install Netdata on Debian or Ubuntu, protect the dashboard with Nginx, HTTPS and a password, then receive alerts by email.
On this page
Your values
Enter them once and the commands in this guide update.
This guide explains how to install Netdata on a VPS or dedicated server running Debian 12/13 or Ubuntu 22.04/24.04. Netdata collects system metrics every second (CPU, memory, disks, network, services) and displays them in a web dashboard.
By the end of this guide, you will have:
- a Netdata agent installed from the official repository, on the stable channel;
- a dashboard reachable only over HTTPS, behind Nginx and a password;
- email alerts, including a custom alert;
- an update and backup procedure.
Order a Server
To monitor your services, HostMyServers offers several options:
Prerequisites
- A server running Debian 12/13 or Ubuntu 22.04/24.04
- SSH access with a user that has
sudo - A domain name with an A record:
netdata.your-domain.commust point to the server's IP address - About 4 GiB of free disk space: with its default settings, Netdata limits its metrics to 3 GiB, plus its metadata
- An SMTP account if you want to receive alerts by email
Ports used
| Port | Protocol | Purpose | Access |
|---|---|---|---|
| 22 | TCP | SSH (or your custom port) | Open, restrict if possible |
| 80 | TCP | Let’s Encrypt validation and redirect to HTTPS | Open |
| 443 | TCP | Dashboard through Nginx | Open |
| 19999 | TCP | Netdata agent | Local only (127.0.0.1) |
Prepare the server
Update the system and install the required tools:
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufw nginx apache2-utils certbot python3-certbot-nginxConfigure the firewall
Allow SSH before enabling UFW, or you will lose access to the server. If you use a different SSH port, replace 22 with that port.
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw enable
sudo ufw status verbosePort 19999 does not appear in these rules, so it stays closed from the outside. To go further, see the Secure your server guide.
Install Netdata
Download the official script, then run it with the stable channel. Without this option, the script offers the nightly channel, which receives development builds.
curl -fsSL https://get.netdata.cloud/kickstart.sh -o /tmp/netdata-kickstart.sh
sh /tmp/netdata-kickstart.sh --release-channel=stable --disable-telemetryThe script detects your distribution, adds the Netdata repository and installs the native packages. It asks for confirmation and uses sudo when needed. The --disable-telemetry option turns off the sending of anonymous statistics.
Then check the service and the installation type:
sudo systemctl status netdata --no-pager
sudo netdata -W buildinfo | grep -E 'Installation Type|Install type:'
curl -s http://127.0.0.1:19999/api/v1/info | head -n 5The service must be active (running), the installation type binpkg-deb, and the last command must return JSON.
Restrict Netdata to the local interface
Open the configuration with the tool provided by Netdata:
cd /etc/netdata
sudo ./edit-config netdata.confIn the [web] section, add or change the bind to line:
[web]
bind to = 127.0.0.1Restart the agent and check the listening address:
sudo systemctl restart netdata
sudo ss -tlnp | grep 19999The output must show 127.0.0.1:19999, not 0.0.0.0:19999 or *:19999.
Publish the dashboard with Nginx
Create the password
Create a credentials file. The command asks you to choose a password for the admin user:
sudo htpasswd -c /etc/nginx/.htpasswd-netdata admin
sudo chown root:www-data /etc/nginx/.htpasswd-netdata
sudo chmod 640 /etc/nginx/.htpasswd-netdataCreate the Nginx site
sudo nano /etc/nginx/sites-available/netdata.confPaste the following configuration, adapting the domain:
upstream netdata_backend {
server 127.0.0.1:19999;
keepalive 64;
}
server {
listen 80;
listen [::]:80;
server_name netdata.your-domain.com;
location / {
auth_basic "Netdata";
auth_basic_user_file /etc/nginx/.htpasswd-netdata;
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;
}
}Enable the site and reload Nginx:
sudo ln -s /etc/nginx/sites-available/netdata.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxEnable HTTPS
Request a Let’s Encrypt certificate and enable the redirect to HTTPS:
sudo certbot --nginx -d netdata.your-domain.com -m admin@your-domain.com --agree-tos --no-eff-email --redirect
sudo certbot renew --dry-runFor more details, see the Install an SSL Certificate with Let's Encrypt guide.
Check access
From your own computer, run these three tests:
curl -s -o /dev/null -w '%{http_code}\n' https://netdata.your-domain.com/
curl -s -o /dev/null -w '%{http_code}\n' -u admin https://netdata.your-domain.com/
curl -m 5 http://YOUR_SERVER_IP:19999/| Test | Expected result |
|---|---|
| Without credentials | 401 |
| With credentials | 200 |
| Direct access to port 19999 | Connection failure or timeout |
Then open https://netdata.your-domain.com in your browser and sign in. If the interface offers to connect the agent to Netdata Cloud, this step is optional: the local dashboard works without an account.
Configure alerts
Netdata ships with many ready-to-use alerts (disk, memory, CPU, network, etc.). To list all the ones that are loaded:
curl -s 'http://127.0.0.1:19999/api/v1/alarms?all' | head -n 30Enable email sending
Netdata sends its emails with the sendmail command. The msmtp-mta package provides it and relays messages to your SMTP server:
sudo apt install -y msmtp msmtp-mta
sudo nano /etc/msmtprcIf the installation asks a question about AppArmor, keep the default choice. Then enter your SMTP account:
defaults
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
syslog on
account alertes
host smtp.your-domain.com
port 587
from netdata@your-domain.com
user netdata@your-domain.com
password YOUR_SMTP_PASSWORD
account default : alertesThis file contains a password: only root should be able to modify it, and only the netdata group should be able to read it.
sudo chown root:netdata /etc/msmtprc
sudo chmod 640 /etc/msmtprc
printf 'Subject: msmtp test\n\nTest message.\n' | sudo -u netdata msmtp alertes@your-domain.comChoose the recipient
cd /etc/netdata
sudo ./edit-config health_alarm_notify.confChange these three variables:
EMAIL_SENDER="netdata@your-domain.com"
SEND_EMAIL="YES"
DEFAULT_RECIPIENT_EMAIL="alertes@your-domain.com"The change applies from the next alert. Send a test notification:
sudo su -s /bin/bash netdata
export NETDATA_ALARM_NOTIFY_DEBUG=1
/usr/libexec/netdata/plugins.d/alarm-notify.sh test
exitYou should receive three test messages, matching the WARNING, CRITICAL and CLEAR states.
Add a custom alert
Create a file in the alerts folder:
sudo nano /etc/netdata/health.d/cpu-15min.confThis example monitors the average CPU usage over 15 minutes:
alarm: cpu_usage_15min
on: system.cpu
lookup: average -15m unaligned of user,system,softirq,irq,guest
units: %
every: 1m
warn: $this > 80
crit: $this > 95
delay: down 15m multiplier 1.5 max 1h
summary: High CPU over 15 minutes
info: Average CPU usage over the last 15 minutes
to: sysadminReload the alerts without restarting the agent, then check that yours is loaded:
sudo netdatacli reload-health
curl -s 'http://127.0.0.1:19999/api/v1/alarms?all' | grep cpu_usage_15minUpdate Netdata
The installation script enables a daily automatic update by default. To check its schedule:
systemctl list-timers netdata-updater.timer --no-pagerDepending on the system, scheduling may also go through cron if the systemd timer is not used. To run an update manually, run the official script again:
curl -fsSL https://get.netdata.cloud/kickstart.sh -o /tmp/netdata-kickstart.sh
sh /tmp/netdata-kickstart.shTo disable automatic updates:
sudo /usr/libexec/netdata/netdata-updater.sh --disable-auto-updatesBack up and restore
| Data | Location |
|---|---|
| Configuration | /etc/netdata |
| Metrics | /var/cache/netdata |
| Agent identity and optional token | /var/lib/netdata |
Stop the agent while copying the metrics to get a consistent backup:
sudo systemctl stop netdata
sudo tar -czpf "/root/netdata-$(date +%F).tar.gz" /etc/netdata /var/cache/netdata /var/lib/netdata
sudo systemctl start netdata
sudo chmod 600 /root/netdata-*.tar.gzThen copy the archive off the server. Also back up /etc/msmtprc and the Nginx files if you want to rebuild everything identically.
To restore, reinstall Netdata if needed, then:
sudo systemctl stop netdata
sudo rm -rf /var/cache/netdata
sudo tar -xzpf /root/netdata-YYYY-MM-DD.tar.gz -C /
sudo systemctl start netdataTroubleshooting
502 Bad Gateway error
Nginx cannot reach the agent.
sudo systemctl status netdata --no-pager
sudo ss -tlnp | grep 19999
sudo tail -n 30 /var/log/nginx/error.logCheck that the agent is running and that bind to matches the upstream address, here 127.0.0.1.
The browser keeps asking for the password
Check the file permissions and the username:
sudo ls -l /etc/nginx/.htpasswd-netdata
sudo htpasswd -v /etc/nginx/.htpasswd-netdata adminThe file must be readable by the www-data group. A Permission denied error in /var/log/nginx/error.log confirms a permissions problem.
Port 19999 responds from the Internet
Check that the [web] section is in /etc/netdata/netdata.conf, restart the agent, then check sudo ss -tlnp | grep 19999 and sudo ufw status verbose.
Certbot fails
Check that the domain points to the server with getent hosts netdata.your-domain.com, that port 80 is open and that sudo nginx -t reports no errors.
Emails do not arrive
- Run the
alarm-notify.sh testagain and read its detailed output. - Check the msmtp logs with
sudo journalctl -t msmtp -n 30 --no-pager. - If
command -v sendmailreturns nothing, themsmtp-mtapackage is not installed. - A
Permission deniederror on/etc/msmtprcindicates a permissions problem on that file. - If the SMTP connection times out, try another port listed by your email provider. To find out whether filtering applies to your service, contact support from your customer area.
Netdata uses too much disk space
Check the actual usage, then reduce retention in the [db] section of netdata.conf:
sudo du -sh /var/cache/netdata
cd /etc/netdata
sudo ./edit-config netdata.conf[db]
dbengine tier 0 retention size = 500MiB
dbengine tier 1 retention size = 500MiB
dbengine tier 2 retention size = 500MiBThen restart the agent with sudo systemctl restart netdata.
Going further
To keep metrics from several servers and build your own dashboards, see the Install Prometheus and Grafana guide.