PingPlotter Cloud Manual

Linux Agent

PingPlotter's Linux agent puts a monitoring point on hardware that is ideal for the job: low cost, headless, and always on. Run it on a server already in the rack, a Raspberry Pi at a remote site, or a VM. It traces continuously (everything PingPlotter Cloud shows, including TCP traces!) from that machine's point of view and reports into your PingPlotter Cloud account. It is for PingPlotter Cloud only: there is no on-machine interface, and it does not run standalone the way PingPlotter for Windows or macOS can.

The agent is installed from the Terminal by adding the PingPlotter package repository and installing the agent package, then connecting it to your account. It runs as a systemd service.

Works on x86_64, arm64, and 32-bit Arm (armhf). Requires glibc 2.27 or newer (2.34 on 32-bit Arm): Debian 10+, Ubuntu 18.04+, Raspberry Pi OS (bookworm or newer for 32-bit), RHEL/AlmaLinux/Rocky 8+, Fedora, Amazon Linux 2023. CentOS 7 and Amazon Linux 2 are not supported. Repository metadata and rpm packages are signed; see packages.pingman.com for key details and verification.

Install

Debian / Ubuntu / Raspberry Pi OS:

curl -fsSLO https://packages.pingman.com/pingplotter-repo.deb
sudo dpkg -i pingplotter-repo.deb
sudo apt-get update
sudo apt-get install pingplotter.agent

RHEL / AlmaLinux / Rocky / Fedora / Amazon Linux:

curl -fsSLO https://packages.pingman.com/pingplotter-repo.rpm
sudo rpm -i pingplotter-repo.rpm
sudo dnf install pingplotter.agent

The setup package installs the signing key and repository configuration; the agent installs and starts as a service.

Connect it to your account

There are two ways to connect the agent. Use an Auto Link when you can paste a link into the machine's terminal; it is one command and works in scripts. Use a claim code when reading a short code off the machine's screen and typing it into PingPlotter Cloud is easier than moving a link onto the machine.

With an Auto Link

Copy the Auto Link from your agent's Deploy panel (or the download page), then run:

sudo /opt/pingplotter.agent/PingPlotter.Agent -c 'your auto link'

Keep the quotes - the link contains &. The command shows progress and exits once the agent is connected (exit code 0), so scripts can gate on it. If the machine is already configured as an agent it refuses; add --force-reconfigure to deliberately move a machine to a different account.

With a claim code

A fresh install prints a claim link and a claim code, and reprints them on every service start (systemctl status pingplotter.agent shows the current one). Open the link, or enter the code in PingPlotter Cloud under add agent.

Unattended and fleet deployment

Write the link before first boot (cloud-init, golden images, configuration management), then install as above. Debian family:

echo 'PINGPLOTTER_CONFIG_URL=<your auto link>' | sudo tee /etc/default/pingplotter.agent

RHEL family:

echo 'PINGPLOTTER_CONFIG_URL=<your auto link>' | sudo tee /etc/sysconfig/pingplotter.agent

The agent reads it on first start and joins your account with no claim step. The same link works on every machine; each install becomes its own agent. Remove the file once the agent is connected - a link left in place re-asserts that configuration on every service start.

Updating

Debian / Ubuntu / Raspberry Pi OS:

sudo apt-get update && sudo apt-get install pingplotter.agent

RHEL / AlmaLinux / Rocky / Fedora / Amazon Linux:

sudo dnf upgrade pingplotter.agent

Upgrades can also be started from PingPlotter Cloud; either way the update runs through your package manager and restarts the service itself.

Checking on the agent

/opt/pingplotter.agent/PingPlotter.Agent status
systemctl status pingplotter.agent

status also takes --json for scripts, and works in every state, including before the agent is connected.

Other useful information

  • PingPlotter is installed at /opt/pingplotter.agent; data is stored at /var/lib/pingplotter.agent
  • Agent logs: sudo journalctl -u pingplotter.agent -o cat -n 50. Deeper logs are in /var/lib/pingplotter.agent/Logs
  • Stop/start/restart: sudo systemctl (command) pingplotter.agent
  • On machines without a battery-backed clock (Raspberry Pi), a wrong date breaks TLS before anything else, which looks like claim or connection failures. Check timedatectl and make sure time sync is active.
  • If an update didn't take, the last package operation's outcome is at /var/lib/pingplotter.agent/maint/last-result (and last-log beside it)
  • TCP traces failing while ICMP works: check the packet helper with systemctl status pingplotter.packet-service.socket
  • The agent makes outbound HTTPS (443) connections only - to your PingPlotter Cloud endpoints and packages.pingman.com for updates. No inbound connections.

Uninstalling

  • sudo apt-get remove pingplotter.agent keeps settings, so a reinstall rejoins your account
  • sudo apt-get purge pingplotter.agent removes settings too
  • sudo dnf remove pingplotter.agent on rpm systems

Agents can also be removed from PingPlotter Cloud (delete the agent and choose uninstall).