A systemd timer is a .timer unit that starts the service of the same name on a schedule; its output goes to the journal.
systemctl list-timers
timers and their next run
systemctl list-timers --all
inactive ones too
sudo systemctl enable --now clean.timer
enable and start the timer
sudo systemctl start clean.service
run the job right now
journalctl -u clean.service -n 20
output of the latest runs
systemd-analyze calendar 'Mon..Fri 03:00'
check a schedule
systemctl cat clean.timer
what the unit file says
sudo systemctl daemon-reload
after editing unit files
A timer is a systemd unit with the .timer extension. It runs
nothing itself: at the set time it starts a service, by default the one with
the same name (clean.timer → clean.service). So a job is a pair of
files in /etc/systemd/system: the service says what to do, the timer says
when.
Type=oneshot is a service that runs a command and finishes; while the script
runs, the service is activating. You enable the timer: the service has no
[Install] section, and systemctl enable clean.service only prints a long
warning. An enabled timer shows up in the list with its next run time:
| cron | systemd timer | |
|---|---|---|
| job output | mail, or lost | the service journal, journalctl -u |
| the machine was off | the run is skipped | Persistent=true runs it after boot |
| the previous run is still going | a second one starts | the same unit never starts twice |
| run outside the schedule | paste the command into a terminal | systemctl start, same conditions |
The full form is DayOfWeek Year-Month-Day Hour:Minute:Second. Any part can be
*, a comma-separated list, a range with .. or a step with /.
| Entry | When |
|---|---|
hourly |
every hour at :00 |
daily |
every day at 00:00 |
weekly |
Mondays at 00:00 |
*-*-* 03:30 |
every day at 03:30 |
Mon..Fri 03:00 |
weekdays at 03:00 |
Sat,Sun 10:00 |
weekends at 10:00 |
*-*-01 04:00 |
the first day of every month |
*:0/15 |
every 15 minutes |
03:00 Europe/Moscow |
03:00 Moscow time |
Without a zone, time follows the machine's clock (timedatectl).
systemd-analyze calendar checks an entry and shows its next run:
Besides the calendar, a timer can count from events: OnBootSec=5min is five
minutes after boot, OnUnitActiveSec=1h is an hour after the service last
started.
A service starts outside your terminal and gets an environment of its own:
/, so a relative path in the script starts at the
root; WorkingDirectory= sets another one;PATH is short: ~/bin and whatever ~/.bashrc adds are missing;~/.bashrc and from crontab lines are missing — set them with
Environment=NAME=value or EnvironmentFile=;HOME; with User=student the service runs
as student and gets HOME=/home/student;~/.profile and ~/.bashrc are not read, and umask is 0022.Everything the script prints to stdout and stderr lands in the service
journal. The -o cat option drops the time, host name and
clean.sh[PID] from each line:
Type=oneshot, the full script path in ExecStart=, the
variables it needs in Environment=.30 3 * * * in cron is
OnCalendar=*-*-* 03:30.sudo systemctl daemon-reload, then sudo systemctl start clean.service
and the journal — make sure the job passes.sudo systemctl enable --now clean.timer./etc/cron.d.For oneshot, systemctl start waits for the script to finish and returns 0
or 1. status shows the code the script exited with: status=0/SUCCESS.
Such a timer lasts until reboot; stop it with systemctl stop tick.timer.
The script runs as a temporary service: directory /, short PATH, root or
the user from -p User=. Environment problems show up before the first
scheduled run, and systemd-run returns the script's own code:
It is almost always the service environment (see "The service environment" above). The service journal names the cause:
command not found — use the full path or Environment=PATH=…; a file "not
found" by a relative path — WorkingDirectory=; an empty variable —
Environment=.
The script returned non-zero. The service journal says:
A script's code is the code of its last command (see
exit codes). The service stays failed until the
next successful run or systemctl reset-failed.
systemctl list-timers --all: a dash in the NEXT column means the timer is
not running. systemctl is-enabled clean.timer shows disabled — run
sudo systemctl enable --now clean.timer.
The timer has nothing to point at: no service with the same name exists. Give
both files the same name or name the service in the timer:
Unit=clean.service under [Timer].
OnCalendar= has an error, and the timer will not start. The journal
(journalctl -u clean.timer) has two lines: clean.timer:5: Failed to parse
calendar specification, ignoring: daily at 3 and Timer unit lacks value
setting. Refusing.
Check the entry with systemd-analyze calendar '…' and the whole file with
systemd-analyze verify /etc/systemd/system/clean.timer.
The unit file was edited, but systemd still runs the old version — and the old
schedule. Run sudo systemctl daemon-reload, then
sudo systemctl restart clean.timer.
enable was called on the service. Enable the timer instead:
sudo systemctl enable --now clean.timer.
The service has RemainAfterExit=yes. After the first run it stays active even
though the script has finished:
The timer's next trigger (and systemctl start) does nothing: the service is
already "running". A scheduled job does not need this line — remove it, run
daemon-reload and systemctl stop clean.service.
Once the job moves to a timer, remove it from cron. Otherwise it follows two schedules and the runs can overlap: systemd knows nothing about the cron copy. Guarding different launchers against each other is the job of flock.
The last run time is stored in /var/lib/systemd/timers/stamp-*.timer. If the
machine was off, the missed run happens right after boot — a heavy job (a
backup, a cleanup) starts together with the system.
failed and what status=1 means.PATH comes from and why a service lacks yours.Found an inaccuracy? Report an error in the article