[Enhancement proposal] Systemd timer–based scheduling with randomized execution

[glenmortt]

While scheduling is not currently enforced during patchman-client installation, the documentation recommends configuring periodic execution. I’d like to propose an enhancement to improve both scalability and alignment with modern Linux practices.

Problem statement
Running /usr/sbin/patchman-client simultaneously across a large fleet can create unnecessary load spikes on the Patchman server (thundering herd effect).

Traditional cron does not provide a native mechanism to randomize execution within a time window. Common workarounds such as:
sleep $((RANDOM % 3600))
are ad hoc and not particularly robust or observable.
Proposed solution
Adopt a systemd timer–based approach as the recommended (or default) scheduling mechanism, leveraging:

• RandomizedDelaySec= to spread execution over a defined interval
• Persistent=true to catch up on missed runs (e.g., after downtime)

Rationale
Compared to cron, systemd timers provide several operational advantages:

• Built-in randomization (RandomizedDelaySec) to prevent synchronized execution across nodes
• Centralized logging via journalctl, avoiding reliance on local mail delivery
• Failure visibility and retry semantics through standard service units
• Execution isolation (each timer runs as an independent unit with a well-defined environment)
• Missed run handling (Persistent=true) for systems that were powered off
• Richer configuration model, including dependencies, conditions, and resource controls

Backward compatibility

• Existing cron-based setups remain functional
• This proposal primarily updates documentation and/or installation defaults to prefer systemd timers

Example

# Create the service unit
sudo tee /etc/systemd/system/patchman-client.service > /dev/null <<'EOF'
[Unit]
Description=Run Patchman client

[Service]
Type=oneshot
ExecStart=/usr/sbin/patchman-client
EOF

# Create the daily timer unit
sudo tee /etc/systemd/system/patchman-client.timer > /dev/null <<'EOF'
[Unit]
Description=Daily Patchman client with random delay

[Timer]
# Run every day at 08:00
OnCalendar=*-*-* 08:00:00

# Add random delay up to 2 hours
RandomizedDelaySec=2h

# If the system was off, run missed job after boot
Persistent=true

[Install]
WantedBy=timers.target
EOF

# Create the boot timer unit
sudo tee /etc/systemd/system/patchman-client-boot.timer > /dev/null <<'EOF'
[Unit]
Description=Run Patchman client after boot

[Timer]
OnBootSec=2min
RandomizedDelaySec=5min
Unit=patchman-client.service

[Install]
WantedBy=timers.target
EOF

# Enable and start the timer
systemctl daemon-reexec
systemctl daemon-reload
systemctl enable --now patchman-client.timer
systemctl enable --now patchman-client-boot.timer