EN

Applications

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.

7 min read, updated on 18 November 2026

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.com must 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:

Terminal
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufw nginx apache2-utils certbot python3-certbot-nginx

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

Terminal
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 verbose

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

Terminal
curl -fsSL https://get.netdata.cloud/kickstart.sh -o /tmp/netdata-kickstart.sh
sh /tmp/netdata-kickstart.sh --release-channel=stable --disable-telemetry

The 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:

Terminal
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 5

The 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:

Terminal
cd /etc/netdata
sudo ./edit-config netdata.conf

In the [web] section, add or change the bind to line:

Configuration
[web]
    bind to = 127.0.0.1

Restart the agent and check the listening address:

Terminal
sudo systemctl restart netdata
sudo ss -tlnp | grep 19999

The 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:

Terminal
sudo htpasswd -c /etc/nginx/.htpasswd-netdata admin
sudo chown root:www-data /etc/nginx/.htpasswd-netdata
sudo chmod 640 /etc/nginx/.htpasswd-netdata

Create the Nginx site

Terminal
sudo nano /etc/nginx/sites-available/netdata.conf

Paste the following configuration, adapting the domain:

Nginx
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:

Terminal
sudo ln -s /etc/nginx/sites-available/netdata.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Enable HTTPS

Request a Let’s Encrypt certificate and enable the redirect to HTTPS:

Terminal
sudo certbot --nginx -d netdata.your-domain.com -m admin@your-domain.com --agree-tos --no-eff-email --redirect
sudo certbot renew --dry-run

For more details, see the Install an SSL Certificate with Let's Encrypt guide.

Check access

From your own computer, run these three tests:

Terminal
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:

Terminal
curl -s 'http://127.0.0.1:19999/api/v1/alarms?all' | head -n 30

Enable email sending

Netdata sends its emails with the sendmail command. The msmtp-mta package provides it and relays messages to your SMTP server:

Terminal
sudo apt install -y msmtp msmtp-mta
sudo nano /etc/msmtprc

If the installation asks a question about AppArmor, keep the default choice. Then enter your SMTP account:

Text
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 : alertes

This file contains a password: only root should be able to modify it, and only the netdata group should be able to read it.

Terminal
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.com

Choose the recipient

Terminal
cd /etc/netdata
sudo ./edit-config health_alarm_notify.conf

Change these three variables:

Terminal
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:

Terminal
sudo su -s /bin/bash netdata
export NETDATA_ALARM_NOTIFY_DEBUG=1
/usr/libexec/netdata/plugins.d/alarm-notify.sh test
exit

You should receive three test messages, matching the WARNING, CRITICAL and CLEAR states.

Add a custom alert

Create a file in the alerts folder:

Terminal
sudo nano /etc/netdata/health.d/cpu-15min.conf

This example monitors the average CPU usage over 15 minutes:

Text
    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: sysadmin

Reload the alerts without restarting the agent, then check that yours is loaded:

Terminal
sudo netdatacli reload-health
curl -s 'http://127.0.0.1:19999/api/v1/alarms?all' | grep cpu_usage_15min

Update Netdata

The installation script enables a daily automatic update by default. To check its schedule:

Terminal
systemctl list-timers netdata-updater.timer --no-pager

Depending 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:

Terminal
curl -fsSL https://get.netdata.cloud/kickstart.sh -o /tmp/netdata-kickstart.sh
sh /tmp/netdata-kickstart.sh

To disable automatic updates:

Terminal
sudo /usr/libexec/netdata/netdata-updater.sh --disable-auto-updates

Back 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:

Terminal
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.gz

Then 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:

Terminal
sudo systemctl stop netdata
sudo rm -rf /var/cache/netdata
sudo tar -xzpf /root/netdata-YYYY-MM-DD.tar.gz -C /
sudo systemctl start netdata

Troubleshooting

502 Bad Gateway error

Nginx cannot reach the agent.

Terminal
sudo systemctl status netdata --no-pager
sudo ss -tlnp | grep 19999
sudo tail -n 30 /var/log/nginx/error.log

Check 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:

Terminal
sudo ls -l /etc/nginx/.htpasswd-netdata
sudo htpasswd -v /etc/nginx/.htpasswd-netdata admin

The 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 test again and read its detailed output.
  • Check the msmtp logs with sudo journalctl -t msmtp -n 30 --no-pager.
  • If command -v sendmail returns nothing, the msmtp-mta package is not installed.
  • A Permission denied error on /etc/msmtprc indicates 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:

Terminal
sudo du -sh /var/cache/netdata
cd /etc/netdata
sudo ./edit-config netdata.conf
Configuration
[db]
    dbengine tier 0 retention size = 500MiB
    dbengine tier 1 retention size = 500MiB
    dbengine tier 2 retention size = 500MiB

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

References