Merging upstream version 0.1.24.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 102 insertions, 0 deletions

diff --git a/MANIFEST-FORMAT.md b/MANIFEST-FORMAT.md
index 1b369cf..37773c2 100644
--- a/MANIFEST-FORMAT.md
+++ b/MANIFEST-FORMAT.md
@@ -1304,6 +1304,108 @@ done
 
 (except all symlinks will be ignored)
 
+## Service management (`services`)
+
+If you have non-standard requirements for certain services in the package, you can define those via
+the `services` attribute.
+
+    packages:
+        foo:
+            services:
+              - service: "foo"
+                enable-on-install: false
+              - service: "bar"
+                on-upgrade: stop-then-start
+
+
+The `services` attribute must contain a non-empty list, where each element in that list is a mapping.
+Each mapping has the following key/value pairs:
+
+ * `service` (required): Name of the service to match. The name is usually the basename of the service file.
+   However, aliases can also be used for relevant system managers. When aliases **and** multiple service
+   managers are involved, then the rule will apply to all matches. See alias handling below.
+
+   - Note: For systemd, the `.service` suffix can be omitted from name, but other suffixes such as `.timer`
+     cannot.
+
+ * `type-of-service` (optional, defaults to `service`): The type of service this rule applies to. To act on a
+   `systemd` timer, you would set this to `timer` (etc.). Each service manager defines its own set of types
+   of services.
+
+ * `service-scope` (optional, defaults to `system`): The scope of the service. It must be either `system` and
+   `user`.
+   - Note: The keyword is defined to support `user`, but `debputy` does not support `user` services at the moment
+     (the detection logic is missing).
+
+ * `service-manager` or `service-managers` (optional): Which service managers this rule is for. When omitted, all
+   service managers with this service will be affected. This can be used to specify separate rules for the same
+   service under different service managers.
+   - When this attribute is explicitly given, then all the listed service managers must provide at least one
+     service matching the definition. In contract, when it is omitted, then all service manager integrations
+     are consulted but as long as at least one service is match from any service manager, the rule is accepted.
+
+ * `enable-on-install` (optional): Whether to automatically enable the service on installation. Note: This does
+   **not** affect whether the service will be started nor how restarts during upgrades will happen.
+   - If omitted, the plugin detecting the service decides the default.
+
+ * `start-on-install` (optional): Whether to automatically start the service on installation. Whether it is
+   enabled or how upgrades are handled have separate attributes.
+   - If omitted, the plugin detecting the service decides the default.
+
+ * `on-upgrade` (optional): How `debputy` should handle the service during upgrades. The default depends on the
+   plugin detecting the service. Valid values are:
+
+   - `do-nothing`: During an upgrade, the package should not attempt to stop, reload or restart the service.
+   - `reload`: During an upgrade, prefer reloading the service rather than restarting if possible. Note that
+     the result may become `restart` instead if the service manager integration determines that `reload` is
+     not supported.
+   - `restart`: During an upgrade, `restart` the service post upgrade. The service will be left running during
+     the upgrade process.
+   - `stop-then-start`: Stop the service before the upgrade, preform the upgrade and then start the service.
+
+### Service managers and aliases
+
+When defining a service rule, you can use any name that any of the relevant service managers would call the
+service. As an example, consider a package that has the following services:
+
+ * A `sysvinit` service called `foo`
+ * A `systemd` service called `bar.service` with `Alias=foo.service` in its definition.
+
+Here, depending on which service managers are relevant to the rule, you can use different names to match.
+When the rule applies to the `systemd` service manager, then either of the following names can be used:
+
+ * `bar.service` (the "canonical" name in the systemd world)
+ * `foo.service` (the defined alias)
+ * `bar` + `foo` (automatic aliases based on the above)
+
+Now, if rule *also* applies to the `sysvinit` service manager, then any of those 4 names would cause the
+rule to apply to both the `systemd` and the `sysvinit` services.
+
+To show concrete examples:
+
+    ...:
+            services:
+              # Only applies to systemd. Either of the 4 names would have work.
+              - service: "foo.service"
+                on-upgrade: stop-then-start
+                service-manager: systemd
+
+    ...:
+            services:
+              # Only applies to sysvinit. Must use `foo` since the 3 other names only applies when systemd
+              # is involved.
+              - service: "foo"
+                on-upgrade: stop-then-start
+                service-manager: sysvinit
+
+    ...:
+            services:
+              # Applies to both systemd and sysvinit; this works because the `systemd` service provides an
+              # alias for `foo`. If the systemd service did not have that alias, only the `systemd` service
+              # would have been matched.
+              - service: bar
+                enable-on-install: false
+
 ## Custom binary version (`binary-version`)
 
 In the *rare* case that you need a binary package to have a custom version, you can use the `binary-version:`