Installation Guide

Quick Start

Download and run the install script on the target machine:

wget -O install.sh https://files.threatsabre.com/ts-agent/install.sh
chmod +x install.sh
sudo ./install.sh --name myagent

You will be prompted to enter your AGENT_TOKEN. To obtain a token, see Obtaining Your Agent Token.

Prerequisites

Before installing, ensure your system meets the Requirements.

Installation

Interactive Installation

The simplest method. The script will prompt for the AGENT_TOKEN:

wget -O install.sh https://files.threatsabre.com/ts-agent/install.sh
chmod +x install.sh
sudo ./install.sh --name myagent

Replace myagent with a meaningful name for this Agent instance (e.g. dc1-agent, prod-scanner). Names may only contain letters, numbers, hyphens, and underscores.

Automated Installation (CI/CD)

For non-interactive deployments, store the token in your CI/CD secret manager and inject it as the AGENT_TOKEN environment variable at runtime:

wget -O install.sh https://files.threatsabre.com/ts-agent/install.sh
chmod +x install.sh
sudo AGENT_TOKEN="$AGENT_TOKEN" ./install.sh --name myagent

Avoid hard-coding the token in scripts, pipeline configuration, logs, or shell history.

Pinning a Specific Version

By default the script installs the latest available version. To install a specific version:

sudo ./install.sh --name myagent --version 0.0.7

What the Script Does

The installer performs the following steps automatically:

1. Detects whether the system uses glibc or musl and downloads the correct binary
2. Detects the init system (systemd or OpenRC) and creates the appropriate service file
3. On Alpine, checks for libstdc++ and offers to install it if missing
4. Creates the directory structure, configuration file, and service
5. Enables and starts the Agent service

Directory Layout

After installation, files are organized as follows:

Configuration File

The configuration file at /etc/threatsabre-agent/<name>/agent.conf contains:

The file is created with mode 600 (readable only by root) to protect the token.

These are the settings most deployments need. Additional advanced settings — for tuning timeouts, polling, and FortiManager batching — are available in Advanced Configuration Settings under Troubleshooting.

Managing Multiple Instances

You can run multiple Agent instances on the same machine by installing with different names. Each instance gets its own configuration, logs, and service, while sharing the same binary.

sudo ./install.sh --name network-a
sudo ./install.sh --name network-b

This creates two independent services: threatsabre-agent-network-a and threatsabre-agent-network-b, each with its own AGENT_TOKEN and log file.

Upgrading

To upgrade the Agent binary to the latest version:

sudo ./install.sh --upgrade

To upgrade to a specific version:

sudo ./install.sh --upgrade --version 0.0.8

The upgrade process:

1. Downloads the new binary before stopping any services (minimises downtime)
2. Stops all running instances
3. Backs up the current binary
4. Installs the new binary
5. Restarts all instances
6. Verifies each instance is running

If the script reports that instances failed to start after the upgrade, use --rollback to revert.

Rolling Back

If an upgrade causes issues, revert to the previous version:

sudo ./install.sh --rollback

This restores the binary that was in use before the last upgrade and restarts all instances.

Checking Status

To view all installed instances and their current state:

sudo ./install.sh --status

This displays:

• Installed binary version
• Whether a backup is available for rollback
• Each instance name, running state, and configuration path

Uninstalling

To remove a specific instance:

sudo ./install.sh --uninstall --name myagent

This stops the service, removes the service file, configuration directory, and log directory for that instance. If no other instances remain, the script will ask whether to remove the shared binary as well.

Service Management

After installation, you can manage each instance using standard system commands.

systemd (Ubuntu)

OpenRC (Alpine)

Replace <name> with your Agent instance name (e.g. myagent).

Logging

Agent logs are written to /var/log/threatsabre-agent/<name>/agent.log.

To follow logs in real time:

sudo tail -f /var/log/threatsabre-agent/<name>/agent.log

The install script itself writes a detailed log to /tmp/threatsabre-install-*.log during each run. If an installation or upgrade fails, check this file for diagnostic details.

Troubleshooting

"libstdc++ is required but not installed"

Alpine Linux requires the GNU Standard C++ Library. Install it manually:

apk add libstdc++

Then re-run the install script.

"AGENT_TOKEN must be set as an environment variable in non-interactive mode"

This occurs when running the script without a terminal (e.g. in a CI/CD pipeline) and without setting the AGENT_TOKEN environment variable. Pass the token via the environment:

sudo AGENT_TOKEN="your_token_here" ./install.sh --name myagent

"This script must be run as root"

The script requires root privileges to create system directories, service files, and manage services. Run it with sudo or as the root user directly.

"Failed to download Agent"

Verify the machine has outbound HTTPS access to https://files.threatsabre.com on port 443. Check the install log (path printed on failure) for the specific HTTP error.

"Instance already exists"

An instance with that name is already installed. Either choose a different name, or uninstall the existing instance first:

sudo ./install.sh --uninstall --name myagent
sudo ./install.sh --name myagent

Service Fails to Start After Upgrade

If the new version fails to start, roll back immediately:

sudo ./install.sh --rollback

Then check the Agent log at /var/log/threatsabre-agent/<name>/agent.log for errors before attempting the upgrade again.

Advanced Configuration Settings

Beyond the core settings in the Configuration File, the following optional variables can be added to /etc/threatsabre-agent/<name>/agent.conf to tune logging, polling, and FortiManager batching. The defaults suit most deployments — adjust these only when diagnosing performance or timeout issues, such as slow FortiManager responses or large device configurations.

After changing any of these values, restart the affected instance for the new settings to take effect (see Service Management).