Documentation — Serverpacemaker

Installation

Serverpacemaker runs on Ubuntu 22.04 LTS and 24.04 LTS. It requires systemd (which is standard on Ubuntu) and root access to manage services.

1. Download the binary

After purchase, you'll receive a download link by email. The binary is a static Linux x86-64 executable.

2. Verify the checksum

Before installing, verify the SHA256 checksum matches what we published:

sha256sum serverpacemaker-v6P-linux-amd64

3. Install

sudo install -m 0755 serverpacemaker-v6P-linux-amd64 /usr/local/bin/serverpacemaker
sudo serverpacemaker --install

The --install command creates the config file, writes the baseline snapshot, and registers the systemd unit. It does not start the service yet.

4. Configure

Edit /etc/serverpacemaker.json and set the list of services to monitor:

{
  "services": ["nginx.service", "php8.3-fpm.service"],
  "interval_seconds": 60,
  "alert_log": "/var/log/serverpacemaker.log",
  "dashboard_enabled": true,
  "dashboard_port": 8080,
  "dashboard_bind": "127.0.0.1",
  "log_max_bytes": 1048576
}

5. Start

sudo systemctl enable --now serverpacemaker

6. Verify

sudo serverpacemaker --status

If your services are listed with running, it's working. If a service shows as down, Serverpacemaker will restart it on the next check cycle.

Configuration

The config file is /etc/serverpacemaker.json. It has seven fields.

Field	Default	Description
`services`	`[]`	List of systemd unit names to monitor. Use the full name with `.service` suffix.
`interval_seconds`	`60`	How often to check the services. Minimum practical value is 10 seconds.
`alert_log`	`/var/log/serverpacemaker.log`	Where to write restart events and errors.
`dashboard_enabled`	`true`	Whether to run the read-only status page on localhost.
`dashboard_port`	`8080`	TCP port for the status page. Only binds to localhost.
`dashboard_bind`	`127.0.0.1`	Address for the status page. Never change this to a public IP.
`log_max_bytes`	`1048576`	Rotate the alert log when it exceeds this size. One gzipped rotation is kept.

Forbidden services

Serverpacemaker refuses to monitor these services, because restarting them could cut your access to the server or break the system's own management:

ssh.service, sshd.service
systemd-logind.service, systemd-networkd.service, systemd-resolved.service
dbus.service, polkit.service
serverpacemaker.service (itself)

If you add any of these to the config, Serverpacemaker logs a warning and skips them.

CLI reference

All commands are read-only except --install, --uninstall, and the interactive Settings menu.

Command	Description
`serverpacemaker`	Interactive menu (requires a terminal). Access Settings to pause or resume.
`serverpacemaker --status`	Print current state and exit.
`serverpacemaker --healthcheck`	Quick health summary for monitoring integrations.
`serverpacemaker --compare`	Diff current services against the pre-install baseline.
`serverpacemaker --dry-run`	Run one check cycle without taking any action.
`serverpacemaker --version`	Print version and exit.
`serverpacemaker --help`	Print usage and exit.
`serverpacemaker --install`	Install as a systemd service (requires root).
`serverpacemaker --uninstall`	Remove Serverpacemaker from this host (requires root).

Alert log format

One line per event. Plain text. Greppable. Rotated by size.

[2026-09-14 03:12:05] service_restarted: nginx.service was down; restarted
[2026-09-14 03:14:00] service_restart_failed: php8.3-fpm.service still down after restart
[2026-09-14 03:15:00] pause_started: 15m by admin
[2026-09-14 03:30:00] pause_expired: resuming checks

Event types

service_restarted — a service was down and came back after restart.
service_restart_failed — a service was down and still down after restart. Requires attention.
pause_started — the operator paused checks via the interactive menu.
pause_expired — the pause expired and checks resumed.
pause_resumed — the operator resumed early.
check_cycle_error — something went wrong during a check cycle (rare).

The alert log is the interface. Wire your own monitoring tool (Promtail, Filebeat, journalctl, inotify) to this file if you want alerts.

Pause system

Sometimes you need to stop a service for maintenance, and you don't want Serverpacemaker to restart it while you work.

The pause system is deliberately restrictive:

Only works from an interactive terminal on the server itself.
No CLI flag, no environment variable, no config field.
Four fixed durations: 5 minutes, 15 minutes, 1 hour, 2 hours.
Global — pauses all services, not one at a time.
Requires typed confirmation (PAUSE or RESUME).

To pause

sudo serverpacemaker
# Press S for Settings
# Choose a duration
# Type PAUSE to confirm

To resume early

sudo serverpacemaker
# Press S for Settings
# Choose "Resume now"
# Type RESUME to confirm

If the pause expires on its own, Serverpacemaker logs pause_expired and resumes the check loop.

Baseline and compare

At install time, Serverpacemaker writes a snapshot of all currently running services to /var/lib/serverpacemaker/baseline.txt. This file is never modified afterward.

To see what has changed since install:

sudo serverpacemaker --compare

Output:

Baseline: /var/lib/serverpacemaker/baseline.txt
  Captured: 2026-09-14T03:45:00Z

Comparison (baseline -> current):
  nginx.service              running -> running
  php8.3-fpm.service         running -> running
  redis-server.service       running -> running

No changes detected.

Useful for detecting services that have silently stopped since install. Also useful when investigating what an update changed.

Troubleshooting

The service isn't starting

sudo systemctl status serverpacemaker
sudo journalctl -u serverpacemaker -n 50 --no-pager

It restarts a service I stopped for maintenance

Use the pause system. Run sudo serverpacemaker, choose Settings, pick a duration. No CLI flags exist for pausing — this is deliberate.

A service restarts in a loop

Serverpacemaker will keep restarting a service that keeps failing. This is by design — the log will show repeated service_restarted lines, and you can see the pattern and fix the underlying cause.

The log file is huge

Rotation is automatic. When the log exceeds log_max_bytes, it's gzipped to .1.gz and the original is truncated. Only one rotated file is kept.

I lost the baseline file

The baseline is written once at install. If it's missing, --compare will say so and exit. Re-run --install to regenerate it, or just use --status which doesn't need the baseline.

Uninstall

sudo serverpacemaker --uninstall

This removes:

The systemd unit
The binary at /usr/local/bin/serverpacemaker
The config at /etc/serverpacemaker.json

This preserves by default:

The alert log at /var/log/serverpacemaker.log
The baseline at /var/lib/serverpacemaker/baseline.txt

To remove those as well, pass --purge:

sudo serverpacemaker --uninstall --purge

The preserved files are useful if you plan to reinstall later, or if you need the alert history for an incident review.

Reinstalls

Each purchase includes three free reinstalls within the first 12 months from the date of purchase. A reinstall is needed when Serverpacemaker must be activated on a different server — for example, after a server migration, an operating system reinstall, or a hardware replacement.

How to request a reinstall

Email a copy of your Stripe receipt to hello@serverpacemaker.com. We'll verify the receipt, reset your activation, and reply within one business day.

What counts as a reinstall

Moving to a new server or VPS
Reinstalling the operating system
Replacing hardware after a failure
Any other case where the activation file on the previous server is no longer accessible

What does not count as a reinstall

Restarting the server (the activation persists)
Updating Serverpacemaker to a new version (the activation persists)
Editing the config file (the activation persists)
Pausing and resuming checks (the activation persists)

After three reinstalls, or after 12 months

A new license is required. This applies regardless of the reason for the reinstall. A new license is $29, the same as the original purchase.

The activation file

After activation, Serverpacemaker writes a small file at /var/lib/serverpacemaker/activated.json. This file is the record of your purchase on this server. If you migrate to a new server, you can copy this file to the new server before shutting down the old one, and no reinstall request is needed.

We do not track your server. Serverpacemaker does not phone home at runtime. Reinstalls are handled entirely by email correspondence.