Debian Codegraph @

doc/dbus-daemon.1.xml.in

raw
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4 <refentry id='dbusdaemon1'>
5
6 <!-- dbus&bsol;-daemon manual page.
7 Copyright (C) 2003,2008 Red Hat, Inc. -->
8
9 <refmeta>
10 <refentrytitle>dbus-daemon</refentrytitle>
11 <manvolnum>1</manvolnum>
12 <refmiscinfo class="manual">User Commands</refmiscinfo>
13 <refmiscinfo class="source">D-Bus</refmiscinfo>
14 <refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo>
15 </refmeta>
16 <refnamediv>
17 <refname>dbus-daemon</refname>
18 <refpurpose>Message bus daemon</refpurpose>
19 </refnamediv>
20 <!-- body begins here -->
21 <refsynopsisdiv id='synopsis'>
22 <cmdsynopsis>
23 <command>dbus-daemon</command></cmdsynopsis>
24 <cmdsynopsis>
25 <command>dbus-daemon</command> <arg choice='opt'>--version </arg>
26 <arg choice='opt'>--session </arg>
27 <arg choice='opt'>--system </arg>
28 <arg choice='opt'>--config-file=<replaceable>FILE</replaceable></arg>
29 <arg choice='opt'><arg choice='plain'>--print-address </arg><arg choice='opt'><replaceable>=DESCRIPTOR</replaceable></arg></arg>
30 <arg choice='opt'><arg choice='plain'>--print-pid </arg><arg choice='opt'><replaceable>=DESCRIPTOR</replaceable></arg></arg>
31 <arg choice='opt'>--fork </arg>
32 <arg choice='opt'>--nosyslog </arg>
33 <arg choice='opt'>--syslog </arg>
34 <arg choice='opt'>--syslog-only </arg>
35 <arg choice='opt'>--ready-event-handle=value</arg>
36 <sbr/>
37 </cmdsynopsis>
38 </refsynopsisdiv>
39
40
41 <refsect1 id='description'><title>DESCRIPTION</title>
42 <para><command>dbus-daemon</command> is the D-Bus message bus daemon. See
43 <ulink url='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink> for more information about
44 the big picture. D-Bus is first a library that provides one-to-one
45 communication between any two applications; <command>dbus-daemon</command> is an
46 application that uses this library to implement a message bus
47 daemon. Multiple programs connect to the message bus daemon and can
48 exchange messages with one another.</para>
49
50 <para>There are two standard message bus instances: the systemwide message bus
51 (installed on many systems as the "messagebus" init service) and the
52 per-user-login-session message bus (started each time a user logs in).
53 <command>dbus-daemon</command> is used for both of these instances, but with
54 a different configuration file.</para>
55
56 <para>The --session option is equivalent to
57 "--config-file=@EXPANDED_DATADIR@/dbus-1/session.conf" and the --system
58 option is equivalent to
59 "--config-file=@EXPANDED_DATADIR@/dbus-1/system.conf". By creating
60 additional configuration files and using the --config-file option,
61 additional special-purpose message bus daemons could be created.</para>
62
63 <para>The systemwide daemon is normally launched by an init script,
64 standardly called simply "messagebus".</para>
65
66 <para>The systemwide daemon is largely used for broadcasting system events,
67 such as changes to the printer queue, or adding/removing devices.</para>
68
69 <para>The per-session daemon is used for various interprocess communication
70 among desktop applications (however, it is not tied to X or the GUI
71 in any way).</para>
72
73 <para>SIGHUP will cause the D-Bus daemon to PARTIALLY reload its
74 configuration file and to flush its user/group information caches. Some
75 configuration changes would require kicking all apps off the bus; so they will
76 only take effect if you restart the daemon. Policy changes should take effect
77 with SIGHUP.</para>
78
79 </refsect1>
80
81 <refsect1 id='options'><title>OPTIONS</title>
82 <para>The following options are supported:</para>
83 <variablelist remap='TP'>
84 <varlistentry>
85 <term><option>--config-file=FILE</option></term>
86 <listitem>
87 <para>Use the given configuration file.</para>
88 </listitem>
89 </varlistentry>
90 <varlistentry>
91 <term><option>--fork</option></term>
92 <listitem>
93 <para>Force the message bus to fork and become a daemon, even if
94 the configuration file does not specify that it should.
95 In most contexts the configuration file already gets this
96 right, though. This option is not supported on Windows.</para>
97 </listitem>
98 </varlistentry>
99 <varlistentry>
100 <term><option>--nofork</option></term>
101 <listitem>
102 <para>Force the message bus not to fork and become a daemon, even if
103 the configuration file specifies that it should. On Windows,
104 the dbus-daemon never forks, so this option is allowed but does
105 nothing.</para>
106 </listitem>
107 </varlistentry>
108 <varlistentry>
109 <term><option>--print-address[=DESCRIPTOR]</option></term>
110 <listitem>
111 <para>Print the address of the message bus to standard output, or
112 to the given file descriptor. This is used by programs that
113 launch the message bus.</para>
114 </listitem>
115 </varlistentry>
116 <varlistentry>
117 <term><option>--print-pid[=DESCRIPTOR]</option></term>
118 <listitem>
119 <para>Print the process ID of the message bus to standard output, or
120 to the given file descriptor. This is used by programs that
121 launch the message bus.</para>
122 </listitem>
123 </varlistentry>
124 <varlistentry>
125 <term><option>--session</option></term>
126 <listitem>
127 <para>Use the standard configuration file for the per-login-session message
128 bus.</para>
129 </listitem>
130 </varlistentry>
131 <varlistentry>
132 <term><option>--system</option></term>
133 <listitem>
134 <para>Use the standard configuration file for the systemwide message bus.</para>
135 </listitem>
136 </varlistentry>
137 <varlistentry>
138 <term><option>--version</option></term>
139 <listitem>
140 <para>Print the version of the daemon.</para>
141 </listitem>
142 </varlistentry>
143 <varlistentry>
144 <term><option>--introspect</option></term>
145 <listitem>
146 <para>Print the introspection information for all D-Bus internal interfaces.</para>
147 </listitem>
148 </varlistentry>
149 <varlistentry>
150 <term><option>--address[=ADDRESS]</option></term>
151 <listitem>
152 <para>Set the address to listen on. This option overrides the address
153 configured in the configuration file via the
154 <literal>&lt;listen&gt;</literal> directive.
155 See the documentation of that directive for more details.</para>
156 </listitem>
157 </varlistentry>
158 <varlistentry>
159 <term><option>--systemd-activation</option></term>
160 <listitem>
161 <para>Enable systemd-style service activation. Only useful in conjunction
162 with the systemd system and session manager on Linux.</para>
163 </listitem>
164 </varlistentry>
165 <varlistentry>
166 <term><option>--nopidfile</option></term>
167 <listitem>
168 <para>Don't write a PID file even if one is configured in the configuration
169 files.</para>
170
171 </listitem>
172 </varlistentry>
173
174 <varlistentry>
175 <term><option>--syslog</option></term>
176 <listitem>
177 <para>Force the message bus to use the system log for messages,
178 in addition to writing to standard error, even if the configuration
179 file does not specify that it should. On Unix, this uses
180 the syslog; on Windows, this uses OutputDebugString().</para>
181 </listitem>
182 </varlistentry>
183
184 <varlistentry>
185 <term><option>--syslog-only</option></term>
186 <listitem>
187 <para>Force the message bus to use the system log for messages,
188 and <emphasis>not</emphasis> duplicate them to standard error.
189 On Unix, this uses the syslog; on Windows, this uses
190 OutputDebugString().</para>
191 </listitem>
192 </varlistentry>
193
194 <varlistentry>
195 <term><option>--nosyslog</option></term>
196 <listitem>
197 <para>Force the message bus to use only standard error for messages,
198 even if the configuration file specifies that it should use
199 the system log.</para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><option>--ready-event-handle=value</option></term>
205 <listitem>
206 <para>With this option, the dbus daemon raises an event when it is ready to process
207 connections. The <replaceable>handle</replaceable> must be the Windows handle
208 for an event object, in the format printed by the <function>printf</function>
209 format string <literal>%p</literal>. The parent process must create this event
210 object (for example with the <function>CreateEvent</function> function) in a
211 nonsignaled state, then configure it to be inherited by the dbus-daemon process.
212 The dbus-daemon will signal the event as if via <function>SetEvent</function>
213 when it is ready to receive connections from clients. The parent process can
214 wait for this to occur by using functions such as
215 <function>WaitForSingleObject</function>.
216 This option is only supported under Windows. On Unix platforms,
217 a similar result can be achieved by waiting for the address and/or
218 process ID to be printed to the inherited file descriptors used
219 for <option>--print-address</option> and/or <option>--print-pid</option>.
220 </para>
221 </listitem>
222 </varlistentry>
223
224
225
226 </variablelist>
227 </refsect1>
228
229 <refsect1 id='configuration_file'><title>CONFIGURATION FILE</title>
230 <para>A message bus daemon has a configuration file that specializes it
231 for a particular application. For example, one configuration
232 file might set up the message bus to be a systemwide message bus,
233 while another might set it up to be a per-user-login-session bus.</para>
234
235 <para>The configuration file also establishes resource limits, security
236 parameters, and so forth.</para>
237
238 <para>The configuration file is not part of any interoperability
239 specification and its backward compatibility is not guaranteed; this
240 document is documentation, not specification.</para>
241
242 <para>The standard systemwide and per-session message bus setups are
243 configured in the files "@EXPANDED_DATADIR@/dbus-1/system.conf" and
244 "@EXPANDED_DATADIR@/dbus-1/session.conf". These files normally
245 &lt;include&gt; a system-local.conf or session-local.conf in
246 @EXPANDED_SYSCONFDIR@/dbus-1; you can put local
247 overrides in those files to avoid modifying the primary configuration
248 files.</para>
249
250 <para>The standard system bus normally reads additional XML files from
251 <filename>@EXPANDED_DATADIR@/dbus-1/system.d</filename>. Third-party
252 packages should install the default policies necessary for correct
253 operation into that directory, which has been supported since dbus 1.10
254 (released in 2015).</para>
255
256 <para>The standard system bus normally also reads XML files from
257 <filename>@EXPANDED_SYSCONFDIR@/dbus-1/system.d</filename>, which
258 should be used by system administrators if they wish to override
259 default policies.</para>
260
261 <para>Third-party packages would historically install XML files into
262 <filename>@EXPANDED_SYSCONFDIR@/dbus-1/system.d</filename>, but this
263 practice is now considered to be deprecated: that directory should
264 be treated as reserved for the system administrator.</para>
265
266 <para>The configuration file is an XML document. It must have the following
267 doctype declaration:</para>
268 <literallayout remap='.nf'>
269
270 &lt;!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
271 "<ulink url='http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd'>http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd</ulink>"&gt;
272
273 </literallayout> <!-- .fi -->
274
275
276 <para>The following elements may be present in the configuration file.</para>
277
278 <itemizedlist remap='TP'>
279
280 <listitem><para><emphasis remap='I'>&lt;busconfig&gt;</emphasis></para></listitem>
281
282
283 </itemizedlist>
284
285 <para>Root element.</para>
286
287 <itemizedlist remap='TP'>
288
289 <listitem><para><emphasis remap='I'>&lt;type&gt;</emphasis></para></listitem>
290
291
292 </itemizedlist>
293
294 <para>The well-known type of the message bus. Currently known values are
295 "system" and "session"; if other values are set, they should be
296 either added to the D-Bus specification, or namespaced. The last
297 &lt;type&gt; element "wins" (previous values are ignored). This element
298 only controls which message bus specific environment variables are
299 set in activated clients. Most of the policy that distinguishes a
300 session bus from the system bus is controlled from the other elements
301 in the configuration file.</para>
302
303
304 <para>If the well-known type of the message bus is "session", then the
305 DBUS_STARTER_BUS_TYPE environment variable will be set to "session"
306 and the DBUS_SESSION_BUS_ADDRESS environment variable will be set
307 to the address of the session bus. Likewise, if the type of the
308 message bus is "system", then the DBUS_STARTER_BUS_TYPE environment
309 variable will be set to "system" and the DBUS_SYSTEM_BUS_ADDRESS
310 environment variable will be set to the address of the system bus
311 (which is normally well known anyway).</para>
312
313
314 <para>Example: &lt;type&gt;session&lt;/type&gt;</para>
315
316 <itemizedlist remap='TP'>
317
318 <listitem><para><emphasis remap='I'>&lt;include&gt;</emphasis></para></listitem>
319
320
321 </itemizedlist>
322
323 <para>Include a file &lt;include&gt;filename.conf&lt;/include&gt; at this point. If the
324 filename is relative, it is located relative to the configuration file
325 doing the including.</para>
326
327
328 <para>&lt;include&gt; has an optional attribute "ignore_missing=(yes|no)"
329 which defaults to "no" if not provided. This attribute
330 controls whether it's a fatal error for the included file
331 to be absent.</para>
332
333 <itemizedlist remap='TP'>
334
335 <listitem><para><emphasis remap='I'>&lt;includedir&gt;</emphasis></para></listitem>
336
337
338 </itemizedlist>
339
340 <para>Include all files in &lt;includedir&gt;foo.d&lt;/includedir&gt; at this
341 point. Files in the directory are included in undefined order.
342 Only files ending in ".conf" are included.</para>
343
344 <para>This is intended to allow extension of the system bus by particular
345 packages. For example, if CUPS wants to be able to send out
346 notification of printer queue changes, it could install a file to
347 @EXPANDED_DATADIR@/dbus-1/system.d that allowed all apps to receive
348 this message and allowed the printer daemon user to send it.</para>
349
350 <itemizedlist remap='TP'>
351
352 <listitem><para><emphasis remap='I'>&lt;user&gt;</emphasis></para></listitem>
353
354
355 </itemizedlist>
356
357 <para>The user account the daemon should run as, as either a username or a
358 UID. If the daemon cannot change to this UID on startup, it will exit.
359 If this element is not present, the daemon will not change or care
360 about its UID.</para>
361
362
363 <para>The last &lt;user&gt; entry in the file "wins", the others are ignored.</para>
364
365
366 <para>The user is changed after the bus has completed initialization. So
367 sockets etc. will be created before changing user, but no data will be
368 read from clients before changing user. This means that sockets
369 and PID files can be created in a location that requires root
370 privileges for writing.</para>
371
372 <itemizedlist remap='TP'>
373
374 <listitem><para><emphasis remap='I'>&lt;fork&gt;</emphasis></para></listitem>
375
376
377 </itemizedlist>
378
379 <para>If present, the bus daemon becomes a real daemon (forks
380 into the background, etc.). This is generally used
381 rather than the --fork command line option.</para>
382
383 <itemizedlist remap='TP'>
384
385 <listitem><para><emphasis remap='I'>&lt;keep_umask&gt;</emphasis></para></listitem>
386
387
388 </itemizedlist>
389
390 <para>If present, the bus daemon keeps its original umask when forking.
391 This may be useful to avoid affecting the behavior of child processes.</para>
392
393 <itemizedlist remap='TP'>
394
395 <listitem><para><emphasis remap='I'>&lt;syslog&gt;</emphasis></para></listitem>
396
397
398 </itemizedlist>
399
400 <para>If present, the bus daemon will log to syslog. The
401 --syslog, --syslog-only and --nosyslog command-line options take precedence
402 over this setting.</para>
403
404 <itemizedlist remap='TP'>
405
406 <listitem><para><emphasis remap='I'>&lt;pidfile&gt;</emphasis></para></listitem>
407
408
409 </itemizedlist>
410
411 <para>If present, the bus daemon will write its pid to the specified file.
412 The --nopidfile command-line option takes precedence over this setting.</para>
413
414 <itemizedlist remap='TP'>
415
416 <listitem><para><emphasis remap='I'>&lt;allow_anonymous&gt;</emphasis></para></listitem>
417
418
419 </itemizedlist>
420
421 <para>If present, connections that authenticated using the ANONYMOUS
422 mechanism will be authorized to connect. This option has no practical
423 effect unless the ANONYMOUS mechanism has also been enabled using the
424 <emphasis remap='I'>&lt;auth&gt;</emphasis> element, described below.</para>
425
426 <para>Using this directive in the configuration of the well-known
427 system bus or the well-known session bus will make that bus insecure
428 and should never be done. Similarly, on custom bus types, using this
429 directive will usually make the custom bus insecure, unless its
430 configuration has been specifically designed to prevent anonymous
431 users from causing damage or escalating privileges.</para>
432
433 <itemizedlist remap='TP'>
434
435 <listitem><para><emphasis remap='I'>&lt;listen&gt;</emphasis></para></listitem>
436
437
438 </itemizedlist>
439
440 <para>Add an address that the bus should listen on. The
441 address is in the standard D-Bus format that contains
442 a transport name plus possible parameters/options.</para>
443
444 <para>On platforms other than Windows, <literal>unix</literal>-based
445 transports (<literal>unix</literal>, <literal>systemd</literal>,
446 <literal>launchd</literal>) are the default for both the well-known
447 system bus and the well-known session bus, and are strongly
448 recommended.</para>
449
450 <para>
451 On Windows, <literal>unix</literal>-based transports are not available,
452 so TCP-based transports must be used.
453 Similar to remote X11, the <literal>tcp</literal> and
454 <literal>nonce-tcp</literal> transports have no integrity or
455 confidentiality protection, so they should normally only be
456 used across the local loopback interface, for example using an
457 address like <literal>tcp:host=127.0.0.1</literal> or
458 <literal>nonce-tcp:host=localhost</literal>. In particular,
459 configuring the well-known system bus or the well-known session
460 bus to listen on a non-loopback TCP address is insecure.
461 </para>
462 <para>
463 Developers are sometimes tempted to use remote TCP as a debugging
464 tool. However, if this functionality is left enabled in finished
465 products, the result will be dangerously insecure. Instead of
466 using remote TCP, developers should <ulink
467 url="https://lists.freedesktop.org/archives/dbus/2018-April/017447.html"
468 >relay connections via Secure Shell or a similar protocol</ulink>.
469 <!-- TODO: Ideally someone would write a more formal guide to
470 remote D-Bus debugging, and we could link to that instead -->
471 </para>
472 <para>
473 Remote TCP connections were historically sometimes used to share
474 a single session bus between login sessions of the same user on
475 different machines within a trusted local area network, in
476 conjunction with unencrypted remote X11, a NFS-shared home
477 directory and NIS (YP) authentication. This is insecure against
478 an attacker on the same LAN and should be considered strongly
479 deprecated; more specifically, it is insecure in the same ways
480 and for the same reasons as unencrypted remote X11 and NFSv2/NFSv3.
481 The D-Bus maintainers
482 recommend using a separate session bus per (user, machine) pair,
483 only accessible from within that machine.
484 </para>
485
486 <para>Example: &lt;listen&gt;unix:path=/tmp/foo&lt;/listen&gt;</para>
487
488
489 <para>Example: &lt;listen&gt;tcp:host=localhost,port=1234&lt;/listen&gt;</para>
490
491
492 <para>If there are multiple &lt;listen&gt; elements, then the bus listens
493 on multiple addresses. The bus will pass its address to
494 started services or other interested parties with
495 the last address given in &lt;listen&gt; first. That is,
496 apps will try to connect to the last &lt;listen&gt; address first.</para>
497
498
499 <para>tcp sockets can accept IPv4 addresses, IPv6 addresses or hostnames.
500 If a hostname resolves to multiple addresses, the server will bind
501 to all of them. The family=ipv4 or family=ipv6 options can be used
502 to force it to bind to a subset of addresses</para>
503
504
505 <para>Example: &lt;listen&gt;tcp:host=localhost,port=0,family=ipv4&lt;/listen&gt;</para>
506
507
508 <para>A special case is using a port number of zero (or omitting the port),
509 which means to choose an available port selected by the operating
510 system. The port number chosen can be obtained with the
511 --print-address command line parameter and will be present in other
512 cases where the server reports its own address, such as when
513 DBUS_SESSION_BUS_ADDRESS is set.</para>
514
515
516 <para>Example: &lt;listen&gt;tcp:host=localhost,port=0&lt;/listen&gt;</para>
517
518
519 <para>tcp/nonce-tcp addresses also allow a bind=hostname option,
520 used in a listenable address to configure the interface on which
521 the server will listen: either the hostname is the IP address of
522 one of the local machine's interfaces (most commonly 127.0.0.1),
523 a DNS name that resolves to one of those IP addresses, '0.0.0.0'
524 to listen on all IPv4 interfaces simultaneously, or '::'
525 to listen on all IPv4 and IPv6 interfaces simultaneously (if supported
526 by the OS). If not specified,
527 the default is the same value as "host".</para>
528
529
530 <para>Example: &lt;listen&gt;tcp:host=localhost,bind=0.0.0.0,port=0&lt;/listen&gt;</para>
531
532 <itemizedlist remap='TP'>
533
534 <listitem><para><emphasis remap='I'>&lt;auth&gt;</emphasis></para></listitem>
535
536
537 </itemizedlist>
538
539 <para>Lists permitted authorization mechanisms. If this element doesn't
540 exist, then all known mechanisms are allowed. If there are multiple
541 &lt;auth&gt; elements, all the listed mechanisms are allowed. The order in
542 which mechanisms are listed is not meaningful.</para>
543
544 <para>On non-Windows operating systems, allowing only the
545 <literal>EXTERNAL</literal> authentication
546 mechanism is strongly recommended. This is the default for the
547 well-known system bus and for the well-known session bus.</para>
548
549 <para>Example: &lt;auth&gt;EXTERNAL&lt;/auth&gt;</para>
550
551
552 <para>Example: &lt;auth&gt;DBUS_COOKIE_SHA1&lt;/auth&gt;</para>
553
554 <itemizedlist remap='TP'>
555
556 <listitem><para><emphasis remap='I'>&lt;servicedir&gt;</emphasis></para></listitem>
557
558
559 </itemizedlist>
560
561 <para>
562 Adds a directory to search for .service files, which tell the
563 dbus-daemon how to start a program to provide a particular well-known
564 bus name. See the D-Bus Specification for more details about the
565 contents of .service files.
566 </para>
567
568 <para>
569 If a particular service is found in more than one &lt;servicedir&gt;,
570 the first directory listed in the configuration file takes precedence.
571 If two service files providing the same well-known bus name are found
572 in the same directory, it is arbitrary which one will be chosen
573 (this can only happen if at least one of the service files does not
574 have the recommended name, which is its well-known bus name followed
575 by ".service").
576 </para>
577
578 <itemizedlist remap='TP'>
579
580 <listitem><para><emphasis remap='I'>&lt;standard_session_servicedirs/&gt;</emphasis></para></listitem>
581
582
583 </itemizedlist>
584
585 <para>
586 &lt;standard_session_servicedirs/&gt; requests a standard set of
587 session service directories. Its effect is similar to specifying a series
588 of &lt;servicedir/&gt; elements for each of the data directories,
589 in the order given here.
590 It is not exactly equivalent, because there is currently no way
591 to disable directory monitoring or enforce strict service file naming
592 for a &lt;servicedir/&gt;.
593 </para>
594
595 <para>
596 As with &lt;servicedir/&gt; elements, if a particular service is found
597 in more than one service directory, the first directory takes precedence.
598 If two service files providing the same well-known bus name are found
599 in the same directory, it is arbitrary which one will be chosen
600 (this can only happen if at least one of the service files does not
601 have the recommended name, which is its well-known bus name followed
602 by ".service").
603 </para>
604
605 <para>
606 On Unix, the standard session service directories are:
607 <itemizedlist>
608 <listitem>
609 <para>
610 <emphasis>$XDG_RUNTIME_DIR</emphasis>/dbus-1/services,
611 if XDG_RUNTIME_DIR is set (see the XDG Base Directory
612 Specification for details of XDG_RUNTIME_DIR):
613 this location is suitable for transient services created at runtime
614 by systemd generators (see
615 <citerefentry>
616 <refentrytitle>systemd.generator</refentrytitle>
617 <manvolnum>7</manvolnum>
618 </citerefentry>),
619 session managers or other session infrastructure.
620 It is an extension provided by the reference implementation
621 of dbus-daemon, and is not standardized in the D-Bus Specification.
622 </para>
623 <para>
624 Unlike the other standard session service directories, this directory
625 enforces strict naming for the service files: the filename must be
626 exactly the well-known bus name of the service, followed by
627 ".service".
628 </para>
629 <para>
630 Also unlike the other standard session service directories, this
631 directory is never monitored with
632 <citerefentry>
633 <refentrytitle>inotify</refentrytitle>
634 <manvolnum>7</manvolnum>
635 </citerefentry>
636 or similar APIs. Programs that create service files in this directory
637 while a dbus-daemon is running are expected to call the dbus-daemon's
638 ReloadConfig() method after they have made changes.
639 </para>
640 </listitem>
641 <listitem>
642 <para>
643 <emphasis>$XDG_DATA_HOME</emphasis>/dbus-1/services,
644 where XDG_DATA_HOME defaults to ~/.local/share
645 (see the XDG Base Directory Specification): this location is
646 specified by the D-Bus Specification, and is suitable for per-user,
647 locally-installed software.
648 </para>
649 </listitem>
650 <listitem>
651 <para>
652 <emphasis>directory</emphasis>/dbus-1/services for each
653 directory in XDG_DATA_DIRS, where XDG_DATA_DIRS defaults to
654 /usr/local/share:/usr/share
655 (see the XDG Base Directory Specification): these locations are
656 specified by the D-Bus Specification. The defaults are suitable
657 for software installed locally by a system administrator
658 (/usr/local/share) or for software installed from operating system
659 packages (/usr/share). Per-user or system-wide configuration that
660 sets the XDG_DATA_DIRS environment variable can extend this search
661 path to cover installations in other locations, for example
662 ~/.local/share/flatpak/exports/share/ and
663 /var/lib/flatpak/exports/share/ when
664 <citerefentry>
665 <refentrytitle>flatpak</refentrytitle>
666 <manvolnum>1</manvolnum>
667 </citerefentry>
668 is used.
669 </para>
670 </listitem>
671 <listitem>
672 <para>
673 <emphasis>${datadir}</emphasis>/dbus-1/services
674 for the <emphasis>${datadir}</emphasis> that was specified when
675 dbus was compiled, typically /usr/share: this location is an
676 extension provided by the reference dbus-daemon implementation,
677 and is suitable for software stacks installed alongside dbus-daemon.
678 </para>
679 </listitem>
680 </itemizedlist>
681 </para>
682
683 <para>The "XDG Base Directory Specification" can be found at
684 <ulink url='http://freedesktop.org/wiki/Standards/basedir-spec'>http://freedesktop.org/wiki/Standards/basedir-spec</ulink> if it hasn't moved,
685 otherwise try your favorite search engine.</para>
686
687 <para>
688 On Windows, the standard session service directories are:
689 <itemizedlist>
690 <listitem>
691 <para>
692 <emphasis>%CommonProgramFiles%</emphasis>/dbus-1/services
693 if %CommonProgramFiles% is set: this location is suitable for
694 system-wide installed software packages
695 </para>
696 </listitem>
697 <listitem>
698 <para>
699 A share/dbus-1/services directory found in the same
700 directory hierarchy (prefix) as the dbus-daemon: this location
701 is suitable for software stacks installed alongside dbus-daemon
702 </para>
703 </listitem>
704 </itemizedlist>
705 </para>
706
707
708 <para>The &lt;standard_session_servicedirs/&gt; option is only relevant to the
709 per-user-session bus daemon defined in
710 @EXPANDED_SYSCONFDIR@/dbus-1/session.conf. Putting it in any other
711 configuration file would probably be nonsense.</para>
712
713 <itemizedlist remap='TP'>
714
715 <listitem><para><emphasis remap='I'>&lt;standard_system_servicedirs/&gt;</emphasis></para></listitem>
716
717
718 </itemizedlist>
719
720 <para>&lt;standard_system_servicedirs/&gt; specifies the standard system-wide
721 activation directories that should be searched for service files.
722 As with session services, the first directory listed has highest
723 precedence.</para>
724
725 <para>
726 On Unix, the standard system service directories are:
727 <itemizedlist>
728 <listitem>
729 <para>
730 /etc/dbus-1/system-services: this location is specified
731 by the D-Bus Specification, and is suitable for software
732 installed locally by the system administrator,
733 or by an asset manager deploying services that are
734 not part of the OS (perhaps while /usr/ is read-only)
735 </para>
736 </listitem>
737 <listitem>
738 <para>
739 /run/dbus-1/system-services: this location is specified
740 by the D-Bus Specification, and is suitable for ephemeral
741 services that will disappear after a reboot
742 </para>
743 </listitem>
744 <listitem>
745 <para>
746 /usr/local/share/dbus-1/system-services: this location is
747 specified by the D-Bus Specification, and is suitable for
748 software installed locally by the system administrator
749 </para>
750 </listitem>
751 <listitem>
752 <para>
753 /usr/share/dbus-1/system-services: this location is
754 specified by the D-Bus Specification, and is suitable for
755 software installed by operating system packages
756 </para>
757 </listitem>
758 <listitem>
759 <para>
760 <emphasis>${datadir}</emphasis>/dbus-1/system-services
761 for the <emphasis>${datadir}</emphasis> that was specified when
762 dbus was compiled, typically /usr/share: this location is an
763 extension provided by the reference dbus-daemon implementation,
764 and is suitable for software stacks installed alongside dbus-daemon
765 </para>
766 </listitem>
767 <listitem>
768 <para>
769 /lib/dbus-1/system-services: this location is
770 specified by the D-Bus Specification, and was intended for
771 software installed by operating system packages and used during
772 early boot (but it should be considered deprecated, because
773 the reference dbus-daemon is not designed to be available during
774 early boot)
775 </para>
776 </listitem>
777 </itemizedlist>
778 </para>
779
780 <para>
781 On Windows, there is no standard system bus, so there are no standard
782 system bus directories either.
783 </para>
784
785 <para>The &lt;standard_system_servicedirs/&gt; option is only relevant to the
786 per-system bus daemon defined in
787 @EXPANDED_DATADIR@/dbus-1/system.conf. Putting it in any other
788 configuration file would probably be nonsense.</para>
789
790 <itemizedlist remap='TP'>
791
792 <listitem><para><emphasis remap='I'>&lt;servicehelper/&gt;</emphasis></para></listitem>
793
794
795 </itemizedlist>
796
797 <para>&lt;servicehelper/&gt; specifies the setuid helper that is used to launch
798 system daemons with an alternate user. Typically this should be
799 the dbus-daemon-launch-helper executable in located in libexec.</para>
800
801
802 <para>The &lt;servicehelper/&gt; option is only relevant to the per-system bus daemon
803 defined in @EXPANDED_DATADIR@/dbus-1/system.conf. Putting it in any other
804 configuration file would probably be nonsense.</para>
805
806 <itemizedlist remap='TP'>
807
808 <listitem><para><emphasis remap='I'>&lt;limit&gt;</emphasis></para></listitem>
809
810
811 </itemizedlist>
812
813 <para>&lt;limit&gt; establishes a resource limit. For example:</para>
814 <literallayout remap='.nf'>
815 &lt;limit name="max_message_size"&gt;64&lt;/limit&gt;
816 &lt;limit name="max_completed_connections"&gt;512&lt;/limit&gt;
817 </literallayout> <!-- .fi -->
818
819
820 <para>The name attribute is mandatory.
821 Available limit names are:</para>
822 <literallayout remap='.nf'>
823 "max_incoming_bytes" : total size in bytes of messages
824 incoming from a single connection
825 "max_incoming_unix_fds" : total number of unix fds of messages
826 incoming from a single connection
827 "max_outgoing_bytes" : total size in bytes of messages
828 queued up for a single connection
829 "max_outgoing_unix_fds" : total number of unix fds of messages
830 queued up for a single connection
831 "max_message_size" : max size of a single message in
832 bytes
833 "max_message_unix_fds" : max unix fds of a single message
834 "service_start_timeout" : milliseconds (thousandths) until
835 a started service has to connect
836 "auth_timeout" : milliseconds (thousandths) a
837 connection is given to
838 authenticate
839 "pending_fd_timeout" : milliseconds (thousandths) a
840 fd is given to be transmitted to
841 dbus-daemon before disconnecting the
842 connection
843 "max_completed_connections" : max number of authenticated connections
844 "max_incomplete_connections" : max number of unauthenticated
845 connections
846 "max_connections_per_user" : max number of completed connections from
847 the same user (only enforced on Unix OSs)
848 "max_pending_service_starts" : max number of service launches in
849 progress at the same time
850 "max_names_per_connection" : max number of names a single
851 connection can own
852 "max_match_rules_per_connection": max number of match rules for a single
853 connection
854 "max_replies_per_connection" : max number of pending method
855 replies per connection
856 (number of calls-in-progress)
857 "reply_timeout" : milliseconds (thousandths)
858 until a method call times out
859 </literallayout> <!-- .fi -->
860
861
862 <para>The max incoming/outgoing queue sizes allow a new message to be queued
863 if one byte remains below the max. So you can in fact exceed the max
864 by max_message_size.</para>
865
866
867 <para>max_completed_connections divided by max_connections_per_user is the
868 number of users that can work together to denial-of-service all other users by using
869 up all connections on the systemwide bus.</para>
870
871
872 <para>Limits are normally only of interest on the systemwide bus, not the user session
873 buses.</para>
874
875 <itemizedlist remap='TP'>
876
877 <listitem><para><emphasis remap='I'>&lt;policy&gt;</emphasis></para></listitem>
878
879
880 </itemizedlist>
881
882 <para>The &lt;policy&gt; element defines a security policy to be applied to a particular
883 set of connections to the bus. A policy is made up of
884 &lt;allow&gt; and &lt;deny&gt; elements. Policies are normally used with the systemwide bus;
885 they are analogous to a firewall in that they allow expected traffic
886 and prevent unexpected traffic.</para>
887
888
889 <para>
890 Currently, the system bus has a default-deny policy for sending method calls
891 and owning bus names, and a default-allow policy for receiving messages,
892 sending signals, and sending a single success or error reply for each
893 method call that does not have the <literal>NO_REPLY</literal> flag.
894 Sending more than the expected number of replies is not allowed.
895 </para>
896
897
898 <para>In general, it is best to keep system services as small, targeted programs which
899 run in their own process and provide a single bus name. Then, all that is needed
900 is an &lt;allow&gt; rule for the "own" permission to let the process claim the bus
901 name, and a "send_destination" rule to allow traffic from some or all uids to
902 your service.</para>
903
904
905 <para>The &lt;policy&gt; element has one of four attributes:</para>
906 <literallayout remap='.nf'>
907 context="(default|mandatory)"
908 at_console="(true|false)"
909 user="username or userid"
910 group="group name or gid"
911 </literallayout> <!-- .fi -->
912
913
914 <para>Policies are applied to a connection as follows:</para>
915 <literallayout remap='.nf'>
916 - all context="default" policies are applied
917 - all group="connection's user's group" policies are applied
918 in undefined order
919 - all user="connection's auth user" policies are applied
920 in undefined order
921 - all at_console="true" policies are applied
922 - all at_console="false" policies are applied
923 - all context="mandatory" policies are applied
924 </literallayout> <!-- .fi -->
925
926
927 <para>Policies applied later will override those applied earlier,
928 when the policies overlap. Multiple policies with the same
929 user/group/context are applied in the order they appear
930 in the config file.</para>
931
932 <variablelist remap='TP'>
933 <varlistentry>
934 <term><emphasis remap='I'>&lt;deny&gt;</emphasis></term>
935 <listitem>
936 <para><emphasis remap='I'>&lt;allow&gt;</emphasis></para>
937
938 </listitem>
939 </varlistentry>
940 </variablelist>
941
942 <para>A &lt;deny&gt; element appears below a &lt;policy&gt; element and prohibits some
943 action. The &lt;allow&gt; element makes an exception to previous &lt;deny&gt;
944 statements, and works just like &lt;deny&gt; but with the inverse meaning.</para>
945
946
947 <para>The possible attributes of these elements are:</para>
948 <literallayout remap='.nf'>
949 send_interface="interface_name" | "*"
950 send_member="method_or_signal_name" | "*"
951 send_error="error_name" | "*"
952 send_broadcast="true" | "false"
953 send_destination="name" | "*"
954 send_destination_prefix="name"
955 send_type="method_call" | "method_return" | "signal" | "error" | "*"
956 send_path="/path/name" | "*"
957
958 receive_interface="interface_name" | "*"
959 receive_member="method_or_signal_name" | "*"
960 receive_error="error_name" | "*"
961 receive_sender="name" | "*"
962 receive_type="method_call" | "method_return" | "signal" | "error" | "*"
963 receive_path="/path/name" | "*"
964
965 send_requested_reply="true" | "false"
966 receive_requested_reply="true" | "false"
967
968 eavesdrop="true" | "false"
969
970 own="name" | "*"
971 own_prefix="name"
972 user="username" | "*"
973 group="groupname" | "*"
974 </literallayout> <!-- .fi -->
975
976
977 <para>Examples:</para>
978 <literallayout remap='.nf'>
979 &lt;deny send_destination="org.freedesktop.Service" send_interface="org.freedesktop.System" send_member="Reboot"/&gt;
980 &lt;deny send_destination="org.freedesktop.System"/&gt;
981 &lt;deny receive_sender="org.freedesktop.System"/&gt;
982 &lt;deny user="john"/&gt;
983 &lt;deny group="enemies"/&gt;
984 </literallayout> <!-- .fi -->
985
986
987 <para>The &lt;deny&gt; element's attributes determine whether the deny "matches" a
988 particular action. If it matches, the action is denied (unless later
989 rules in the config file allow it).</para>
990
991 <para>
992 Rules with one or more of the <literal>send_</literal>* family of attributes
993 are checked in order when a connection attempts to send a message. The last
994 rule that matches the message determines whether it may be sent.
995 The well-known session bus normally allows sending any message.
996 The well-known system bus normally allows sending any signal, selected
997 method calls to the <command>dbus-daemon</command>, and exactly one
998 reply to each previously-sent method call (either success or an error).
999 Either of these can be overridden by configuration; on the system bus,
1000 services that will receive method calls must install configuration that
1001 allows them to do so, usually via rules of the form
1002 <literal>&lt;policy context="default"&gt;&lt;allow send_destination="&hellip;"/&gt;&lt;policy&gt;</literal>.
1003 </para>
1004
1005 <para>
1006 Rules with one or more of the <literal>receive_</literal>* family of
1007 attributes, or with the <literal>eavesdrop</literal> attribute and no others,
1008 are checked for each recipient of a message (there might be more than one
1009 recipient if the message is a broadcast or a connection is eavesdropping).
1010 The last rule that matches the message determines whether it may be received.
1011 The well-known session bus normally allows receiving any message, including
1012 eavesdropping. The well-known system bus normally allows receiving any
1013 message that was not eavesdropped (any unicast message addressed to the
1014 recipient, and any broadcast message).
1015 </para>
1016
1017 <para>
1018 The <literal>eavesdrop</literal>, <literal>min_fds</literal> and
1019 <literal>max_fds</literal> attributes are modifiers that can be applied
1020 to either <literal>send_</literal>* or <literal>receive_</literal>*
1021 rules, and are documented below.
1022 </para>
1023
1024 <para>send_destination and receive_sender rules mean that messages may not be
1025 sent to or received from the *owner* of the given name, not that
1026 they may not be sent *to that name*. That is, if a connection
1027 owns services A, B, C, and sending to A is denied, sending to B or C
1028 will not work either. As a special case,
1029 <literal>send_destination="*"</literal> matches any message
1030 (whether it has a destination specified or not), and
1031 <literal>receive_sender="*"</literal> similarly matches any message.</para>
1032
1033 <para>
1034 A <literal>send_destination_prefix</literal> rule opens or closes
1035 the whole namespace for sending. It means that messages may or may not
1036 be sent to the <emphasis>owner</emphasis> of any name matching the prefix, regardless of whether
1037 it is the primary or the queued owner.
1038 In other words, for <literal>&lt;allow send_destination_prefix="a.b"/&gt;</literal>
1039 rule and names "a.b", "a.b.c", and "a.b.c.d" present on the bus, it works the same as
1040 if three separate rules: <literal>&lt;allow send_destination="a.b"/&gt;</literal>,
1041 <literal>&lt;allow send_destination="a.b.c"/&gt;</literal>, and
1042 <literal>&lt;allow send_destination="a.b.c.d"/&gt;</literal> had been defined.
1043 The rules for matching names are the same as in <literal>own_prefix</literal>
1044 (see below): a prefix of "a.b" matches names "a.b" or "a.b.c" or "a.b.c.d", but not "a.bc"
1045 or "a.c". The <literal>send_destination_prefix</literal> attribute cannot be combined
1046 with the <literal>send_destination</literal> attribute in the same rule.
1047 </para>
1048
1049 <para>
1050 Rules with <literal>send_broadcast="true"</literal> match signal messages
1051 with no destination (broadcasts). Rules with
1052 <literal>send_broadcast="false"</literal> are the inverse: they match any
1053 unicast destination (unicast signals, together with all method calls, replies
1054 and errors) but do not match messages with no destination (broadcasts). This
1055 is not the same as <literal>send_destination="*"</literal>, which matches any
1056 sent message, regardless of whether it has a destination or not.
1057 </para>
1058
1059 <para>
1060 The other <literal>send_</literal>* and <literal>receive_</literal>*
1061 attributes are purely textual/by-value matches against the given field in
1062 the message header, except that for the attributes where it is allowed,
1063 <literal>*</literal> matches any message (whether it has the relevant
1064 header field or not). For example, <literal>send_interface="*"</literal>
1065 matches any sent message, even if it does not contain an interface header
1066 field. More complex glob matching such as <literal>foo.bar.*</literal> is
1067 not allowed.
1068 </para>
1069
1070 <para>"Eavesdropping" occurs when an application receives a message that
1071 was explicitly addressed to a name the application does not own, or
1072 is a reply to such a message. Eavesdropping thus only applies to
1073 messages that are addressed to services and replies to such messages
1074 (i.e. it does not apply to signals).</para>
1075
1076 <para>For &lt;allow&gt;, eavesdrop="true" indicates that the rule matches even
1077 when eavesdropping. eavesdrop="false" is the default and means that
1078 the rule only allows messages to go to their specified recipient.
1079 For &lt;deny&gt;, eavesdrop="true" indicates that the rule matches
1080 only when eavesdropping. eavesdrop="false" is the default for &lt;deny&gt;
1081 also, but here it means that the rule applies always, even when
1082 not eavesdropping. The eavesdrop attribute can only be combined with
1083 send and receive rules (with send_* and receive_* attributes).</para>
1084
1085 <para>The [send|receive]_requested_reply attribute works similarly to the eavesdrop
1086 attribute. It controls whether the &lt;deny&gt; or &lt;allow&gt; matches a reply
1087 that is expected (corresponds to a previous method call message).
1088 This attribute only makes sense for reply messages (errors and method
1089 returns), and is ignored for other message types.</para>
1090
1091
1092 <para>For &lt;allow&gt;, [send|receive]_requested_reply="true" is the default and indicates that
1093 only requested replies are allowed by the
1094 rule. [send|receive]_requested_reply="false" means that the rule allows any reply
1095 even if unexpected.</para>
1096
1097
1098 <para>For &lt;deny&gt;, [send|receive]_requested_reply="false" is the default but indicates that
1099 the rule matches only when the reply was not
1100 requested. [send|receive]_requested_reply="true" indicates that the rule applies
1101 always, regardless of pending reply state.</para>
1102
1103 <para>
1104 The <literal>min_fds</literal> and <literal>max_fds</literal> attributes
1105 modify either <literal>send_</literal>* or <literal>receive_</literal>*
1106 rules. A rule with the <literal>min_fds</literal> attribute only matches
1107 messages if they have at least that many Unix file descriptors attached.
1108 Conversely, a rule with the <literal>max_fds</literal> attribute only
1109 matches messages if they have no more than that many file descriptors
1110 attached. In practice, rules with these attributes will most commonly
1111 take the form
1112 <literal>&lt;allow send_destination="&hellip;" max_fds="0"/&gt;</literal>,
1113 <literal>&lt;deny send_destination="&hellip;" min_fds="1"/&gt;</literal> or
1114 <literal>&lt;deny receive_sender="*" min_fds="1"/&gt;</literal>.
1115 </para>
1116
1117 <para>
1118 Rules with the <literal>user</literal> or <literal>group</literal>
1119 attribute are checked when a new connection to the message bus is
1120 established, and control whether the connection can continue.
1121 Each of these attributes cannot be combined with any other
1122 attribute. As a special case, both <literal>user="*"</literal> and
1123 <literal>group="*"</literal> match any connection. If there are
1124 no rules of this form, the default is to allow connections from the same
1125 user ID that owns the <command>dbus-daemon</command> process. The well-known
1126 session bus normally uses that default behaviour, while the well-known
1127 system bus normally allows any connection.
1128 </para>
1129
1130 <para>
1131 Rules with the <literal>own</literal> or <literal>own_prefix</literal>
1132 attribute are checked when a connection attempts to own a well-known bus
1133 names. As a special case, <literal>own="*"</literal> matches any well-known
1134 bus name. The well-known session bus normally allows any connection to
1135 own any name, while the well-known system bus normally does not allow any
1136 connection to own any name, except where allowed by further configuration.
1137 System services that will own a name must install configuration that allows
1138 them to do so, usually via rules of the form
1139 <literal>&lt;policy user="some-system-user"&gt;&lt;allow own="&hellip;"/&gt;&lt;/policy&gt;</literal>.
1140 </para>
1141
1142 <para>&lt;allow own_prefix="a.b"/&gt; allows you to own the name "a.b" or any
1143 name whose first dot-separated elements are "a.b": in particular,
1144 you can own "a.b.c" or "a.b.c.d", but not "a.bc" or "a.c".
1145 This is useful when services like Telepathy and ReserveDevice
1146 define a meaning for subtrees of well-known names, such as
1147 org.freedesktop.Telepathy.ConnectionManager.(anything)
1148 and org.freedesktop.ReserveDevice1.(anything).</para>
1149
1150
1151 <para>It does not make sense to deny a user or group inside a &lt;policy&gt;
1152 for a user or group; user/group denials can only be inside
1153 context="default" or context="mandatory" policies.</para>
1154
1155
1156 <para>A single &lt;deny&gt; rule may specify combinations of attributes such as
1157 send_destination and send_interface and send_type. In this case, the
1158 denial applies only if both attributes match the message being denied.
1159 e.g. &lt;deny send_interface="foo.bar" send_destination="foo.blah"/&gt; would
1160 deny messages with the given interface AND the given bus name.
1161 To get an OR effect you specify multiple &lt;deny&gt; rules.</para>
1162
1163
1164 <para>You can't include both send_ and receive_ attributes on the same
1165 rule, since "whether the message can be sent" and "whether it can be
1166 received" are evaluated separately.</para>
1167
1168
1169 <para>Be careful with send_interface/receive_interface, because the
1170 interface field in messages is optional. In particular, do NOT
1171 specify &lt;deny send_interface="org.foo.Bar"/&gt;! This will cause
1172 no-interface messages to be blocked for all services, which is
1173 almost certainly not what you intended. Always use rules of
1174 the form: &lt;deny send_interface="org.foo.Bar" send_destination="org.foo.Service"/&gt;</para>
1175
1176 <itemizedlist remap='TP'>
1177
1178 <listitem><para><emphasis remap='I'>&lt;selinux&gt;</emphasis></para></listitem>
1179
1180
1181 </itemizedlist>
1182
1183 <para>The &lt;selinux&gt; element contains settings related to Security Enhanced Linux.
1184 More details below.</para>
1185
1186 <itemizedlist remap='TP'>
1187
1188 <listitem><para><emphasis remap='I'>&lt;associate&gt;</emphasis></para></listitem>
1189
1190
1191 </itemizedlist>
1192
1193 <para>An &lt;associate&gt; element appears below an &lt;selinux&gt; element and
1194 creates a mapping. Right now only one kind of association is possible:</para>
1195 <literallayout remap='.nf'>
1196 &lt;associate own="org.freedesktop.Foobar" context="foo_t"/&gt;
1197 </literallayout> <!-- .fi -->
1198
1199
1200 <para>This means that if a connection asks to own the name
1201 "org.freedesktop.Foobar" then the source context will be the context
1202 of the connection and the target context will be "foo_t" - see the
1203 short discussion of SELinux below.</para>
1204
1205
1206 <para>Note, the context here is the target context when requesting a name,
1207 NOT the context of the connection owning the name.</para>
1208
1209
1210 <para>There's currently no way to set a default for owning any name, if
1211 we add this syntax it will look like:</para>
1212 <literallayout remap='.nf'>
1213 &lt;associate own="*" context="foo_t"/&gt;
1214 </literallayout> <!-- .fi -->
1215 <para>If you find a reason this is useful, let the developers know.
1216 Right now the default will be the security context of the bus itself.</para>
1217
1218
1219 <para>If two &lt;associate&gt; elements specify the same name, the element
1220 appearing later in the configuration file will be used.</para>
1221
1222 <itemizedlist remap='TP'>
1223
1224 <listitem><para><emphasis remap='I'>&lt;apparmor&gt;</emphasis></para></listitem>
1225
1226
1227 </itemizedlist>
1228
1229 <para>The &lt;apparmor&gt; element is used to configure AppArmor mediation on
1230 the bus. It can contain one attribute that specifies the mediation mode:</para>
1231
1232 <literallayout remap='.nf'>
1233 &lt;apparmor mode="(enabled|disabled|required)"/&gt;
1234 </literallayout> <!-- .fi -->
1235
1236 <para>The default mode is "enabled". In "enabled" mode, AppArmor mediation
1237 will be performed if AppArmor support is available in the kernel. If it is not
1238 available, dbus-daemon will start but AppArmor mediation will not occur. In
1239 "disabled" mode, AppArmor mediation is disabled. In "required" mode, AppArmor
1240 mediation will be enabled if AppArmor support is available, otherwise
1241 dbus-daemon will refuse to start.</para>
1242
1243 <para>The AppArmor mediation mode of the bus cannot be changed after the bus
1244 starts. Modifying the mode in the configuration file and sending a SIGHUP
1245 signal to the daemon has no effect on the mediation mode.</para>
1246
1247 </refsect1>
1248
1249 <refsect1 id='session_services'>
1250 <title>INTEGRATING SESSION SERVICES</title>
1251
1252 <para>
1253 Integration files are not mandatory for session services: any program
1254 with access to the session bus can request a well-known name and
1255 provide D-Bus interfaces.
1256 </para>
1257
1258 <para>
1259 Many D-Bus session services support <firstterm>service
1260 activation</firstterm>, a mechanism in which the
1261 <command>dbus-daemon</command> can launch the service on-demand,
1262 either by running the session service itself or by communicating
1263 with <command>systemd --user</command>. This is set up by
1264 creating a <firstterm>service file</firstterm> in the directory
1265 <filename><replaceable>${datadir}</replaceable>/dbus-1/services</filename>,
1266 for example:
1267
1268 <programlisting>
1269 [D-BUS Service]
1270 Name=<replaceable>com.example.SessionService1</replaceable>
1271 Exec=<replaceable>/usr/bin/example-session-service</replaceable>
1272 # Optional
1273 SystemdService=<replaceable>example-session-service</replaceable>
1274 </programlisting>
1275
1276 See the
1277 <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
1278 Specification</ulink> for details of the contents and interpretation
1279 of service files.</para>
1280
1281 <para>If there is a service file for
1282 <replaceable>com.example.SessionService1</replaceable>, it should be named
1283 <filename><replaceable>com.example.SessionService1</replaceable>.service</filename>,
1284 although for compatibility with legacy services this is not mandatory.
1285 </para>
1286
1287 <para>Session services that declare the optional
1288 <literal>SystemdService</literal> must also provide a systemd user
1289 service unit file whose name or <literal>Alias</literal> matches the
1290 <literal>SystemdService</literal> (see
1291 <citerefentry>
1292 <refentrytitle>systemd.unit</refentrytitle>
1293 <manvolnum>5</manvolnum>
1294 </citerefentry>,
1295 <citerefentry>
1296 <refentrytitle>systemd.service</refentrytitle>
1297 <manvolnum>5</manvolnum>
1298 </citerefentry> for further details on systemd service units), for
1299 example:
1300
1301 <programlisting>
1302 [Unit]
1303 Description=Example session service
1304
1305 [Service]
1306 Type=dbus
1307 BusName=<replaceable>com.example.SessionService1</replaceable>
1308 ExecStart=<replaceable>/usr/bin/example-session-service</replaceable>
1309 </programlisting>
1310 </para>
1311 </refsect1>
1312
1313 <refsect1 id='system_services'>
1314 <title>INTEGRATING SYSTEM SERVICES</title>
1315
1316 <para>
1317 The standard system bus does not allow method calls or owning well-known
1318 bus names by default, so a useful D-Bus system service will normally
1319 need to configure a default security policy that allows it to work.
1320 D-Bus system services should install a default policy file in
1321 <filename><replaceable>${datadir}</replaceable>/dbus-1/service.d</filename>,
1322 containing the policy rules necessary to make that system service
1323 functional. A best-practice policy file will often look like this:
1324
1325 <programlisting>
1326 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
1327 &lt;!DOCTYPE busconfig PUBLIC
1328 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
1329 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
1330 &lt;busconfig&gt;
1331 &lt;policy user="<replaceable>_example</replaceable>"&gt;
1332 &lt;allow own="<replaceable>com.example.Example1</replaceable>"/&gt;
1333 &lt;/policy&gt;
1334
1335 &lt;policy context="default"&gt;
1336 &lt;allow send_destination="<replaceable>com.example.Example1</replaceable>"/&gt;
1337 &lt;/policy&gt;
1338 &lt;/busconfig&gt;
1339 </programlisting>
1340
1341 where <replaceable>_example</replaceable> is the username of the
1342 system uid that will run the system service daemon process, and
1343 <replaceable>com.example.Example1</replaceable> is its well-known
1344 bus name.</para>
1345
1346 <para>The policy file for <replaceable>com.example.Example1</replaceable>
1347 should normally be named
1348 <filename><replaceable>com.example.Example1</replaceable>.conf</filename>.
1349 </para>
1350
1351 <para>Some existing system services rely on more complex &lt;policy&gt;
1352 rules to control the messages that the service can receive. However,
1353 the <command>dbus-daemon</command>'s policy language is not well-suited
1354 to finer-grained policies: any policy has to be expressed in terms of
1355 D-Bus interfaces and method names, not in terms of higher-level
1356 domain-specific concepts like removable or built-in devices. It is
1357 recommended that new services should normally accept method call messages
1358 from all callers, then apply a sysadmin-controllable policy to decide
1359 whether to obey the requests contained in those method call messages,
1360 for example by consulting
1361 <ulink url="https://www.freedesktop.org/wiki/Software/polkit/">polkit</ulink>.
1362 </para>
1363
1364 <para>
1365 Like session services, many D-Bus system services support service
1366 activation, a mechanism in which the <command>dbus-daemon</command>
1367 can launch the service on-demand, either by running the system service
1368 itself or by communicating with <command>systemd</command>. This is set
1369 up by creating a service file in the directory
1370 <filename><replaceable>${datadir}</replaceable>/dbus-1/system-services</filename>,
1371 for example:
1372
1373 <programlisting>
1374 [D-BUS Service]
1375 Name=<replaceable>com.example.Example1</replaceable>
1376 Exec=<replaceable>/usr/sbin/example-service</replaceable>
1377 User=<replaceable>_example</replaceable>
1378 # Optional
1379 SystemdService=<replaceable>dbus-com.example.Example1.service</replaceable>
1380 </programlisting>
1381
1382 See the
1383 <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
1384 Specification</ulink> for details of the contents and interpretation
1385 of service files.</para>
1386
1387 <para>If there is a service file for
1388 <replaceable>com.example.Example1</replaceable>, it must be named
1389 <filename><replaceable>com.example.Example1</replaceable>.service</filename>.
1390 </para>
1391
1392 <para>System services that declare the optional
1393 <literal>SystemdService</literal> must also provide a systemd
1394 service unit file whose name or <literal>Alias</literal> matches the
1395 <literal>SystemdService</literal> (see
1396 <citerefentry>
1397 <refentrytitle>systemd.unit</refentrytitle>
1398 <manvolnum>5</manvolnum>
1399 </citerefentry>,
1400 <citerefentry>
1401 <refentrytitle>systemd.service</refentrytitle>
1402 <manvolnum>5</manvolnum>
1403 </citerefentry> for further details on systemd service units), for
1404 example:
1405
1406 <programlisting>
1407 [Unit]
1408 Description=Example service
1409
1410 [Service]
1411 Type=dbus
1412 BusName=<replaceable>com.example.Example1</replaceable>
1413 ExecStart=<replaceable>/usr/sbin/example-service</replaceable>
1414
1415 [Install]
1416 WantedBy=multi-user.target
1417 Alias=dbus-<replaceable>com.example.Example1</replaceable>.service
1418 </programlisting>
1419 </para>
1420 </refsect1>
1421
1422 <refsect1 id='selinux'><title>SELinux</title>
1423 <para>See <ulink url='http://www.nsa.gov/selinux/'>http://www.nsa.gov/selinux/</ulink> for full details on SELinux. Some useful excerpts:</para>
1424
1425
1426 <para>Every subject (process) and object (e.g. file, socket, IPC object,
1427 etc) in the system is assigned a collection of security attributes,
1428 known as a security context. A security context contains all of the
1429 security attributes associated with a particular subject or object
1430 that are relevant to the security policy.</para>
1431
1432
1433 <para>In order to better encapsulate security contexts and to provide
1434 greater efficiency, the policy enforcement code of SELinux typically
1435 handles security identifiers (SIDs) rather than security contexts. A
1436 SID is an integer that is mapped by the security server to a security
1437 context at runtime.</para>
1438
1439
1440 <para>When a security decision is required, the policy enforcement code
1441 passes a pair of SIDs (typically the SID of a subject and the SID of
1442 an object, but sometimes a pair of subject SIDs or a pair of object
1443 SIDs), and an object security class to the security server. The object
1444 security class indicates the kind of object, e.g. a process, a regular
1445 file, a directory, a TCP socket, etc.</para>
1446
1447
1448 <para>Access decisions specify whether or not a permission is granted for a
1449 given pair of SIDs and class. Each object class has a set of
1450 associated permissions defined to control operations on objects with
1451 that class.</para>
1452
1453
1454 <para>D-Bus performs SELinux security checks in two places.</para>
1455
1456
1457 <para>First, any time a message is routed from one connection to another
1458 connection, the bus daemon will check permissions with the security context of
1459 the first connection as source, security context of the second connection
1460 as target, object class "dbus" and requested permission "send_msg".</para>
1461
1462
1463 <para>If a security context is not available for a connection
1464 (impossible when using UNIX domain sockets), then the target
1465 context used is the context of the bus daemon itself.
1466 There is currently no way to change this default, because we're
1467 assuming that only UNIX domain sockets will be used to
1468 connect to the systemwide bus. If this changes, we'll
1469 probably add a way to set the default connection context.</para>
1470
1471
1472 <para>Second, any time a connection asks to own a name,
1473 the bus daemon will check permissions with the security
1474 context of the connection as source, the security context specified
1475 for the name in the config file as target, object
1476 class "dbus" and requested permission "acquire_svc".</para>
1477
1478
1479 <para>The security context for a bus name is specified with the
1480 &lt;associate&gt; element described earlier in this document.
1481 If a name has no security context associated in the
1482 configuration file, the security context of the bus daemon
1483 itself will be used.</para>
1484
1485 </refsect1>
1486
1487 <refsect1 id='apparmor'><title>AppArmor</title>
1488 <para>The AppArmor confinement context is stored when applications connect to
1489 the bus. The confinement context consists of a label and a confinement mode.
1490 When a security decision is required, the daemon uses the confinement context
1491 to query the AppArmor policy to determine if the action should be allowed or
1492 denied and if the action should be audited.</para>
1493
1494 <para>The daemon performs AppArmor security checks in three places.</para>
1495
1496 <para>First, any time a message is routed from one connection to another
1497 connection, the bus daemon will check permissions with the label of the first
1498 connection as source, label and/or connection name of the second connection as
1499 target, along with the bus name, the path name, the interface name, and the
1500 member name. Reply messages, such as method_return and error messages, are
1501 implicitly allowed if they are in response to a message that has already been
1502 allowed.</para>
1503
1504 <para>Second, any time a connection asks to own a name, the bus daemon will
1505 check permissions with the label of the connection as source, the requested
1506 name as target, along with the bus name.</para>
1507
1508 <para>Third, any time a connection attempts to eavesdrop, the bus daemon will
1509 check permissions with the label of the connection as the source, along with
1510 the bus name.</para>
1511
1512 <para>AppArmor rules for bus mediation are not stored in the bus configuration
1513 files. They are stored in the application's AppArmor profile. Please see
1514 <emphasis remap='I'>apparmor.d(5)</emphasis> for more details.</para>
1515
1516 </refsect1>
1517
1518 <refsect1 id='debugging'><title>DEBUGGING</title>
1519 <para>If you're trying to figure out where your messages are going or why
1520 you aren't getting messages, there are several things you can try.</para>
1521
1522 <para>Remember that the system bus is heavily locked down and if you
1523 haven't installed a security policy file to allow your message
1524 through, it won't work. For the session bus, this is not a concern.</para>
1525
1526 <para>The simplest way to figure out what's happening on the bus is to run
1527 the <emphasis remap='I'>dbus-monitor</emphasis> program, which comes with the D-Bus
1528 package. You can also send test messages with <emphasis remap='I'>dbus-send</emphasis>. These
1529 programs have their own man pages.</para>
1530
1531 <para>If you want to know what the daemon itself is doing, you might consider
1532 running a separate copy of the daemon to test against. This will allow you
1533 to put the daemon under a debugger, or run it with verbose output, without
1534 messing up your real session and system daemons.</para>
1535
1536 <para>To run a separate test copy of the daemon, for example you might open a terminal
1537 and type:</para>
1538 <literallayout remap='.nf'>
1539 DBUS_VERBOSE=1 dbus-daemon --session --print-address
1540 </literallayout> <!-- .fi -->
1541
1542 <para>The test daemon address will be printed when the daemon starts. You will need
1543 to copy-and-paste this address and use it as the value of the
1544 DBUS_SESSION_BUS_ADDRESS environment variable when you launch the applications
1545 you want to test. This will cause those applications to connect to your
1546 test bus instead of the DBUS_SESSION_BUS_ADDRESS of your real session bus.</para>
1547
1548 <para>DBUS_VERBOSE=1 will have NO EFFECT unless your copy of D-Bus
1549 was compiled with verbose mode enabled. This is not recommended in
1550 production builds due to performance impact. You may need to rebuild
1551 D-Bus if your copy was not built with debugging in mind. (DBUS_VERBOSE
1552 also affects the D-Bus library and thus applications using D-Bus; it may
1553 be useful to see verbose output on both the client side and from the daemon.)</para>
1554
1555 <para>If you want to get fancy, you can create a custom bus
1556 configuration for your test bus (see the session.conf and system.conf
1557 files that define the two default configurations for example). This
1558 would allow you to specify a different directory for .service files,
1559 for example.</para>
1560
1561 </refsect1>
1562
1563 <refsect1 id='author'><title>AUTHOR</title>
1564 <para>See <ulink url='https://dbus.freedesktop.org/doc/AUTHORS'>https://dbus.freedesktop.org/doc/AUTHORS</ulink></para>
1565
1566 </refsect1>
1567
1568 <refsect1 id='bugs'><title>BUGS</title>
1569 <para>Please send bug reports to the D-Bus mailing list or bug tracker,
1570 see <ulink url='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink></para>
1571 </refsect1>
1572 </refentry>