Knowledge/timer-as-service.md

Timer as a service — quick manual

This short guide shows how to set up a systemd timer that runs a job, how to enable/start it, and how to list and inspect existing timers.

Checklist

• Create a .service that performs the work
• Create a corresponding .timer with the schedule
• Reload systemd, enable and start the timer
• List timers and inspect logs for failures

Units: example

System-wide units live under /etc/systemd/system. For per-user timers use ~/.config/systemd/user/ and systemctl --user.

Create /etc/systemd/system/my-job.service:

[Unit]
Description=My scheduled job

[Service]
Type=oneshot
ExecStart=/usr/local/bin/my-job.sh

Create /etc/systemd/system/my-job.timer:

[Unit]
Description=Run my-job every day at 02:30

[Timer]
OnCalendar=*-*-* 02:30:00
Persistent=true

[Install]
WantedBy=timers.target

Notes:

• Type=oneshot is appropriate for short scripts that exit.
• Persistent=true makes missed runs (while the machine was down) run on next boot.

Install, enable and start

After creating or editing unit files run:

sudo systemctl daemon-reload
sudo systemctl enable --now my-job.timer

For a user timer (no sudo):

systemctl --user daemon-reload
systemctl --user enable --now my-job.timer

List existing timers

Show all timers (system):

systemctl list-timers --all

This shows UNIT, ACTIVATES, NEXT, LEFT, LAST and PASSED columns. NEXT is the next trigger time.

User timers:

systemctl --user list-timers --all

Filter for a specific timer:

systemctl list-timers --all | grep my-job
systemctl status my-job.timer
systemctl status my-job.service

Logs and debugging

View recent service logs:

journalctl -u my-job.service -b

View timer logs:

journalctl -u my-job.timer -b

If the job never ran, check:

• systemctl status my-job.timer for errors
• ExecStart path and executable permissions
• run the ExecStart command manually to verify behavior
• OnCalendar syntax (see man systemd.time)

Common fixes:

• sudo systemctl daemon-reload after edits
• ensure my-job.service is reachable and executable by the user that runs it
• for user timers, make sure the user session is running or enable linger if run outside a login session

Helpful examples

Run the job 10 seconds after boot and every 5 minutes:

[Timer]
OnBootSec=10s
OnUnitActiveSec=5min
Persistent=true

Use environment variables inside the service:

[Service]
Environment=ENVIRONMENT=production
EnvironmentFile=/etc/default/my-job

Remove or disable a timer

sudo systemctl disable --now my-job.timer
sudo rm /etc/systemd/system/my-job.timer /etc/systemd/system/my-job.service
sudo systemctl daemon-reload

Quick troubleshooting checklist

• Confirm unit files are syntactically correct
• Check permissions and shebang on the script
• journalctl -u <unit> for errors
• For user timers: check systemctl --user status and enable linger with loginctl enable-linger <user> if needed

---

This file provides a compact reference; tell me if you want a tailored example script and a ready-to-install pair of units added to the repo.