Skip to content

Install agent and collector

Open in the platform

Step-by-step guide to deploy an agent on a monitored host or stand up a local collector on a machine inside the customer network. The platform produces packaged installers, per OS and version, already bound to the collector you picked.

For the concepts (agent vs collector, cloud collector vs local), see Agents & Hubs.

Where to find the package

  1. Open Administration → Agents & Hubs.
  2. On the row of the collector that will receive the hosts: hover Agent and pick Windows or Linux, or click Collector (only on local collectors) for the collector page.
  3. The platform opens the list of supported distributions. Click a distribution/version to see the steps prepared, with the URL and package name already generated.

The package is specific to the tenant + collector pair

The file name embeds the picked collector. Downloading a package from collector A and installing it pointing to collector B will not work: each agent is bound to the originating collector.

Common prerequisites

  • Connectivity from the host to the collector (agent port).
  • Working DNS, if the collector address is an FQDN.
  • root (Linux) or Administrator (Windows) access on the agent host.
  • Operating system in the supported list (see tables below).

Linux agent

Supported distributions and architectures:

Family Versions Architectures
RHEL 7, 8, 9 x86_64
Debian 9, 10, 11, 12, 13 9 x86_64 only; 10 and up x86_64 and arm64
Ubuntu 18.04, 20.04, 22.04, 24.04 18.04 x86_64 only; 20.04 and up x86_64 and arm64

RHEL family

Applies to RHEL 7, 8 and 9 (and binary derivatives like Rocky and Alma).

Step 1. Install system dependencies:

sudo yum install -y \
  unixODBC-devel \
  net-snmp-devel \
  OpenIPMI-devel \
  c-ares \
  libevent-devel \
  curl

Step 2. Download the package. Use the Download link on the agent page or copy the curl -L -O the platform already generates with the URL and the package name ready for your collector.

Step 3. Install:

sudo rpm -ivh "<package-name>.rpm"

The package name follows <collector>_specialone-agent-rhel<version>-el<version>.<agent-version>-1.x86_64.rpm. The platform copies the exact name to you in step 3.

Debian and Ubuntu family

Same procedure for Debian 9 through 13 and Ubuntu 18.04 through 24.04.

Step 1. Refresh repositories and install dependencies:

sudo apt update && sudo apt install -y \
  unixodbc-dev \
  libsnmp-dev \
  libopenipmi-dev \
  libc-ares2 \
  libevent-dev \
  curl

Step 2. Download the package via the Download link or the curl -L -O from the page.

Step 3. Install:

sudo dpkg -i "<package-name>.deb"

Package name patterns:

  • Debian: <collector>_specialone-agent-debian<X>_<version>.<codename>_<arch>.deb
  • Ubuntu: <collector>_specialone-agent-ubuntu<X.YY>_<version>.<codename>_<arch>.deb

Codenames in use:

Version Codename
Debian 9 stretch
Debian 10 buster
Debian 11 bullseye
Debian 12 bookworm
Debian 13 trixie
Ubuntu 18.04 bionic
Ubuntu 20.04 focal
Ubuntu 22.04 jammy
Ubuntu 24.04 noble

ARM64 available

For Raspberry Pi, ARM Servers and ARM clouds (Graviton, Ampere), pick the ARM64 option on step 2. Available on Debian 10+ and Ubuntu 20.04+.

Use the matching distribution package

A bookworm package installed on a bullseye host fails due to glibc dependency mismatch. Confirm the target codename before downloading.

Windows agent

Two variants on the download page:

  • Windows Server: 2016, 2019, 2022.
  • Windows Desktop: 10 and 11.

The flow is the same for both, only the package name differs.

Step 1. Download the package.

By browser: Download link on the agent page.

By PowerShell (Administrator session):

Invoke-WebRequest `
  -Uri "<platform-generated-url>" `
  -OutFile "<package-name>.zip"

Step 2. Install:

Expand-Archive "<package-name>.zip" -DestinationPath .
# Run as Administrator:
.\SpecialOne Agent Install.bat

Package name patterns:

  • Windows Server: <collector>_specialone-agent-x86_64.zip
  • Windows Desktop: <collector>_specialone-agent_desktop-x86_64.zip

Run as Administrator

The .bat registers a service, installs the agent under C:\Program Files\SpecialOne\Agent, and configures autostart. Without Administrator privilege the install fails silently (the archive extracts but the service is not created).

Distribution via GPO or MDM

For fleets, wrap the .zip in a distribution package (GPO on AD, Intune, MEM, JAMF for mixed clients). The collector name is part of the .zip, so the same package serves every host reporting to the same collector.

Local collector

The collector runs on Linux. For 100% Windows environments, the SpecialOne default cloud collector (pre-provisioned on every tenant) covers the use case.

Supported distributions for the collector package:

Family Versions
RHEL 9
Debian 11, 12
Ubuntu 20.04, 22.04, 24.04

Flow

Step 1. Register the collector under Agents & Hubs → New Collector (name and address).

Step 2. On the row of the new collector, click Collector.

Step 3. Pick the distribution of the machine that will host the collector.

Step 4. Download the package via the Download link.

Step 5. Install on the machine.

On RHEL 9:

sudo rpm -ivh "<collector>_specialone-collector-rhel9-...rpm"

On Debian or Ubuntu:

sudo dpkg -i "<collector>_specialone-collector-<distro>-...deb"

Step 6. Wait for the first communication: the collector status moves from Unknown to Online within 3 minutes.

Cloud collector has no package

The SpecialOne default cloud collector runs on platform infrastructure; it has no Collector button for download. Use it for synthetic checks against public targets without installing anything in the customer network.

Post-install validation

After installing the agent or collector, validate at 3 points.

1. Service status on the host

On Linux:

systemctl status specialone-agent
# expected: active (running)

systemctl status specialone-collector

On Windows: open services.msc, look for SpecialOne Agent, state Running.

2. Connectivity to the collector (agent only)

On Linux:

nc -vz <collector-address> <agent-port>

On Windows PowerShell:

Test-NetConnection -ComputerName <collector-address> -Port <agent-port>

3. Appearance on the platform

Open Infrastructure → Hosts and search the host by name. It should show up Online within 3 minutes (the platform auto-refresh window).

If after ~5 minutes the host is still Offline or missing, head to troubleshooting.

Troubleshooting

Agent installed but never goes Online

  • Host firewall: allow outbound to the collector address and the agent port.
  • Segment firewall: rules across VLANs, DMZ, datacenters or cloud VPCs.
  • DNS: if the collector was registered as an FQDN, the host must resolve it. Test with nslookup or Resolve-DnsName.
  • Agent log:
    • Linux: /var/log/specialone-agent/agent.log
    • Windows: C:\Program Files\SpecialOne\Agent\logs\agent.log

Package rejected by the package manager

  • RHEL with dependency error: run step 1 before rpm -ivh. Without unixODBC-devel, net-snmp-devel and OpenIPMI-devel the package will not install.

  • Debian/Ubuntu with pending dependencies: resolve with:

    sudo apt -f install

    Then retry dpkg -i.

  • Wrong distribution version: the package carries el8, bullseye, jammy, etc. in the name. Installing the RHEL 9 package on a RHEL 8 host fails due to glibc mismatch.

401 or 403 on curl

The download is authenticated. Running curl in a session that has no platform cookie returns 401/403. Fixes:

  • Download via the browser logged in and copy the file to the target machine (scp, S3, etc).
  • Run curl -L -O on a machine where you logged into the platform in the same session.

Reinstall after changing collector name or address

Editing the collector (name or address) forces reinstall on the agents. Flow:

  1. Under Agents & Hubs, edit the collector.
  2. Download the fresh package from the agent page, now with the updated name or address.
  3. Reinstall on the hosts. The installer detects the previous agent and updates the configuration (no need to uninstall first).

Windows: Install.bat finishes but the service is missing

Almost always a privilege issue:

  • Open PowerShell with Run as Administrator before running the .bat.
  • Check services.msc: the service SpecialOne Agent should exist and be Running.
  • If missing, run the .bat again as Administrator.

Next steps

  • Agents & Hubs

    Registration and management screen for the collectors that receive the agents.

    Back to Agents & Hubs

  • Hosts

    Register hosts and assign them to the responsible collector.

    Open Hosts

  • Concepts

    Platform vocabulary: agent, collector, monitoring profile.

    See Concepts