docs: Explain about the `systemctl enable` trap

This commit is contained in:
Colin Walters 2024-01-19 14:48:38 -05:00
parent e4744ffad7
commit abb6a025c2
1 changed files with 38 additions and 0 deletions

View File

@ -4,6 +4,44 @@ nav_order: 3
# Operating system content and usage
## Configuring systemd units
To add a custom systemd unit:
```dockerfile
COPY mycustom.service /usr/lib/systemd/system
RUN ln -s mycustom.service /usr/lib/systemd/system/default.target.wants
```
It will *not* work currently to do `RUN systemctl enable mycustom.service` instead
of the second line - unless you also write a
[systemd preset file](https://www.freedesktop.org/software/systemd/man/latest/systemd.preset.html)
enabling that unit.
### Static enablement versus presets
systemd presets are designed for "run once" semantics - thereafter, OS upgrades
won't cause new services to start. In contrast, "static enablement" by creating
the symlink (as is done above) bypasses the preset logic.
In general, it's recommended to follow the "static enablement" approach because
it more closely aligns with "immutable infrastructure" model.
### Using presets
If nevertheless you want to use presets instead of "static enablement", One
recommended pattern to avoid this problem (nd is also somewhat of a best
practice anyways) is to use a common prefix (e.g. `examplecorp-` for all of your
custom systemd units), resulting in `examplecorp-checkin.service`,
`examplecorp-agent.service` etc.
Then you can write a single systemd preset file to e.g.
`/usr/lib/systemd/system-preset/50-examplecorp.preset` that contains:
```systemd
enable examplecorp-*
```
## Automatic updates enabled by default
The base image here enables the