Skip to content

Linux Agent

The SentriKat Linux Agent collects installed package inventory from Linux systems and reports it to your SentriKat instance.

Prerequisites

  • Linux with glibc 2.17+ (most distributions from 2014 onward)
  • curl or wget for downloading
  • Root or sudo access for installation
  • Network access to your SentriKat server (HTTPS recommended)
  • An API key from SentriKat (see Agent API Keys)

Installation

Download the agent from your SentriKat instance under Admin > Agents > Downloads.

# Download the package
curl -o sentrikat-agent.sh https://sentrikat.example.com/api/agents/script/linux

# Install
sudo dpkg -i sentrikat-agent.deb

# Configure
sudo sentrikat-agent configure \
  --server https://sentrikat.example.com \
  --api-key sk_agent_xxxxxxxxxxxx

# Start the service
sudo systemctl enable --now sentrikat-agent

# Download the package
curl -o sentrikat-agent.sh https://sentrikat.example.com/api/agents/script/linux

# Install
sudo rpm -i sentrikat-agent.rpm

# Configure
sudo sentrikat-agent configure \
  --server https://sentrikat.example.com \
  --api-key sk_agent_xxxxxxxxxxxx

# Start the service
sudo systemctl enable --now sentrikat-agent

# Download and extract
curl -o sentrikat-agent.sh https://sentrikat.example.com/api/agents/script/linux
sudo tar xzf sentrikat-agent.tar.gz -C /opt/sentrikat/

# Configure
sudo /opt/sentrikat/sentrikat-agent configure \
  --server https://sentrikat.example.com \
  --api-key sk_agent_xxxxxxxxxxxx

# Install systemd service
sudo cp /opt/sentrikat/sentrikat-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sentrikat-agent

Verify Installation

# Check service status
sudo systemctl status sentrikat-agent

# View agent info
sentrikat-agent status

Expected output:

SentriKat Agent v1.2.0
Status: Running
Server: https://sentrikat.example.com
Last Check-in: 2024-12-01 14:30:00 UTC
Packages Reported: 387

Configuration

The configuration file is located at /etc/sentrikat/agent.conf:

[server]
url = https://sentrikat.example.com
api_key = sk_agent_xxxxxxxxxxxx
verify_ssl = true

[agent]
hostname_override =
scan_interval = 86400
log_level = INFO
log_file = /var/log/sentrikat/agent.log

[scan]
include_kernel = true
include_libs = false
exclude_patterns = lib32-*,*-debug,*-dev
Setting Description Default
url SentriKat server URL Required
api_key Agent API key Required
verify_ssl Validate server certificate true
scan_interval Seconds between scans 86400 (24h)
include_kernel Report kernel version true
include_libs Report shared libraries false
exclude_patterns Glob patterns for packages to skip None

After changing the configuration:

sudo systemctl restart sentrikat-agent

Systemd Service

The agent runs as a systemd service:

# Start
sudo systemctl start sentrikat-agent

# Stop
sudo systemctl stop sentrikat-agent

# Restart
sudo systemctl restart sentrikat-agent

# View logs
sudo journalctl -u sentrikat-agent -f

The service file is installed at /etc/systemd/system/sentrikat-agent.service:

[Unit]
Description=SentriKat Inventory Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/sentrikat-agent run
Restart=on-failure
RestartSec=60
User=sentrikat-agent
Group=sentrikat-agent

[Install]
WantedBy=multi-user.target

What the Agent Collects

The Linux agent scans the system's package manager:

Package Manager Distributions
dpkg Debian, Ubuntu, Linux Mint
rpm RHEL, CentOS, Fedora, openSUSE, Amazon Linux
pacman Arch Linux, Manjaro
apk Alpine Linux

The agent reports:

  • Package name and version
  • Architecture
  • Package manager source
  • Hostname and OS distribution
  • Kernel version (if enabled)

Note

If multiple package managers are present (e.g., dpkg and snap), the agent scans all of them.

Distro-Specific Notes

Ubuntu / Debian

Snap packages are collected automatically if snap is installed:

# Verify snap detection
sentrikat-agent scan --dry-run | grep snap

RHEL / CentOS

On SELinux-enabled systems, you may need to set the context for the agent binary:

sudo semanage fcontext -a -t bin_t '/opt/sentrikat/sentrikat-agent'
sudo restorecon -v /opt/sentrikat/sentrikat-agent

Alpine Linux

For Alpine containers, run the agent as a one-shot scan instead of a service:

/opt/sentrikat/sentrikat-agent scan --once

Firewall Rules

The agent requires outbound HTTPS access to your SentriKat server:

# iptables
sudo iptables -A OUTPUT -p tcp --dport 443 -d sentrikat.example.com -j ACCEPT

# firewalld
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" destination address="<SENTRIKAT_IP>" port port="443" protocol="tcp" accept'
sudo firewall-cmd --reload

Note

No inbound rules are required. The agent only makes outbound connections.

Proxy Configuration

If your servers access the internet through a proxy:

# In /etc/sentrikat/agent.conf
[server]
proxy = http://proxy.example.com:8080

Or set environment variables in the systemd override:

sudo systemctl edit sentrikat-agent

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"

Uninstallation

sudo apt remove sentrikat-agent
sudo rm -rf /etc/sentrikat /var/log/sentrikat

sudo rpm -e sentrikat-agent
sudo rm -rf /etc/sentrikat /var/log/sentrikat

sudo systemctl disable --now sentrikat-agent
sudo rm /etc/systemd/system/sentrikat-agent.service
sudo rm -rf /opt/sentrikat /etc/sentrikat /var/log/sentrikat
sudo systemctl daemon-reload

Troubleshooting

Agent Not Reporting

# Check service status
sudo systemctl status sentrikat-agent

# View recent logs
sudo journalctl -u sentrikat-agent --since "1 hour ago"

# Test connectivity
curl -v https://sentrikat.example.com/api/health

Permission Denied

Ensure the agent user can read package databases:

sudo usermod -aG adm sentrikat-agent
sudo systemctl restart sentrikat-agent

Sprint 4+5 additions

Delta scans with SHA-256 fingerprinting

Starting in Sprint 4, Linux agents perform delta scans by default: on each scheduled run, the agent computes a SHA-256 hash of the full inventory (package list + versions + paths) and compares it against the hash from the previous run. If the hash matches, only a tiny "no change" heartbeat is sent instead of the full inventory payload.

Impact:

  • ~95% bandwidth reduction on typical servers where the package set changes rarely.
  • Full inventory is still transmitted on any change, so no data is lost — only unchanged scans are elided.
  • The fingerprint algorithm is pinned to SHA-256.

Gzip compression

All inventory uploads are gzipped before transmission. Typical compression ratio for package inventories is ~10×, cutting wire traffic further. Enabled transparently — no configuration needed.

Store-and-forward spool

If the agent cannot reach the SentriKat server (network partition, VPN down, server maintenance), it now spools inventory payloads to /var/lib/sentrikat/spool/ and retries on an exponential backoff. The spool has a 100 MB cap and drops the oldest entries when full. When connectivity is restored, the spool is drained to the server in order. Spool location is configurable via the spool_path field in /etc/sentrikat/agent.yml.

Next Steps