Skip to Content
DocsApplicationsUtilitiesNetdata
Netdata

Netdata

Real-time system telemetry with a web UI and rich charts

Overview

Netdata is a real-time monitoring service for infrastructure metrics. In QuickBox Pro, Netdata is installed as a system service and proxied through nginx, while a companion poller writes bandwidth totals used by the dashboard widgets.

Key features

QuickBox Pro configures Netdata with a local-only web listener and a secure reverse proxy for browser access.

🎯 Local-only listener

netdata.conf binds to localhost with a default port of 19979

🌐 Reverse proxy routes

nginx proxies /netdata/v3/ plus /netdata/api/, /netdata/lib/, and dashboard.js assets

🔐 HTTP basic auth

The UI route /netdata/v3/ is protected by /etc/htpasswd.d/htpasswd.username

📡 Bandwidth poller

qbnetwork runs _qb-poll_netstats every 300 seconds to write /srv/quickbox/db/bandwidth

🧰 Service hardening

Netdata runs as the netdata user with runtime/cache/log directories and a LimitNOFILE=30000 override

🙅 Telemetry opt-out

Installer creates /etc/netdata/.opt-out-from-anonymous-statistics to disable anonymous reporting

When to use it

Use Netdata when you want live system metrics through the QuickBox proxy and a bandwidth widget backed by VNStat.

Symptoms

  • Need real-time system metrics and charts from a local daemon
  • Want the Netdata UI behind nginx and HTTP basic auth
  • Need bandwidth totals sourced from VNStat
  • Netdata is an admin-installed service in QuickBox Pro

Resolution

  • Netdata listens on localhost and is proxied at /netdata/v3/
  • Basic auth is enforced via /etc/htpasswd.d/htpasswd.username
  • qbnetwork writes /srv/quickbox/db/bandwidth for dashboard usage totals
  • Install with an admin user using the QuickBox CLI or dashboard controls

Installation

Install from the QuickBox CLI

Netdata is installed through the QuickBox CLI using the Netdata software handler.

Command
qb install netdata -u username
Description
Install Netdata and the qbnetwork poller service
Command
qb reinstall netdata -u username
Description
Reapply templates and restart services
Command
qb update netdata -u username
Description
Update Netdata packages and refresh configs
Command
qb remove netdata -u username
Description
Remove Netdata and related files

CLI Options

-u, --usernameRequired

Target QuickBox username for install, reinstall, update, or remove

Install from the Dashboard

The dashboard Package Management tab includes Install and Reinstall actions for Netdata. The catalog is filtered by group membership — you will see Netdata if your group includes the Utilities and System category.

Access and authentication

URL / route

Netdata is reverse-proxied at /netdata/v3/ and served through nginx. The proxy also exposes /netdata/api/, /netdata/lib/, /netdata/dashboard.js, /netdata/dashboard.slate.css, and /netdata/dashboard.css for embedded assets.

Login / credentials / tokens

The Netdata UI uses HTTP basic auth and reads credentials from /etc/htpasswd.d/htpasswd.username.

Security notes

The nginx proxy enforces basic auth on /netdata/v3/ while leaving the API and static asset routes unauthenticated for dashboard embedding.

Configuration and files

The Netdata installer templates configuration, systemd units, and nginx proxy routes, then writes bandwidth totals via the poller service.

/
etc/
├── netdata/
│ ├── netdata.conf# Default port and localhost bind
│ └── .opt-out-from-anonymous-statistics# Telemetry opt-out marker
├── nginx/
│ └── software/
│ │ └── netdata.conf# Reverse proxy for /netdata/v3/ and assets
├── systemd/
│ └── system/
│ │ ├── netdata.service.d/
│ │ │ └── limits.conf# LimitNOFILE override
│ │ └── qbnetwork.service# VNStat poller service
└── htpasswd.d/
│ └── htpasswd.username# Basic-auth credentials
usr/
├── local/
│ └── bin/
│ │ └── _qb-poll_netstats# Polls VNStat every 300 seconds
└── share/
│ └── netdata/
│ │ └── web/# Netdata dashboard assets
srv/
└── quickbox/
│ └── db/
│ │ ├── bandwidth# VNStat totals for dashboard
│ │ └── qbnetwork.service.pid# Poller PID file

Common tasks

Use systemd to manage the Netdata and qbnetwork services, and rely on the dashboard port field to confirm the active Netdata port.

Task
Check status
Command
systemctl status netdata qbnetwork
Task
Restart services
Command
systemctl restart netdata qbnetwork
Task
Reload nginx proxy
Command
systemctl reload nginx

Typical workflows:

  • Confirm the live port in the Service Control list for Netdata.
  • Use /netdata/v3/ in the browser instead of exposing the raw port.
  • Verify /srv/quickbox/db/bandwidth updates if bandwidth tiles appear empty.
  • Reinstall Netdata to reapply the proxy template.

FAQ

The Netdata UI route is protected by HTTP basic auth using /etc/htpasswd.d/htpasswd.username.
The qbnetwork service runs _qb-poll_netstats every 300 seconds and writes totals to /srv/quickbox/db/bandwidth.
The default port is 19979 in /etc/netdata/netdata.conf. The dashboard shows the active port in the Netdata service row.
Netdata is configured to bind to localhost. Use the nginx proxy at /netdata/v3/ for browser access.

Best practices

Do

  • Use /netdata/v3/ instead of exposing the Netdata port
  • Check systemctl status netdata qbnetwork after installs or updates
  • Keep /etc/netdata/netdata.conf and /etc/nginx/software/netdata.conf in sync via qb reinstall netdata -u username
  • Inspect /srv/quickbox/db/bandwidth if bandwidth tiles look empty

Don't

  • Do not expose the localhost-only Netdata port directly
  • Avoid editing /etc/nginx/software/netdata.conf manually—reinstall to re-template
  • Do not delete /etc/netdata/.opt-out-from-anonymous-statistics unless you intend to enable telemetry

Troubleshooting

Netdata UI prompts or 401/403

Symptom: The browser keeps prompting for credentials or denies access.

Checks: Confirm /etc/htpasswd.d/htpasswd.username exists and rerun qb reinstall netdata -u username to reapply the proxy template.

Charts missing or stale

Symptom: Charts are blank or stop updating.

Checks: Verify systemctl status netdata qbnetwork, then confirm the bind/port in /etc/netdata/netdata.conf matches the proxy in /etc/nginx/software/netdata.conf.

502/404 at /netdata/v3/

Symptom: The proxy returns 502/404 errors.

Checks: Ensure /usr/share/netdata/web/dashboard.js exists and reload nginx with systemctl reload nginx. If the proxy is missing /netdata/v3/, run qb update netdata -u username.

Resources

Netdata Documentation

Official guides for configuration, charts, and systemd service

Netdata on GitHub

Source, issues, and release notes

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
Let's Encrypt SSLphpMyAdmin