Merge pull request #169 from cgwalters/doc-units

docs: Explain about the `systemctl enable` trap

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 (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.
+
+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