From abb6a025c2945205cf06379bf97a93976ce62a3f Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Fri, 19 Jan 2024 14:48:38 -0500
Subject: [PATCH 1/3] docs: Explain about the `systemctl enable` trap

---
 docs/usage.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/usage.md b/docs/usage.md
index 242a250..2320568 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -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

From 856e206ec41505c7b098cf61a32614e77e7c7e49 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 22 Jan 2024 08:01:54 -0500
Subject: [PATCH 2/3] Update docs/usage.md

Co-authored-by: Valentin Rothberg <vrothberg@redhat.com>
---
 docs/usage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage.md b/docs/usage.md
index 2320568..9d6d938 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -29,7 +29,7 @@ it more closely aligns with "immutable infrastructure" model.
 
 ### Using presets
 
-If nevertheless you want to use presets instead of "static enablement", One
+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`,

From 568428be35d0289f7308bc0064b7a8a0eaf5dc57 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 22 Jan 2024 08:01:58 -0500
Subject: [PATCH 3/3] Update docs/usage.md

Co-authored-by: Valentin Rothberg <vrothberg@redhat.com>
---
 docs/usage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage.md b/docs/usage.md
index 9d6d938..d6f921b 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -30,7 +30,7 @@ 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
+recommended pattern to avoid this problem (and 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.