Command Reference

The agent ships as a single executable on the device. You can run it directly from a terminal session to check the installed version, inspect its capabilities, or start it in the foreground for troubleshooting.

The agent is installed at /opt/mutexer/agent, and every command must be run as the root user:

cd /opt/mutexer/agent
sudo ./agent <command>

INFO

The agent must be run from its own directory. It reads its configuration from a path relative to the working directory, so running it from elsewhere will fail to start.

Commands

Command	Alias	Description
start	s	Starts the agent in the foreground.
version	v	Prints the installed version, variant, and capabilities.
--help	-h	Prints usage and the available commands.

Running ./agent with no command is the same as running ./agent start.

version

sudo ./agent version

The command prints three lines:

1.0.24
variant: base+cloudlink
capabilities: cloudlink

Line	Description
First line	The installed agent version, on its own so it can be read by scripts.
variant	The build this device is running. For more information, see Variant names.
capabilities	The optional capabilities compiled into this build, comma separated. Empty on a Core install.

Use this to confirm both the version and the install type actually present on the device, which is the authoritative answer when the platform and the device appear to disagree.

start

sudo ./agent start

Starts the agent in the foreground and logs to the terminal.

WARNING

Only one agent can run on a system at a time. The agent normally starts automatically on boot as the mutexer service, so stop that service before starting the agent by hand:

sudo service mutexer stop

Restart it when you have finished:

sudo service mutexer start

Managing the agent service

Day to day, the agent runs as the mutexer service rather than being started by hand.

Action	Command
Stop the agent	sudo service mutexer stop
Start the agent	sudo service mutexer start
Restart the agent	sudo service mutexer restart

Debug mode

The agent logs at the info level by default. To capture more detail while troubleshooting, set the LOG_FILTER_LEVEL environment variable when starting it.

cd /opt/mutexer/agent
sudo service mutexer stop
sudo LOG_FILTER_LEVEL=debug ./agent start

The agent then runs in the foreground and writes debug output to the terminal. Press Ctrl+C to stop it, then restart the service:

sudo service mutexer start

Log levels

Value	Detail
error	Errors only.
warn	Errors and warnings.
info	Default. Connection changes, version information, and program activity.
debug	Adds detailed internal activity. Use this for troubleshooting.
trace	Maximum detail. Very high volume, and normally only needed at the request of Mutexer Support.

An unrecognised value falls back to info.

INFO

LOG_FILTER_LEVEL is read once when the agent starts. Changing it has no effect on an agent that is already running, so the agent must be restarted for a new level to take effect.

WARNING

Debug and trace output is verbose and can fill the device's disk if left running on a busy device. Use it for a troubleshooting session rather than as a permanent setting.

Log output from the running service goes to syslog rather than the terminal. For more information, see Logging.