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
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
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
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
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
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
- Configure Netdata Slack and Teams integration for real-time monitoring alerts
- Set up Netdata high availability clustering with load balancing
- Configure custom Netdata dashboards and specialized metrics collection
Running this in production?
Automated install script
Run this to automate the entire setup
#!/usr/bin/env bash
set -euo pipefail
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Global variables
PARENT_IP=""
NODE_TYPE=""
API_KEY=""
HOSTNAME=""
SSL_ENABLED="true"
# Usage function
usage() {
echo "Usage: $0 [OPTIONS]"
echo "Options:"
echo " --parent Setup as parent node"
echo " --child <parent_ip> Setup as child node with parent IP"
echo " --api-key <key> API key for authentication (optional, will generate if not provided)"
echo " --hostname <name> Custom hostname for child node"
echo " --no-ssl Disable SSL encryption"
echo " --help Show this help message"
exit 1
}
# Logging functions
log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
# Cleanup function
cleanup() {
log_error "Installation failed. Cleaning up..."
if systemctl is-active --quiet netdata 2>/dev/null; then
systemctl stop netdata || true
fi
rm -f /tmp/netdata-kickstart.sh
}
trap cleanup ERR
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--parent)
NODE_TYPE="parent"
shift
;;
--child)
NODE_TYPE="child"
PARENT_IP="$2"
shift 2
;;
--api-key)
API_KEY="$2"
shift 2
;;
--hostname)
HOSTNAME="$2"
shift 2
;;
--no-ssl)
SSL_ENABLED="false"
shift
;;
--help)
usage
;;
*)
log_error "Unknown option: $1"
usage
;;
esac
done
# Validate arguments
if [[ -z "$NODE_TYPE" ]]; then
log_error "Must specify --parent or --child"
usage
fi
if [[ "$NODE_TYPE" == "child" && -z "$PARENT_IP" ]]; then
log_error "Parent IP required for child node"
usage
fi
# Check prerequisites
if [[ $EUID -ne 0 ]]; then
log_error "This script must be run as root"
exit 1
fi
# Detect distribution
echo "[1/10] Detecting distribution..."
if [ -f /etc/os-release ]; then
. /etc/os-release
case "$ID" in
ubuntu|debian)
PKG_MGR="apt"
PKG_INSTALL="apt install -y"
PKG_UPDATE="apt update && apt upgrade -y"
FIREWALL_CMD="ufw"
;;
almalinux|rocky|centos|rhel|ol|fedora)
PKG_MGR="dnf"
PKG_INSTALL="dnf install -y"
PKG_UPDATE="dnf update -y"
FIREWALL_CMD="firewall-cmd"
;;
amzn)
PKG_MGR="yum"
PKG_INSTALL="yum install -y"
PKG_UPDATE="yum update -y"
FIREWALL_CMD="firewall-cmd"
;;
*)
log_error "Unsupported distribution: $ID"
exit 1
;;
esac
log_info "Detected: $PRETTY_NAME"
else
log_error "Cannot detect distribution"
exit 1
fi
# Update system packages
echo "[2/10] Updating system packages..."
$PKG_UPDATE
# Install prerequisites
echo "[3/10] Installing prerequisites..."
if [[ "$PKG_MGR" == "apt" ]]; then
$PKG_INSTALL curl openssl uuid-runtime
else
$PKG_INSTALL curl openssl util-linux
fi
# Generate API key if not provided
if [[ -z "$API_KEY" ]]; then
echo "[4/10] Generating API key..."
API_KEY=$(openssl rand -hex 32)
log_info "Generated API key: $API_KEY"
else
echo "[4/10] Using provided API key..."
fi
# Install Netdata
echo "[5/10] Installing Netdata..."
curl -Ss 'https://my-netdata.io/kickstart.sh' > /tmp/netdata-kickstart.sh
bash /tmp/netdata-kickstart.sh --stable-channel --disable-telemetry --dont-wait
# Configure based on node type
if [[ "$NODE_TYPE" == "parent" ]]; then
echo "[6/10] Configuring parent node..."
# Generate UUID for stream configuration
STREAM_UUID=$(uuidgen)
# Create stream configuration
cat > /etc/netdata/stream.conf << EOF
[$STREAM_UUID]
enabled = yes
default history = 3600
default memory = ram
health enabled by default = auto
allow from = *
api key = $API_KEY
default postpone alarms on connect seconds = 60
EOF
if [[ "$SSL_ENABLED" == "true" ]]; then
echo "[7/10] Configuring SSL..."
mkdir -p /etc/netdata/ssl
cd /etc/netdata/ssl
openssl genrsa -out netdata-key.pem 2048
openssl req -new -key netdata-key.pem -out netdata-csr.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=netdata"
openssl x509 -req -in netdata-csr.pem -signkey netdata-key.pem -out netdata-cert.pem -days 365
# Set proper permissions
chown netdata:netdata /etc/netdata/ssl/*
chmod 600 /etc/netdata/ssl/netdata-key.pem
chmod 644 /etc/netdata/ssl/netdata-cert.pem
# Configure SSL in netdata.conf
cat >> /etc/netdata/netdata.conf << EOF
[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
EOF
else
echo "[7/10] Configuring without SSL..."
cat >> /etc/netdata/netdata.conf << EOF
[global]
bind socket to IP = 0.0.0.0
allow connections from = *
enable web responses gzip compression = yes
EOF
fi
echo "[8/10] Configuring firewall..."
if [[ "$FIREWALL_CMD" == "ufw" ]]; then
ufw allow 19999/tcp || log_warn "UFW not enabled or already configured"
else
firewall-cmd --permanent --add-port=19999/tcp || log_warn "Firewall not running or already configured"
firewall-cmd --reload || true
fi
else
echo "[6/10] Configuring child node..."
# Set hostname if provided
if [[ -n "$HOSTNAME" ]]; then
CHILD_HOSTNAME="$HOSTNAME"
else
CHILD_HOSTNAME=$(hostname)
fi
# Configure streaming to parent
cat > /etc/netdata/stream.conf << EOF
[stream]
enabled = yes
api key = $API_KEY
destination = $PARENT_IP:19999
timeout seconds = 60
reconnect delay seconds = 5
initial clock resync iterations = 60
EOF
echo "[7/10] Configuring child node settings..."
cat >> /etc/netdata/netdata.conf << EOF
[global]
memory mode = ram
history = 1200
hostname = $CHILD_HOSTNAME
[web]
mode = none
EOF
echo "[8/10] Firewall configuration not needed for child node..."
fi
# Set proper ownership for configuration files
chown netdata:netdata /etc/netdata/stream.conf
chmod 640 /etc/netdata/stream.conf
chown netdata:netdata /etc/netdata/netdata.conf
chmod 644 /etc/netdata/netdata.conf
# Restart and enable Netdata
echo "[9/10] Starting Netdata service..."
systemctl restart netdata
systemctl enable netdata
# Wait a moment for service to fully start
sleep 3
# Verify installation
echo "[10/10] Verifying installation..."
if systemctl is-active --quiet netdata; then
log_info "Netdata service is running"
else
log_error "Netdata service failed to start"
exit 1
fi
# Display final information
echo ""
log_info "Netdata $NODE_TYPE node installation completed successfully!"
if [[ "$NODE_TYPE" == "parent" ]]; then
echo ""
log_info "Parent node configuration:"
log_info "- Web interface: http://$(hostname -I | awk '{print $1}'):19999"
if [[ "$SSL_ENABLED" == "true" ]]; then
log_info "- HTTPS interface: https://$(hostname -I | awk '{print $1}'):19999"
fi
log_info "- API Key: $API_KEY"
log_info "- Stream UUID: $STREAM_UUID"
echo ""
log_warn "Save the API key and Stream UUID for configuring child nodes!"
else
echo ""
log_info "Child node configuration:"
log_info "- Hostname: $CHILD_HOSTNAME"
log_info "- Parent: $PARENT_IP:19999"
log_info "- Web interface disabled (view metrics on parent node)"
fi
# Cleanup
rm -f /tmp/netdata-kickstart.sh
log_info "Installation completed successfully!"
Review the script before running. Execute with: bash install.sh