From Fedora Project Wiki
(Created page with "= Timer guidelines = == Main page == Add in 'Cron Files' section: {{admon/note|Cron files and systemd timer units| * All packages with timed execution which already depen...")
 
No edit summary
Line 15: Line 15:


Additions/rework of systemd guildelines:
Additions/rework of systemd guildelines:
== Systemd guidelines ==
For [https://fedoraproject.org/wiki/Packaging:Systemd https://fedoraproject.org/wiki/Packaging:Systemd]:
Systemd allows for multiple forms of activated services. This document discusses #Hardware activation, #Socket activation, and #DBus activation, and #Timer activation.
...
=== Timer activation ===
Timer activation is used for tasks that run at a specified calendar time, a
specified repeating interval, or at a specifed interval relative to system
boot or other actions.  A timer unit file ends in .timer, and contains a
[Timer] section that describes when the timer unit performs an action. By
default, when a timer unit triggers, it starts a service unit of the same
name.
==== [Install] section for timer units ====
A timer unit that is tied to a specific service and should only run if that
service is enabled running should include:
<pre>
[Install]
WantedBy=<dependent service>.service
</pre>
If it '''also''' should only run if that
service is running, it should include:
<pre>
[Unit]
BindsTo=<dependent service>.service
</pre>
On the other hand, a timer unit that is independent of other services should
include:
<pre>
[Install]
WantedBy=timers.target
</pre>
{{admon/note|Note on enablement|Whether a timer unit is enabled by default is controlled by
systemd presets, just like any other systemd unit.}}
==== Examples ====
===== Bound to another service =====
A periodic service to be run while a service is running consists of three
units - the main service unit, the timer unit, and a service unit for the
scheduled task.
acme.service:
<pre>
[Unit]
Description=ACME Sample Service
Documentation=man:acme(1)
[Service]
ExecStart=/usr/bin/acmed
[Install]
WantedBy=multi-user.target
</pre>
acme-job.timer
<pre>
[Unit]
Description=ACME Sample Timer Trigger
Documentation=man:acme(1)
BindTo=acme.service
[Timer]
OnCalendar=daily
[Install]
WantedBy=acme.service
</pre>
acme-job.service
<pre>
[Unit]
Description=ACME post-boot service
Documentation=man:acme(1)
[Service]
User=acme
ExecStart=/usr/bin/acme-job
</pre>
===== After Boot Time Trigger =====
A one-shot timer that runs after boot. Not tied to any service.
acme-job.timer
<pre>
[Unit]
Description=ACME Sample Timer Trigger 5 Minutes After Boot
Documentation=man:acme(1)
[Timer]
OnBootSec=5m
[Install]
WantedBy=timers.target
</pre>
acme-job.service
<pre>
[Unit]
Description=ACME post-boot service
Documentation=man:acme(1)
[Service]
User=acme
ExecStart=/usr/bin/acme-job
</pre>
===== Post-boot and Hourly timer =====
Differnt methods of scheduling the timer can be combined with the use of
multiple directives under [Timer].
acme.service:
<pre>
[Unit]
Description=ACME Sample Service
Documentation=man:acme(1)
[Service]
ExecStart=/usr/bin/acmed
[Install]
WantedBy=multi-user.target
</pre>
acme-job.timer
<pre>
[Unit]
Description=ACME Sample Timer Trigger 5 Minutes After Boot And Hourly After
That
Documentation=man:acme(1)
BindTo=acme.service
[Timer]
OnBootSec=5m
OnUnitActiveSec=1h
[Install]
WantedBy=timers.target
</pre>
acme-job.service:
<pre>
[Unit]
Description=Daily ACME Job
Documentation=man:acme(1)
[Service]
User=acme
ExecStart=/usr/bin/acme-job
</pre>
===== Traditional Hourly/Daily/etc timer =====
A timer that runs on an interval, much like a 'normal' cron task.
acme.timer
<pre>
[Unit]
Description=ACME Sample Timer Unit
Documentation=man:acme(1)
[Timer]
OnCalendar=daily|hourly|monthly
[Install]
WantedBy=timers.target
</pre>
acme.service
<pre>
[Unit]
Description=Periodic ACME task
Documentation=man:acme(1)
[Service]
User=acme
ExecStart=/usr/bin/acme
</pre>
{{admon/note|Timer formats|
For more examples of time formats that can be
specified in an OnCalendar directive, see man 7 systemd.time
}}

Revision as of 20:52, 2 April 2014

Timer guidelines

Main page

Add in 'Cron Files' section:


Note.png
Cron files and systemd timer units
  • All packages with timed execution which already depend on systemd (for example because they contain service units) MUST use timer units instead of cron jobs, with no dependency on a cron daemon.
  • Packages which do not already depend on systemd MUST NOT use timer units and instead use cron as specified here, to avoid introducing unnecessary new dependencies on systemd directly.

This would go on the cron-specific page as well.

Additions/rework of systemd guildelines:

Systemd guidelines

For https://fedoraproject.org/wiki/Packaging:Systemd:

Systemd allows for multiple forms of activated services. This document discusses #Hardware activation, #Socket activation, and #DBus activation, and #Timer activation.

...

Timer activation

Timer activation is used for tasks that run at a specified calendar time, a specified repeating interval, or at a specifed interval relative to system boot or other actions. A timer unit file ends in .timer, and contains a [Timer] section that describes when the timer unit performs an action. By default, when a timer unit triggers, it starts a service unit of the same name.


[Install] section for timer units

A timer unit that is tied to a specific service and should only run if that service is enabled running should include:

[Install]
WantedBy=<dependent service>.service

If it also should only run if that service is running, it should include:

[Unit]
BindsTo=<dependent service>.service

On the other hand, a timer unit that is independent of other services should include:

[Install]
WantedBy=timers.target
Note.png
Note on enablement
Whether a timer unit is enabled by default is controlled by systemd presets, just like any other systemd unit.


Examples

Bound to another service

A periodic service to be run while a service is running consists of three units - the main service unit, the timer unit, and a service unit for the scheduled task.

acme.service:

[Unit]
Description=ACME Sample Service
Documentation=man:acme(1)

[Service]
ExecStart=/usr/bin/acmed

[Install]
WantedBy=multi-user.target

acme-job.timer

[Unit]
Description=ACME Sample Timer Trigger
Documentation=man:acme(1)
BindTo=acme.service

[Timer]
OnCalendar=daily

[Install]
WantedBy=acme.service

acme-job.service

[Unit]
Description=ACME post-boot service
Documentation=man:acme(1)

[Service]
User=acme
ExecStart=/usr/bin/acme-job


After Boot Time Trigger

A one-shot timer that runs after boot. Not tied to any service.

acme-job.timer

[Unit]
Description=ACME Sample Timer Trigger 5 Minutes After Boot
Documentation=man:acme(1)

[Timer]
OnBootSec=5m

[Install]
WantedBy=timers.target

acme-job.service

[Unit]
Description=ACME post-boot service
Documentation=man:acme(1)

[Service]
User=acme
ExecStart=/usr/bin/acme-job


Post-boot and Hourly timer

Differnt methods of scheduling the timer can be combined with the use of multiple directives under [Timer].

acme.service:

[Unit]
Description=ACME Sample Service
Documentation=man:acme(1)

[Service]
ExecStart=/usr/bin/acmed

[Install]
WantedBy=multi-user.target

acme-job.timer

[Unit]
Description=ACME Sample Timer Trigger 5 Minutes After Boot And Hourly After
That
Documentation=man:acme(1)
BindTo=acme.service

[Timer]
OnBootSec=5m
OnUnitActiveSec=1h

[Install]
WantedBy=timers.target


acme-job.service:

[Unit]
Description=Daily ACME Job
Documentation=man:acme(1)

[Service]
User=acme
ExecStart=/usr/bin/acme-job


Traditional Hourly/Daily/etc timer

A timer that runs on an interval, much like a 'normal' cron task.

acme.timer

[Unit]
Description=ACME Sample Timer Unit
Documentation=man:acme(1)

[Timer]
OnCalendar=daily|hourly|monthly

[Install]
WantedBy=timers.target

acme.service

[Unit]
Description=Periodic ACME task
Documentation=man:acme(1)

[Service]
User=acme
ExecStart=/usr/bin/acme


Note.png
Timer formats
For more examples of time formats that can be specified in an OnCalendar directive, see man 7 systemd.time