Overview & Entry Point | Documentation

The UTMStack Agent is a cross-platform application designed for Windows and Linux systems that serves as the primary endpoint component for the UTMStack ecosystem. It is responsible for executing remote commands, collecting and forwarding logs, and performing essential tasks for monitoring and maintaining system security.

Architecture & Execution Flow

The agent is built in Go and operates in two primary modes: as a background service daemon and as a Command Line Interface (CLI) utility for configuration.

When the binary is executed, the entry point initializes the logging system and hands off execution to the CLI router. If no specific command arguments are provided, it defaults to running the continuous background service.

Application Entry Point

The core entry point (main.go) is intentionally kept minimal. It delegates logging initialization to the utils package and command routing to the cmd package.

package main

import (
	"github.com/utmstack/UTMStack/agent/cmd"
	"github.com/utmstack/UTMStack/agent/config"
	"github.com/utmstack/UTMStack/agent/utils"
)

func main() {
    // Initialize the logger using the configured service log file path
	utils.InitLogger(config.ServiceLogFile)
    
    // Hand off to the Cobra CLI framework
	cmd.Execute()
}

Detailed operational logs are written to the file specified by config.ServiceLogFile. Always check this file when troubleshooting agent connectivity or execution issues.

CLI Command Structure

The agent utilizes the spf13/cobra library to provide a robust CLI. The root command is utmstack_agent.

Administrative Privileges Required
All utmstack_agent CLI commands modify system services, network ports, or core configuration files. You must run these commands with root (sudo) on Linux or as an Administrator on Windows.

Available Commands

Common Configuration Workflows

Install the agent by pointing it to your UTMStack server, providing your unique UTM key, and specifying whether to skip certificate validation (yes or no).

utmstack_agent install 192.168.1.100 my_secret_utm_key no

For secure communication, load your own TLS certificates. You can provide just the server certificate and key, or optionally include the CA certificate.

# 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

Enable specific integrations to start collecting logs. You can append the --tls flag to enforce encrypted collection.

# Enable syslog over TCP with TLS encryption
utmstack_agent enable-integration syslog tcp --tls

# Enable syslog over TCP without TLS (default behavior)
utmstack_agent enable-integration syslog tcp

Advanced Integration Management

When managing integrations, the agent automatically handles the underlying service reloads and configuration updates.

If the default port for an integration conflicts with another service on your host, use the change-port command:

utmstack_agent change-port syslog tcp 1514

Running the disable-integration command stops the listener for that specific protocol and integration. If TLS was enabled for that integration, the agent automatically safely disables the TLS requirement as part of the teardown process.

utmstack_agent disable-integration syslog tcp

Agent Troubleshooting

If commands fail or the agent isn't reporting to the UTMStack server, ensure you are running the terminal as an Administrator/root and verify the output in the service log file defined during initialization.