Installation¶

SenHub Agent is a monitoring collector that runs on your infrastructure and collects metrics from various sources (servers, applications, network devices). It installs as a system service and runs in the background.

System Requirements¶

Platform	Versions	Architecture
Windows	Server 2016+, Windows 10+	x64
Linux	RHEL 7+, Ubuntu 18.04+, Debian 10+	x64, ARM64

Resource requirements: 1 CPU core, 512 MB RAM, 500 MB disk space.

Network requirements: outbound HTTPS from the agent host to whichever sink you configure (Prometheus scraper, OTLP collector, vmagent, Grafana Cloud OTLP). For an agent that only exposes data through its local HTTPS endpoint, no outbound connection is required at all.

Obtaining the Agent¶

Contact SenHub support (support@senhub.io) or download from the GitHub releases page. You will receive:

The agent ZIP for your platform (see naming convention below)
A license token (required for premium probes: Citrix, NetScaler, Redfish, etc.)

Release Artifact Naming¶

Release artifacts are ZIP archives named with dashes between OS and architecture:

Platform	ZIP filename	Binary inside ZIP
Windows x86_64	`senhub-agent-windows-amd64.zip`	`senhub-agent.exe`
Linux x86_64	`senhub-agent-linux-amd64.zip`	`senhub-agent`
Linux ARM64	`senhub-agent-linux-arm64.zip`	`senhub-agent`
macOS Intel	`senhub-agent-darwin-amd64.zip`	`senhub-agent`
macOS Apple Silicon	`senhub-agent-darwin-arm64.zip`	`senhub-agent`

Each ZIP contains a binary already named senhub-agent (or senhub-agent.exe on Windows). No renaming is needed after extraction.

Windows Installation¶

1. Prepare the binary¶

Download senhub-agent-windows-amd64.zip, then extract it to your installation directory:

mkdir C:\SenHub
Expand-Archive .\senhub-agent-windows-amd64.zip -DestinationPath C:\SenHub\

The ZIP contains senhub-agent.exe, already correctly named.

2. Install the service¶

Open a PowerShell terminal as Administrator and run:

cd C:\SenHub\
.\senhub-agent.exe install

This registers SenHub Agent as a Windows Service with automatic restart on failure. A UUID agent key is generated automatically and saved to the configuration file.

To install with HTTPS enabled on the local API:

.\senhub-agent.exe install --enable-https --https-port 8443

3. Start the service¶

.\senhub-agent.exe start

4. Verify the installation¶

.\senhub-agent.exe status

You can also check the health endpoint:

Invoke-WebRequest -Uri "http://localhost:8080/health"

Expected response:

{"status":"ok","version":"0.1.87","uptime":"1m30s","probes_active":2,"metrics_cached":12}

Windows service running

Log file location¶

Windows logs are stored at:

%ProgramData%\SenHub\logs\senhubagent.log

Typically: C:\ProgramData\SenHub\logs\senhubagent.log

Log rotation: 10 MB max per file, 5 backup files, 30-day retention, compressed.

Linux Installation¶

1. Prepare the binary¶

Download the ZIP for your architecture (senhub-agent-linux-amd64.zip or senhub-agent-linux-arm64.zip), then extract it:

sudo mkdir -p /opt/senhub/bin
sudo unzip senhub-agent-linux-amd64.zip -d /opt/senhub/bin/
sudo chmod +x /opt/senhub/bin/senhub-agent

The ZIP contains senhub-agent, already correctly named.

2. Install the service¶

sudo /opt/senhub/bin/senhub-agent install

This creates and registers a hardened systemd service (senhub-agent.service) that runs the agent as a dedicated unprivileged system user (senhub, created during install if missing) with all Linux capabilities dropped — the same unit the .deb/.rpm packages ship. A UUID agent key is generated automatically and saved to the configuration file, and the configuration and log directories are handed to the senhub user.

If a probe needs a privilege the default unit does not grant (for example snmp_trap on UDP/162 or ICMP raw sockets), grant the single capability with a unit drop-in — see Running the agent least-privilege. To keep the previous behavior of running the service as root:

sudo /opt/senhub/bin/senhub-agent install --user root

Upgrading from an earlier version

install never touches an existing senhub-agent.service unit — it fails with "Init already exists". Existing installs keep running as before. The hardened unit applies only after an explicit uninstall followed by install; at that point review any probe that relied on root (privileged ports, raw sockets) against the per-probe privilege map in the least-privilege guide, or reinstall with --user root.

To install with HTTPS enabled and a custom certificate hostname:

sudo /opt/senhub/bin/senhub-agent install \
  --enable-https \
  --https-hosts "agent.company.com,192.168.1.100" \
  --https-port 8443

3. Start the service¶

sudo /opt/senhub/bin/senhub-agent start

4. Verify the installation¶

sudo /opt/senhub/bin/senhub-agent status

Or check the health endpoint:

curl http://localhost:8080/health

Log file location¶

Linux logs are stored at:

/var/log/senhub-agent/senhubagent.log

If this directory is not writable, logs fall back to the binary directory.

Log rotation: 10 MB max per file, 5 backup files, 30-day retention, compressed.

Installation Options¶

The install command accepts the following options:

Configuration¶

Flag	Default	Description
`--config-path PATH`	OS canonical path	Path to the configuration file
`--user USER`	`senhub`	System user the installed Linux service runs as. Use `root` to keep the legacy root unit. Ignored on Windows and macOS.

HTTPS / TLS¶

Flag	Default	Description
`--enable-https`	disabled	Enable HTTPS on the agent API
`--https-port PORT`	`8443`	HTTPS listening port
`--https-hosts HOSTS`	`localhost,127.0.0.1`	Hostnames for the auto-generated certificate (comma-separated)
`--cert-file PATH`	auto-generated	Path to a custom TLS certificate file
`--key-file PATH`	auto-generated	Path to a custom TLS private key file
`--min-tls-version VER`	`1.2`	Minimum TLS version (1.2 or 1.3)

Logging¶

Flag	Description
`--verbose` or `-v`	Enable verbose logging for all modules
`--filter MODULES`	Filter debug logs by module prefix (implies verbose). Example: `--filter probe.veeam`

What Happens During Installation¶

When you run senhub-agent install, the agent:

Checks for administrator/root privileges (required on Windows and Linux)
On Linux: creates the dedicated senhub system user and group if they do not exist (skipped with --user root)
Registers the system service (SenHub Agent on Windows, the hardened senhub-agent.service running as senhub on Linux)
Configures automatic restart on failure
Generates the multi-file configuration layout at the OS canonical path: a globals-only agent.yaml plus sibling probes.d/ and strategies.d/ directories prefilled with sane defaults (host probes + HTTP strategy). A fresh UUID is generated for the agent key.
If --enable-https is specified: creates a certs/ directory with a self-signed certificate and private key (valid for 365 days), and configures the HTTP strategy fragment to use them.
On Linux: hands the configuration, log and certificate files to the service user so the unprivileged daemon can read them.

Files Created¶

File	Permissions	Description
`agent.yaml`	`0600` (owner only)	Globals only (agent identity, auto-update, cache). At the OS canonical path.
`probes.d/00-host.yaml`	`0600` (owner only)	Default host probes: cpu, memory, network, logicaldisk.
`strategies.d/00-http.yaml`	`0600` (owner only)	Default HTTP strategy (PRTG / Web / Nagios on 127.0.0.1:8080).
`certs/agent-cert.pem`	`0600` (owner only)	TLS certificate (if HTTPS enabled).
`certs/agent-key.pem`	`0600` (owner only)	TLS private key (if HTTPS enabled).

Add additional probes by creating new fragment files under probes.d/ (e.g. 10-mysql.yaml — files load alphabetically). Add another strategy by creating a new file under strategies.d/ with exactly one top-level key (the strategy name). Disable any fragment by renaming it to *.disabled — no deletion required. The agent watches both directories with fsnotify, so add/modify/remove reloads automatically without a restart.

Migrating an existing monolithic install¶

If you upgraded from a pre-0.2.x agent that used the single-file agent-config.yaml layout, the agent keeps loading it transparently — no immediate action required. To move to the multi-file layout cleanly:

sudo senhub-agent config migrate /etc/senhub-agent/agent-config.yaml

The command takes a timestamped backup of the original, splits globals into agent.yaml, probes into probes.d/00-host.yaml, and strategies into per-strategy files under strategies.d/. It then verifies the post-split data matches the original (and restores the backup on any mismatch). Comments from the monolithic file are NOT carried into the fragments — they live in the backup for reference. The command is idempotent: running it on an already-multi-file install reports "nothing to do" and exits 0.

Service Management Commands¶

The agent binary provides built-in service management:

Command	Description
`senhub-agent install`	Install the system service
`senhub-agent uninstall`	Remove the system service and clean up files
`senhub-agent start`	Start the service
`senhub-agent stop`	Stop the service
`senhub-agent restart`	Restart the service
`senhub-agent status`	Show service status, health, and resource usage
`senhub-agent status --otlp`	Same as above, plus a block showing the OTLP push pipeline self-metrics
`senhub-agent version`	Show agent version and build information
`senhub-agent run`	Run interactively in console mode (for debugging)
`senhub-agent config check`	Validate configuration file
`senhub-agent update`	Check for updates
`senhub-agent update --list`	List available versions
`senhub-agent update VERSION`	Install a specific version

Console Mode¶

The run command starts the agent interactively in the foreground (not as a service). This is useful for debugging:

senhub-agent run
senhub-agent run --verbose
senhub-agent run --filter probe.veeam

The agent auto-detects its mode from the configuration file. All logs are printed to the console. Press Ctrl+C to stop.

Use --filter to limit debug output to specific modules (see CLI Reference).

Updating the Agent¶

Check for available updates:

senhub-agent update --list

Install a specific version:

senhub-agent update 0.1.87

Post-Installation Checklist¶

After installing and starting the agent, verify the following:

The service is running: senhub-agent status
The health endpoint responds: curl http://localhost:8080/health
The web dashboard is accessible: open http://localhost:8080/web/{key}/ in a browser
Probes are collecting metrics: check the probes endpoint curl http://localhost:8080/api/{key}/info/probes
The log file exists and is being written to

Next Steps¶

After installation:

Configure your monitoring probes (see Configuration)
Activate your license if you have premium probes (see License section in Configuration)
Set up HTTPS if required (see HTTP/HTTPS Configuration)
Configure your monitoring system (PRTG, Nagios) to collect metrics (see Web Interface)

Uninstallation¶

Windows:

.\senhub-agent.exe stop
.\senhub-agent.exe uninstall

Linux:

sudo /opt/senhub/bin/senhub-agent stop
sudo /opt/senhub/bin/senhub-agent uninstall

The uninstall command stops the service, removes the service registration, and cleans up generated files (configuration, certificates, logs).