Official NixOS Wiki

Systemd/timers: Difference between revisions

← Older edit
VisualWikitext
0x4A6F (talk | contribs)
moderator, trusted
83 edits
m 0x4A6F moved page Systemd/Timers to Systemd/timers
https://man.archlinux.org/man/systemd.timer.5.en "services with RemainAfterExit=yes set (which stay around continuously even after the service's main process exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and then stay around forever."
Tags: Manual revert Visual edit
 
(7 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Systemd/breadcrumb}}
{{Systemd/breadcrumb}}


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>
 
<!--T:1-->
== Configuration ==
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" = {
   wantedBy = [ "timers.target" ];
   wantedBy = [ "timers.target" ];
Line 13: Line 18:
       OnBootSec = "5m";
       OnBootSec = "5m";
       OnUnitActiveSec = "5m";
       OnUnitActiveSec = "5m";
      # Alternatively, if you prefer to specify an exact timestamp
      # like one does in cron, you can use the `OnCalendar` option
      # to specify a calendar event expression.
      # Run every Monday at 10:00 AM in the Asia/Kolkata timezone.
      #OnCalendar = "Mon *-*-* 10:00:00 Asia/Kolkata";
       Unit = "hello-world.service";
       Unit = "hello-world.service";
     };
     };
Line 26: Line 36:
     User = "root";
     User = "root";
   };
   };
};
</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.
==== Verifying your timestamp for systemd.time ====
If you do not understand the format that [https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html systemd.time] expects, you can use the <code>systemd-analyze</code>'s <code>calendar</code> sub-command to understand the next ''N'' times when the timer will get triggered. Following is an example:<syntaxhighlight lang="shell-session">
$ systemd-analyze calendar --iterations=5 "10:00:00"
  Original form: 10:00:00
Normalized form: *-*-* 10:00:00
    Next elapse: Sat 2024-12-07 10:00:00 IST
      (in UTC): Sat 2024-12-07 04:30:00 UTC
      From now: 33min left
  Iteration #2: Sun 2024-12-08 10:00:00 IST
      (in UTC): Sun 2024-12-08 04:30:00 UTC
      From now: 24h left
  Iteration #3: Mon 2024-12-09 10:00:00 IST
      (in UTC): Mon 2024-12-09 04:30:00 UTC
      From now: 2 days left
  Iteration #4: Tue 2024-12-10 10:00:00 IST
      (in UTC): Tue 2024-12-10 04:30:00 UTC
      From now: 3 days left
  Iteration #5: Wed 2024-12-11 10:00:00 IST
      (in UTC): Wed 2024-12-11 04:30:00 UTC
      From now: 4 days left
</syntaxhighlight>
====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>
</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">
...
...
Line 39: Line 108:
};
};
</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]]
Retrieved from "https://wiki.nixos.org/wiki/Systemd/timers"