Sign InStart Free
Netwarden
Sign InStart Free
Back to Documentation
Installationv2.0

Agent Installation Guide

Complete guide for installing the Netwarden monitoring agent on various systems

Last updated: January 14, 2024
6 min read

Agent Installation Guide

The Netwarden agent is a lightweight monitoring daemon that collects metrics from your hosts and sends them to the Netwarden platform. This guide covers installation on various operating systems and deployment scenarios.

Prerequisites

Before installing the Netwarden agent, ensure your system meets these requirements:

  • Operating System: Linux (Ubuntu 18.04+, Debian 10+, RHEL/CentOS 7+, Amazon Linux 2+), Windows Server 2016+, or macOS 10.14+
  • Memory: Minimum 128MB RAM (256MB recommended)
  • Disk Space: 100MB for agent installation
  • Network: Outbound HTTPS (port 443) to api.netwarden.com
  • Permissions: Root/Administrator access for installation

Quick Install (Recommended)

The fastest way to install the Netwarden agent is using our automated installer script:

bash
curl -sSL https://get.netwarden.com/install.sh | sudo bash -s -- --tenant-id YOUR_TENANT_ID --api-key YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key from the Netwarden dashboard (Settings → Agent Tokens).

Package Installation

DEB-based Systems (Ubuntu, Debian)

For Debian-based distributions, we provide official .deb packages:

1. Add Netwarden Repository

bash
# Add the GPG key
curl -fsSL https://get.netwarden.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/netwarden.gpg

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/netwarden.gpg] https://get.netwarden.com/deb stable main" | sudo tee /etc/apt/sources.list.d/netwarden.list

2. Install the Agent

bash
sudo apt update
sudo apt install netwarden

2. Configure the Agent

bash
sudo nano /etc/netwarden/netwarden.conf

Add your tenant ID and API key to the configuration:

ini
# Netwarden Agent Configuration
tenant_id: "YOUR_TENANT_ID"
api_key: "YOUR_API_KEY"

# Collection interval (default: 60s)
collection_interval = 60

# Log level: debug, info, warn, error
log_level = "info"

3. Start the Service

bash
sudo systemctl enable netwarden
sudo systemctl start netwarden
sudo systemctl status netwarden

RPM-based Systems (RHEL, CentOS, Fedora, Amazon Linux)

For RPM-based distributions, we provide official .rpm packages that automatically configure the repository:

1. Install the Agent

For RHEL/CentOS/Rocky/AlmaLinux:

bash
sudo yum install netwarden

For Fedora:

bash
sudo dnf install netwarden

2. Configure the Agent

bash
sudo vi /etc/netwarden/netwarden.conf

3. Start the Service

bash
sudo systemctl enable netwarden
sudo systemctl start netwarden
sudo systemctl status netwarden

Docker Installation

For containerized environments, use our official Docker image:

bash
docker run -d \
  --name netwarden \
  --restart unless-stopped \
  -e NETWARDEN_TOKEN=YOUR_AGENT_TOKEN \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  netwarden/agent:latest

Docker Compose

Create a docker-compose.yml file:

yaml
version: '3.8'
services:
  netwarden:
    image: netwarden/agent:latest
    container_name: netwarden
    restart: unless-stopped
    environment:
      - NETWARDEN_TENANT_ID=YOUR_TENANT_ID
      - NETWARDEN_API_KEY=YOUR_API_KEY
      - NETWARDEN_HOSTNAME=${HOSTNAME}
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: host
    pid: host

Then start with:

bash
docker-compose up -d

Kubernetes Installation

Netwarden can monitor Kubernetes workloads through the standard agent installed on each node. Container-level metrics are collected automatically when Docker or containerd is detected. For dedicated Kubernetes DaemonSet deployment, see our container monitoring guide.

Windows Installation

Using Windows Installer

  1. Download the latest Windows installer from the Downloads page

  2. Run the installer as Administrator

  3. During installation, enter your tenant ID and API key when prompted

  4. The agent will start automatically as a Windows Service

Direct Download

You can also download the agent binary directly from the Downloads page for manual installation.

macOS Installation

Using Homebrew

bash
# Add Netwarden tap
brew tap netwarden/tap

# Install agent
brew install netwarden

# Configure with your credentials
sudo nano /etc/netwarden/netwarden.conf

# Start the service
brew services start netwarden

Configuration Options

The agent configuration file (/etc/netwarden/netwarden.conf) supports these options:

ini
# Required Settings
tenant_id = "YOUR_TENANT_ID"          # Your 10-character tenant ID
api_key = "YOUR_API_KEY"              # Your API key (starts with nw_sk_)

# Collection Settings
collection_interval = 60               # Metrics submission interval in seconds (10-300)
log_level = "info"                    # Log level: debug, info, warn, error

# Monitoring Options (all enabled by default)
enable_cpu = true
enable_memory = true
enable_disk = true
enable_system = true
enable_containers = true               # Docker/Podman/Containerd monitoring
enable_vms = false                    # VM monitoring (KVM, Proxmox, etc)
enable_updates = false                # System updates monitoring

# Container Monitoring
container_runtime = "auto"            # auto, docker, podman, containerd
container_socket = "/var/run/docker.sock"
container_stats_interval = "60s"

# Virtual Machine Monitoring
vm_hypervisor = "auto"                # auto, proxmox, libvirt, kvm, xen, qemu
vm_stats_interval = "60s"

# Proxmox Configuration (if using Proxmox)
proxmox_api = "https://proxmox.example.com:8006"
proxmox_username = "monitoring@pve"
proxmox_password = "your_password"
# OR use token authentication:
# proxmox_token_id = "monitoring@pve!token"
# proxmox_token_secret = "your_token_secret"
proxmox_node = ""                     # Empty for all nodes
proxmox_skip_tls_verify = false

# Database Monitoring
enable_postgresql = false
postgresql_host = "localhost:5432"
postgresql_user = "monitoring"
postgresql_password = "secret"
postgresql_database = "postgres"

enable_mysql = false
mysql_host = "localhost:3306"
mysql_user = "monitoring"
mysql_password = "secret"

# Process Monitoring
enable_process_monitoring = true
process_cpu_threshold = 1.0           # Min CPU % to track
process_memory_threshold = 50          # Min memory MB to track
max_tracked_processes = 100

Verifying Installation

After installation, verify the agent is running correctly:

Check Service Status

bash
sudo systemctl status netwarden

You should see output similar to:

● netwarden.service - Netwarden Monitoring Agent
   Active: active (running) since Mon 2024-01-15 12:00:00 UTC; 1h 23min ago
 Main PID: 12345 (netwarden)
   Status: "Collecting and sending metrics"
   Memory: 45.2M
   CGroup: /system.slice/netwarden.service
           └─12345 /usr/bin/netwarden

Check Logs

bash
sudo tail -f /var/log/netwarden/agent.log

Test Connection

bash
curl -I https://api.netwarden.com/health

You should see:

HTTP/2 200
date: Mon, 15 Jan 2024 14:23:45 GMT
content-type: application/json
content-length: 15

Troubleshooting

Agent Not Starting

  1. Check the logs for errors:
bash
sudo journalctl -u netwarden -n 50
  1. Verify the configuration file:
bash
cat /etc/netwarden/netwarden.conf | grep -E '^(tenant_id|api_key)'

Connection Issues

  1. Test network connectivity:
bash
curl -I https://api.netwarden.com/health
  1. Check firewall rules:
bash
sudo iptables -L -n | grep 443

High Resource Usage

Adjust the monitoring interval and disable unnecessary collectors in the configuration file.

Uninstallation

Linux (DEB-based)

bash
sudo apt remove --purge netwarden

Linux (RPM-based)

bash
sudo yum remove netwarden

Docker

bash
docker stop netwarden && docker rm netwarden

macOS

bash
brew services stop netwarden && brew uninstall netwarden

Next Steps

Was this page helpful?

Help us improve our documentation

Edit on GitHubReport an Issue