Skip to main content
The UTMStack Agent provides a comprehensive command-line interface for installation, configuration, and management.

​
Command Syntax

./utmstack_agent <command> [arguments] [flags]
All commands require administrative privileges (root/sudo on Linux, administrator on Windows).

​
Installation Commands

​
install

Install the UTMStack Agent service. 
./utmstack_agent install
Installation Flow:
1

Display Banner

Shows UTMStack Agent version and information
2

Collect Configuration

Prompts for:
  • UTMStack server address
  • Agent registration key
3

Check Server Connection

Verifies connectivity to required ports:
  • Agent Manager Port
  • Log Auth Proxy Port
  • Dependencies Port
Checking server connection ... [OK]
4

Download Dependencies

Downloads required components from the server:
Downloading dependencies ... [OK]
5

Configure Agent

  • Registers agent with the server
  • Saves configuration file
  • Configures collectors
  • Installs Beat collectors
  • Sets default data retention
Configuring agent ... [OK]
6

Create Service

Installs the system service:
Creating service ... [OK]
UTMStackAgent service installed correctly
Example: 
sudo ./utmstack_agent install

​
uninstall

Completely remove the UTMStack Agent. 
./utmstack_agent uninstall
Uninstallation Process:
  1. Stops the UTMStackUpdater service
  2. Deletes agent registration from server
  3. Uninstalls all collectors
  4. Removes configuration files
  5. Uninstalls system service
Example: 
sudo ./utmstack_agent uninstall

​
Service Commands

​
run

Run the agent service (typically used by the system service manager). 
./utmstack_agent run

​
Integration Commands

​
enable-integration

Enable a log integration for a specific protocol. 
./utmstack_agent enable-integration <integration> <protocol> [--tls]
Parameters:
  • <integration>: Integration name (e.g., syslog)
  • <protocol>: Protocol type (tcp, udp)
  • --tls: (Optional) Enable TLS encryption (TCP only)
Examples: Enable syslog over UDP: 
./utmstack_agent enable-integration syslog udp
Enable syslog over TCP: 
./utmstack_agent enable-integration syslog tcp
Enable syslog over TCP with TLS: 
./utmstack_agent enable-integration syslog tcp --tls
Output: 
Changing integration status ...
Integration syslog tcp enabled on port 5140
With TLS: 
Integration syslog tcp enabled with TLS on port 6514

​
disable-integration

Disable a log integration. 
./utmstack_agent disable-integration <integration> <protocol>
Parameters:
  • <integration>: Integration name (e.g., syslog)
  • <protocol>: Protocol type (tcp, udp)
Disabling an integration automatically disables TLS if it was enabled.
Example: 
./utmstack_agent disable-integration syslog tcp
Output: 
Changing integration status ...
Integration syslog tcp disabled (port 6514 freed)

​
TLS Certificate Commands

​
load-tls-certs

Load custom TLS certificates for secure integrations. 
./utmstack_agent load-tls-certs <certificate_path> <private_key_path> [ca_certificate_path]
Parameters:
  • <certificate_path>: Path to server certificate (.crt)
  • <private_key_path>: Path to private key (.key)
  • [ca_certificate_path]: (Optional) Path to CA certificate
Process:
  1. Validates certificate files
  2. Copies certificates to agent directory
  3. Sets appropriate permissions
Examples: With CA certificate: 
./utmstack_agent load-tls-certs /path/to/server.crt /path/to/server.key /path/to/ca.crt
Without CA certificate: 
./utmstack_agent load-tls-certs /path/to/server.crt /path/to/server.key
Output: 
Loading user TLS certificates ...
Validating certificate files ... [OK]
Installing certificates ... [OK]
TLS certificates loaded successfully!

​
check-tls-certs

Check the status and validity of loaded TLS certificates. 
./utmstack_agent check-tls-certs

​
Port Management Commands

​
change-port

Change the listening port for a specific integration. 
./utmstack_agent change-port <integration> <protocol> <new_port>
Parameters:
  • <integration>: Integration name (e.g., syslog)
  • <protocol>: Protocol type (tcp, udp)
  • <new_port>: New port number
Example: 
./utmstack_agent change-port syslog tcp 5140
Output: 
Changing integration port ...
Port changed correctly from 514 to 5140

​
Log Management Commands

​
change-retention

Change the local log retention limit. 
./utmstack_agent change-retention <retention_mb>
Parameters:
  • <retention_mb>: Retention limit in megabytes
Example: Set retention to 100 MB: 
./utmstack_agent change-retention 100
Output: 
Changing log retention ...
Retention changed correctly to 100

​
clean-logs

Manually clean old logs based on the retention policy. 
./utmstack_agent clean-logs
Example: 
./utmstack_agent clean-logs
Output: 
Cleaning old logs ...
Logs cleaned correctly

​
Help Command

​
help

Display complete help information and usage examples. 
./utmstack_agent help
Output includes:
  • Command syntax for all commands
  • Detailed descriptions
  • TLS certificate management examples
  • TLS integration examples
  • Usage notes and requirements

​
Command Reference Table

CommandDescriptionRequires Restart
installInstall the agent serviceN/A
uninstallRemove the agent serviceN/A
runRun the agent serviceN/A
enable-integrationEnable a log integrationNo
disable-integrationDisable a log integrationNo
load-tls-certsLoad custom TLS certificatesYes*
check-tls-certsCheck TLS certificate statusNo
change-portChange integration portNo
change-retentionChange log retention limitNo
clean-logsClean old logs manuallyNo
helpDisplay help informationN/A
*Requires enabling/disabling the integration to apply TLS certificates.

​
Common Workflows

​
Setup Syslog with TLS

1

Load TLS Certificates

./utmstack_agent load-tls-certs /path/to/cert.crt /path/to/cert.key
2

Enable Syslog with TLS

./utmstack_agent enable-integration syslog tcp --tls
3

Verify Configuration

./utmstack_agent check-tls-certs

​
Change Syslog Port

1

Change the Port

./utmstack_agent change-port syslog tcp 5140
2

Update Firewall Rules

Update your firewall to allow the new port:Linux (firewalld):
sudo firewall-cmd --permanent --add-port=5140/tcp
sudo firewall-cmd --reload
Linux (ufw):
sudo ufw allow 5140/tcp

​
Manage Log Storage

1

Set Retention Policy

./utmstack_agent change-retention 200
2

Monitor Disk Usage

Linux:
du -sh /opt/utmstack/agent/data/
Windows:
dir "C:\Program Files\UTMStack\Agent\data" | find "bytes"
3

Clean Logs if Needed

./utmstack_agent clean-logs

​
Exit Codes

  • 0: Success
  • 1: Error (check error message for details)

​
Best Practices

  1. Always use administrative privileges: Run commands with sudo (Linux) or as administrator (Windows)
  2. Check connectivity before installation: Ensure the server is reachable
  3. Use TLS in production: Always enable TLS for TCP integrations in production environments
  4. Load custom certificates: Use your own TLS certificates instead of auto-generated ones
  5. Monitor log retention: Adjust retention based on your disk space and log volume
  6. Review help output: Run ./utmstack_agent help for detailed usage examples

​
Next Steps

Windows Agent

Windows-specific examples and workflows

Linux Agent

Linux-specific examples and workflows

Configuration

Detailed configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us