diff options
Diffstat (limited to 'MANIFEST-FORMAT.md')
| -rw-r--r-- | MANIFEST-FORMAT.md | 102 |
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:` |