89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
# Systemd
|
|
|
|
Systemd is a service manager, used in some Linux distributions.
|
|
|
|
This Scone module allows declaring units, enabling them, and marking them to be started.
|
|
|
|
| Recipe | Needs | Provides |
|
|
| -----: | ----- | -------- |
|
|
| [`systemd`](#systemd) | `file`? | |
|
|
| [`systemd-timer`](#systemd-timer) | | |
|
|
|
|
|
|
## `systemd`
|
|
|
|
Declares and optionally enables and/or starts a systemd unit.
|
|
|
|
**Note:** probably must be run as the `root` user.
|
|
|
|
**Preconditions:** if `already_installed` is `true`, the specified unit must already be available for systemd.
|
|
|
|
| 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 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. |
|
|
| ~~restart_on~~ | ~~list of paths~~ | *optional* | **NOT IMPLEMENTED** ~~a list of files to which changes will cause the unit to be restarted.~~ reloaded? |
|
|
|
|
It is an error to not specify **at** if **already_installed** is not specified as true.
|
|
|
|
### Example
|
|
|
|
```scoml
|
|
[[systemd]] Enable the gitea service
|
|
unit = "gitea"
|
|
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"
|
|
```
|