summaryrefslogtreecommitdiffstats
path: root/MANIFEST-FORMAT.md
diff options
context:
space:
mode:
Diffstat (limited to 'MANIFEST-FORMAT.md')
-rw-r--r--MANIFEST-FORMAT.md102
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:`