AstraNetmon

Agent Installation

Install and configure AstraNetmon monitoring agents on Windows, Linux, and macOS

Overview

The AstraNetmon agent is a lightweight service that runs on your systems to collect and report metrics. This guide covers installation on all supported platforms.

ℹī¸

Before you begin: You'll need your Agent API Key from the dashboard. Navigate to Dashboard → Settings → Agents to find it.

System Requirements

đŸĒŸ Windows

  • Windows 10/11 or Server 2016+
  • 50 MB disk space
  • Internet connection

🐧 Linux

  • Ubuntu 20.04+, Debian 11+, RHEL 8+
  • 50 MB disk space
  • Internet connection

🍎 macOS

  • macOS 11 (Big Sur) or later
  • 50 MB disk space
  • Internet connection

Windows Installation

1. Download the Agent

Download the Windows agent executable from your dashboard or directly:

powershell
# Using PowerShell
Invoke-WebRequest -Uri "https://your-domain.com/downloads/astra-netmon-agent.exe" -OutFile "astra-netmon-agent.exe"

2. Create Configuration File

Create a config.toml file in the same directory as the agent:

toml
api_url = "https://your-domain.astraid.io/api/agent"
api_key = "YOUR_AGENT_API_KEY_HERE"
poll_interval = 60
speedtest_enabled = true
speedtest_interval = 3600
traceroute_enabled = true
traceroute_targets = ["8.8.8.8", "1.1.1.1"]
⚠ī¸

Replace YOUR_AGENT_API_KEY_HERE with your actual API key from the dashboard.

3. Install as Windows Service

Run PowerShell as Administrator and execute:

powershell
# Install the service
.\astra-netmon-agent.exe install

# Start the service
Start-Service "AstraNetmon Agent"

# Verify it's running
Get-Service "AstraNetmon Agent"

4. View Logs

Logs are written to:

text
C:\ProgramData\AstraNetmon\logs\agent.log

Service Management

Common service commands:

powershell
# Stop the service
Stop-Service "AstraNetmon Agent"

# Restart the service
Restart-Service "AstraNetmon Agent"

# Uninstall the service
.\astra-netmon-agent.exe uninstall

Linux Installation

1. Download the Agent

Download the Linux agent binary:

bash
# Download
wget https://your-domain.com/downloads/astra-netmon-agent-linux -O /usr/local/bin/astra-netmon-agent

# Make executable
chmod +x /usr/local/bin/astra-netmon-agent

2. Create Configuration

Create the configuration directory and file:

bash
# Create config directory
sudo mkdir -p /etc/astranetmon

# Create config file
sudo cat > /etc/astranetmon/config.toml << 'EOF'
api_url = "https://your-domain.astraid.io/api/agent"
api_key = "YOUR_AGENT_API_KEY_HERE"
poll_interval = 60
speedtest_enabled = true
speedtest_interval = 3600
traceroute_enabled = true
traceroute_targets = ["8.8.8.8", "1.1.1.1"]
EOF

# Set permissions
sudo chmod 600 /etc/astranetmon/config.toml

3. Create Systemd Service

Create a systemd service file:

bash
sudo cat > /etc/systemd/system/astranetmon-agent.service << 'EOF'
[Unit]
Description=AstraNetmon Agent
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/astra-netmon-agent --config /etc/astranetmon/config.toml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

4. Start the Service

bash
# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start on boot
sudo systemctl enable astranetmon-agent

# Start the service
sudo systemctl start astranetmon-agent

# Check status
sudo systemctl status astranetmon-agent

5. View Logs

bash
# View recent logs
sudo journalctl -u astranetmon-agent -n 50

# Follow logs in real-time
sudo journalctl -u astranetmon-agent -f

Service Management

Common service commands:

bash
# Stop the service
sudo systemctl stop astranetmon-agent

# Restart the service
sudo systemctl restart astranetmon-agent

# Disable auto-start
sudo systemctl disable astranetmon-agent

macOS Installation

1. Download the Agent

bash
# Download
curl -L https://your-domain.com/downloads/astra-netmon-agent-macos -o /usr/local/bin/astra-netmon-agent

# Make executable
chmod +x /usr/local/bin/astra-netmon-agent

2. Create Configuration

bash
# Create config directory
sudo mkdir -p /etc/astranetmon

# Create config file
sudo cat > /etc/astranetmon/config.toml << 'EOF'
api_url = "https://your-domain.astraid.io/api/agent"
api_key = "YOUR_AGENT_API_KEY_HERE"
poll_interval = 60
speedtest_enabled = true
speedtest_interval = 3600
traceroute_enabled = true
traceroute_targets = ["8.8.8.8", "1.1.1.1"]
EOF

3. Create LaunchDaemon

Create a launchd plist file:

bash
sudo cat > /Library/LaunchDaemons/com.astranetmon.agent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.astranetmon.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/astra-netmon-agent</string>
        <string>--config</string>
        <string>/etc/astranetmon/config.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/astranetmon-agent.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/astranetmon-agent-error.log</string>
</dict>
</plist>
EOF

# Set permissions
sudo chmod 644 /Library/LaunchDaemons/com.astranetmon.agent.plist

4. Load and Start

bash
# Load the daemon
sudo launchctl load /Library/LaunchDaemons/com.astranetmon.agent.plist

# Check if it's running
sudo launchctl list | grep astranetmon

5. View Logs

bash
# View stdout logs
tail -f /var/log/astranetmon-agent.log

# View error logs
tail -f /var/log/astranetmon-agent-error.log

Service Management

bash
# Stop the daemon
sudo launchctl unload /Library/LaunchDaemons/com.astranetmon.agent.plist

# Start the daemon
sudo launchctl load /Library/LaunchDaemons/com.astranetmon.agent.plist

# Restart
sudo launchctl unload /Library/LaunchDaemons/com.astranetmon.agent.plist
sudo launchctl load /Library/LaunchDaemons/com.astranetmon.agent.plist

Configuration Options

Available configuration options in config.toml:

OptionTypeRequiredDescription
api_urlstringYesAPI endpoint URL
api_keystringYesYour agent API key
poll_intervalintegerNoMetrics polling interval (seconds, default: 60)
speedtest_enabledbooleanNoEnable speed tests (default: false)
speedtest_intervalintegerNoSpeed test interval (seconds, default: 3600)
traceroute_enabledbooleanNoEnable traceroute (default: false)
traceroute_targetsarrayNoTarget IPs for traceroute
ℹī¸

For more advanced configuration options, see the Agent Configuration Guide.

Verification

After installation, verify the agent is working:

  1. Check the service is running using the platform-specific status command above
  2. Review logs to ensure no errors
  3. Navigate to Dashboard → Agents in the web interface
  4. Your agent should appear with a green "Online" status within 1-2 minutes
✅

Agent is online! You should start seeing metrics in the dashboard within a few minutes.

Troubleshooting

Agent Not Appearing Online

  • Verify the API key is correct in the config file
  • Check that the API URL matches your AstraNetmon domain
  • Ensure the agent has internet access
  • Review agent logs for connection errors
  • Verify firewall rules allow outbound HTTPS connections

Service Won't Start

  • Check config file syntax (valid TOML format)
  • Verify file permissions on the config file
  • Ensure the agent binary is executable
  • Review service logs for startup errors

High Resource Usage

  • Increase the poll_interval to reduce metric collection frequency
  • Disable speed tests if not needed
  • Reduce the number of traceroute targets

For more help, see the Troubleshooting Guide.

Next Steps

→ Advanced Configuration

Customize agent behavior and features

→ Monitoring Features

Learn about available monitoring capabilities

→ Configure Alerts

Set up notifications and webhooks

→ API Access

Access your data programmatically