Monitoring Client for Linux Overview

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.

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).

If a host already runs the older Python Linux agent:

1. Follow the dashboard install steps for the new agent (repository, package install, enroll with install code).
2. During enrollment, the agent detects legacy settings and preserves your existing Watchman ID, group, and server configuration.
3. 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.

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

• 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

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.

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).

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

Use your package manager so maintainer scripts run correctly.

Debian/Ubuntu:

sudo apt-get remove monitoringclient

RHEL family:

sudo dnf remove monitoringclient

Configuration under /etc/monitoringclient/ may be left on disk after removal. Remove that directory only if you are sure you will not reinstall on the same host.

To remove a computer from your dashboard and uninstall the agent, follow your normal offboarding process. Do not rely on package removal alone to remove the computer record from Watchman Monitoring.