Astra - Enterprise Network Monitoring Made Simple

Overview

The Astra agent is a lightweight service that runs on your systems to collect and report network metrics — latency, jitter, packet loss, uptime, ISP, and public IP — back to the platform. This guide covers downloading and installing the agent 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.

Step 1: Download the Agent

Agent packages are distributed through your portal. Log in to your dashboard and navigate to Settings → Agents. You'll see a setup page with platform tabs — select your operating system.

Dashboard → Settings → Agents

1.Select your platform tab: Windows, Linux, or macOS

2.Under Step 1, click the download button to get the agent package ZIP for your platform

3.Your Agent API Key and pre-filled configuration are shown on the same page — copy these for the next step

ℹ️

The agent package is a ZIP archive containing the agent binary and a sample config.toml. Extract it to your preferred location before proceeding.

System Requirements

🪟 Windows

Windows 10/11 or Server 2016+
x64 architecture
50 MB disk space
Outbound HTTPS (port 443)

🐧 Linux

Ubuntu 20.04+, Debian 11+
Fedora 38+, CentOS Stream 9+, RHEL 8+
Arch Linux / Manjaro
openSUSE Leap 15+ / Tumbleweed
Alpine Linux 3.18+
x64 architecture
50 MB disk space
Outbound HTTPS (port 443)
wget and unzip (see Step 0)

🍎 macOS

macOS 11 (Big Sur) or later
Apple Silicon (aarch64) or Intel (x64)
50 MB disk space
Outbound HTTPS (port 443)

Windows Installation

1. Extract the Package

Extract the downloaded ZIP to a permanent location, such as C:\Program Files\AstraNetmon.

2. Create Configuration File

Create or edit config.toml in the extracted directory. Your API key and base URL are available on the Agent Setup page in your portal.

toml

api_base_url = "https://your-org.astraid.io"
api_key = "YOUR_AGENT_API_KEY_HERE"
local_db_path = "./local_metrics.db"

[agent_config]
targets = ["8.8.8.8", "1.1.1.1"]
poll_interval_secs = 300
traceroute_interval_secs = 300
speedtest_interval_secs = 3600
service_test_interval_secs = 300
public_ip_check_interval_secs = 1800

[[agent_config.services_to_test]]
name = "DNS Server"
service_type = "dns"
host = "8.8.8.8"
port = 53

⚠️

Replace your-org.astraid.io with your tenant subdomain and YOUR_AGENT_API_KEY_HERE with your actual API key. The api_base_url should be the base URL only — do not include /api/agents.

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

text

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

Service Management

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

0. Install Prerequisites

Three packages are required before installing the agent. wget downloads the package, unzip extracts it, and traceroute provides hop-by-hop path data. None are guaranteed to be pre-installed — run the command for your distribution before proceeding.

Ubuntu / Debian(apt)

bash

sudo apt update && sudo apt install -y wget unzip traceroute

Fedora(dnf)

bash

sudo dnf install -y wget unzip traceroute

CentOS Stream / RHEL 8+(dnf)

bash

sudo dnf install -y wget unzip traceroute

CentOS 7 / RHEL 7: replace dnf with yum

Arch Linux / Manjaro(pacman)

bash

sudo pacman -S --noconfirm wget unzip traceroute

openSUSE(zypper)

bash

sudo zypper install -y wget unzip traceroute

Alpine Linux(apk)

bash

sudo apk add wget unzip traceroute

Alpine uses OpenRC instead of systemd. The service setup step below includes Alpine-specific instructions.

1. Extract and Place the Binaries

The install package contains two binaries: astra-netmon-agent (the monitoring agent) and astra-updater (handles automatic updates). Both must be installed.

bash

# Extract the package
unzip astra-netmon-linux_x64.zip -d astra-netmon

# Move both binaries
sudo mv astra-netmon/astra-netmon-agent /usr/local/bin/astra-netmon-agent
sudo mv astra-netmon/astra-updater      /usr/local/bin/astra-updater

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

2. Create Configuration

bash

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

# Create config file
sudo tee /etc/astranetmon/config.toml > /dev/null << 'EOF'
api_base_url = "https://your-org.astraid.io"
api_key = "YOUR_AGENT_API_KEY_HERE"
local_db_path = "/var/lib/astranetmon/local_metrics.db"

[agent_config]
targets = ["8.8.8.8", "1.1.1.1"]
poll_interval_secs = 300
traceroute_interval_secs = 300
speedtest_interval_secs = 3600
service_test_interval_secs = 300
public_ip_check_interval_secs = 1800

[[agent_config.services_to_test]]
name = "DNS Server"
service_type = "dns"
host = "8.8.8.8"
port = 53
EOF

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

3. Create a Dedicated Service User

Avoid running the agent as root. Create a locked-down system account that owns the agent files:

bash

# Create a system account (no login shell, no home directory)
sudo useradd --system --no-create-home --shell /usr/sbin/nologin astranetmon

# Hand ownership of the config directory to the new user
sudo chown -R astranetmon:astranetmon /etc/astranetmon
sudo chmod 750 /etc/astranetmon
sudo chmod 640 /etc/astranetmon/config.toml

# Create and own the data directory used for the local SQLite cache
sudo mkdir -p /var/lib/astranetmon
sudo chown astranetmon:astranetmon /var/lib/astranetmon

4. Create and Start the Service

Most distributions use systemd. Alpine Linux uses OpenRC — see the Alpine tab below.

systemdUbuntu, Debian, Fedora, CentOS/RHEL, Arch, openSUSE

bash

sudo tee /etc/systemd/system/astranetmon-agent.service > /dev/null << 'EOF'
[Unit]
Description=AstraNetmon Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=astranetmon
Group=astranetmon
ExecStart=/usr/local/bin/astra-netmon-agent --config /etc/astranetmon/config.toml
Restart=always
RestartSec=10
# KillMode=process ensures only the main process is signalled on stop/restart.
# This allows the astra-updater child process to survive the service restart
# and complete the binary swap before systemd starts the new version.
KillMode=process
StandardOutput=journal
StandardError=journal

# CAP_NET_RAW is required for raw ICMP sockets (ping/latency monitoring).
# AmbientCapabilities grants this to the unprivileged service user without
# running as root. NoNewPrivileges still applies after exec.
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW

# Harden the service
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/astranetmon

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now astranetmon-agent

# Verify
sudo systemctl status astranetmon-agent

OpenRCAlpine Linux

bash

sudo tee /etc/init.d/astranetmon-agent > /dev/null << 'EOF'
#!/sbin/openrc-run
name="astranetmon-agent"
description="AstraNetmon Agent"
command="/usr/local/bin/astra-netmon-agent"
command_args="--config /etc/astranetmon/config.toml"
user="astranetmon"
group="astranetmon"
pidfile="/run/astranetmon-agent.pid"
command_background=yes
depend() {
    need net
    after firewall
}
EOF

sudo chmod +x /etc/init.d/astranetmon-agent
sudo rc-update add astranetmon-agent default
sudo rc-service astranetmon-agent start

# Verify
sudo rc-service astranetmon-agent status

5. View Logs

systemd distros

bash

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

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

Alpine Linux (OpenRC)

bash

sudo rc-service astranetmon-agent status

Service Management

systemd distros

bash

sudo systemctl stop    astranetmon-agent
sudo systemctl restart astranetmon-agent
sudo systemctl disable astranetmon-agent

Alpine Linux (OpenRC)

bash

sudo rc-service astranetmon-agent stop
sudo rc-service astranetmon-agent restart
sudo rc-update del astranetmon-agent default

macOS Installation

1. Extract and Place the Binary

bash

# Extract the package (Apple Silicon)
unzip astra-netmon-macos_aarch64.zip -d astra-netmon

# Or for Intel Macs
unzip astra-netmon-macos_x64.zip -d astra-netmon

# Move binary to system path
sudo mv astra-netmon/astra-netmon-agent /usr/local/bin/astra-netmon-agent
sudo chmod +x /usr/local/bin/astra-netmon-agent

2. Create Configuration

bash

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

# Create config file
sudo tee /etc/astranetmon/config.toml > /dev/null << 'EOF'
api_base_url = "https://your-org.astraid.io"
api_key = "YOUR_AGENT_API_KEY_HERE"
local_db_path = "/var/lib/astranetmon/local_metrics.db"

[agent_config]
targets = ["8.8.8.8", "1.1.1.1"]
poll_interval_secs = 300
traceroute_interval_secs = 300
speedtest_interval_secs = 3600
service_test_interval_secs = 300
public_ip_check_interval_secs = 1800

[[agent_config.services_to_test]]
name = "DNS Server"
service_type = "dns"
host = "8.8.8.8"
port = 53
EOF

3. Create LaunchDaemon

bash

sudo tee /Library/LaunchDaemons/com.astranetmon.agent.plist > /dev/null << '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

tail -f /var/log/astranetmon-agent.log

Service Management

bash

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

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

Configuration Reference

All available options in config.toml:

Option	Required	Description
api_base_url	Yes	Your tenant base URL (e.g., https://your-org.astraid.io). Do not include /api/agents.
api_key	Yes	Agent API key from Dashboard → Settings → Agents
local_db_path	No	Path for local SQLite cache (offline metric storage). Default: ./local_metrics.db
agent_config.targets	No	Target IPs or hostnames for latency/jitter/packet-loss monitoring
agent_config.poll_interval_secs	No	Ping metrics polling interval in seconds (default: 300)
agent_config.speedtest_interval_secs	No	Speed test interval in seconds (default: 3600)
agent_config.traceroute_interval_secs	No	Traceroute interval in seconds (default: 300)
agent_config.public_ip_check_interval_secs	No	How often to refresh public IP and ISP detection (default: 1800)
agent_config.services_to_test	No	List of services to test for reachability (each with name, service_type, host, port)

Verification

After installing and starting the agent:

Check the service is running using the platform-specific status command above
Review logs to confirm no errors on startup
Navigate to Dashboard → Agents
Your agent should appear with a green "Online" status within 1–2 minutes

✅

Once online, metrics start flowing immediately. Click the agent name to view real-time latency, jitter, and packet loss graphs.

Troubleshooting

Agent Not Appearing Online

Verify the API key is correct in the config file (compare with dashboard)
Check api_base_url matches your tenant subdomain
Ensure outbound HTTPS (port 443) is not blocked by a firewall
Review agent logs for connection errors

Service Won't Start

Check config file syntax (valid TOML format)
Verify file permissions on the config file and binary
Review service/system logs for startup errors

Permission Denied / Status 203 on CentOS or RHEL (SELinux)

CentOS Stream and RHEL run SELinux in enforcing mode by default. Binaries extracted into /opt or other non-standard paths inherit an unlabelled file context that SELinux will block from executing. The symptom is Failed at step EXEC … Permission denied in the journal even though the file permissions are correct.

Run restorecon after placing the files to apply the correct context:

bash

sudo restorecon -Rv /opt/astra-netmon/
# or, if using /usr/local/bin:
sudo restorecon -v /usr/local/bin/astra-netmon-agent /usr/local/bin/astra-updater

Then restart the service:

bash

sudo systemctl restart astranetmon-agent

Ping / Latency Data Not Appearing (Linux)

The agent uses raw ICMP sockets for ping, which require the CAP_NET_RAW Linux capability. Running the agent as a non-root user without this capability causes the ping monitor to fail silently at startup — the agent stays online but reports no latency or jitter data.

The systemd unit in the installation steps above already includes the required lines. If you installed the service manually or from an older version, add them under [Service]:

ini

AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW

Then reload and restart:

bash

sudo systemctl daemon-reload
sudo systemctl restart astranetmon-agent

To confirm the capability is active after restart:

bash

# Should show cap_net_raw in the Ambient set
cat /proc/$(systemctl show -p MainPID --value astranetmon-agent)/status | grep -i cap

Traceroute Errors (Linux)

If you see Traceroute failed: No such file or directory in the agent logs, neither traceroute nor tracepath is installed. The agent automatically falls back to tracepath if traceroute is not found — install whichever is available for your distro:

bash

# Ubuntu / Debian
sudo apt install traceroute

# Fedora / CentOS / RHEL
sudo dnf install traceroute

# Arch Linux / Manjaro
sudo pacman -S traceroute

# openSUSE
sudo zypper install traceroute

# Alpine Linux
sudo apk add traceroute

No service restart is needed — the agent probes for the binary on each traceroute cycle.

For more help, see the Troubleshooting Guide.

Agent Installation

Overview

Step 1: Download the Agent

System Requirements

🪟 Windows

🐧 Linux

🍎 macOS

Windows Installation

1. Extract the Package

2. Create Configuration File

3. Install as Windows Service

4. View Logs

Service Management

Linux Installation

0. Install Prerequisites

1. Extract and Place the Binaries

2. Create Configuration

3. Create a Dedicated Service User

4. Create and Start the Service

5. View Logs

Service Management

macOS Installation

1. Extract and Place the Binary

2. Create Configuration

3. Create LaunchDaemon

4. Load and Start

5. View Logs

Service Management

Configuration Reference

Verification

Troubleshooting

Agent Not Appearing Online

Service Won't Start

Permission Denied / Status 203 on CentOS or RHEL (SELinux)

Ping / Latency Data Not Appearing (Linux)

Traceroute Errors (Linux)

Next Steps

→ Monitoring Features

→ Configure Alerts

→ API Access

→ Troubleshooting