Monitoring Client for Linux Overview

Watchman Monitoring’s Linux agent (monitoringclient) is a single compiled Go binary. It does not require Python or any other runtime on the host. The agent runs built-in monitoring checks on an hourly schedule via systemd, reports to your Watchman Monitoring dashboard, and can send Beacon uptime notifications when that feature is enabled for that Computer.

The legacy Python 2 Linux agent is retired and no longer receives updates. New installations and upgrades should use the current agent (version 4.0.2 and later).

The Linux agent is available to all subscribers.

Supported platforms

Every version is tested on:

Ubuntu 22.04 and 24.04
Debian 12
Rocky Linux 9
Fedora 40
Amazon Linux 2023

Also compatible with: other RHEL 9-family distributions (AlmaLinux, RHEL) and recent glibc-based Linux with systemd.

Tested on architectures: amd64 and arm64

Other distributions may work but are not officially tested. The host must have systemd and network access to your Watchman Monitoring reporting server.

Installation

Step-by-step install commands are in your Watchman Monitoring dashboard on the Installers → Linux page.

The dashboard provides separate instructions for Debian/Ubuntu (apt) and RHEL family (dnf/yum), including the Cloudsmith repository setup script and enrollment command.

You will need a valid install code from your dashboard (same enrollment codes used for Mac and Windows).

Upgrading from the legacy Python agent

If a host already runs the older Python Linux agent:

Follow the dashboard install steps for the new agent (repository, package install, enroll with install code).
During enrollment, the agent detects legacy settings and preserves your existing Watchman ID, group, and server configuration.
The new agent automatically removes the old Python agent files as part of enrollment. The computer stays enrolled on your dashboard.

Important: Do not run the legacy run-client –remove command or purge the package as part of an upgrade. That can report the computer as removed from your dashboard. Install and configure the new agent instead.

Features and Plugins

The current Linux agent includes built-in checks for common server monitoring. No separate plugin installation is required.

Plugin Name	What It Reports
Root Capacity	Root volume usage
RAM	Installed system memory
Operating System	OS Name and version from /etc/os-release
Reboot Events	Last boot time
Failed Logins	Recent failed SSH login attempts
Fail2ban	Fail2ban service status and active jails
MySQL/MariaDB	Whether the MySQL/MariaDB systemd service is active
Local IP Address	Primaroy internal IPv4 address
Volumes	Mounted volume status
Network Status	Network interface errors
Monitoring Agent	Installed agent version and self-check
Beacon Reporting	Uptime/downtime notifications (when enabled)

How the agent works

monitoringclient run performs a full check-in: runs all built-in checks, sends results to Watchman, and applies any server-side setting updates.
monitoringclient.timer (systemd) triggers check-ins on a schedule (typically hourly).
monitoringclient-beacon.service runs continuously for beacon uptime reporting when enabled.
monitoringclient configure exchanges your install code for enrollment settings.
monitoringclient validate runs a post-install health check (settings, systemd units, plugins, and one test check-in).

To check the version of the agent, you can run: monitoringclient version

Configuration

Main settings file

/etc/monitoringclient/ClientSettings.plist

Despite the .plist extension, this file is JSON. It is created and updated by monitoringclient configure and by each successful check-in. It includes your Watchman ID, server address, group, and other enrollment settings.

You normally do not need to edit this file by hand.

Legacy note

The retired Python agent used:

/etc/monitoringclient/client_settings.conf

The new agent migrates relevant values from that file during enrollment when it is still present.

Install code (one-time enrollment)

During unattended or image-based installs, you may place a one-time code in:

/etc/monitoringclient/install_code

The package runs enrollment automatically on first install when this file exists.

Updating the agent

Agent updates are delivered through your Linux package manager, the same way you install other system software. There is no separate in-agent auto-update command.

Debian/Ubuntu:

sudo apt-get update sudo apt-get install --only-upgrade monitoringclient

RHEL family:

sudo dnf upgrade monitoringclient

Keep the Watchman Monitoring Cloudsmith repository configured on the host so updates are available through your normal patch process (manual upgrades, unattended-upgrades, dnf-automatic, etc.).

For more detail, see Updating Linux Monitoring Client (companion article; update to match this agent if needed).

Verification and troubleshooting

Recommended after install or upgrade:

sudo monitoringclient validate

JSON output (for scripts or support):

sudo monitoringclient validate --json

Local checks only (no server contact):

sudo monitoringclient validate --skip-server

Force a check-in manually:

sudo monitoringclient run --force

View recent agent logs:

sudo journalctl -u monitoringclient.service -u monitoringclient-beacon.service -n 80 --no-pager

Check systemd status:

systemctl status monitoringclient.timer monitoringclient-beacon.service

Removal

Use your package manager so maintainer scripts run correctly.