1DBUS-BROKER(1)                   User Commands                  DBUS-BROKER(1)
2
3
4

NAME

6       dbus-broker - D-Bus message broker
7

SYNOPSIS

9       dbus-broker [ OPTIONS ]
10       dbus-broker --version
11       dbus-broker --help
12
13

DESCRIPTION

15       dbus-broker is an implementation of the D-Bus Message Bus Specification
16       [1]. Each instance provides a single, unique message bus  that  clients
17       can  connect  to, and send messages over. The broker takes care of mes‐
18       sage mediation, access control, subscriptions, and bus control, accord‐
19       ing to the D-Bus specification.
20
21       dbus-broker  is  a pure implementation, meaning that it only implements
22       the message mediation. It needs a controlling process that performs the
23       bus setup and all external communication. dbus-broker-launch(1) is such
24       a controller aiming at perfect  compatibility  to  dbus-daemon(1),  the
25       D-Bus  Reference  Implementation. See dbus-broker-launch(1) for details
26       how to spawn a message bus.
27
28       This man-page documents the interface between dbus-broker and its  con‐
29       troller (e.g., dbus-broker-launch(1)).
30

OPTIONS

32       The  following  command-line  options  are  supported.  If an option is
33       passed, which is not listed here, the broker will deny startup and exit
34       with an error.
35
36       -h, --help
37              print usage information and exit immediately
38
39       --version
40              print build-version and exit immediately
41
42       --audit
43              enable logging to the linux audit subsystem (no-op if audit sup‐
44              port was not compiled in; Default: off)
45
46       --controller=FD
47              use the inherited file-descriptor with the given number  as  the
48              controlling  socket  (see  CONTROLLER  section;  this  option is
49              mandatory)
50
51       --log FD
52              use the inherited file-descriptor with the given number  to  ac‐
53              cess the system log (see LOGGING section; Default: no logging)
54
55       --machine-id=ID
56              set  the  machine-id  to  be  advertised  by  the broker via the
57              org.freedesktop.DBus interface (this  option  is  mandatory  and
58              usually sourced from /etc/machine-id)
59
60       --max-bytes=BYTES
61              maximum  number  of  bytes  each user may allocate in the broker
62              (Default: 16 MiB)
63
64       --max-fds=FDS
65              maximum number of file descriptors each user may allocate in the
66              broker (Default: 64)
67
68       --max-matches=MATCHES
69              maximum number of match rules each user may allocate in the bro‐
70              ker (Default: 16k)
71
72       --max-objects=OBJECTS
73              maximum total number of names, peers, pending replies, etc  each
74              user may allocate in the broker (Default: 16k)
75

CONTROLLER

77       Every instance of dbus-broker inherits a unix(7) socket from its parent
78       process. This socket must be specified via the --controller option. The
79       broker  uses  this  socket  to  accept control commands from its parent
80       process (or from whomever owns the other  side  of  this  socket,  also
81       called  The  Controller).  This socket uses normal D-Bus P2P communica‐
82       tion. The interfaces provided on this socket are described in  the  API
83       section.
84
85       By  default, a broker instance is idle. That is, after forking and exe‐
86       cuting a broker, it starts with an empty list of bus-sockets to manage,
87       as well as no way for clients to connect to it. The controller must use
88       the controller interface to create listener sockets,  specify  the  bus
89       policy, create activatable names, and react to bus events.
90
91       The  dbus-broker  process  never  accesses any external resources other
92       than those passed in either via the command-line or the controller  in‐
93       terfaces.  That is, no file-system access, no nss(5) calls, no external
94       process communication, is performed by the broker. On the contrary, the
95       broker  never  accesses any resources but the sockets provided to it by
96       the controller. This is guaranteed by the implementation. At  the  same
97       time,  this  implies that the controller is required to perform all ex‐
98       ternal resource acquisitions and communication on behalf of the  broker
99       (in case this is needed).
100

LOGGING

102       If a logging FD is provided via the --log command-line option, the bro‐
103       ker will log some information through this FD. Two different  log-types
104       are supported:
105
106          1. If  the FD is a unix(7) SOCK_STREAM socket, information is logged
107             as human-readable line-based chunks.
108
109          2. If the FD is a unix(7) SOCK_DGRAM socket, information  is  logged
110             as  key/value based annotated data blocks. The format is compati‐
111             ble to the format used by the systemd-journal (though it  is  not
112             dependent  on  systemd).   This  key/value based logging is a lot
113             more verbose as the stream based logging. A lot  of  metadata  is
114             provided as separate keys, allowing precise tracing and interpre‐
115             tation of the logged data.
116
117       The broker has strict rules when it logs data. It logs  during  startup
118       and  shutdown, one message each to provide information on its setup and
119       environment.  At runtime, the broker only ever logs in unexpected situ‐
120       ations. That is, every message the broker logs at runtime was triggered
121       by a malfunctioning client. If a system is properly set up, no  runtime
122       log-message will be triggered.
123
124       The situations where the broker logs are:
125
126          1. During  startup  and shutdown, the broker submits a short message
127             including metadata about its controller, environment, and setup.
128
129          2. Whenever a client-request is denied by the policy, a  message  is
130             logged including the affected client and policies.
131
132          3. Whenever a client exceeds its resource quota, a message is logged
133             with information on the client.
134

API

136       The following interfaces are implemented by the broker on  the  respec‐
137       tive nodes.  The controller is free to call these at any time. The con‐
138       troller connection is considered trusted. No resource  accounting,  nor
139       access control is performed.
140
141       The  controller  itself  is also required to implement interfaces to be
142       used by the broker. See the section below for a list of  interfaces  on
143       the controller.
144
145       node /org/bus1/DBus/Broker {
146         interface org.bus1.DBus.Broker {
147
148           # Create new activatable name @name, accounted on user @uid. The name
149           # will be exposed by the controller as @path (which must fit the
150           # template /org/bus1/DBus/Name/%).
151           method AddName(o path, s name, u uid) -> ()
152
153           # Add a listener socket to this bus. The listener socket must be
154           # ready in listening mode and specified as @socket. As soon as this
155           # call returns, incoming client connection attempts will be served
156           # on this socket.
157           # The listener is exposed by the controller as @path (which must fit
158           # the template /org/bus1/DBus/Listener/%).
159           # The policy for all clients connecting through this socket is
160           # provided as @policy. See org.bus1.DBus.Listener.SetPolicy() for
161           # details.
162           method AddListener(o path, h socket, v policy) -> ()
163
164           # This signal is raised according to client-requests of
165           # org.freedesktop.DBus.UpdateActivationEnvironment().
166           signal SetActivationEnvironment(a{ss} environment)
167
168         }
169       }
170
171       node /org/bus1/DBus/Listener/% {
172         interface org.bus1.DBus.Listener {
173
174           # Release this listener. It will immediately be removed by the broker
175           # and no more connections will be served on it. All clients connected
176           # through this listener are forcefully disconnected.
177           method Release() -> ()
178
179           # Change the policy on this listener socket to @policy. The syntax of
180           # the policy is still subject to change and not stable, yet.
181           method SetPolicy(v policy) -> ()
182
183         }
184       }
185
186       node /org/bus1/DBus/Name/% {
187         interface org.bus1.DBus.Name {
188
189           # Release this activatable name. It will be removed with immediate
190           # effect by the broker. Note that the name is still valid to be
191           # acquired by clients, though no activation-features will be
192           # supported on this name.
193           method Release() -> ()
194
195           # Reset the activation state of this name. Any pending activation
196           # requests are cancelled. The call requires a serial number to be
197           # passed along. This must be the serial number received by the last
198           # activation event on this name. Calls for other serial numbers are
199           # silently ignored and considered stale.
200           # A org.bus1.DBus.Name.Error string is also passed, giving a hint
201           # about the reason the activation was reset. The list is defined below.
202           method Reset(t serial, s error) -> ()
203
204           # Activation request failed: a concurrent deactivation request is already in progress
205           error org.bus1.DBus.Name.Error.DestructiveTransaction
206           # Activation request failed: unknown unit
207           error org.bus1.DBus.Name.Error.UnknownUnit
208           # Activation request failed: unit is masked
209           error org.bus1.DBus.Name.Error.MaskedUnit
210           # Activation request failed: unit is invalid
211           error org.bus1.DBus.Name.Error.InvalidUnit
212           # Unit activation job succeeded, but the unit failed afterwards
213           error org.bus1.DBus.Name.Error.UnitFailure
214           # The startup job was valid, but it failed during activation
215           error org.bus1.DBus.Name.Error.StartupFailure
216           # The startup job was valid, but it was skipped during activation
217           error org.bus1.DBus.Name.Error.StartupSkipped
218           # Activation request cancelled: bus name was released
219           error org.bus1.DBus.Name.Error.NameReleased
220
221           # This signal is sent whenever a client requests activation of this
222           # name. Note that multiple activation requests are coalesced by the
223           # broker. The controller can cancel outstanding requests via the
224           # Reset() method.
225           # The broker sends a serial number with the event. This number
226           # represents the activation request and must be used when reacting
227           # to the request with methods like Reset(). The serial number is
228           # unique for each event, and is never reused. A serial number of 0
229           # is never sent and considered invalid.
230           signal Activate(t serial)
231
232         }
233       }
234
235
236
237       The controller itself is required to implement the following interfaces
238       on the given nodes. These interfaces are called by the broker to imple‐
239       ment  some parts of the driver-interface as defined by the D-Bus speci‐
240       fication.
241
242       Note that all method-calls performed by the  broker  are  always  fully
243       asynchronous.  That  is,  regardless how long it takes to serve the re‐
244       quest, the broker is still fully operational and might even  send  fur‐
245       ther requests to the controller.
246
247       A  controller  is  free to implement these calls in a blocking fashion.
248       However, it is up to the controller to make sure not to perform  block‐
249       ing recursive calls back into the broker (via any means).
250
251       node /org/bus1/DBus/Controller {
252         interface org.bus1.DBus.Controller {
253
254           # This function is called for each client-request of
255           # org.freedesktop.DBus.ReloadConfig().
256           method ReloadConfig() -> ()
257
258         }
259       }
260
261
262

SEE ALSO

264       dbus-broker-launch(1) dbus-daemon(1)
265

NOTES

267       [1]  D-Bus                                               Specification:
268            https://dbus.freedesktop.org/doc/dbus-specification.html
269
270
271
272
273                                                                DBUS-BROKER(1)
Impressum