docs/3_Developer_Guides/2_Creating_a_New_Service.md

   1 ---
   2 title: Creating a New Service
   3 ---
   4
   5 Services are software running in the background and providing, as their name suggests,
   6 various services to other software: access to specific system hardware, connectivity
   7 management, network servers... They can be split into 2 categories:
   8 - system services: those usually run as a privileged user and make use of shared system
   9   resources which they should have exclusive access to
  10 - user services: such services run as part of an unprivileged user's session and can
  11   only be called by said user
  12
  13 # Basic requirements
  14
  15 The only mandatory requirement is that service packages provide a `.service` file
  16 so they can be properly managed by `systemd`. This file must be installed to a specific
  17 location, determined by the service type (system or user):
  18 - `/usr/lib/systemd/system/` for system services
  19 - `/usr/lib/systemd/user/` for user services
  20
  21 Below is an example of a simple user service, running in a graphical session and
  22 therefore requiring a compositor to be already running before the service starts:
  23
  24 ```
  25 [Unit]
  26 Requires=agl-compositor.service
  27 After=agl-compositor.service
  28
  29 [Service]
  30 Type=simple
  31 ExecStart=/usr/bin/homescreen
  32 Restart=on-failure
  33
  34 [Install]
  35 WantedBy=agl-session.target
  36 ```
  37
  38 The `WantedBy=agl-session.target` indicates the service is part of the default AGL
  39 user session, as mentioned in the [Application Framework](1_Application_Framework/1_Introduction/#user-session-management)
  40 documentation.
  41
  42 The `Restart=on-failure` directive ensures the service will be automatically
  43 restarted by `systemd` in case it crashes.
  44
  45 More details about `systemd` service files can be found in the
  46 [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html).
  47
  48 # D-Bus activation
  49
  50 Services can also provide a D-Bus interface. In this case, they need not be started
  51 on system boot (or user session startup in the case of user services) but can be
  52 automatically started only when a client sends a request to the D-Bus name the service
  53 registers.
  54
  55 D-Bus activated services must name their `systemd` service file `dbus-NAME.service`
  56 where `NAME` is the D-Bus name registered by the service. This file must include the
  57 following lines:
  58
  59 ```
  60 [Service]
  61 Type=dbus
  62 BusName=NAME
  63 ExecStart=/path/to/executable
  64 ```
  65
  66 In addition, they must provide a D-Bus service file named `NAME.service` and installed
  67 to one of the following locations:
  68 - `/usr/share/dbus-1/system-services` for system services
  69 - `/usr/share/dbus-1/services` for user services
  70
  71 The contents of the D-Bus service file must be the following:
  72
  73 ```
  74 [D-BUS Service]
  75 Name=NAME
  76 Exec=/path/to/executable
  77 SystemdService=dbus-NAME.service
  78 ```
  79
  80 This ensures the service can be safely activated through D-Bus and no conflict will occur
  81 between `systemd` and the D-Bus daemon.
  82
  83 More details about D-Bus activation can be found in the
  84 [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services),
  85 under the "Message Bus Starting Services (Activation)" section.
  86
  87 # Services startup
  88
  89 For D-Bus activated services, no additional action is required as those will be automatically
  90 started whenever needed. Other services, however, need a few more steps in order to be
  91 executed on system or session startup.
  92
  93 ## System services
  94
  95 System services can take advantage of the Yocto `systemd` class which automates the process of
  96 enabling such services.
  97
  98 1. Ensure the recipe inherits from the `systemd` class:
  99
 100 ```
 101 inherit systemd
 102 ```
 103
 104 2. Declare the system services that needs to be enabled on boot:
 105
 106 ```
 107 SYSTEMD_SERVICE:${PN} = "NAME.service"
 108 ```
 109
 110 3. Ensure the `FILES` variable includes the systemd service directory the corresponding
 111 file will be installed to:
 112
 113 ```
 114 FILES:${PN} = "\
 115     ...
 116     ${systemd_system_unitdir}/* \
 117 "
 118 ```
 119
 120 ## User services
 121
 122 The `systemd` class doesn't provide an equivalent mechanism for user services. This must
 123 therefore be done manually as part of the package's install process.
 124
 125 1. Make the service a part of the user session:
 126
 127 ```
 128 do_install:append() {
 129     install -d ${D}${systemd_user_unitdir}/agl-session.target.wants
 130     ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service
 131 }
 132 ```
 133
 134 This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore
 135 automatically started on session creation.
 136
 137 2. Ensure the `FILES` variable includes the systemd service directory the corresponding
 138 file will be installed to:
 139
 140 ```
 141 FILES:${PN} = "\
 142     ...
 143     ${systemd_user_unitdir}/* \
 144 "
 145 ```