No edit summary |
m (Change wording for MUST.) |
||
| (7 intermediate revisions by 4 users not shown) | |||
| Line 7: | Line 7: | ||
{{admon/ | {{admon/important|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 [https://fedoraproject.org/wiki/Packaging:Systemd#Timer_activation timer units] instead of cron jobs, with no dependency on a cron daemon. | * All packages with timed execution or scheduled tasks which already depend on systemd (for example because they contain service units) '''MUST''' use [https://fedoraproject.org/wiki/Packaging:Systemd#Timer_activation timer units] instead of cron jobs, with no dependency on a cron daemon. | ||
* Packages | * Packages '''MUST NOT''' depend ong both cron and system systemd directly. | ||
}} | }} | ||
| Line 29: | Line 29: | ||
specified repeating interval, or at a specifed interval relative to system | 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 | 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. | <code>[Timer]</code> section that describes when the timer unit performs an action. | ||
A timer unit does not itself run a command. Instead it starts a service unit when it | |||
name. | triggers. By default, it starts a service unit of the same name. | ||
==== [Install] section for timer units ==== | ==== <code>[Install]</code> section for timer units ==== | ||
A timer unit that is tied to a specific service and should only run if that | A timer unit that is tied to a specific service and should only run if that | ||
| Line 68: | Line 68: | ||
A periodic service to be run while a service is running consists of three | 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 | units - the main service unit that must be running for the timer unit to | ||
trigger, the timer unit, and a service unit that actually performs the | |||
scheduled task. | scheduled task. | ||
acme.service: | <code>acme.service</code>: | ||
<pre> | <pre> | ||
| Line 85: | Line 86: | ||
</pre> | </pre> | ||
acme-job.timer | <code>acme-job.timer</code>: | ||
<pre> | <pre> | ||
| Line 91: | Line 92: | ||
Description=ACME Sample Timer Trigger | Description=ACME Sample Timer Trigger | ||
Documentation=man:acme(1) | Documentation=man:acme(1) | ||
BindsTo=acme.service | |||
[Timer] | [Timer] | ||
| Line 100: | Line 101: | ||
</pre> | </pre> | ||
acme-job.service | <code>acme-job.service</code>: | ||
<pre> | <pre> | ||
| Line 111: | Line 112: | ||
ExecStart=/usr/bin/acme-job | ExecStart=/usr/bin/acme-job | ||
</pre> | </pre> | ||
===== After Boot Time Trigger ===== | ===== After Boot Time Trigger ===== | ||
| Line 118: | Line 117: | ||
A one-shot timer that runs after boot. Not tied to any service. | A one-shot timer that runs after boot. Not tied to any service. | ||
acme-job.timer | <code>acme-job.timer</code>: | ||
<pre> | <pre> | ||
| Line 132: | Line 131: | ||
</pre> | </pre> | ||
acme-job.service | <code>acme-job.service</code>: | ||
<pre> | <pre> | ||
| Line 150: | Line 149: | ||
multiple directives under [Timer]. | multiple directives under [Timer]. | ||
acme.service: | <code>acme.service</code>: | ||
<pre> | <pre> | ||
| Line 164: | Line 163: | ||
</pre> | </pre> | ||
acme-job.timer | <code>acme-job.timer</code>: | ||
<pre> | <pre> | ||
| Line 171: | Line 170: | ||
That | That | ||
Documentation=man:acme(1) | Documentation=man:acme(1) | ||
BindsTo=acme.service | |||
[Timer] | [Timer] | ||
| Line 182: | Line 181: | ||
acme-job.service: | <code>acme-job.service</code>:: | ||
<pre> | <pre> | ||
| Line 199: | Line 198: | ||
A timer that runs on an interval, much like a 'normal' cron task. | A timer that runs on an interval, much like a 'normal' cron task. | ||
acme.timer | <code>acme.timer</code> | ||
<pre> | <pre> | ||
| Line 213: | Line 212: | ||
</pre> | </pre> | ||
acme.service | <code>acme.service</code> | ||
<pre> | <pre> | ||
| Line 226: | Line 225: | ||
{{admon/note| | |||
For more examples of time formats that can be | {{admon/note|Time formats| | ||
specified in an OnCalendar directive, see | For more examples of time formats that can be specified in an <code>OnCalendar</code> directive, see the <code>systemd.time(7)</code> man page. | ||
}} | }} | ||
Latest revision as of 16:48, 17 April 2014
Timer guidelines
Main page
Add in 'Cron Files' section:
- All packages with timed execution or scheduled tasks 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 MUST NOT depend ong both cron and system 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.
A timer unit does not itself run a command. Instead it starts a service unit when it
triggers. By default, 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
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 that must be running for the timer unit to trigger, the timer unit, and a service unit that actually performs 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) BindsTo=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) BindsTo=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
For more examples of time formats that can be specified in an
OnCalendar directive, see the systemd.time(7) man page.