2 title: Creating a New Service
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:
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
12 - **User services:** such services run as part of an unprivileged user's session and can
13 only be called by said user
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):
21 - `/usr/lib/systemd/system/` for system services
23 - `/usr/lib/systemd/user/` for user services
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:
30 Requires=agl-compositor.service
31 After=agl-compositor.service
35 ExecStart=/usr/bin/homescreen
39 WantedBy=agl-session.target
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_Application_Framework/01_Introduction/#user-session-management)
46 The `Restart=on-failure` directive ensures the service will be automatically
47 restarted by `systemd` in case it crashes.
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).
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
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
67 ExecStart=/path/to/executable
70 In addition, they must provide a D-Bus service file named `NAME.service` and installed
71 to one of the following locations:
73 - `/usr/share/dbus-1/system-services` for system services
75 - `/usr/share/dbus-1/services` for user services
77 The contents of the D-Bus service file must be the following:
82 Exec=/path/to/executable
83 SystemdService=dbus-NAME.service
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.
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.
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.
101 System services can take advantage of the Yocto `systemd` class which automates the process of
102 enabling such services.
104 1\. Ensure the recipe inherits from the `systemd` class:
110 2\. Declare the system services that needs to be enabled on boot:
113 SYSTEMD_SERVICE:${PN} = "NAME.service"
116 3\. Ensure the `FILES` variable includes the systemd service directory the corresponding
117 file will be installed to:
122 ${systemd_system_unitdir}/* \
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.
131 1\. Make the service a part of the user session:
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
140 This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore
141 automatically started on session creation.
143 2\. Ensure the `FILES` variable includes the systemd service directory the corresponding
144 file will be installed to:
149 ${systemd_user_unitdir}/* \