From 3c4a6638005edbd412c58b8baf60a25b6087af3e Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 19 Dec 2018 17:29:11 +0000 Subject: [PATCH] dbus-daemon(1): Give more comprehensive examples of how to add services While writing the wording to deprecate XML policy installed by packages into ${sysconfdir}, I realised we didn't give a typical example of what packages *should* do. Signed-off-by: Simon McVittie --- doc/dbus-daemon.1.xml.in | 173 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in index 70a8fb3d4..acbc7ded4 100644 --- a/doc/dbus-daemon.1.xml.in +++ b/doc/dbus-daemon.1.xml.in @@ -1197,6 +1197,179 @@ signal to the daemon has no effect on the mediation mode. + + INTEGRATING SESSION SERVICES + + + Integration files are not mandatory for session services: any program + with access to the session bus can request a well-known name and + provide D-Bus interfaces. + + + + Many D-Bus session services support service + activation, a mechanism in which the + dbus-daemon can launch the service on-demand, + either by running the session service itself or by communicating + with systemd --user. This is set up by + creating a service file in the directory + ${datadir}/dbus-1/services, + for example: + + +[D-BUS Service] +Name=com.example.SessionService1 +Exec=/usr/bin/example-session-service +# Optional +SystemdService=example-session-service + + + See the + D-Bus + Specification for details of the contents and interpretation + of service files. + + If there is a service file for + com.example.SessionService1, it should be named + com.example.SessionService1.service, + although for compatibility with legacy services this is not mandatory. + + + Session services that declare the optional + SystemdService must also provide a systemd user + service unit file whose name or Alias matches the + SystemdService (see + + systemd.unit + 5 + , + + systemd.service + 5 + for further details on systemd service units), for + example: + + +[Unit] +Description=Example session service + +[Service] +Type=dbus +BusName=com.example.SessionService1 +ExecStart=/usr/bin/example-session-service + + + + + + INTEGRATING SYSTEM SERVICES + + + The standard system bus does not allow method calls or owning well-known + bus names by default, so a useful D-Bus system service will normally + need to configure a default security policy that allows it to work. + D-Bus system services should install a default policy file in + ${datadir}/dbus-1/service.d, + containing the policy rules necessary to make that system service + functional. A best-practice policy file will often look like this: + + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE busconfig PUBLIC + "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" + "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> +<busconfig> + <policy user="_example"> + <allow own="com.example.Example1"/> + </policy> + + <policy context="default"> + <allow send_destination="com.example.Example1"/> + </policy> +</busconfig> + + + where _example is the username of the + system uid that will run the system service daemon process, and + com.example.Example1 is its well-known + bus name. + + The policy file for com.example.Example1 + should normally be named + com.example.Example1.conf. + + + Some existing system services rely on more complex <policy> + rules to control the messages that the service can receive. However, + the dbus-daemon's policy language is not well-suited + to finer-grained policies: any policy has to be expressed in terms of + D-Bus interfaces and method names, not in terms of higher-level + domain-specific concepts like removable or built-in devices. It is + recommended that new services should normally accept method call messages + from all callers, then apply a sysadmin-controllable policy to decide + whether to obey the requests contained in those method call messages, + for example by consulting + polkit. + + + + Like session services, many D-Bus system services support service + activation, a mechanism in which the dbus-daemon + can launch the service on-demand, either by running the system service + itself or by communicating with systemd. This is set + up by creating a service file in the directory + ${datadir}/dbus-1/system-services, + for example: + + +[D-BUS Service] +Name=com.example.Example1 +Exec=/usr/sbin/example-service +User=_example +# Optional +SystemdService=dbus-com.example.Example1.service + + + See the + D-Bus + Specification for details of the contents and interpretation + of service files. + + If there is a service file for + com.example.Example1, it must be named + com.example.Example1.service. + + + System services that declare the optional + SystemdService must also provide a systemd + service unit file whose name or Alias matches the + SystemdService (see + + systemd.unit + 5 + , + + systemd.service + 5 + for further details on systemd service units), for + example: + + +[Unit] +Description=Example service + +[Service] +Type=dbus +BusName=com.example.Example1 +ExecStart=/usr/sbin/example-service + +[Install] +WantedBy=multi-user.target +Alias=dbus-com.example.Example1.service + + + + SELinux See http://www.nsa.gov/selinux/ for full details on SELinux. Some useful excerpts: -- 2.47.3