Skip to main content
The UTMStack Linux Agent enables comprehensive security monitoring and log collection on Linux servers and systems.

​
Prerequisites

Before installing the Linux agent, ensure you have:
  • Root or sudo privileges
  • Network connectivity to the UTMStack server
  • UTMStack server hostname or IP address
  • Agent registration key from your UTMStack deployment

​
Supported Distributions

The agent supports major Linux distributions including:
  • Ubuntu/Debian
  • RHEL/CentOS/Rocky Linux
  • Amazon Linux
  • Other systemd-based distributions

​
Installation

1

Download the Agent

Download the Linux agent binary (utmstack_agent) from your UTMStack server or deployment package.
2

Make the Binary Executable

chmod +x utmstack_agent
3

Run the Installation Command

Execute the installer with root privileges:
sudo ./utmstack_agent install
The installer will prompt you for:
  • UTMStack server address
  • Agent registration key
4

Installation Process

The agent will automatically:
  • Check server connection and verify port accessibility
  • Download required dependencies from the server
  • Register the agent with the UTMStack server
  • Configure collectors and log retention settings
  • Install the systemd service
You’ll see output like:
Installing UTMStackAgent service ...
Checking server connection ... [OK]
Downloading dependencies ... [OK]
Configuring agent ... [OK]
Creating service ... [OK]
UTMStackAgent service installed correctly
5

Verify Installation

Check that the UTMStackAgent service is running:
sudo systemctl status UTMStackAgent

​
Service Management

​
Start the Service

sudo systemctl start UTMStackAgent

​
Stop the Service

sudo systemctl stop UTMStackAgent

​
Restart the Service

sudo systemctl restart UTMStackAgent

​
Check Service Status

sudo systemctl status UTMStackAgent

​
Enable Auto-Start on Boot

sudo systemctl enable UTMStackAgent

​
Common Tasks

​
Enable Syslog Integration

Enable syslog over UDP: 
sudo ./utmstack_agent enable-integration syslog udp
Enable syslog over TCP: 
sudo ./utmstack_agent enable-integration syslog tcp
Enable syslog over TCP with TLS: 
sudo ./utmstack_agent enable-integration syslog tcp --tls

​
Load Custom TLS Certificates

For production environments, load your own TLS certificates: 
sudo ./utmstack_agent load-tls-certs /path/to/server.crt /path/to/server.key /path/to/ca.crt
Without CA certificate: 
sudo ./utmstack_agent load-tls-certs /path/to/server.crt /path/to/server.key

​
Check TLS Certificate Status

sudo ./utmstack_agent check-tls-certs

​
Change Integration Port

Change the syslog TCP port to 5140: 
sudo ./utmstack_agent change-port syslog tcp 5140

​
Change Log Retention

Set log retention to 100 MB: 
sudo ./utmstack_agent change-retention 100

​
Clean Old Logs

Manually clean old logs based on retention policy: 
sudo ./utmstack_agent clean-logs

​
Uninstalling the Agent

To completely remove the agent: 
sudo ./utmstack_agent uninstall
This will:
  • Stop the service
  • Uninstall collectors
  • Delete the agent from the server
  • Remove the systemd service
  • Clean up configuration files

​
Troubleshooting

​
Installation Fails

If installation fails, check:
  1. Network connectivity: Ensure the server is reachable 
    ping your-utmstack-server
  2. Firewall rules: Verify required ports are open 
    sudo firewall-cmd --list-all  # For firewalld
sudo ufw status              # For ufw
  3. Permissions: Ensure you’re running with sudo or as root

​
Service Won’t Start

Check the service logs: 
sudo journalctl -u UTMStackAgent -n 50 --no-pager
Or check the agent log file directly at /opt/utmstack/agent/logs/service.log

​
Agent Not Appearing in Console

Verify the agent is registered:
  • Check network connectivity to the server
  • Ensure the correct server address and key were used during installation
  • Review the agent log files

​
Permission Denied Errors

Ensure you’re running all agent commands with sudo or as the root user.

​
Log Files

Agent logs are typically stored at: 
/opt/utmstack/agent/logs/service.log
View recent logs: 
sudo tail -f /opt/utmstack/agent/logs/service.log

​
File Locations

  • Agent binary: /opt/utmstack/agent/utmstack_agent
  • Configuration: /opt/utmstack/agent/config.yml
  • Logs: /opt/utmstack/agent/logs/
  • Database: /opt/utmstack/agent/data/

​
Next Steps

Agent Commands

Explore all available CLI commands

Build docs developers (and LLMs) love

Get started for freeTalk to us