From 7507eb84ed8d27e540c073804ca955c954c6f1fa Mon Sep 17 00:00:00 2001
From: Olivier 'reivilibre <olivier@librepush.net>
Date: Sun, 19 Sep 2021 15:20:01 +0100
Subject: [PATCH] Improve systemd documentation

---
 docs/SUMMARY.md            |  1 +
 docs/recipes/os/systemd.md | 53 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 1860db0..a91ddd5 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -11,6 +11,7 @@
 - [Recipes](./recipes/index.md)
   - [Declare](./recipes/declare.md)
   - [Operating System Recipes](./recipes/os/index.md)
+    - [Systemd](./recipes/os/systemd.md)
     - [Users](./recipes/os/users.md)
   - [Filesystem Recipes](./recipes/filesystem/index.md)
   - [Database Recipes](./recipes/database/index.md)
diff --git a/docs/recipes/os/systemd.md b/docs/recipes/os/systemd.md
index 14c0463..7040fd0 100644
--- a/docs/recipes/os/systemd.md
+++ b/docs/recipes/os/systemd.md
@@ -7,9 +7,10 @@ This Scone module allows declaring units, enabling them, and marking them to be
 | Recipe | Needs | Provides |
 | -----: | ----- | -------- |
 | [`systemd`](#systemd) | `file`? | |
+| [`systemd-timer`](#systemd-timer) | | |
 
 
-## `systemd`: Systemd unit
+## `systemd`
 
 Declares and optionally enables and/or starts a systemd unit.
 
@@ -20,7 +21,7 @@ Declares and optionally enables and/or starts a systemd unit.
 | Argument | Accepted Values | Default | Description |
 | -------: | --------------- | ------- | ----------- |
 | unit | any systemd unit name string | *required* | Name of the Systemd unit. If no extension is provided, `.service` will be inferred. |
-| at | a path | *semi-optional* | If specified, the path to where the . |
+| at | a path | *semi-optional* | If specified, the path to where the unit file already exists. |
 | already_installed | true, false | false | If true, no path is needed, as it will be assumed that the unit is already available. |
 | enabled | true, false | *optional* | If true, the unit will be enabled ('installed'). |
 | started | true, false | *optional* | If true, the unit will be started. |
@@ -37,3 +38,51 @@ at = "/etc/systemd/system/gitea.service"
 enabled = true
 started = true
 ```
+
+
+## `systemd-timer`
+
+Declares and starts a Systemd Timer (along with a simple service for it to trigger). This is a useful alternative to cronjobs.
+
+**Note:** probably must be run as the `root` user.
+
+**Preconditions:** The `cd` path must be provided.
+
+**Postconditions:** `{unit}.service` and `{unit}.timer` will exist as Systemd units. `{unit}.timer` will be configured to trigger `{unit}.service` and will be started.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| user | string | *required* | Name of the user that will run the executable in the systemd service. |
+| group | string | same as `user` | Name of the group that will run the executable in the systemd service. |
+| unit | any systemd unit name string | *required* | Name of the Systemd units, **without** extension. |
+| description | string | *required* | `[Unit] Description=` string for systemd. |
+| cd | path | *required* | Working directory for the executable |
+| command | string | *required* | Executable for the service to start. |
+| calendar | string or list of strings | *required* | List of Systemd `OnCalendar=` times to trigger this timer at. |
+| persistent | true, false | false | If true, the timer will trigger immediately upon activation if it missed the previous trigger time. |
+| enabled | true, false | true | If true, the timer will be enabled and started. |
+| environment | dict of string to string | *optional* | If specified, these environment variables will be provided to the command. |
+
+
+### Systemd `OnCalendar` syntax
+
+Examples:
+
+* `Fri *-*-* 10:00:00`: every Friday at 10h00
+* `*-*-1 09:00:00`: every 1st of the month at 09h00
+* `Wed *-*-1..7 12:00:00`: the first Wednesday of every month at noon
+* `*-11-* 06,09:00:00`: every day of November at 06h00 and 09h00
+
+You can use `systemd-analyze calendar '*-*-* *:*:*'` (for example) to test an `OnCalendar` expression.
+
+### Example
+
+```scoml
+[[systemd-timer]]  Install timer to renew certificates every day at 04h00
+user = radm
+unit = "radm_renew"
+description = "Renews, issues and deploys TLS certificates"
+cd = "/home/radm/rei-acme-dns"
+command = "/home/radm/rei-acme-dns/radm.sh --contact 'mailto:${radm.contact_email}'"
+calendar = "*-*-* 04:00:00"
+```