Reliable systemd timers: missed runs, repeatable jobs and completion intervals

A daily maintenance task can disappear during downtime, run twice after a retry, or still be running when its next deadline arrives. A timer answers when to request a service start; the job must decide whether work is needed and whether a previous attempt committed its result.

We build a new, isolated daily marker job, inspect its result, and then compare a UTC wall-clock schedule with an interval measured after completion. The marker writes only its own tiny files. It is not a backup, billing system or exactly-once transaction example. Use a staging host; do not replace an existing production schedule with this fixture.

A calendar schedule suits a particular hour. A completion-relative interval suits polling or maintenance that should rest after each run. A machine-local timer does not coordinate a cluster; use an application queue or distributed coordinator if every missed business event must be processed.

Open the example-values form, choose a new job name and a UTC hour from 0 to 23, then apply the values. The delay spreads starts by up to 300 seconds; it is not a deadline guarantee. The job name also chooses the unit files, script and managed state directory, so never reuse an existing application name.

Values stay in this tab for the selected tutorial and environment. Pending or invalid edits block copying until Apply or Reset. These fields accept public examples only: no passwords, tokens or private application arguments. The daily marker always uses the UTC date; changing the hour does not change its timezone.

The job uses the state directory supplied by systemd, derives today’s UTC date, and returns success if that day’s marker already exists. Otherwise it writes a temporary file in the same directory and renames it into place. A normal interruption before the rename leaves no completed marker; an abrupt power loss can leave a temporary file.

This illustrates repeatability for one small local artifact. The rename does not make an external API call, database update or backup exactly once, and it is not a disk-flush durability protocol. A real job needs its own transaction, idempotency key or durable checkpoint. Start this script only through this service; a direct parallel invocation bypasses systemd’s serialization.

#!/bin/sh
set -eu
umask 077
: "${STATE_DIRECTORY:?Start this job through its systemd service}"
day=$(date -u +%F)
report="$STATE_DIRECTORY/$day.txt"
if test -f "$report"; then
    printf 'ALREADY_DONE %s\n' "$day"
    exit 0
fi
tmp=$(mktemp "$STATE_DIRECTORY/.report.XXXXXX")
trap 'rm -f -- "$tmp"' EXIT HUP INT TERM
printf 'academy daily marker for UTC day %s\n' "$day" > "$tmp"
mv -- "$tmp" "$report"
trap - EXIT HUP INT TERM
printf 'COMPLETED %s\n' "$day"