1DBUS-BROKER(1) User Commands DBUS-BROKER(1)
2
6 dbus-broker - D-Bus message broker
7
9 dbus-broker [ OPTIONS ]
10 dbus-broker --version
11 dbus-broker --help
12
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 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 This man-page documents the interface between dbus-broker and its con‐
29 troller (e.g., dbus-broker-launch(1)).
30
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 -h, --help
37 print usage information and exit immediately
38 --version
40 print build-version and exit immediately
41 --audit
43 enable logging to the linux audit subsystem (no-op if audit sup‐
44 port was not compiled in; Default: off)
45 --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 --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 --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 --max-bytes=BYTES
61 maximum number of bytes each user may allocate in the broker
62 (Default: 16 MiB)
63 --max-fds=FDS
65 maximum number of file descriptors each user may allocate in the
66 broker (Default: 64)
67 --max-matches=MATCHES
69 maximum number of match rules each user may allocate in the bro‐
70 ker (Default: 16k)
71 --max-objects=OBJECTS
73 maximum total number of names, peers, pending replies, etc each
74 user may allocate in the broker (Default: 16k)
75
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 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 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
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 1. If the FD is a unix(7) SOCK_STREAM socket, information is logged
107 as human-readable line-based chunks.
108 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 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 The situations where the broker logs are:
125 1. During startup and shutdown, the broker submits a short message
127 including metadata about its controller, environment, and setup.
128 2. Whenever a client-request is denied by the policy, a message is
130 logged including the affected client and policies.
131 3. Whenever a client exceeds its resource quota, a message is logged
133 with information on the client.
134
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 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 node /org/bus1/DBus/Broker {
146 interface org.bus1.DBus.Broker {
147 # 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 # 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 # This signal is raised according to client-requests of
165 # org.freedesktop.DBus.UpdateActivationEnvironment().
166 signal SetActivationEnvironment(a{ss} environment)
167 }
169 }
170 node /org/bus1/DBus/Listener/% {
172 interface org.bus1.DBus.Listener {
173 # 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 # 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 }
184 }
185 node /org/bus1/DBus/Name/% {
187 interface org.bus1.DBus.Name {
188 # 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 # 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 # 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 # 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 }
233 }
234 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 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 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 node /org/bus1/DBus/Controller {
252 interface org.bus1.DBus.Controller {
253 # This function is called for each client-request of
255 # org.freedesktop.DBus.ReloadConfig().
256 method ReloadConfig() -> ()
257 }
259 }
260
264 dbus-broker-launch(1) dbus-daemon(1)
265
267 [1] D-Bus Specification:
268 https://dbus.freedesktop.org/doc/dbus-specification.html
269 DBUS-BROKER(1)