Agent Command Line

The UTMStack agent program has a small command line for checking and adjusting the agent on the host. This page lists the commands, where the program lives on each system, how the agent stores logs locally, and the files it keeps.

Where the agent program is

The agent program is the file the install command downloaded. Run it with administrator rights: an administrator PowerShell window on Windows, sudo on Linux and macOS.

SystemAgent program
Windows (AMD64)C:\Program Files\UTMStack\UTMStack Agent\\utmstack_agent_service_windows_amd64.exe
Windows (ARM64)C:\Program Files\UTMStack\UTMStack Agent\\utmstack_agent_service_windows_arm64.exe
Linux (AMD64)/opt/utmstack-linux-agent/utmstack_agent_service_linux_amd64
Linux (ARM64)/opt/utmstack-linux-agent/utmstack_agent_service_linux_arm64
macOS (Apple Silicon)/opt/utmstack-macos-agent/utmstack_agent_service_darwin_arm64

For example, to see the agent's status:

& "C:\Program Files\UTMStack\UTMStack Agent\\utmstack_agent_service_windows_amd64.exe" status

Commands

CommandWhat it does
install <server> <connection-key> <yes|no> [--no-remote-control]Installs and registers the agent. The third argument is "skip TLS certificate validation". Use the install command from the product instead of typing this yourself.
uninstallStops the agent, removes the updater service and the agent's service, and cleans up what the agent set up (for example the Linux audit rules). The uninstall command in the product also deletes the agent folder.
statusShows how log collection is going, one row per source (see below).
set-auto-update <on|off>Pauses (off) or resumes (on) automatic agent updates. See Updates and Status.
change-retention <megabytes>Sets how many megabytes of logs the agent keeps on the host. Must be a whole number of 1 or more. Example: change-retention 50.
clean-logsDeletes old logs from the agent's local store now, and reports how many delivered (and, if needed, undelivered) logs it removed.

Running the program with no command starts the agent service itself; the operating system does this for you.

Reading the status output

status prints the time of the snapshot and one row per collection source:

ColumnMeaning
SOURCEThe log source on this host, for example a Windows channel or the Linux journal.
RECEIVEDEvents the agent read from this source.
PERSISTEDEvents the agent saved to its local store, ready to send.
PERSIST_FAILEvents the agent could not save.
LAST EVENTWhen the last event from this source arrived, or never.

If the service is not running, status says that no status snapshot is available yet.

How the agent stores logs on the host

The agent saves every log in a small local database before it sends it, and marks it as delivered when UTMStack confirms it. If the connection to UTMStack drops, the agent keeps the undelivered logs and sends them again when the connection is back.

  • The retention is the size of that local store in megabytes. The default is 20 MB. Change it with change-retention.

  • Every 10 minutes the agent deletes the oldest delivered logs until the store is back under the retention size.

  • Undelivered logs are kept until the store reaches five times the retention size (100 MB with the default). Beyond that, the agent deletes the oldest undelivered logs and writes a message to its log file. This only happens when UTMStack has been unreachable for a long time.

If your hosts may be cut off from UTMStack for long periods, raise the retention so the agent can hold more undelivered logs until the connection returns.

When UTMStack no longer accepts the agent

If the UTMStack server no longer recognises the agent, for example because the server was reinstalled or the agent's registration was removed, the server refuses its connection: the agent log shows PermissionDenied errors (for example invalid credential or invalid key). The agent keeps retrying and does not register again on its own. To connect the host again, uninstall the agent and run the install command from your current UTMStack server. See Reinstall, Move or Remove an Agent.

Remote command lock

If you install the agent with Disable remote command execution on this host (the --no-remote-control flag), the agent refuses every remote command on that machine, from the Data Sources console and from SOAR. In SOAR > Interactive Console, such an agent shows: "This agent was installed with remote control disabled…".

The lock can only be removed by uninstalling the agent and installing it again without the option.

Files in the agent folder

FileWhat it holds
config.ymlThe agent's connection settings.
uuid.ymlThe agent's unique installation ID.
retention.jsonThe local retention size in megabytes.
config_state.jsonWhich settings sent by the server the agent has already applied.
update_hold.jsonWhether the server has put this agent's updates on hold.
version.jsonThe agent version information downloaded from the server.
agent_status.jsonThe snapshot that the status command prints.
wineventlog_bookmarks.json (Windows)Where the agent stopped reading in each Event Log channel.
journald_cursor.txt, audit_log_cursor.json (Linux)Where the agent stopped reading in the journal and the audit log.
logs/utmstack_agent.logThe agent's own log file. Check it first when something does not work.
logs_process/logs.dbThe local log store described above.

Do not copy these files to another machine, and do not include an installed agent in a virtual machine template or disk image: every copy would report as the same agent. See Reinstall, Move or Remove an Agent.

Services

ServiceWhat it does
UTMStackAgentCollects and sends the logs, and runs remote commands.
UTMStackUpdaterKeeps the agent up to date. See Updates and Status.