From f65d4c28bceadcf89d2a4f772b082b6591617517 Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Thu, 28 May 2026 15:25:20 +0530 Subject: [PATCH 1/6] Fix #6257 first draft --- docs/explanation/index.rst | 1 + docs/explanation/services-daemons.rst | 220 ++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 docs/explanation/services-daemons.rst diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index a463eb42c5..16feb5532c 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -88,6 +88,7 @@ communicating with local processes, and storing user credentials. Extensions Components snap-configurations + services-daemons build-overrides remote-build /common/craft-parts/explanation/filesets diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst new file mode 100644 index 0000000000..e8ebba43e4 --- /dev/null +++ b/docs/explanation/services-daemons.rst @@ -0,0 +1,220 @@ +.. _explanation-services-daemons: + +Services and daemons +====================== + +When `creating snapcraft.yaml `__ to build a new snap, a snap’s executable component can be either exposed as a command or run as a background service or daemon. + +For details on how to expose an executable from its constituent parts, see `Defining a command `__. + +A snap daemon or service behaves the same as a native daemon or service, and will either start automatically at boot time and end when the machine is shutdown, or start and stop on demand through socket activation. + +Snap confinement prohibits a system’s users and groups from running as traditional services might, such as under a user’s ownership. But a *daemon* user and group can alternatively be created within a snap to provide similar user and group level control outside of a snap’s confinement. See `System usernames `__ for more details. + +See `Service management `__ for details on starting and stopping services from the *snap* command. Services and daemons can also be managed from within a snap, such as via a hook, with the `snapctl `__. + +To set memory and CPU resource limits for a service or daemon, see `Quota groups `__ + +If you need to add user configurable options to your service or daemon, such as which port it should use, see `Adding snap configuration `__. + +` <#p-52963-defining-a-daemon-1>`__\ Defining a daemon +------------------------------------------------------ + +To define an executable as a daemon or service, add ``daemon: simple`` to its *apps* stanza: + +:: + + apps: + part-os-release: + command: bin/os-release.sh + daemon: simple + +The value for ``daemon:`` can be one of the following: + +- **simple** Run for as along as the service is active - this is typically the default option. +- **oneshot** Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. +- **forking** The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. +- **notify** Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the `daemon-notify interface `__. + +In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: + +- **after** An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. +- **before** An ordered list of applications the daemon is to be started *before*. An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. +- **install-mode** Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use `snapctl `__ with a `hook `__, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. +- **post-stop-command** Sets the command to run from inside the snap *after* a service stops. +- **refresh-mode** Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . +- **reload-command** Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the ``snap restart --reload`` command. + Example: ``reload-command: sbin/nginx -s reload`` +- **restart-condition** Defines when a service should be restarted, using values returned from `systemd service exit status `__. Can be one of ``[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]``. +- **restart-delay** The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. +- **sockets** Requires an activated daemon socket, and works with the `network-bind interface `__ to map a daemon’s socket to a service and activate it. +- **socket-mode** The mode of a socket in octal. +- **start-timeout** Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. +- **stop-command** An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be to used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. +- **stop-mode** Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . +- **stop-timeout** The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). +- **timer** Declares that the service is activated by a timer and that the app must be a daemon. See `Timer string format `__ for syntax examples. +- **watchdog-timeout** This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. + +For further details, see `Snapcraft app and service metadata `__. + +` <#p-52963-daemons-and-d-bus-2>`__\ Daemons and D-Bus +------------------------------------------------------ + +Daemons can configured to interact with D-Bus in a number of ways. D-Bus can be used to indicate to *systemd* that a daemon is running, it can be used as the mechanism to activate a daemon, and it can be used generally to expose services to applications. + +D-Bus activation can only be used for services on the system bus. + +` <#p-52963-daemon-type-3>`__\ Daemon type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``daemon`` keyword is used to specify the type of a daemon and the mechanism it uses to inform *systemd* that it is running. + +A daemon can be configured to use D-Bus to notify *systemd* that it is running by claiming a D-Bus name. This behaviour is enabled by setting the ``daemon`` keyword to a value of ``dbus`` in the app metadata. + +Daemons that use D-Bus in other ways that do not need this feature can set the ``daemon`` type to a value other than ``dbus``. This enables other methods to be used to indicate to *systemd* that they are running. + +If the ``dbus`` type is used, either the ``bus-name`` keyword or ``activates-on`` keyword must be used to define a bus name for the daemon. If both keywords are defined, the bus name takes precedence. If only the ``activates-on`` keyword is defined, the last name in its list of slots is used as the bus name. + +` <#p-52963-activation-4>`__\ Activation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``activates-on`` keyword is used to define a list of names that will be exposed via D-Bus. These names are automatically added to the slots for the snap. + +This provides a way for a daemon to be started on a D-Bus method call. When a method on any of the names is invoked, the daemon’s ``command`` is run to start the daemon. + +` <#p-52963-general-use-5>`__\ General use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A daemon that needs to provide services to applications can be configured to use a bus name by setting its ``bus-name`` keyword. This enables the system bus to be used for communication, as with regular system daemons. + +As noted above, the ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. + +.. |:construction:| image:: https://forum.snapcraft.io/images/emoji/twitter/construction.png?v=14 + :class: emoji + :width: 20px + :height: 20px + +Raw (verbatim) +^^^^^^^^^^^^^^ +:: + + + [quote] + :construction: **NOTE TO EDITORS** :construction: + + This page of documentation has moved to: + [https://snapcraft.io/docs/](https://snapcraft.io/docs/) + + It will continue to be updated and supported only from the new location. We also welcome [community contributions](https://snapcraft.io/docs/contributing/). + + To suggest improvements, or to notify us of an issue, please use the **Give feedback** button on any page in the [new documentation](https://snapcraft.io/docs/). Thank you! + [/quote] + + When [creating snapcraft.yaml](/t/creating-snapcraft-yaml/11666) to build a new snap, a snap's executable component can be either exposed as a command or run as a background service or daemon. + + For details on how to expose an executable from its constituent parts, see [Defining a command](/t/defining-a-command/12060). + + A snap daemon or service behaves the same as a native daemon or service, and will either start automatically at boot time and end when the machine is shutdown, or start and stop on demand through socket activation. + + Snap confinement prohibits a system’s users and groups from running as traditional services might, such as under a user's ownership. But a *daemon* user and group can alternatively be created within a snap to provide similar user and group level control outside of a snap’s confinement. See [System usernames](/t/system-usernames/13386) for more details. + + See [Service management](https://forum.snapcraft.io/t/service-management/3965) for details on starting and stopping services from the _snap_ command. Services and daemons can also be managed from within a snap, such as via a hook, with the [snapctl](/t/using-the-snapctl-tool/15002#heading--services). + + To set memory and CPU resource limits for a service or daemon, see [Quota groups](/t/quota-groups/25553/3) + + If you need to add user configurable options to your service or daemon, such as which port it should use, see [Adding snap configuration](/t/adding-snap-configuration/15246). + + ## Defining a daemon + + To define an executable as a daemon or service, add `daemon: simple` to its _apps_ stanza: + + ```yaml + apps: + part-os-release: + command: bin/os-release.sh + daemon: simple + ``` + + The value for `daemon:` can be one of the following: + + - **simple** + Run for as along as the service is active - this is typically the default option. + - **oneshot** + Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. + - **forking** + The configured command calls `fork()` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn't the recommended behaviour on a modern Linux system. + - **notify** + Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the [daemon-notify interface](/t/the-daemon-notify-interface/7809). + + In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: + - **after** + An ordered list of applications the daemon is to be started _after_. Applications must be part of the same snap. + - **before** + An ordered list of applications the daemon is to be started _before_. Applications must be part of the same snap. + - **install-mode** + Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use [snapctl](/t/using-the-snapctl-tool/15002) with a [hook](/t/supported-snap-hooks/3795), for instance, or another management agent. Can be `enable` (default) or `disable`. + - **post-stop-command** + Sets the command to run from inside the snap _after_ a service stops. + - **refresh-mode** + Controls whether a daemon should be restarted during a snap refresh. Can be either `restart` , `endure`, (do not restart) or `ignore-running` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . + - **reload-command** + Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the `snap restart --reload` command.
Example: `reload-command: sbin/nginx -s reload` + - **restart-condition** + Defines when a service should be restarted, using values returned from [systemd service exit status](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=). + Can be one of `[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]`. + - **restart-delay** + The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. + Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. + - **sockets** + Requires an activated daemon socket, and works with the [network-bind interface](/t/the-network-bind-interface/7881) to map a daemon’s socket to a service and activate it. + - **socket-mode** + The mode of a socket in octal. + - **start-timeout** + Optional time to wait for daemon to start. + Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. + - **stop-command** + An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified _stop-command_ terminates. This can be to used to gracefully handle a daemon stop or restart, such as when a _refresh_ happens, by allowing the daemon to reach a stoppable state first. + - **stop-mode** + Defines which [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) to use when stopping the daemon. Can be one of either `sigterm`, `sigterm-all`, `sighup`, `sighup-all`, `sigusr1`, `sigusr1-all`, `sigusr2`, `sigusr2-all`, `sigint` and `sigint-all` . + - **stop-timeout** + The length of time to wait before terminating a service. + Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. Termination is via `SIGTERM` (and `SIGKILL` if that doesn't work). + - **timer** + Declares that the service is activated by a timer and that the app must be a daemon. See [Timer string format](/t/timer-string-format/6562) for syntax examples. + - **watchdog-timeout** + This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. + Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. + + For further details, see [Snapcraft app and service metadata](/t/snapcraft-app-and-service-metadata/8335). + + ## Daemons and D-Bus + + Daemons can configured to interact with D-Bus in a number of ways. + D-Bus can be used to indicate to *systemd* that a daemon is running, it can + be used as the mechanism to activate a daemon, and it can be used generally + to expose services to applications. + + D-Bus activation can only be used for services on the system bus. + + ### Daemon type + + The `daemon` keyword is used to specify the type of a daemon and the mechanism it uses to inform *systemd* that it is running. + + A daemon can be configured to use D-Bus to notify *systemd* that it is running by claiming a D-Bus name. This behaviour is enabled by setting the ``daemon`` keyword to a value of ``dbus`` in the app metadata. + + Daemons that use D-Bus in other ways that do not need this feature can set the ``daemon`` type to a value other than ``dbus``. This enables other methods to be used to indicate to *systemd* that they are running. + + If the ``dbus`` type is used, either the `bus-name` keyword or `activates-on` keyword must be used to define a bus name for the daemon. If both keywords are defined, the bus name takes precedence. If only the ``activates-on`` keyword is defined, the last name in its list of slots is used as the bus name. + + ### Activation + + The `activates-on` keyword is used to define a list of names that will be exposed via D-Bus. These names are automatically added to the slots for the snap. + + This provides a way for a daemon to be started on a D-Bus method call. When a method on any of the names is invoked, the daemon's `command` is run to start the daemon. + + ### General use + + A daemon that needs to provide services to applications can be configured to use a bus name by setting its `bus-name` keyword. This enables the system bus to be used for communication, as with regular system daemons. + + As noted above, the `daemon` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file From 920b706e93835d7a46409e98363f3916698e62ab Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Thu, 28 May 2026 17:18:48 +0530 Subject: [PATCH 2/6] docs: clean up services and daemons page --- docs/explanation/services-daemons.rst | 159 +++----------------------- 1 file changed, 15 insertions(+), 144 deletions(-) diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst index e8ebba43e4..9816666c8e 100644 --- a/docs/explanation/services-daemons.rst +++ b/docs/explanation/services-daemons.rst @@ -17,8 +17,8 @@ To set memory and CPU resource limits for a service or daemon, see `Quota groups If you need to add user configurable options to your service or daemon, such as which port it should use, see `Adding snap configuration `__. -` <#p-52963-defining-a-daemon-1>`__\ Defining a daemon ------------------------------------------------------- +Defining a daemon +------------------ To define an executable as a daemon or service, add ``daemon: simple`` to its *apps* stanza: @@ -31,7 +31,7 @@ To define an executable as a daemon or service, add ``daemon: simple`` to its *a The value for ``daemon:`` can be one of the following: -- **simple** Run for as along as the service is active - this is typically the default option. +- **simple** Run for as long as the service is active - this is typically the default option. - **oneshot** Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. - **forking** The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. - **notify** Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the `daemon-notify interface `__. @@ -39,7 +39,7 @@ The value for ``daemon:`` can be one of the following: In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: - **after** An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. -- **before** An ordered list of applications the daemon is to be started *before*. An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. +- **before** An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. - **install-mode** Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use `snapctl `__ with a `hook `__, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. - **post-stop-command** Sets the command to run from inside the snap *after* a service stops. - **refresh-mode** Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . @@ -50,7 +50,7 @@ In addition to the above types of daemon or service, the following can be set to - **sockets** Requires an activated daemon socket, and works with the `network-bind interface `__ to map a daemon’s socket to a service and activate it. - **socket-mode** The mode of a socket in octal. - **start-timeout** Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. -- **stop-command** An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be to used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. +- **stop-command** An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. - **stop-mode** Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . - **stop-timeout** The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). - **timer** Declares that the service is activated by a timer and that the app must be a daemon. See `Timer string format `__ for syntax examples. @@ -58,15 +58,15 @@ In addition to the above types of daemon or service, the following can be set to For further details, see `Snapcraft app and service metadata `__. -` <#p-52963-daemons-and-d-bus-2>`__\ Daemons and D-Bus ------------------------------------------------------- +Daemons and D-Bus +------------------- -Daemons can configured to interact with D-Bus in a number of ways. D-Bus can be used to indicate to *systemd* that a daemon is running, it can be used as the mechanism to activate a daemon, and it can be used generally to expose services to applications. +Daemons can be configured to interact with D-Bus in a number of ways. D-Bus can be used to indicate to *systemd* that a daemon is running, it can be used as the mechanism to activate a daemon, and it can be used generally to expose services to applications. D-Bus activation can only be used for services on the system bus. -` <#p-52963-daemon-type-3>`__\ Daemon type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Daemon type +~~~~~~~~~~~~ The ``daemon`` keyword is used to specify the type of a daemon and the mechanism it uses to inform *systemd* that it is running. @@ -76,145 +76,16 @@ Daemons that use D-Bus in other ways that do not need this feature can set the ` If the ``dbus`` type is used, either the ``bus-name`` keyword or ``activates-on`` keyword must be used to define a bus name for the daemon. If both keywords are defined, the bus name takes precedence. If only the ``activates-on`` keyword is defined, the last name in its list of slots is used as the bus name. -` <#p-52963-activation-4>`__\ Activation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Activation +~~~~~~~~~~~ The ``activates-on`` keyword is used to define a list of names that will be exposed via D-Bus. These names are automatically added to the slots for the snap. This provides a way for a daemon to be started on a D-Bus method call. When a method on any of the names is invoked, the daemon’s ``command`` is run to start the daemon. -` <#p-52963-general-use-5>`__\ General use -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +General use +~~~~~~~~~~~~ A daemon that needs to provide services to applications can be configured to use a bus name by setting its ``bus-name`` keyword. This enables the system bus to be used for communication, as with regular system daemons. -As noted above, the ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. - -.. |:construction:| image:: https://forum.snapcraft.io/images/emoji/twitter/construction.png?v=14 - :class: emoji - :width: 20px - :height: 20px - -Raw (verbatim) -^^^^^^^^^^^^^^ -:: - - - [quote] - :construction: **NOTE TO EDITORS** :construction: - - This page of documentation has moved to: - [https://snapcraft.io/docs/](https://snapcraft.io/docs/) - - It will continue to be updated and supported only from the new location. We also welcome [community contributions](https://snapcraft.io/docs/contributing/). - - To suggest improvements, or to notify us of an issue, please use the **Give feedback** button on any page in the [new documentation](https://snapcraft.io/docs/). Thank you! - [/quote] - - When [creating snapcraft.yaml](/t/creating-snapcraft-yaml/11666) to build a new snap, a snap's executable component can be either exposed as a command or run as a background service or daemon. - - For details on how to expose an executable from its constituent parts, see [Defining a command](/t/defining-a-command/12060). - - A snap daemon or service behaves the same as a native daemon or service, and will either start automatically at boot time and end when the machine is shutdown, or start and stop on demand through socket activation. - - Snap confinement prohibits a system’s users and groups from running as traditional services might, such as under a user's ownership. But a *daemon* user and group can alternatively be created within a snap to provide similar user and group level control outside of a snap’s confinement. See [System usernames](/t/system-usernames/13386) for more details. - - See [Service management](https://forum.snapcraft.io/t/service-management/3965) for details on starting and stopping services from the _snap_ command. Services and daemons can also be managed from within a snap, such as via a hook, with the [snapctl](/t/using-the-snapctl-tool/15002#heading--services). - - To set memory and CPU resource limits for a service or daemon, see [Quota groups](/t/quota-groups/25553/3) - - If you need to add user configurable options to your service or daemon, such as which port it should use, see [Adding snap configuration](/t/adding-snap-configuration/15246). - - ## Defining a daemon - - To define an executable as a daemon or service, add `daemon: simple` to its _apps_ stanza: - - ```yaml - apps: - part-os-release: - command: bin/os-release.sh - daemon: simple - ``` - - The value for `daemon:` can be one of the following: - - - **simple** - Run for as along as the service is active - this is typically the default option. - - **oneshot** - Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. - - **forking** - The configured command calls `fork()` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn't the recommended behaviour on a modern Linux system. - - **notify** - Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the [daemon-notify interface](/t/the-daemon-notify-interface/7809). - - In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: - - **after** - An ordered list of applications the daemon is to be started _after_. Applications must be part of the same snap. - - **before** - An ordered list of applications the daemon is to be started _before_. Applications must be part of the same snap. - - **install-mode** - Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use [snapctl](/t/using-the-snapctl-tool/15002) with a [hook](/t/supported-snap-hooks/3795), for instance, or another management agent. Can be `enable` (default) or `disable`. - - **post-stop-command** - Sets the command to run from inside the snap _after_ a service stops. - - **refresh-mode** - Controls whether a daemon should be restarted during a snap refresh. Can be either `restart` , `endure`, (do not restart) or `ignore-running` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . - - **reload-command** - Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the `snap restart --reload` command.
Example: `reload-command: sbin/nginx -s reload` - - **restart-condition** - Defines when a service should be restarted, using values returned from [systemd service exit status](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=). - Can be one of `[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]`. - - **restart-delay** - The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. - Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. - - **sockets** - Requires an activated daemon socket, and works with the [network-bind interface](/t/the-network-bind-interface/7881) to map a daemon’s socket to a service and activate it. - - **socket-mode** - The mode of a socket in octal. - - **start-timeout** - Optional time to wait for daemon to start. - Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. - - **stop-command** - An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified _stop-command_ terminates. This can be to used to gracefully handle a daemon stop or restart, such as when a _refresh_ happens, by allowing the daemon to reach a stoppable state first. - - **stop-mode** - Defines which [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) to use when stopping the daemon. Can be one of either `sigterm`, `sigterm-all`, `sighup`, `sighup-all`, `sigusr1`, `sigusr1-all`, `sigusr2`, `sigusr2-all`, `sigint` and `sigint-all` . - - **stop-timeout** - The length of time to wait before terminating a service. - Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. Termination is via `SIGTERM` (and `SIGKILL` if that doesn't work). - - **timer** - Declares that the service is activated by a timer and that the app must be a daemon. See [Timer string format](/t/timer-string-format/6562) for syntax examples. - - **watchdog-timeout** - This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. - Time duration units can be `10ns`, `10us`, `10ms`, `10s`, `10m`. - - For further details, see [Snapcraft app and service metadata](/t/snapcraft-app-and-service-metadata/8335). - - ## Daemons and D-Bus - - Daemons can configured to interact with D-Bus in a number of ways. - D-Bus can be used to indicate to *systemd* that a daemon is running, it can - be used as the mechanism to activate a daemon, and it can be used generally - to expose services to applications. - - D-Bus activation can only be used for services on the system bus. - - ### Daemon type - - The `daemon` keyword is used to specify the type of a daemon and the mechanism it uses to inform *systemd* that it is running. - - A daemon can be configured to use D-Bus to notify *systemd* that it is running by claiming a D-Bus name. This behaviour is enabled by setting the ``daemon`` keyword to a value of ``dbus`` in the app metadata. - - Daemons that use D-Bus in other ways that do not need this feature can set the ``daemon`` type to a value other than ``dbus``. This enables other methods to be used to indicate to *systemd* that they are running. - - If the ``dbus`` type is used, either the `bus-name` keyword or `activates-on` keyword must be used to define a bus name for the daemon. If both keywords are defined, the bus name takes precedence. If only the ``activates-on`` keyword is defined, the last name in its list of slots is used as the bus name. - - ### Activation - - The `activates-on` keyword is used to define a list of names that will be exposed via D-Bus. These names are automatically added to the slots for the snap. - - This provides a way for a daemon to be started on a D-Bus method call. When a method on any of the names is invoked, the daemon's `command` is run to start the daemon. - - ### General use - - A daemon that needs to provide services to applications can be configured to use a bus name by setting its `bus-name` keyword. This enables the system bus to be used for communication, as with regular system daemons. - - As noted above, the `daemon` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file +As noted above, the ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file From 6f87a3972d1cca0fbb93e43a1b91dc05fc15e72e Mon Sep 17 00:00:00 2001 From: shalz Date: Thu, 28 May 2026 18:13:28 +0530 Subject: [PATCH 3/6] Update docs/explanation/services-daemons.rst Signed-off-by: shalz --- docs/explanation/services-daemons.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst index 9816666c8e..ac22d1016c 100644 --- a/docs/explanation/services-daemons.rst +++ b/docs/explanation/services-daemons.rst @@ -88,4 +88,4 @@ General use A daemon that needs to provide services to applications can be configured to use a bus name by setting its ``bus-name`` keyword. This enables the system bus to be used for communication, as with regular system daemons. -As noted above, the ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file +The ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file From e3dac1ea313959c55be49d0ee59f657908bdb7ba Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Thu, 28 May 2026 20:23:44 +0530 Subject: [PATCH 4/6] docs: fix lint issues in services-daemons --- docs/explanation/services-daemons.rst | 44 +++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst index ac22d1016c..1ea06424a2 100644 --- a/docs/explanation/services-daemons.rst +++ b/docs/explanation/services-daemons.rst @@ -31,30 +31,30 @@ To define an executable as a daemon or service, add ``daemon: simple`` to its *a The value for ``daemon:`` can be one of the following: -- **simple** Run for as long as the service is active - this is typically the default option. -- **oneshot** Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. -- **forking** The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. -- **notify** Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the `daemon-notify interface `__. +- ``simple``: Run for as long as the service is active - this is typically the default option. +- ``oneshot``: Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. +- ``forking``: The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. +- ``notify`` Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the `daemon-notify interface `__. In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: - -- **after** An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. -- **before** An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. -- **install-mode** Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use `snapctl `__ with a `hook `__, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. -- **post-stop-command** Sets the command to run from inside the snap *after* a service stops. -- **refresh-mode** Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . -- **reload-command** Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the ``snap restart --reload`` command. + +- ``after``: An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. +- ``before``: An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. +- ``install-mode``: Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use `snapctl `__ with a `hook `__, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. +- ``post-stop-command``: Sets the command to run from inside the snap *after* a service stops. +- ``refresh-mode``: Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . +- ``reload-command``: Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the ``snap restart --reload`` command. Example: ``reload-command: sbin/nginx -s reload`` -- **restart-condition** Defines when a service should be restarted, using values returned from `systemd service exit status `__. Can be one of ``[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]``. -- **restart-delay** The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. -- **sockets** Requires an activated daemon socket, and works with the `network-bind interface `__ to map a daemon’s socket to a service and activate it. -- **socket-mode** The mode of a socket in octal. -- **start-timeout** Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. -- **stop-command** An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. -- **stop-mode** Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . -- **stop-timeout** The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). -- **timer** Declares that the service is activated by a timer and that the app must be a daemon. See `Timer string format `__ for syntax examples. -- **watchdog-timeout** This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. +- ``restart-condition``: Defines when a service should be restarted, using values returned from `systemd service exit status `__. Can be one of ``[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]``. +- ``restart-delay``: The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. +- ``sockets``: Requires an activated daemon socket, and works with the `network-bind interface `__ to map a daemon’s socket to a service and activate it. +- ``socket-mode``: The mode of a socket in octal. +- ``start-timeout``: Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. +- ``stop-command``: An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. +- ``stop-mode``: Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . +- ``stop-timeout``: The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). +- ``timer``: Declares that the service is activated by a timer and that the app must be a daemon. See `Timer string format `__ for syntax examples. +- ``watchdog-timeout``: This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. For further details, see `Snapcraft app and service metadata `__. @@ -88,4 +88,4 @@ General use A daemon that needs to provide services to applications can be configured to use a bus name by setting its ``bus-name`` keyword. This enables the system bus to be used for communication, as with regular system daemons. -The ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. \ No newline at end of file +The ``daemon`` keyword does not need to specify the ``dbus`` type for this use case, unless it is convenient to notify *systemd* about start-up by claiming a D-Bus name. From c326074aeffcc1767976791815c914632d07b629 Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Fri, 29 May 2026 12:15:21 +0530 Subject: [PATCH 5/6] docs: change long list to table for better comprehensibility --- docs/explanation/services-daemons.rst | 72 +++++++++++++++++---------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst index 1ea06424a2..3c276ac711 100644 --- a/docs/explanation/services-daemons.rst +++ b/docs/explanation/services-daemons.rst @@ -3,19 +3,19 @@ Services and daemons ====================== -When `creating snapcraft.yaml `__ to build a new snap, a snap’s executable component can be either exposed as a command or run as a background service or daemon. +When :ref:`creating snapcraft.yaml ` to build a new snap, a snap’s executable component can be either exposed as a command or run as a background service or daemon. -For details on how to expose an executable from its constituent parts, see `Defining a command `__. +For details on how to expose an executable from its constituent parts, see :ref:`Defining a command with snapcraft.yaml app keys `. A snap daemon or service behaves the same as a native daemon or service, and will either start automatically at boot time and end when the machine is shutdown, or start and stop on demand through socket activation. -Snap confinement prohibits a system’s users and groups from running as traditional services might, such as under a user’s ownership. But a *daemon* user and group can alternatively be created within a snap to provide similar user and group level control outside of a snap’s confinement. See `System usernames `__ for more details. +Snap confinement prohibits a system’s users and groups from running as traditional services might, such as under a user’s ownership. But a *daemon* user and group can alternatively be created within a snap to provide similar user and group level control outside of a snap’s confinement. See :external+snap:ref:`System usernames ` for more details. -See `Service management `__ for details on starting and stopping services from the *snap* command. Services and daemons can also be managed from within a snap, such as via a hook, with the `snapctl `__. +See :external+snap:ref:`Service management ` for details on starting and stopping services from the *snap* command. Services and daemons can also be managed from within a snap, such as via a hook, with the :external+snap:ref:`snapctl `. -To set memory and CPU resource limits for a service or daemon, see `Quota groups `__ +To set memory and CPU resource limits for a service or daemon, see :external+snap:ref:`Quota groups `. -If you need to add user configurable options to your service or daemon, such as which port it should use, see `Adding snap configuration `__. +If you need to add user configurable options to your service or daemon, such as which port it should use, see `Adding snap configuration `__. Defining a daemon ------------------ @@ -34,29 +34,49 @@ The value for ``daemon:`` can be one of the following: - ``simple``: Run for as long as the service is active - this is typically the default option. - ``oneshot``: Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. - ``forking``: The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. -- ``notify`` Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the `daemon-notify interface `__. +- ``notify`` Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the :external+snap:ref:`daemon-notify interface `. In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: -- ``after``: An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. -- ``before``: An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. -- ``install-mode``: Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use `snapctl `__ with a `hook `__, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. -- ``post-stop-command``: Sets the command to run from inside the snap *after* a service stops. -- ``refresh-mode``: Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . -- ``reload-command``: Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the ``snap restart --reload`` command. - Example: ``reload-command: sbin/nginx -s reload`` -- ``restart-condition``: Defines when a service should be restarted, using values returned from `systemd service exit status `__. Can be one of ``[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]``. -- ``restart-delay``: The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. -- ``sockets``: Requires an activated daemon socket, and works with the `network-bind interface `__ to map a daemon’s socket to a service and activate it. -- ``socket-mode``: The mode of a socket in octal. -- ``start-timeout``: Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. -- ``stop-command``: An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. -- ``stop-mode``: Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . -- ``stop-timeout``: The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). -- ``timer``: Declares that the service is activated by a timer and that the app must be a daemon. See `Timer string format `__ for syntax examples. -- ``watchdog-timeout``: This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. - -For further details, see `Snapcraft app and service metadata `__. +.. list-table:: + :header-rows: 1 + :widths: 24 76 + :align: left + + * - Option + - Description + * - ``after`` + - An ordered list of applications the daemon is to be started *after*. Applications must be part of the same snap. + * - ``before`` + - An ordered list of applications the daemon is to be started *before*. Applications must be part of the same snap. + * - ``install-mode`` + - Defines whether a freshly installed daemon is started automatically, or whether startup control is deferred to the snap. The snap could then use :external+snap:ref:`snapctl ` with a :external+snap:ref:`hook `, for instance, or another management agent. Can be ``enable`` (default) or ``disable``. + * - ``post-stop-command`` + - Sets the command to run from inside the snap *after* a service stops. + * - ``refresh-mode`` + - Controls whether a daemon should be restarted during a snap refresh. Can be either ``restart`` , ``endure``, (do not restart) or ``ignore-running`` (does not refresh running services to facilitate the refresh app awareness feature). Defaults to *restart* . + * - ``reload-command`` + - Defines the command within the snap to be executed when a service needs to be restarted or reloaded after a configuration change, as initiated with the ``snap restart --reload`` command. Example: ``reload-command: sbin/nginx -s reload`` + * - ``restart-condition`` + - Defines when a service should be restarted, using values returned from `systemd service exit status `__. Can be one of ``[on-failure|on-success|on-abnormal|on-abort|on-watchdog|always|never]``. + * - ``restart-delay`` + - The delay between service restarts. Defaults to unset. See the systemd.service manual on RestartSec for details. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. + * - ``sockets`` + - Requires an activated daemon socket, and works with the :external+snap:ref:`network-bind interface ` to map a daemon’s socket to a service and activate it. + * - ``socket-mode`` + - The mode of a socket in octal. + * - ``start-timeout`` + - Optional time to wait for daemon to start. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. + * - ``stop-command`` + - An optional executable command to run before the daemon is stopped, and the daemon is not stopped until the specified *stop-command* terminates. This can be used to gracefully handle a daemon stop or restart, such as when a *refresh* happens, by allowing the daemon to reach a stoppable state first. + * - ``stop-mode`` + - Defines which `termination signal `__ to use when stopping the daemon. Can be one of either ``sigterm``, ``sigterm-all``, ``sighup``, ``sighup-all``, ``sigusr1``, ``sigusr1-all``, ``sigusr2``, ``sigusr2-all``, ``sigint`` and ``sigint-all`` . + * - ``stop-timeout`` + - The length of time to wait before terminating a service. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Termination is via ``SIGTERM`` (and ``SIGKILL`` if that doesn’t work). + * - ``timer`` + - Declares that the service is activated by a timer and that the app must be a daemon. See :external+snap:ref:`Timer string format ` for syntax examples. + * - ``watchdog-timeout`` + - This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. Daemons and D-Bus ------------------- From a04a0d17394ed5fe99270d097016fbe60f373782 Mon Sep 17 00:00:00 2001 From: shaloo <5890484+shaloo@users.noreply.github.com> Date: Fri, 29 May 2026 19:49:09 +0530 Subject: [PATCH 6/6] sync up changes in main and update missing daemon scope fields --- docs/explanation/services-daemons.rst | 7 +++++-- snapcraft/parts/desktop_file.py | 7 ++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/explanation/services-daemons.rst b/docs/explanation/services-daemons.rst index 3c276ac711..583c5e2434 100644 --- a/docs/explanation/services-daemons.rst +++ b/docs/explanation/services-daemons.rst @@ -15,7 +15,7 @@ See :external+snap:ref:`Service management `. -If you need to add user configurable options to your service or daemon, such as which port it should use, see `Adding snap configuration `__. +If you need to add user configurable options to your service or daemon, such as which port it should use, see :ref:`Adding snap configuration `. Defining a daemon ------------------ @@ -34,7 +34,8 @@ The value for ``daemon:`` can be one of the following: - ``simple``: Run for as long as the service is active - this is typically the default option. - ``oneshot``: Run once and exit after completion, notifying systemd. After completion, the daemon is still considered active and *running*. - ``forking``: The configured command calls ``fork()`` as part of its start-up and the parent process is then expected to exit when start-up is complete. This isn’t the recommended behaviour on a modern Linux system. -- ``notify`` Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the :external+snap:ref:`daemon-notify interface `. +- ``notify``: Assumes the command will send a signal to *systemd* to indicate its running state. Note this requires usage of the :external+snap:ref:`daemon-notify interface `. +- ``dbus``: Registers a D-Bus name to notify systemd. Requires bus-name or activates-on to be specified. In addition to the above types of daemon or service, the following can be set to help manage how a service is run, how it can be stopped, and what should happen after it stops: @@ -77,6 +78,8 @@ In addition to the above types of daemon or service, the following can be set to - Declares that the service is activated by a timer and that the app must be a daemon. See :external+snap:ref:`Timer string format ` for syntax examples. * - ``watchdog-timeout`` - This value declares the service watchdog timeout. For watchdog to work, the application requires access to the *systemd* notification socket, which can be declared by listing a daemon-notify plug in the plugs section. Time duration units can be ``10ns``, ``10us``, ``10ms``, ``10s``, ``10m``. + * - ``daemon-scope`` + - Scope of the daemon. Accepts ``system`` (default) or ``user`` as values. ``system`` runs regardless of user login. Use when the service needs elevated privileges or must run without an active session. ``user`` starts on login, stops on logout. Use for unprivileged services that only need to run within a user session. Daemons and D-Bus ------------------- diff --git a/snapcraft/parts/desktop_file.py b/snapcraft/parts/desktop_file.py index 860d8cca16..c3f5ec737c 100644 --- a/snapcraft/parts/desktop_file.py +++ b/snapcraft/parts/desktop_file.py @@ -21,14 +21,13 @@ import configparser import os import shlex -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING from craft_cli import emit from snapcraft import errors if TYPE_CHECKING: - from collections.abc import Callable from pathlib import Path @@ -58,7 +57,9 @@ def __init__( ) self._parser = configparser.ConfigParser(interpolation=None) - self._parser.optionxform: Callable[[Any], str] = str + # The configparser docs recommend overriding this function to preserve the case. + # However, ty doesn't like attribute assignment that shadows a class method. + self._parser.optionxform = str # ty: ignore[invalid-assignment] self._parser.read(file_path, encoding="utf-8") def _parse_and_reformat_section_exec(self, section: str):