systemd_timer

Manages a systemd .timer unit: it generates the unit from structured parameters and controls whether the timer is enabled at boot and currently armed. Idempotent: re-applying an unchanged declaration reports no change.

Category: Scheduled tasks

States

State	Meaning
`present`	The `/etc/systemd/system/<name>.timer` unit exists with the generated content; with `enable: true` (the default) the timer is also enabled at boot and active, with `enable: false` it is disabled and inactive.
`absent`	The timer unit is removed (after a best-effort disable+stop) and systemd is reloaded.

Parameters

Parameter	Type	Required	Description
`on_calendar`	string	yes	systemd `OnCalendar=` expression (required for state `present`). Single line; not pre-validated — systemctl rejects malformed expressions at enable time.
`service`	string		Unit the timer triggers (`Unit=`). The paired service is the operator’s responsibility. Default: `<name>.service`.
`persistent`	bool		systemd `Persistent=` flag — run the job on next boot if a scheduled run was missed. Default: `false`.
`description`	string		Unit `Description=` value. Single line. Default: `Keystone-managed timer <name>`.
`enable`	bool		Enable at boot and activate now. `false` requires the timer disabled and inactive. Default: `true`.

Examples

Nightly backup timer

Triggers backup.service every day at 02:00, catching up after downtime.

systemd_timer:
  backup:
    state: present
    on_calendar: "*-*-* 02:00:00"
    persistent: true
    description: "Nightly backup"

Timer paired with its service

Compose with the file module for the unit; require orders the timer after it.

systemd_timer:
  report:
    state: present
    on_calendar: "Mon *-*-* 08:00:00"
    service: report.service
    require:
      - file: /etc/systemd/system/report.service

Remove a timer

systemd_timer:
  backup:
    state: absent

Notes

Backend: systemd only. On a Linux host without systemctl operations fail with ErrNoBackend; on non-Linux, ErrUnsupportedOS.
Declaration.Name is the timer base name (backup → unit backup.timer).
The .service the timer triggers is the operator’s responsibility — compose with the file and service modules, or point service: at an existing unit.
state=absent cannot carry attribute params (on_calendar, service, persistent, description).
Out of scope (planned, #106): generating the paired .service, --user (per-user) timers, and additional [Timer] knobs (OnBootSec / OnUnitActiveSec / RandomizedDelaySec). v1.0 takes OnCalendar + Persistent only.

cron disk