systemd/Timers

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

Contents

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 which defines when and how the timer activates. Timers are defined as one of two types:

Realtime timers (a.k.a. wallclock timers) activate on a calendar event, the same way that cronjobs do. The option OnCalendar= is used to define them.

Monotonic timers activate after a time span relative to a varying starting point. They stop if the computer is temporarily suspended or shut down. There are number of different monotonic timers but all have the form: OnTypeSec=. Common monotonic timers include OnBootSec and OnActiveSec.

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 .timer suffix). To view all started timers, run:

To list all timers (including inactive), use systemctl list-timers --all.

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 (or ~/.local/share/systemd/ in case of user 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.

Examples

A service unit file can be scheduled with a timer out-of-the-box. The following examples schedule foo.service to be run with a corresponding timer called foo.timer.

Monotonic timer

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

Realtime timer

A timer which starts once a week (at 12:00am on Monday). When activated, it triggers the service immediately if it missed the last start time (option Persistent=true), for example due to the system being powered off:

OnCalendar time specifications can be tested in order to verify their validity and to calculate the next time the condition would elapse when used on a timer unit file with the calendar option of the systemd-analyze utility. For example, one can use systemd-analyze calendar weekly or systemd-analyze calendar "Mon,Tue *-*-01..04 12:00:00".

The faketime command is especially useful to test various scenarios with the above command; it comes with the libfaketime package.

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. The RandomizedDelaySec option in the [Timer] section avoids this problem by randomly staggering the start time of each timer. See systemd.timer(5).

Transient .timer units

One can use systemd-run to create transient .timer units. That is, one can set a command to run at a specified time without having a service file. For example the following command touches a file after 30 seconds:

# systemd-run --on-active=30 /bin/touch /tmp/foo

One can also specify a pre-existing service file that does not have a timer file. For example, the following starts the systemd unit named someunit.service after 12.5 hours have elapsed:

Caveats

Some things that are easy to do with cron are difficult to do with timer units alone:

Creation: to set up a timed job with systemd you need to create two files and run systemctl commands, compared to adding a single line to a crontab.

Emails: there is no built-in equivalent to cron's MAILTO for sending emails on job failure. See the next section for an example of setting up a similar functionality using OnFailure=.

MAILTO

You can set up systemd to send an e-mail when a unit fails. Cron sends mail to MAILTO if the job outputs to stdout or stderr, but many jobs are setup to only output on error. First you need two files: an executable for sending the mail and a .service for starting the executable. For this example, the executable is just a shell script using sendmail:

Whatever executable you use, it should probably take at least two arguments as this shell script does: the address to send to and the unit file to get the status of. The .service we create will pass these arguments:

Where user is the user being emailed and address is that user's email address. Although the recipient is hard-coded, the unit file to report on is passed as an instance parameter, so this one service can send email for many other units. At this point you can startstatus-email-user@dbus.service to verify that you can receive the emails.

Then simply edit the service you want emails for and add OnFailure=status-email-user@%n.service to the [Unit] section. %n passes the unit's name to the template.

Note:

If you set up SSMTP security according to SSMTP#Security the user nobody will not have access to /etc/ssmtp/ssmtp.conf, and the systemctl start status-email-user@dbus.service command will fail. One solution is to use root as the User in the status-email-user@.service unit.

If you try to use mail -s somelogs address in your email script, mail will fork and systemd will kill the mail process when it sees your script exit. Make the mail non-forking by doing mail -Ssendwait -s somelogs address.

Using a crontab

Several of the caveats can be worked around by installing a package that parses a traditional crontab to configure the timers. systemd-cron-nextAUR and systemd-cronAUR are two such packages. These can provide the missing MAILTO feature.

Also, like with crontabs, a unified view of all scheduled jobs can be obtained with systemctl. See #Management.