quadlet: Add documentation about template use to manpage

Signed-off-by: Alexander Larsson <[email protected]>

Author: alexlarsson

docs/source/markdown/podman-systemd.unit.5.md

@@ -109,16 +109,86 @@ WantedBy=default.target
 
 Currently, only the `Alias`, `WantedBy` and `RequiredBy` keys are supported.
 
+The Install section can be part of the main file, or it can be in a
+separate drop-in file as described above. The latter allows you to
+install an non-enabled unit and then later enabling it by installing
+the drop-in.
+
+
 **NOTE:** To express dependencies between containers, use the generated names of the service. In other
 words `WantedBy=other.service`, not `WantedBy=other.container`. The same is
 true for other kinds of dependencies, too, like `After=other.service`.
 
+### Template files
+
+Systemd supports a concept of [template files](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html#Service%20Templates).
+They are units with names of the form "[email protected]"
+when they are running, but that can be instantiated multiple times
+from a single "[email protected]" file. The individual instances can
+also be different by using drop-in files with the full instance name.
+
+Quadlets support these in two ways. First of all, a quadlet unit with
+a template form will generate a systemd service with a template form,
+and the template systemd service can be used as a regular template.
+For example, "[email protected]" will generate "[email protected]" and you can
+then "systemctl start [email protected]".
+
+Secondly, if you make a symlink like "[email protected]", that
+will generate an instantiated template file. When generating this file
+quadlet will read drop-in files both from the instanced directory
+([email protected]) and the template directory
+([email protected]). This allows customization of individual instances.
+
+Instanced template files (like `[email protected]`) can be enabled
+just like non-templated ones. However, templated ones
+(`[email protected]`) are different, because they need to be
+instantiated. If the `[Install]` section contains a `DefaultInstance=`
+key, then that instance will be enabled, but if not, nothing will
+happen and the options will only be used as the default for units
+that are instantiated using symlinks.
+
+An example template file `[email protected]` might look like this:
+
+```
+[Unit]
+Description=A templated sleepy container
+
+[Container]
+Image=quay.io/fedora/fedora
+Exec=sleep %i
+
+[Service]
+# Restart service when sleep finishes
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+DefaultInstance=100
+```
+
+If this is installed, then on boot there will be a `[email protected]`
+running that sleeps for 100 seconds. You can then do something like
+`systemctl start [email protected]` to start another instance that
+sleeps 50 seconds, or alternatively another service can start it via a
+dependency like `[email protected]`.
+
+In addition, if you do `ln -s [email protected] [email protected]` you
+will also have a 10 second sleep running at boot. And, if you want
+that particular instance to be running with another image, you can
+create a drop-in file like `[email protected]/10-image.conf`:
+```
+[Container]
+Image=quay.io/centos/centos
+```
+
 ### Debugging unit files
 
-After placing the unit file in one of the unit search paths (mentioned above), you can start it with
-`systemctl start {--user}`. If it fails with "Failed to start example.service: Unit example.service not found.",
-then it is possible that you used incorrect syntax or you used an option from a newer version of Podman
-Quadlet and the generator failed to create a service file.
+After placing the unit file in one of the unit search paths (mentioned
+above), you can start it with `systemctl start {--user}`. If it fails
+with "Failed to start example.service: Unit example.service not
+found.", then it is possible that you used incorrect syntax or you
+used an option from a newer version of Podman Quadlet and the
+generator failed to create a service file.
 
 View the generated files and/or error messages with:
 ```