From dee0f551112349da4aa3f913f92f2c7c8f48f1f0 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 19 Dec 2018 17:27:15 +0000 Subject: [PATCH 1/2] Officially deprecate package-supplied dbus-daemon policy in ${sysconfdir} Now that dbus 1.10 has become widely available, we should start to treat ${sysconfdir} as reserved for the sysadmin, and encourage third-party software packages to install their integration files into ${datadir}. Signed-off-by: Simon McVittie --- NEWS | 15 +++++++++++++++ doc/dbus-daemon.1.xml.in | 19 ++++++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/NEWS b/NEWS index 112d196c0..349b2e9f8 100644 --- a/NEWS +++ b/NEWS @@ -1,6 +1,21 @@ dbus 1.13.10 (UNRELEASED) ========================= +Deprecations: + +• Third-party software should install default dbus policies for the system + bus into ${datadir}/dbus-1/system.d (this has been supported since dbus + 1.10, released in August 2015). Installing default dbus policies in + ${sysconfdir}/dbus-1/system.d is now considered to be deprecated. Policy + files in ${sysconfdir}/dbus-1/system.d continue to be read, but this + directory should only be used by system administrators wishing to + override the default policies. + + The ${datadir} applicable to dbus is usually /usr/share and the + ${sysconfdir} is usually /etc. + +• A similar pattern applies to the session bus policies in session.d. + Fixes: • Avoid possible memory corruption in certain DBusHashTableIter use diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in index 526b85ba7..70a8fb3d4 100644 --- a/doc/dbus-daemon.1.xml.in +++ b/doc/dbus-daemon.1.xml.in @@ -223,6 +223,21 @@ configured in the files "@EXPANDED_DATADIR@/dbus-1/system.conf" and overrides in those files to avoid modifying the primary configuration files. +The standard system bus normally reads additional XML files from + @EXPANDED_DATADIR@/dbus-1/system.d. Third-party + packages should install the default policies necessary for correct + operation into that directory, which has been supported since dbus 1.10 + (released in 2015). + +The standard system bus normally also reads XML files from + @EXPANDED_SYSCONFDIR@/dbus-1/system.d, which + should be used by system administrators if they wish to override + default policies. + +Third-party packages would historically install XML files into + @EXPANDED_SYSCONFDIR@/dbus-1/system.d, but this + practice is now considered to be deprecated: that directory should + be treated as reserved for the system administrator. The configuration file is an XML document. It must have the following doctype declaration: @@ -302,12 +317,10 @@ to be absent. point. Files in the directory are included in undefined order. Only files ending in ".conf" are included. - This is intended to allow extension of the system bus by particular packages. For example, if CUPS wants to be able to send out notification of printer queue changes, it could install a file to -@EXPANDED_DATADIR@/dbus-1/system.d or -@EXPANDED_SYSCONFDIR@/dbus-1/system.d that allowed all apps to receive +@EXPANDED_DATADIR@/dbus-1/system.d that allowed all apps to receive this message and allowed the printer daemon user to send it. -- GitLab From 3c4a6638005edbd412c58b8baf60a25b6087af3e Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 19 Dec 2018 17:29:11 +0000 Subject: [PATCH 2/2] 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: -- GitLab