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