Oracle Cloud Infrastructure Documentation

Working with Timers in Systemd

Explains how systemd timer units schedule work and how to configure real-time, monotonic, and transient timers.

Timer unit files are a type of systemd file that the systemctl utility uses to schedule tasks, similar to the cron utility that uses crontab and other cron jobs for the same purpose.

Note that the cron daemon runs as a service within systemd, so timer units are preferred because they remove a layer of added processing and offer much more utility and more granular configuration than is available in the cron service.

Typically, packages that use specific services to function in the system include their own systemd timer unit files. Thus, when these packages are installed with Oracle Linux, the timer unit files are automatically included. You can display the timer files on the system with the following command: 

systemctl list-unit-files --type=timer
Note

The list of timer files might differ depending on where Oracle Linux is running, such as in an instance in Oracle Cloud Infrastructure, a physical system, and so on.

Each timer unit file contains parameter settings that manage the schedule of a task. For example, the schedule for running dnf-makecache.service is set in the dnf-makecache.timer file. The file contains the following settings:

systemctl cat dnf-makecache.timer
# /usr/lib/systemd/system/dnf-makecache.timer
[Unit]
Description=dnf makecache --timer
ConditionKernelCommandLine=!rd.live.image
# See comment in dnf-makecache.service
ConditionPathExists=!/run/ostree-booted
Wants=network-online.target

[Timer]
OnBootSec=10min
OnUnitInactiveSec=1h
RandomizedDelaySec=60m
Unit=dnf-makecache.service

[Install]
WantedBy=timers.target

The schedule information is specified under the [Timer] section.

In the sample configuration, the dnf-makecache.service service is set to automatically run 10 minutes after the system is booted. The service then goes into idle mode for an hour, as specified by the OnUnitInactiveSec parameter. At the end of the hour, the service runs again. This cycle continues every hour indefinitely.

The RandomizedDelaySec setting provides a value limit for how much a run can be delayed beyond its schedule.

In the example, the service is allowed to run one minute later than its schedule at the latest. This parameter is useful for preventing too many jobs that start at the same time on a specified schedule, which would otherwise risk overloading the resources.

OnCalendar is another useful parameter for task scheduling. Suppose that the parameter is set as follows:

OnCalendar=*:00/10

The *:00 indicates every hour at the top of the hour, while the /10 setting indicates 10 minutes. Therefore, the job is set to run hourly, at ten minutes past the top of the hour.

For a complete list of systemd timer unit file parameters for scheduling a job, see the systemd.timer(5) manual pages.

Tip

For a tutorial on how to use systemd in Oracle Linux, including how to configure systemd timer unit files, see https://docs.oracle.com/en/learn/ol-systemd/.

Using Timer Units to Control Service Unit Runtime

Explains how timer units replace cron jobs and how to inspect, enable, and monitor timer-triggered services.

Timer units can be configured to control when service units run.

You can use timer units instead of configuring the cron daemon for time-based events. Timer units can be more complicated to configure than creating a crontab entry. However, timer units are more configurable and the services that they control can be configured for better logging and deeper integration with systemd architecture.

Timer units are started, enabled, and stopped similarly to service units. For example, to enable and start a timer unit immediately, type:

sudo systemctl enable --now myscript.timer

To list all existing timers on the system, to see when they last ran, and when they're next configured to run, type:

systemctl list-timers

For more information about system timers, see the systemd.timer(5) and systemd.time(7) manual pages.

Configuring a Realtime Timer Unit

Realtime timers activate on a calendar event, similar to events in a crontab. The option OnCalendar specifies when the timer runs a service.

  • If needed, create a .service file that defines the service to be triggered by the timer unit. In the following procedure, the sample service is /etc/systemd/system/update.service which is a service unit that runs an update script.

    For more information about creating service units, see Creating a User-Based systemd Service.

  • Decide the time and frequency for running the service. In this procedure, the timer is configured to run the service every 2 hours from Monday to Friday.

This task shows you how to create a system timer to trigger a service to run based on a calendar event. The definition of the calendar event is similar to entries that you put in a cron job.

  1. Create the /etc/systemd/system/update.timer with the following content: 
    [Unit]
Description="Run the update.service every two hours from Mon to Fri."

[Timer]
OnCalendar=Mon..Fri 00/2 
Unit=update.service

[Install]
WantedBy=multi-user.target

    OnCalendar can use a straightforward setting such as OnCalendar=weekly or can use more complex definitions that are more detailed. However, the format for defining settings is constant, as follows:

    DayofWeek Year-Month-Day Hour:Minute:Second

    The following definition means "the first 4 days of each month at 12:00 o'clock noon, but only if that day is either a Monday or a Tuesday":

    OnCalendar=Mon,Tue *-*-01..04 12:00:00

    For other ways to define OnCalendar and for more timer options that you can configure in the system timer file, see the systemd.timer(5) and systemd.time(7) manual pages.

  2. Check that all the files related to this timer are configured correctly. 
    systemd-analyze verify /etc/systemd/system/update.*

    Any detected errors are reported on the screen.

  3. Start the timer. 
    sudo systemctl start update.timer

    This command starts the timer for the current session only.

  4. Ensure that the timer starts when the system is booted. 
    sudo systemctl enable update.timer

Configuring a Monotonic Timer Unit

Monotonic timers activate after a time span relative to a varying starting point, such as a boot event, or when a particular systemd unit becomes active. These timer units stop if the computer is temporarily suspended or shut down. Monotonic timers are configured by using the OnTypeSec option, where Type is the name of the event to which the timer is related. Common monotonic timers include OnBootSec and OnUnitActiveSec.

  • If needed, create a .service file that defines the service to be triggered by the timer unit. In the following procedure, the sample service is /etc/systemd/system/update.service which is a service unit that runs an update script.

    For more information about creating service units, see Creating a User-Based systemd Service.

  • Decide the time and frequency for running the service. In this procedure, the timer is configured to run the service 10 minutes after a system boot, and every 2 hours from when the service is last activated.

This task shows you how to create a system timer to trigger a service to run at specific events, which are when the system boots or after 2 hours have lapsed from the timer's activation.

  1. Create the /etc/systemd/system/update.timer with the following content: 
    [Unit]
Description="Run the update.service every two hours from Mon to Fri."

[Timer]
OnBootSec=10min
OnUnitActiveSec=2h
Unit=update.service

[Install]
WantedBy=multi-user.target

    For more timer options that you can configure in the system timer, see the systemd.timer(5) and systemd.time(7) manual pages.

  2. Check that all the files related to this timer are configured correctly. 
    systemd-analyze verify /etc/systemd/system/update.*

    Any detected errors are reported on the screen.

  3. Start the timer. 
    sudo systemctl start update.timer

    This command starts the timer for the current session only.

  4. Ensure that the timer starts when the system is booted. 
    sudo systemctl enable update.timer

Running a Transient Timer Unit

Demonstrates how to launch one-off timers with systemctl run so you can schedule ad hoc tasks without creating unit files.

Transient timers are temporary timers that are valid only for the current session.

These timers can be created to run a program or script directly without requiring service or timer units to be configured within systemd. These units are generated by using the systemd-run command. See the systemd-run(1) manual page for more information.

The parameter options that you would add to the unit-file.timer file also serve as arguments when you use systemd-run command to run a transient timer unit.

The following examples show how to use systemd-run to activate transient timers.

  • Run update.service after 2 hours have elapsed.

    sudo systemd-run --on-active="2h" --unit update.service

  • Create ~/tmp/myfile after 1 hour. 

    sudo systemd-run --on-active="1h" /bin/touch ~/tmp/myfile

  • Run ~/myscripts/update.sh 5 minutes after the service manager is started. Use this syntax to run a service after the service manager has started at user login.

    sudo systemd-run --on-startup="5m" ~/myscripts/update.sh

  • Run myjob.service 10 minutes after system boot.

    sudo systemd-run --on-boot="10m" --unit myjob.service

  • Run report.service at the end of the day.

    sudo systemd-run --on-calendar="17:00:00"