Systemd/timers: Difference between revisions

From NixOS Wiki
imported>Skylark
Copyedit, don't like to potentially out-of-date copy of manpage
H7x4 (talk | contribs)
Add section about systemd.services.<name>.startAt
 
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Timers are systemd unit files whose name ends in .timer that control .service files or events. Timers can be used as an alternative to <code>cron</code>. Timers have built-in support for calendar-based events and monotonic time events, and can be run asynchronously.
{{Systemd/breadcrumb}}
 
== Configuration ==


<translate>
<!--T:1-->
Timers are systemd unit files whose name ends in .timer that control .service files or events. Timers can be used as an alternative to <code>cron</code>. Timers have built-in support for calendar-based events and monotonic time events, and can be run asynchronously.
</translate>
<translate>
== Configuration == <!--T:2-->
</translate>
<translate>
<!--T:3-->
The following example timer runs a systemd unit every 5 minutes which invokes a bash script.
The following example timer runs a systemd unit every 5 minutes which invokes a bash script.
 
</translate>
<syntaxHighlight lang="nix">
<syntaxHighlight lang="nix">
systemd.timers."hello-world" = {
systemd.timers."hello-world" = {
Line 27: Line 34:
</syntaxHighlight>
</syntaxHighlight>


Alternatively here, avoid quotes when calling for the binary and its command options:
<syntaxHighlight lang="nix">
${pkgs.foo}/bin/foo command-options
</syntaxHighlight>
This will yield the same result as running
<syntaxhighlight lang="bash">
foo command-options
</syntaxhighlight>
in your terminal.
====Using the <code>systemd.services.&lt;name&gt;.startAt</code> shorthand====
If you only want a service to execute at an interval and don't plan to configure the timer much more, you can use the <code>systemd.services.&lt;name&gt;.startAt</code> option. This will have the underlying systemd module in nixpkgs create the timer for you, and set its <code>OnCalendar</code> field. Note that the semantics for <code>OnCalendar</code> are different to <code>OnUnitActiveSec</code>.
This example shows the previous <code>hello-world</code> service configured with <code>startAt</code>, running every 5 minutes.
<syntaxHighlight lang="nix">
systemd.services."hello-world" = {
  script = ''
    set -eu
    ${pkgs.coreutils}/bin/echo "Hello World"
  '';
  serviceConfig = {
    Type = "oneshot";
    User = "root";
  };
  startAt = "*:0/5";
};
</syntaxHighlight>
====Running timer on a schedule====
<translate>
<!--T:4-->
The following example starts once a day (at 12:00am). 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.
The following example starts once a day (at 12:00am). 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.
 
</translate>
<syntaxHighlight lang="nix">
<syntaxHighlight lang="nix">
...
...
   serviceConfig = {
   timerConfig = {
       OnCalendar = "daily";
       OnCalendar = "daily";
       Persistent = true;  
       Persistent = true;  
Line 37: Line 81:
};
};
</syntaxHighlight>
</syntaxHighlight>
 
<translate>
<!--T:5-->
More examples can be found at the [https://wiki.archlinux.org/title/Systemd/Timers Arch Wiki] and at the <code>systemd.timer</code> manpage.
More examples can be found at the [https://wiki.archlinux.org/title/Systemd/Timers Arch Wiki] and at the <code>systemd.timer</code> manpage.
 
</translate>
== Usage ==
<translate>
 
== Usage == <!--T:6-->
</translate>
<translate>
<!--T:7-->
List active timers and their current state:
List active timers and their current state:
 
</translate>
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl list-timers
systemctl list-timers
</syntaxhighlight>
</syntaxhighlight>
 
<translate>
<!--T:8-->
Manually run a service once for testing purposes:
Manually run a service once for testing purposes:
 
</translate>
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl start hello-world
systemctl start hello-world
</syntaxhighlight>
</syntaxhighlight>
[[Category:systemd]]

Latest revision as of 22:55, 15 September 2024

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. Timers have built-in support for calendar-based events and monotonic time events, and can be run asynchronously.

Configuration

The following example timer runs a systemd unit every 5 minutes which invokes a bash script.

systemd.timers."hello-world" = {
  wantedBy = [ "timers.target" ];
    timerConfig = {
      OnBootSec = "5m";
      OnUnitActiveSec = "5m";
      Unit = "hello-world.service";
    };
};

systemd.services."hello-world" = {
  script = ''
    set -eu
    ${pkgs.coreutils}/bin/echo "Hello World"
  '';
  serviceConfig = {
    Type = "oneshot";
    User = "root";
  };
};


Alternatively here, avoid quotes when calling for the binary and its command options:

${pkgs.foo}/bin/foo command-options

This will yield the same result as running

foo command-options

in your terminal.

Using the systemd.services.<name>.startAt shorthand

If you only want a service to execute at an interval and don't plan to configure the timer much more, you can use the systemd.services.<name>.startAt option. This will have the underlying systemd module in nixpkgs create the timer for you, and set its OnCalendar field. Note that the semantics for OnCalendar are different to OnUnitActiveSec.

This example shows the previous hello-world service configured with startAt, running every 5 minutes.

systemd.services."hello-world" = {
  script = ''
    set -eu
    ${pkgs.coreutils}/bin/echo "Hello World"
  '';
  serviceConfig = {
    Type = "oneshot";
    User = "root";
  };
  startAt = "*:0/5";
};

Running timer on a schedule

The following example starts once a day (at 12:00am). 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.

...
  timerConfig = {
      OnCalendar = "daily";
      Persistent = true; 
  };
};

More examples can be found at the Arch Wiki and at the systemd.timer manpage.

Usage

List active timers and their current state:

systemctl list-timers

Manually run a service once for testing purposes:

systemctl start hello-world