From 81e218ddb6a842614577ba099b1091614ec9addd Mon Sep 17 00:00:00 2001
From: Konrad Bucheli <konrad.bucheli@psi.ch>
Date: Thu, 19 Dec 2024 10:51:50 +0100
Subject: [PATCH] document how to run a command on boot

---
 _toc.yml                                      |  1 +
 .../configuration/software/services.md        | 40 +++++++++----------
 admin-guide/configuration/software/timers.md  | 23 +++++++++++
 3 files changed, 42 insertions(+), 22 deletions(-)
 create mode 100644 admin-guide/configuration/software/timers.md

diff --git a/_toc.yml b/_toc.yml
index efdaa6fb..7c480101 100644
--- a/_toc.yml
+++ b/_toc.yml
@@ -73,6 +73,7 @@ chapters:
             sections:
               - file: admin-guide/configuration/software/packages
               - file: admin-guide/configuration/software/services
+              - file: admin-guide/configuration/software/timers
               - file: admin-guide/configuration/software/selinux_configuration
               - file: admin-guide/configuration/software/package_updates
               - file: admin-guide/configuration/software/package_repositories
diff --git a/admin-guide/configuration/software/services.md b/admin-guide/configuration/software/services.md
index 3971db01..d5ea07b9 100644
--- a/admin-guide/configuration/software/services.md
+++ b/admin-guide/configuration/software/services.md
@@ -22,28 +22,6 @@ base::services:
         enable: false
 ```
 
-## Systemd Timers
-To have custom executables run regulary on given time/interval, you may use the `base::timers` Hiera key:
-
-```
-base::timers:
-    'timer_test':
-        description: 'test timers'
-        command: '/usr/bin/logger foo'
-        on_calendar: '*:*:10'
-        timer_options:
-            persistence:  false
-```
-
-For each timer following keys are mandatory
-
-- `description` for a short explaination what it is about
-- `command` for the command to run
-- `on_calendar` defining when it should run using the [`systemd` calendar event format](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events), (alternatively see also chapter "CALENDAR EVENTS" of `man systemd.date`)
-
-Optional is
-- `timer_options` for additional options. In the example it is  `persistence`which signals if the timer should run immediately after boot when the node was switched of on the last scheduled run time (default is `false`).
-
 ## Manage Services with Custom Unit Files
 
 It is also possible to provide a full systemd unit file if there is none already. For this define the different secions and their content with subkeys below the `options` key as in below example:
@@ -102,4 +80,22 @@ base::services:
 
 If there are multiple dropins, you might also name them individually with the `dropin_name` parameter.
 
+## Run Command on Startup
+If a command should run only once at boot time you may create a `oneshot` service with `RemainAfterExit` and have one or more commands ready in `ExecStart`:
+```
+base::services:
+  tuned_setup:
+    enable: true
+    options:
+      Unit:
+        After: 'tuned.service'
+      Install:
+        WantedBy: 'multi-user.target'
+      Service:
+        Type: 'oneshot'
+        ExecStart:
+          - '/usr/sbin/tuned-adm active'
+          - '/usr/sbin/tuned-adm profile virtual-host'
+        RemainAfterExit: 'true'
+```
 
diff --git a/admin-guide/configuration/software/timers.md b/admin-guide/configuration/software/timers.md
new file mode 100644
index 00000000..a9d6441f
--- /dev/null
+++ b/admin-guide/configuration/software/timers.md
@@ -0,0 +1,23 @@
+# Systemd Timers for Regular Tasks
+
+To have custom executables run regulary on given time/interval, you may use the `base::timers` Hiera key:
+
+```
+base::timers:
+    'timer_test':
+        description: 'test timers'
+        command: '/usr/bin/logger foo'
+        on_calendar: '*:*:10'
+        timer_options:
+            persistence:  false
+```
+
+For each timer following keys are mandatory
+
+- `description` for a short explaination what it is about
+- `command` for the command to run
+- `on_calendar` defining when it should run using the [`systemd` calendar event format](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events), (alternatively see also chapter "CALENDAR EVENTS" of `man systemd.date`)
+
+Optional is
+- `timer_options` for additional options. In the example it is  `persistence`which signals if the timer should run immediately after boot when the node was switched of on the last scheduled run time (default is `false`).
+