Documentation

Welcome to the NodeGuarder documentation. Learn how to install, configure, and master your Linux monitoring.

Quick Start

Get the full dashboard stack running in less than 2 minutes using Docker.

# 1. Clone the repo
git clone https://github.com/nodeguarder/nodeguarder.git
cd nodeguarder/deploy

# 2. Start the dashboard (Dev/HTTP)
docker compose up -d

# 3. Access the UI
# URL: http://localhost:8080
# Default User: admin
# Default Password: admin (required change on first login)

For production (HTTPS): Use docker-compose.customer.yml with valid SSL certificates. See the Installation Guide for details.

Agent Installation

Once your dashboard is running, you can add servers using the one-line installer or manual binary download.

Method 1: One-Line Installer (Recommended)

Log in to your Dashboard (e.g., http://localhost:8080).
Navigate to Distribute Agent in the sidebar.

Copy the provided installer command. It will look similar to:

curl -sfL https://your-dashboard.com/api/v1/agent/package/bash?token=YOUR_TOKEN | sudo bash -s -- --dashboard-url https://your-dashboard.com

Run this command on your target Linux servers (Ubuntu, Debian, CentOS, RHEL).
The agent will automatically install, configure, and connect to your dashboard.

Method 2: Manual Binary Download

Log in to your Dashboard.
Go to Distribute Agent in the sidebar.
Click Download Binary for your architecture (AMD64 or ARM64).
Transfer the binary to your server.

Create a config.yaml file:

server_id: "server-unique-id"
api_secret: "generated-secret"
dashboard_url: "https://your-dashboard.com"
registration_token: "YOUR_TOKEN"

Run: sudo ./nodeguarder-agent --config config.yaml

Note: The agent runs as a systemd service and automatically starts on system reboot.

Health Monitoring

NodeGuarder monitors CPU, RAM, and Disk metrics every 60 seconds.

Sustain Duration

To prevent alerting on momentary spikes (like a compile job), we use a Sustain Duration (default: 30s). A metric must exceed the threshold for this entire duration to trigger an alert.

Stability Window

To prevent flapping (rapid alert → resolved → alert cycles), we use a Stability Window (default: 120s). After a server recovers from a critical or offline state, it must remain healthy for this duration before a "Resolved" notification is sent.

Metric	Default Warning	Default Critical
CPU Usage	80%	95%
Memory	80%	95%
Disk Usage	80%	95%

Cron Monitoring

Our eBPF-based monitor detects cron jobs without any wrapper scripts.

Timeouts

Global Max Runtime: A safety net for all jobs (e.g., alert if any job runs > 5 hours).
Alert After (Override): Specific timeout for a specific job (e.g., `backup.sh` should take 5 mins).

Ignoring Errors

Some scripts are designed to fail safely. You can ignore specific exit codes (e.g., `1`, `42`) in the Global Configuration settings.

Drift Detection (FIM)

Drift detection monitors file hashes in `/etc` (or configured paths) to detect unauthorized changes.

Ignore Patterns

You can ignore noisy files using glob patterns:

`*.tmp` - Ignores all .tmp files.
`kubernetes/*` - Ignores specific subdirectories.

Offline Detection

The dashboard expects a heartbeat every minute. By default, if a server is silent for 120 seconds, it is marked as Offline.

You can adjust this timeout in Settings > Global Config if your network is unstable.

FAQ

Is NodeGuarder fully open source?

Yes. The agent is 100% open source under the MIT license. The dashboard has a Community Edition that is free forever for up to 5 servers.

Do I need to install a database?

No. The dashboard comes with an embedded SQLite database for zero-config deployments. It is designed to be self-contained.

Does it work on ARM/Raspberry Pi?

Yes! We provide multi-arch Docker images and binaries for both AMD64 and ARM64.

How do I update the agent?

The agent automatically checks for updates from your dashboard every hour. When you update your dashboard (by pulling the new Docker image), your agents will self-update automatically. You can also manually force an update by re-running the install script.

How do I uninstall the agent?

You have three options:

From Dashboard: Go to the Server Details page and click "Delete & Uninstall". The agent will self-destruct on its next check-in.
Script: Run sudo /opt/nodeguarder-agent/uninstall.sh on the server.
Manual: Stop the service and remove the files manually.

If you prefer to remove it manually:

sudo systemctl stop nodeguarder-agent
sudo systemctl disable nodeguarder-agent
sudo rm /etc/systemd/system/nodeguarder-agent.service
sudo systemctl daemon-reload
sudo rm -rf /opt/nodeguarder-agent