Download the Pingmon agent

A single small binary that reports CPU, memory, disk and detailed network statistics from your servers — and monitors the devices it can reach on their network. Current version 0.3.3.

The agent makes one outbound HTTPS connection and needs no inbound firewall rule. It pairs with a key you create in Pingmon, so nothing here is secret — the key is what grants access, and it is issued separately.

Before you install

Every host pairs with your account using an enrolment key. Sign in to Pingmon, open Agents and create one — have it in front of you before you start, because the installer asks for it.

One key can admit as many hosts as you like, so it belongs in a deployment script or a machine image rather than being created per machine. Each host that enrols is issued its own separate credential, so revoking a key later stops new hosts joining without disturbing the ones already reporting. Keys, and individual agents, are revoked from the same page.

Install from the package repository

The best route on Debian and Ubuntu: the agent installs like any other package, and updates arrive with the rest of the machine's rather than needing anyone to remember it.

curl -fsSL https://pingmon.tech/apt/pingmon-agent-archive-keyring.gpg \
    | sudo tee /usr/share/keyrings/pingmon-agent-archive-keyring.gpg > /dev/null

echo 'deb [signed-by=/usr/share/keyrings/pingmon-agent-archive-keyring.gpg] https://pingmon.tech/apt stable main' \
    | sudo tee /etc/apt/sources.list.d/pingmon-agent.list

sudo apt update
sudo apt install pingmon-agent

The repository is signed, and the key above is what apt checks each update against. The package has no dependencies at all, so this works on old releases as well as current ones. Installing runs the same pairing wizard as the downloaded package below — or supply PINGMON_SERVER and PINGMON_TOKEN in the environment to skip it.

Install from the RPM repository

The same arrangement for RHEL, Fedora, Rocky, Alma and SUSE: the agent installs with dnf and stays current with everything else on the machine.

sudo rpm --import https://pingmon.tech/yum/pingmon-agent.asc

sudo tee /etc/yum.repos.d/pingmon-agent.repo > /dev/null <<'REPO'
[pingmon-agent]
name=PingMon Agent
baseurl=https://pingmon.tech/yum
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pingmon.tech/yum/pingmon-agent.asc
REPO

sudo dnf install pingmon-agent

Both the packages and the repository index are signed with the same key as the Debian repository, which is what gpgcheck and repo_gpgcheck check respectively. The metadata is gzip rather than zstd and includes the sqlite indexes, so this works on RHEL 7-era yum as well as current dnf — on those systems use yum in place of dnf above.

Install a single package

For a machine that should not follow a repository — an image build, or a host with no route to this server at install time. It installs the agent, registers the service and then asks for your server address and enrolment key.

Then, in the directory you downloaded it to:

sudo apt install ./pingmon-agent_0.3.3_amd64.deb

To pair without being prompted — for a machine image or a configuration-management run — supply the same details through the environment instead:

sudo PINGMON_SERVER=https://your-org.pingmon.tech \
     PINGMON_TOKEN=<your-enrolment-key> \
     apt install ./pingmon-agent_0.3.3_amd64.deb

You can re-run the wizard at any time with sudo pingmon-agent-setup, and check what a paired agent is doing with pingmon-agent status.

Check it worked

The agent takes a baseline reading, waits, and sends its first report within a minute of enrolling. On the host:

systemctl status pingmon-agent   # is it running?
pingmon-agent status             # paired to which server, as which device?

In Pingmon the machine then appears under Agents with the time of its last report, and gets a device page of its own carrying the host metrics.

If something looks wrong, two commands answer most of it without disturbing the service:

pingmon-agent once             # collect and print everything, sending nothing
pingmon-agent probe 10.0.0.1   # ping a device from this host, ignoring the server

Pinging other devices needs a ping or raw socket. The packaged service unit grants exactly that and nothing else; a hand-written unit may not, in which case the agent logs a warning, carries on reporting host metrics, and probes nothing rather than refusing to start. Probing is Linux-only and IPv4-only today — an IPv6 device is reported as unprobed rather than as down, because a device wrongly marked down wakes somebody at 3am and one honestly not covered does not.

Upgrading

A machine installed from either repository upgrades with everything else — apt upgrade or dnf upgrade, or whatever already runs unattended upgrades on it. Nothing else to do.

Otherwise download the newer package and install it the same way. A machine that is already paired is asked nothing: its credentials are still good, so the service restarts into the new binary and carries on. For a host installed from a raw binary, replace the file and restart the service.

Removing the package leaves the configuration in place, so reinstalling re-attaches the host to the device it already had — only apt purge deletes it. Revoking an agent in Pingmon is the other half of that: it stops the credential working, wherever the machine has got to.

Other builds

All checksums: SHA256SUMS. Verify a download before installing it:

sha256sum -c SHA256SUMS --ignore-missing

Installing without a package

With your enrolment key to hand, on each host:

sudo install -m 0755 pingmon-agent-0.3.3-linux-x86_64 /usr/local/bin/pingmon-agent
sudo pingmon-agent enroll \
    --server https://your-org.pingmon.tech \
    --token <your-enrolment-key>

Then install the service unit for your platform and start it, and check the result the same way as above.

Linux (systemd)

sudo cp pingmon-agent.service /etc/systemd/system/
sudo systemctl enable --now pingmon-agent

FreeBSD

sudo install -m 0555 pingmon-agent.rc /usr/local/etc/rc.d/pingmon_agent
sudo sysrc pingmon_agent_enable=YES
sudo service pingmon_agent start

Windows

The agent is a console application and does not yet implement the Windows service protocol, so register it under a service wrapper such as WinSW or NSSM rather than with sc.exe directly. The supplied PowerShell installer does both steps.

Haiku

cp pingmon-agent /boot/system/non-packaged/bin/
cp pingmon-agent.launch /boot/system/settings/launch/pingmon-agent
launch_roster start pingmon-agent

Building from source

The agent is a single Rust crate with no build step beyond Cargo. Service units for every platform are in packaging/.

cargo build --release

For a portable Linux binary, build against musl so the result does not depend on the build machine's C library:

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

On Haiku, build on the machine itself and select the system TLS backend — the default one has no support for that platform:

pkgman install rust_bin
cargo build --release --no-default-features --features tls-native

What it collects

• CPU usage and core count; load averages
• Memory and swap, used and available
• Disk usage per filesystem, skipping pseudo-filesystems that would always read full
• Uptime and process count

Network, per interface

• Throughput and packet rates in both directions
• Errors, drops, collisions and multicast — the counters that explain a link that is up but unhappy
• Link state, negotiated speed, MTU, and a count of carrier flaps

Network, whole host

• TCP connections by state, retransmit rate, resets and failed connects
• Accept-queue overflows and listen drops — why a busy service starts refusing connections
• UDP throughput, buffer errors and no-port responses; ICMP counts
• Socket and connection-tracking table usage, against the table limit

Devices on the same network

The agent also pings the devices in your Pingmon account that it can reach, and reports the results as if Pingmon had pinged them itself. That is how equipment behind NAT or a firewall gets monitored: from the inside, by something that already has a route to it.

A device answers the agent, so the agent takes over pinging it and Pingmon's own poller steps aside — one measurement per device, not two. If the agent stops reporting, the poller picks the device back up on its own within a few minutes.

Readings appear on the device page alongside everything else Pingmon knows about that host, and are kept for as long as your plan's retention allows.

Back to features