20
19
application that uses this library to implement a message bus
21
20
daemon. Multiple programs connect to the message bus daemon and can
22
21
exchange messages with one another.
25
There are two standard message bus instances: the systemwide message bus
26
(installed on many systems as the "messagebus" init service) and the
23
There are two standard message bus instances: the systemwide message bus
24
(installed on many systems as the "messagebus" init service) and the
27
25
per-user-login-session message bus (started each time a user logs in).
28
\fIdbus-daemon\fP is used for both of these instances, but with
26
\fIdbus-daemon\fP is used for both of these instances, but with
29
27
a different configuration file.
32
29
The \-\-session option is equivalent to
33
30
"\-\-config-file=@EXPANDED_SYSCONFDIR@/dbus-1/session.conf" and the \-\-system
34
31
option is equivalent to
35
"\-\-config-file=@EXPANDED_SYSCONFDIR@/dbus-1/system.conf". By creating
32
"\-\-config-file=@EXPANDED_SYSCONFDIR@/dbus-1/system.conf". By creating
36
33
additional configuration files and using the \-\-config-file option,
37
34
additional special-purpose message bus daemons could be created.
40
The systemwide daemon is normally launched by an init script,
41
standardly called simply "messagebus".
44
The systemwide daemon is largely used for broadcasting system events,
36
The systemwide daemon is normally launched by an init script,
37
standardly called simply "messagebus".
39
The systemwide daemon is largely used for broadcasting system events,
45
40
such as changes to the printer queue, or adding/removing devices.
48
The per-session daemon is used for various interprocess communication
49
among desktop applications (however, it is not tied to X or the GUI
42
The per-session daemon is used for various interprocess communication
43
among desktop applications (however, it is not tied to X or the GUI
53
46
SIGHUP will cause the D-Bus daemon to PARTIALLY reload its
54
47
configuration file and to flush its user/group information caches. Some
63
56
Use the given configuration file.
66
Force the message bus to fork and become a daemon, even if
59
Force the message bus to fork and become a daemon, even if
67
60
the configuration file does not specify that it should.
68
61
In most contexts the configuration file already gets this
64
Force the message bus not to fork and become a daemon, even if
65
the configuration file specifies that it should.
71
67
.I "--print-address[=DESCRIPTOR]"
72
Print the address of the message bus to standard output, or
73
to the given file descriptor. This is used by programs that
68
Print the address of the message bus to standard output, or
69
to the given file descriptor. This is used by programs that
74
70
launch the message bus.
76
72
.I "--print-pid[=DESCRIPTOR]"
77
Print the process ID of the message bus to standard output, or
78
to the given file descriptor. This is used by programs that
73
Print the process ID of the message bus to standard output, or
74
to the given file descriptor. This is used by programs that
79
75
launch the message bus.
89
85
Print the version of the daemon.
88
Print the introspection information for all D-Bus internal interfaces.
90
.I "--address[=ADDRESS]"
91
Set the address to listen on. This option overrides the address
92
configured in the configuration file.
94
.I "--systemd-activation"
95
Enable systemd-style service activation. Only useful in conjunction
96
with the systemd system and session manager on Linux.
91
98
.SH CONFIGURATION FILE
93
100
A message bus daemon has a configuration file that specializes it
94
for a particular application. For example, one configuration
95
file might set up the message bus to be a systemwide message bus,
101
for a particular application. For example, one configuration
102
file might set up the message bus to be a systemwide message bus,
96
103
while another might set it up to be a per-user-login-session bus.
99
105
The configuration file also establishes resource limits, security
100
106
parameters, and so forth.
103
108
The configuration file is not part of any interoperability
104
109
specification and its backward compatibility is not guaranteed; this
105
110
document is documentation, not specification.
108
112
The standard systemwide and per-session message bus setups are
109
113
configured in the files "@EXPANDED_SYSCONFDIR@/dbus-1/system.conf" and
164
168
Include a file <include>filename.conf</include> at this point. If the
165
169
filename is relative, it is located relative to the configuration file
166
170
doing the including.
169
173
<include> has an optional attribute "ignore_missing=(yes|no)"
170
which defaults to "no" if not provided. This attribute
171
controls whether it's a fatal error for the included file
174
which defaults to "no" if not provided. This attribute
175
controls whether it's a fatal error for the included file
202
206
The user is changed after the bus has completed initialization. So
203
207
sockets etc. will be created before changing user, but no data will be
204
read from clients before changing user. This means that sockets
205
and PID files can be created in a location that requires root
208
read from clients before changing user. This means that sockets
209
and PID files can be created in a location that requires root
206
210
privileges for writing.
212
If present, the bus daemon becomes a real daemon (forks
213
into the background, etc.). This is generally used
216
If present, the bus daemon becomes a real daemon (forks
217
into the background, etc.). This is generally used
214
218
rather than the \-\-fork command line option.
217
221
.I "<keep_umask>"
220
224
If present, the bus daemon keeps its original umask when forking.
221
225
This may be useful to avoid affecting the behavior of child processes.
235
239
Example: <listen>tcp:host=localhost,port=1234</listen>
238
If there are multiple <listen> elements, then the bus listens
239
on multiple addresses. The bus will pass its address to
240
started services or other interested parties with
241
the last address given in <listen> first. That is,
242
If there are multiple <listen> elements, then the bus listens
243
on multiple addresses. The bus will pass its address to
244
started services or other interested parties with
245
the last address given in <listen> first. That is,
242
246
apps will try to connect to the last <listen> address first.
294
298
Adds a directory to scan for .service files. Directories are
295
scanned starting with the last to appear in the config file
296
(the first .service file found that provides a particular
299
scanned starting with the last to appear in the config file
300
(the first .service file found that provides a particular
297
301
service will be used).
300
304
Service files tell the bus how to automatically start a program.
301
They are primarily used with the per-user-session bus,
305
They are primarily used with the per-user-session bus,
302
306
not the systemwide bus.
366
370
"max_incoming_bytes" : total size in bytes of messages
367
371
incoming from a single connection
372
"max_incoming_unix_fds" : total number of unix fds of messages
373
incoming from a single connection
368
374
"max_outgoing_bytes" : total size in bytes of messages
369
375
queued up for a single connection
376
"max_outgoing_unix_fds" : total number of unix fds of messages
377
queued up for a single connection
370
378
"max_message_size" : max size of a single message in
372
"service_start_timeout" : milliseconds (thousandths) until
380
"max_message_unix_fds" : max unix fds of a single message
381
"service_start_timeout" : milliseconds (thousandths) until
373
382
a started service has to connect
374
383
"auth_timeout" : milliseconds (thousandths) a
375
384
connection is given to
377
"max_completed_connections" : max number of authenticated connections
386
"max_completed_connections" : max number of authenticated connections
378
387
"max_incomplete_connections" : max number of unauthenticated
380
389
"max_connections_per_user" : max number of completed connections from
382
391
"max_pending_service_starts" : max number of service launches in
383
392
progress at the same time
384
"max_names_per_connection" : max number of names a single
393
"max_names_per_connection" : max number of names a single
385
394
connection can own
386
"max_match_rules_per_connection": max number of match rules for a single
395
"max_match_rules_per_connection": max number of match rules for a single
388
"max_replies_per_connection" : max number of pending method
397
"max_replies_per_connection" : max number of pending method
389
398
replies per connection
390
399
(number of calls-in-progress)
391
"reply_timeout" : milliseconds (thousandths)
392
until a method call times out
400
"reply_timeout" : milliseconds (thousandths)
401
until a method call times out
413
422
The <policy> element defines a security policy to be applied to a particular
414
423
set of connections to the bus. A policy is made up of
415
424
<allow> and <deny> elements. Policies are normally used with the systemwide bus;
416
they are analogous to a firewall in that they allow expected traffic
425
they are analogous to a firewall in that they allow expected traffic
417
426
and prevent unexpected traffic.
420
Currently, the system bus has a default-deny policy for sending method calls
429
Currently, the system bus has a default-deny policy for sending method calls
421
430
and owning bus names. Everything else, in particular reply messages, receive
422
431
checks, and signals has a default allow policy.
455
Policies applied later will override those applied earlier,
456
when the policies overlap. Multiple policies with the same
457
user/group/context are applied in the order they appear
463
Policies applied later will override those applied earlier,
464
when the policies overlap. Multiple policies with the same
465
user/group/context are applied in the order they appear
458
466
in the config file.
470
478
The possible attributes of these elements are:
472
480
send_interface="interface_name"
473
send_member="method_or_signal_name"
474
send_error="error_name"
475
send_destination="name"
476
send_type="method_call" | "method_return" | "signal" | "error"
481
send_member="method_or_signal_name"
482
send_error="error_name"
483
send_destination="name"
484
send_type="method_call" | "method_return" | "signal" | "error"
477
485
send_path="/path/name"
479
487
receive_interface="interface_name"
480
receive_member="method_or_signal_name"
481
receive_error="error_name"
482
receive_sender="name"
488
receive_member="method_or_signal_name"
489
receive_error="error_name"
490
receive_sender="name"
483
491
receive_type="method_call" | "method_return" | "signal" | "error"
484
492
receive_path="/path/name"
499
<deny send_interface="org.freedesktop.System" send_member="Reboot"/>
500
<deny receive_interface="org.freedesktop.System" receive_member="Reboot"/>
501
<deny own="org.freedesktop.System"/>
507
<deny send_destination="org.freedesktop.Service" send_interface="org.freedesktop.System" send_member="Reboot"/>
502
508
<deny send_destination="org.freedesktop.System"/>
503
509
<deny receive_sender="org.freedesktop.System"/>
504
510
<deny user="john"/>
509
515
The <deny> element's attributes determine whether the deny "matches" a
510
516
particular action. If it matches, the action is denied (unless later
511
517
rules in the config file allow it).
514
519
send_destination and receive_sender rules mean that messages may not be
515
520
sent to or received from the *owner* of the given name, not that
516
521
they may not be sent *to that name*. That is, if a connection
517
522
owns services A, B, C, and sending to A is denied, sending to B or C
518
523
will not work either.
521
525
The other send_* and receive_* attributes are purely textual/by-value
522
526
matches against the given field in the message header.
525
528
"Eavesdropping" occurs when an application receives a message that
526
529
was explicitly addressed to a name the application does not own, or
527
530
is a reply to such a message. Eavesdropping thus only applies to
528
531
messages that are addressed to services and replies to such messages
529
532
(i.e. it does not apply to signals).
532
For <allow>, eavesdrop="true" indicates that the rule matches even
533
when eavesdropping. eavesdrop="false" is the default and means that
534
For <allow>, eavesdrop="true" indicates that the rule matches even
535
when eavesdropping. eavesdrop="false" is the default and means that
534
536
the rule only allows messages to go to their specified recipient.
535
For <deny>, eavesdrop="true" indicates that the rule matches
537
For <deny>, eavesdrop="true" indicates that the rule matches
536
538
only when eavesdropping. eavesdrop="false" is the default for <deny>
537
also, but here it means that the rule applies always, even when
539
also, but here it means that the rule applies always, even when
538
540
not eavesdropping. The eavesdrop attribute can only be combined with
539
541
send and receive rules (with send_* and receive_* attributes).
543
543
The [send|receive]_requested_reply attribute works similarly to the eavesdrop
544
544
attribute. It controls whether the <deny> or <allow> matches a reply
587
587
received" are evaluated separately.
590
Be careful with send_interface/receive_interface, because the
590
Be careful with send_interface/receive_interface, because the
591
591
interface field in messages is optional. In particular, do NOT
592
592
specify <deny send_interface="org.foo.Bar"/>! This will cause
593
593
no-interface messages to be blocked for all services, which is
608
608
An <associate> element appears below an <selinux> element and
609
609
creates a mapping. Right now only one kind of association is possible:
611
<associate own="org.freedesktop.Foobar" context="foo_t"/>
611
<associate own="org.freedesktop.Foobar" context="foo_t"/>
615
615
This means that if a connection asks to own the name
616
616
"org.freedesktop.Foobar" then the source context will be the context
617
of the connection and the target context will be "foo_t" - see the
617
of the connection and the target context will be "foo_t" - see the
618
618
short discussion of SELinux below.
625
625
There's currently no way to set a default for owning any name, if
626
626
we add this syntax it will look like:
628
<associate own="*" context="foo_t"/>
628
<associate own="*" context="foo_t"/>
630
630
If you find a reason this is useful, let the developers know.
631
631
Right now the default will be the security context of the bus itself.
677
677
as target, object class "dbus" and requested permission "send_msg".
680
If a security context is not available for a connection
681
(impossible when using UNIX domain sockets), then the target
680
If a security context is not available for a connection
681
(impossible when using UNIX domain sockets), then the target
682
682
context used is the context of the bus daemon itself.
683
There is currently no way to change this default, because we're
684
assuming that only UNIX domain sockets will be used to
685
connect to the systemwide bus. If this changes, we'll
683
There is currently no way to change this default, because we're
684
assuming that only UNIX domain sockets will be used to
685
connect to the systemwide bus. If this changes, we'll
686
686
probably add a way to set the default connection context.
689
Second, any time a connection asks to own a name,
690
the bus daemon will check permissions with the security
689
Second, any time a connection asks to own a name,
690
the bus daemon will check permissions with the security
691
691
context of the connection as source, the security context specified
692
for the name in the config file as target, object
692
for the name in the config file as target, object
693
693
class "dbus" and requested permission "acquire_svc".
696
The security context for a bus name is specified with the
696
The security context for a bus name is specified with the
697
697
<associate> element described earlier in this document.
698
If a name has no security context associated in the
699
configuration file, the security context of the bus daemon
698
If a name has no security context associated in the
699
configuration file, the security context of the bus daemon
700
700
itself will be used.
705
705
If you're trying to figure out where your messages are going or why
706
706
you aren't getting messages, there are several things you can try.
709
708
Remember that the system bus is heavily locked down and if you
710
709
haven't installed a security policy file to allow your message
711
710
through, it won't work. For the session bus, this is not a concern.
714
712
The simplest way to figure out what's happening on the bus is to run
715
713
the \fIdbus-monitor\fP program, which comes with the D-Bus
716
714
package. You can also send test messages with \fIdbus-send\fP. These
717
715
programs have their own man pages.
720
717
If you want to know what the daemon itself is doing, you might consider
721
running a separate copy of the daemon to test against. This will allow you
722
to put the daemon under a debugger, or run it with verbose output, without
718
running a separate copy of the daemon to test against. This will allow you
719
to put the daemon under a debugger, or run it with verbose output, without
723
720
messing up your real session and system daemons.
726
To run a separate test copy of the daemon, for example you might open a terminal
722
To run a separate test copy of the daemon, for example you might open a terminal
729
725
DBUS_VERBOSE=1 dbus-daemon --session --print-address
733
728
The test daemon address will be printed when the daemon starts. You will need
734
to copy-and-paste this address and use it as the value of the
729
to copy-and-paste this address and use it as the value of the
735
730
DBUS_SESSION_BUS_ADDRESS environment variable when you launch the applications
736
you want to test. This will cause those applications to connect to your
731
you want to test. This will cause those applications to connect to your
737
732
test bus instead of the DBUS_SESSION_BUS_ADDRESS of your real session bus.
740
734
DBUS_VERBOSE=1 will have NO EFFECT unless your copy of D-Bus
741
735
was compiled with verbose mode enabled. This is not recommended in
742
736
production builds due to performance impact. You may need to rebuild
743
737
D-Bus if your copy was not built with debugging in mind. (DBUS_VERBOSE
744
also affects the D-Bus library and thus applications using D-Bus; it may
738
also affects the D-Bus library and thus applications using D-Bus; it may
745
739
be useful to see verbose output on both the client side and from the daemon.)
748
741
If you want to get fancy, you can create a custom bus
749
742
configuration for your test bus (see the session.conf and system.conf
added
removed
bus/dbus-daemon.1.in
