Set up Netdata slave nodes for centralized monitoring with parent-child architecture

Intermediate 45 min May 11, 2026 80 views
Ubuntu 24.04 Debian 12 AlmaLinux 9 Rocky Linux 9

Configure Netdata parent-child architecture to stream metrics from multiple servers to a centralized dashboard. Set up authentication, SSL encryption, and troubleshoot streaming issues for scalable monitoring infrastructure.

Prerequisites

  • Multiple Linux servers
  • Network connectivity between nodes
  • Root or sudo access
  • Basic understanding of systemd services

What this solves

Netdata's parent-child architecture allows you to monitor multiple servers from a single centralized dashboard. Child nodes stream their metrics to parent nodes, reducing resource usage on monitored servers while maintaining centralized visibility. This setup is essential for managing distributed infrastructure where you need unified monitoring without overwhelming individual servers.

Step-by-step configuration

Update system packages

Start by updating your package manager on all servers that will participate in the monitoring cluster.

sudo apt update && sudo apt upgrade -y
sudo dnf update -y

Install Netdata on parent node

Install Netdata on your designated parent server that will collect metrics from child nodes.

curl -Ss 'https://my-netdata.io/kickstart.sh' > /tmp/netdata-kickstart.sh
sudo bash /tmp/netdata-kickstart.sh --stable-channel --disable-telemetry

Configure parent node for streaming

Create the streaming configuration to accept connections from child nodes.

[11111111-2222-3333-4444-555555555555]
    enabled = yes
    default history = 3600
    default memory = ram
    health enabled by default = auto
    allow from = *
    default postpone alarms on connect seconds = 60
Note: Replace the UUID with a unique identifier for each child node. Generate UUIDs with uuidgen command.

Set up API key authentication

Generate a secure API key for child node authentication.

openssl rand -hex 32

Add the API key to the parent's stream configuration:

[11111111-2222-3333-4444-555555555555]
    enabled = yes
    default history = 3600
    default memory = ram
    health enabled by default = auto
    allow from = *
    api key = your-generated-api-key-here
    default postpone alarms on connect seconds = 60

Configure SSL encryption on parent

Enable SSL to encrypt communication between parent and child nodes.

sudo mkdir -p /etc/netdata/ssl
cd /etc/netdata/ssl
sudo openssl genrsa -out netdata-key.pem 2048
sudo openssl req -new -key netdata-key.pem -out netdata-csr.pem
sudo openssl x509 -req -in netdata-csr.pem -signkey netdata-key.pem -out netdata-cert.pem -days 365

Update parent Netdata configuration

Enable SSL and streaming in the main Netdata configuration.

[global]
    bind socket to IP = 0.0.0.0
    allow connections from = *
    enable web responses gzip compression = yes

[web]
    web files owner = root
    web files group = netdata
    ssl key = /etc/netdata/ssl/netdata-key.pem
    ssl certificate = /etc/netdata/ssl/netdata-cert.pem

Restart parent Netdata service

Apply the configuration changes by restarting the Netdata service.

sudo systemctl restart netdata
sudo systemctl enable netdata
sudo systemctl status netdata

Install Netdata on child nodes

Install Netdata on each server you want to monitor. Repeat this step for all child nodes.

curl -Ss 'https://my-netdata.io/kickstart.sh' > /tmp/netdata-kickstart.sh
sudo bash /tmp/netdata-kickstart.sh --stable-channel --disable-telemetry

Configure child nodes for streaming

Configure each child node to stream data to the parent server.

[stream]
    enabled = yes
    api key = your-generated-api-key-here
    destination = 203.0.113.10:19999
    timeout seconds = 60
    reconnect delay seconds = 5
    initial clock resync iterations = 60
Note: Replace 203.0.113.10 with your parent node's IP address.

Disable child node web interface

Reduce resource usage by disabling the web interface on child nodes since metrics will be viewed on the parent.

[global]
    memory mode = ram
    history = 1200

[web]
    mode = none

Configure child node hostname

Set a unique hostname for each child node to identify them in the parent dashboard.

[global]
    hostname = server-web-01

Restart child node services

Apply the configuration changes on each child node.

sudo systemctl restart netdata
sudo systemctl enable netdata
sudo systemctl status netdata

Configure firewall rules

Allow Netdata traffic between parent and child nodes.

sudo ufw allow 19999/tcp
sudo ufw reload
sudo firewall-cmd --permanent --add-port=19999/tcp
sudo firewall-cmd --reload

Verify your setup

Check that child nodes are streaming to the parent successfully.

sudo netdata -W buildinfo | grep version
curl -k https://203.0.113.10:19999/api/v1/info
sudo tail -f /var/log/netdata/error.log

Access the parent node's web interface at https://your-parent-ip:19999 and verify all child nodes appear in the nodes dropdown menu.

Configure advanced monitoring

Set up custom dashboards

Create custom dashboards that aggregate metrics from multiple child nodes.

template: high_cpu_usage_cluster
      on: system.cpu
    calc: $system
   every: 10s
    warn: $this > 70
    crit: $this > 90
   delay: down 5m multiplier 1.5 max 1h
    info: CPU usage is above normal levels
      to: webmaster

Configure data retention

Adjust data retention settings based on your monitoring requirements.

[global]
    memory mode = dbengine
    storage tiers = 3
    dbengine multihost disk space MB = 2048
    dbengine disk space MB = 1024

Enable email notifications

Configure email alerts for critical system events across your infrastructure.

SEND_EMAIL="YES"
SMTP_SERVER="smtp.example.com"
SMTP_PORT="587"
SMTP_USERNAME="alerts@example.com"
SMTP_PASSWORD="your-smtp-password"
DEFAULT_RECIPIENT_EMAIL="admin@example.com"

Optimize performance

Tune streaming parameters

Optimize streaming settings for better performance with multiple child nodes.

[11111111-2222-3333-4444-555555555555]
    enabled = yes
    default history = 3600
    default memory = ram
    health enabled by default = auto
    allow from = *
    api key = your-generated-api-key-here
    default postpone alarms on connect seconds = 60
    compression = yes
    enable replication = yes

Configure resource limits

Set appropriate resource limits to prevent Netdata from consuming excessive system resources.

[Service]
LimitNOFILE=65536
LimitCORE=infinity
LimitAS=infinity
LimitRSS=1G
sudo systemctl daemon-reload
sudo systemctl restart netdata

Troubleshoot streaming issues

Check streaming connectivity

Verify network connectivity between child and parent nodes.

telnet 203.0.113.10 19999
curl -k https://203.0.113.10:19999/api/v1/info
ss -tlnp | grep 19999

Debug authentication issues

Check for API key mismatches and authentication failures.

sudo grep "STREAM" /var/log/netdata/error.log
sudo grep "API key" /var/log/netdata/access.log
sudo netdata -D 2>&1 | grep stream

Common issues

Symptom Cause Fix
Child node not appearing in parent dashboard Streaming configuration mismatch Verify API keys match in both stream.conf files
Connection refused errors Firewall blocking port 19999 Configure firewall rules to allow Netdata traffic
SSL certificate errors Self-signed certificate not trusted Use curl -k or configure proper SSL certificates
High memory usage on parent Too much historical data retention Adjust default history and memory mode settings
Intermittent disconnections Network timeouts or instability Increase timeout seconds and reconnect delay seconds

Security considerations

Security: Always use strong API keys and enable SSL encryption for production deployments. Restrict access using firewall rules and consider using VPN connections between nodes.

Implement access controls

Restrict which hosts can connect to your parent node using IP-based filtering.

[11111111-2222-3333-4444-555555555555]
    enabled = yes
    allow from = 203.0.113.0/24 192.168.1.0/24
    api key = your-generated-api-key-here

Configure log monitoring

Monitor Netdata logs for security events and unauthorized access attempts.

sudo tail -f /var/log/netdata/access.log | grep -E "(40[0-9]|50[0-9])"
sudo logrotate -f /etc/logrotate.d/netdata

For additional monitoring infrastructure, consider setting up Netdata MySQL monitoring or implementing advanced system monitoring with custom alerting.

Next steps

Running this in production?

Want this handled for you? Setting this up once is straightforward. Keeping it patched, monitored, backed up and performant across environments is the harder part. See how we run infrastructure like this for European teams.

Automated install script

Run this to automate the entire setup

Need help?

Don't want to manage this yourself?

We handle managed devops services for businesses that depend on uptime. From initial setup to ongoing operations.