From 57df3b2ea3304b0a1b1091a2f8757b469b9d8f51 Mon Sep 17 00:00:00 2001
From: Stonewall Jackson <stonewall@sacredheartsc.com>
Date: Mon, 20 Feb 2023 20:07:18 -0500
Subject: systemd_timer: add docs

---
 roles/systemd_timer/README.md         | 45 +++++++++++++++++++++++++++++++++++
 roles/systemd_timer/defaults/main.yml |  7 ------
 2 files changed, 45 insertions(+), 7 deletions(-)
 create mode 100644 roles/systemd_timer/README.md

(limited to 'roles/systemd_timer')

diff --git a/roles/systemd_timer/README.md b/roles/systemd_timer/README.md
new file mode 100644
index 0000000..8eb518c
--- /dev/null
+++ b/roles/systemd_timer/README.md
@@ -0,0 +1,45 @@
+Systemd Timer
+=============
+
+Description
+-----------
+
+The `systemd_timer` role creates a systemd timer to run a specified command.
+The command can either be passed directly to `exec`, or be run within the shell.
+
+
+Variables
+---------
+
+This role **accepts** the following variables:
+
+Variable            | Default                        | Description
+--------------------|--------------------------------|------------
+`timer_name`        | &nbsp;                         | Name of systemd unit
+`timer_description` | `name` of timer                | Description of systemd unit
+`timer_enabled`     | yes                            | Enable the timer unit
+`timer_after`       | &nbsp;                         | Systemd units to run before timer (space-separated or list, see [documentation](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=))
+`timer_persistent`  | yes                            | Persist timer across reboots (see [documentation](https://www.freedesktop.org/software/systemd/man/systemd.timer.html#Persistent=))
+`timer_user`        | `root`                         | Unix user that executes the command
+`timer_group`       | &nbsp;                         | Unix group that executes the command
+`timer_chdir`       | &nbsp;                         | Systemd `WorkingDirectory` (see [documentation](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#WorkingDirectory=))
+`timer_exec`        | &nbsp;                         | Command to run
+`timer_shell`       | no                             | Run command within a shell
+
+
+Usage
+-----
+
+Example task:
+
+````yaml
+- name: create timer to update invidious
+  include_role:
+    name: systemd_timer
+  vars:
+    timer_name: invidious-update
+    timer_description: Update invidious
+    timer_after: network.target
+    timer_on_calendar: weekly
+    timer_exec: /opt/invidious/invidious-update.sh
+````
diff --git a/roles/systemd_timer/defaults/main.yml b/roles/systemd_timer/defaults/main.yml
index e429f17..54d38f4 100644
--- a/roles/systemd_timer/defaults/main.yml
+++ b/roles/systemd_timer/defaults/main.yml
@@ -2,10 +2,3 @@ timer_persistent: yes
 timer_user: root
 timer_shell: no
 timer_enabled: yes
-
-# timer_group: groupname
-# timer_chdir: /path/to/working/directory
-#
-# timer_shell: some $shell | command
-#   OR
-# timer_exec: command to exec
-- 
cgit