systemd/Timers

Related articles

• systemd
• systemd/User
• systemd/Services
• systemd FAQ
• cron

Timers are systemd unit files whose name ends in .timer that control .service files or events. Timers have the ability to be an alternate to cron (read #As a cron replacement). Timers have built-in support for calendar time events, monotonic time events, and have the ability to run asynchronously.

Timer units

Timers are systemd unit files with a suffix of .timer. Timers are like other unit configuration files and are loaded from the same paths but include a [Timer] section. The[Timer] section defines when and how the timer activates. Timers are defined as one of two types:

• Monotonic timers activate after a time span relative to a varying starting point. There are number of different monotonic timers but all have the form of: OnTypeSec=. OnBootSec and OnActiveSec are common monotonic timers.
• Realtime timers (a.k.a. wallclock timers) activate on a calendar event (like cronjobs). The option OnCalender= is used to define them.

For a full explanation of timer options, see the systemd.timer(5) man page. The argument syntax for calendar events and time spans is defined on the systemd.time(7) man page.

Service unit

For each .timer file, a matching .service file exists (e.g. foo.timer and foo.service). The .timer file activates and controls the .service file. The .service does not require an [Install] section as it is the timer units that are enabled. If necessary, it is possible to control a differently-named unit using the Unit= option in the timer's [Timer] section.

Management

To use a timer unit enable and start it like any other unit (remember to add the the .timer suffix). To view all started timers, run:

$ systemctl list-timers

NEXT                          LEFT        LAST                          PASSED     UNIT                         ACTIVATES
Thu 2014-07-10 19:37:03 CEST  11h left    Wed 2014-07-09 19:37:03 CEST  12h ago    systemd-tmpfiles-clean.timer systemd-tmpfiles-clean.service
Fri 2014-07-11 00:00:00 CEST  15h left    Thu 2014-07-10 00:00:13 CEST  8h ago     logrotate.timer              logrotate.service

Note:

• The status of a service started by a timer will likely be inactive unless it is currently being triggered.
• If a timer gets out of sync, it may help to delete its stamp-* file in /var/lib/systemd/timers. These are zero length files which mark the last time each timer was run. If deleted, they will be reconstructed on the next start of their timer.

Example

Service units do not require any changes to be scheduled with timers. This example schedules foo.service, thus the timers will be named foo.timer.

Monotonic timer

A timer which will start 15 minutes after boot and again every week while the system is running.

/etc/systemd/system/foo.timer

[Unit]
Description=Run foo weekly and on boot

[Timer]
OnBootSec=15min
OnUnitActiveSec=1w 

[Install]
WantedBy=timers.target

Realtime timer

A timer which starts once a week (specifically 12:00am on Monday) and starts immediately if it missed the last start time.

/etc/systemd/system/foo.timer

[Unit]
Description=Run foo weekly

[Timer]
OnCalendar=weekly
Persistent=true     
 
[Install]
WantedBy=timers.target

Tip: Special event expressions like daily and weekly refer to specific start times and thus any timers sharing such calendar events will start simultaneously. Timers sharing start events can cause poor system performance if the timers' services compete for system resources. Consider manually staggering such timers using specific events e.g. OnCalendar=Wed, 23:15. See #Caveats.

As a cron replacement

Although cron is arguably the most well-known job scheduler, systemd timers can be an alternative.

Benefits

The main benefits of using timers come from each job having its own systemd service. Some of these benefits are:

• Jobs can be easily started independently of their timers. This simplifies debugging.
• Each job can be configured to run in a specific environment (see the systemd.exec(5) man page).
• Jobs can be attached to cgroups.
• Jobs can be set up to depend on other systemd units.
• Jobs are logged in the systemd journal for easy debugging.

Caveats

• Verbosity: to set up a timed job with systemd you create two files and run a couple systemctl commands. Compare that to adding a single line to a crontab. systemd-crontab-generator and systemd-cron are tools that let you manage timed services using a crontab. If you like crontabs just because they provide a unified view of all scheduled jobs, systemctl can provide this. See #Management.
• Emails: there is no built-in equivalent to cron's MAILTO for sending emails on job failure. Similar functionality could be set up with the OnFailure= option in each service.
• Random delay: there is no built-in equivalent to cron's RANDOM_DELAY for randomly spreading timers out across a given interval (see bug report). Services which you do not want to run concurrently must have their timers manually set to minimize overlap.

Note: The AccuracySec option is not useful for randomly staggering timers since it "is synchronized between all local timers units" (systemd.timer(5)). In other words, AccuracySec shifts all timer activation times by the same amount. For example, all OnCalendar=daily timer units with AccuracySec=15m will trigger the associated services at the same point in time between 00:00 and 00:15.

See also

• systemd.timer man page on freedesktop.org
• Fedora Project wiki page on systemd calendar timers
• Gentoo wiki section on systemd timer services
• systemd-crontab-generator — tool to generate timers/services from crontab and anacrontab files

https://github.com/kstep/systemd-crontab-generator || systemd-crontab-generator

• systemd-cron — provides systemd units to run cron scripts; using systemd-crontab-generator to convert crontabs

https://github.com/systemd-cron/systemd-cron || systemd-cron