Systemd/timers/en: Difference between revisions

(One intermediate revision by the same user not shown)

Line 4:

== Configuration ==

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

<~~syntaxHighlight~~ lang="nix">

systemd.timers."hello-world" = {

wantedBy = [ "timers.target" ];

Line 10:

OnBootSec = "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";

};

Line 22:

Line 27:

Type = "oneshot";

User = "root";

RemainAfterExit = true; # Prevents the service from automatically starting on rebuild. See https://discourse.nixos.org/t/how-to-prevent-custom-systemd-service-from-restarting-on-nixos-rebuild-switch/43431

};

</syntaxhighlight>

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

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

</syntaxHighlight>

This will yield the same result as running

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.<name>.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.<name>.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.

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====

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.

@@ Line 4: / Line 4: @@
 == Configuration ==
 The following example timer runs a systemd unit every 5 minutes which invokes a bash script.
-<syntaxHighlight lang="nix">
+<syntaxhighlight lang="nix">
 systemd.timers."hello-world" = {
    wantedBy = [ "timers.target" ];
@@ Line 10: / Line 10: @@
        OnBootSec = "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";
      };
@@ Line 22: / Line 27: @@
      Type = "oneshot";
      User = "root";
+    RemainAfterExit = true; # Prevents the service from automatically starting on rebuild. See https://discourse.nixos.org/t/how-to-prevent-custom-systemd-service-from-restarting-on-nixos-rebuild-switch/43431
    };
 };
+</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>
+====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.
 <syntaxHighlight lang="nix">