1 A few hints on supporting kdbus as backend in your favorite D-Bus library.
5 Before you read this, have a look at the DIFFERENCES and
6 GVARIANT_SERIALIZATION texts you find in the same directory where you
9 We invite you to port your favorite D-Bus protocol implementation
10 over to kdbus. However, there are a couple of complexities
11 involved. On kdbus we only speak GVariant marshaling, kdbus clients
12 ignore traffic in dbus1 marshaling. Thus, you need to add a second,
13 GVariant compatible marshaler to your library first.
15 After you have done that: here's the basic principle how kdbus works:
17 You connect to a bus by opening its bus node in /dev/kdbus/. All
18 buses have a device node there, it starts with a numeric UID of the
19 owner of the bus, followed by a dash and a string identifying the
20 bus. The system bus is thus called /dev/kdbus/0-system, and for user
21 buses the device node is /dev/kdbus/1000-user (if 1000 is your user
24 (Before we proceed, please always keep a copy of libsystemd next
25 to you, ultimately that's where the details are, this document simply
26 is a rough overview to help you grok things.)
30 To connect to a bus, simply open() its device node and issue the
31 KDBUS_CMD_HELLO call. That's it. Now you are connected. Do not send
32 Hello messages or so (as you would on dbus1), that does not exist for
35 The structure you pass to the ioctl will contain a couple of
36 parameters that you need to know, to operate on the bus.
38 There are two flags fields, one indicating features of the kdbus
39 kernel side ("conn_flags"), the other one ("bus_flags") indicating
40 features of the bus owner (i.e. systemd). Both flags fields are 64bit
43 When calling into the ioctl, you need to place your own supported
44 feature bits into these fields. This tells the kernel about the
45 features you support. When the ioctl returns, it will contain the
46 features the kernel supports.
48 If any of the higher 32bit are set on the two flags fields and your
49 client does not know what they mean, it must disconnect. The upper
50 32bit are used to indicate "incompatible" feature additions on the bus
51 system, the lower 32bit indicate "compatible" feature additions. A
52 client that does not support a "compatible" feature addition can go on
53 communicating with the bus, however a client that does not support an
54 "incompatible" feature must not proceed with the connection.
56 The hello structure also contains another flags field "attach_flags"
57 which indicates metadata that is optionally attached to all incoming
58 messages. You probably want to set KDBUS_ATTACH_NAMES unconditionally
59 in it. This has the effect that all well-known names of a sender are
60 attached to all incoming messages. You need this information to
61 implement matches that match on a message sender name correctly. Of
62 course, you should only request the attachment of as little metadata
65 The kernel will return in the "id" field your unique id. This is a
66 simple numeric value. For compatibility with classic dbus1 simply
67 format this as string and prefix ":0.".
69 The kernel will also return the bloom filter size used for the signal
70 broadcast bloom filter (see below).
72 The kernel will also return the bus ID of the bus in a 128bit field.
74 The pool size field specifies the size of the memory mapped buffer.
75 After the calling the hello ioctl, you should memory map the kdbus
76 fd. In this memory mapped region, the kernel will place all your incoming
81 Use the MSG_SEND ioctl to send a message to another peer. The ioctl
82 takes a structure that contains a variety of fields:
84 The flags field corresponds closely to the old dbus1 message header
85 flags field, though the DONT_EXPECT_REPLY field got inverted into
88 The dst_id/src_id field contains the unique id of the destination and
89 the sender. The sender field is overridden by the kernel usually, hence
90 you shouldn't fill it in. The destination field can also take the
91 special value KDBUS_DST_ID_BROADCAST for broadcast messages. For
92 messages intended to a well-known name set the field to
93 KDBUS_DST_ID_NAME, and attach the name in a special "items" entry to
94 the message (see below).
96 The payload field indicates the payload. For all dbus traffic it
97 should carry the value 0x4442757344427573ULL. (Which encodes
100 The cookie field corresponds with the "serial" field of classic
101 dbus1. We simply renamed it here (and extended it to 64bit) since we
102 didn't want to imply the monotonicity of the assignment the way the
103 word "serial" indicates it.
105 When sending a message that expects a reply, you need to set the
106 EXPECT_REPLY flag in the message flag field. In this case you should
107 also fill out the "timeout_ns" value which indicates the timeout in
108 nsec for this call. If the peer does not respond in this time you will
109 get a notification of a timeout. Note that this is also used for
110 security purposes: a single reply messages is only allowed through the
111 bus as long as the timeout has not ended. With this timeout value you
112 hence "open a time window" in which the peer might respond to your
113 request and the policy allows the response to go through.
115 When sending a message that is a reply, you need to fill in the
116 cookie_reply field, which is similar to the reply_serial field of
117 dbus1. Note that a message cannot have EXPECT_REPLY and a reply_serial
120 This pretty much explains the ioctl header. The actual payload of the
121 data is now referenced in additional items that are attached to this
122 ioctl header structure at the end. When sending a message, you attach
123 items of the type PAYLOAD_VEC, PAYLOAD_MEMFD, FDS, BLOOM, DST_NAME to
126 KDBUS_ITEM_PAYLOAD_VEC: contains a pointer + length pair for
127 referencing arbitrary user memory. This is how you reference most
128 of your data. It's a lot like the good old iovec structure of glibc.
130 KDBUS_ITEM_PAYLOAD_MEMFD: for large data blocks it is preferable
131 to send prepared "memfds" (see below) over. This item contains an
132 fd for a memfd plus a size.
134 KDBUS_ITEM_PAYLOAD_FDS: for sending over fds attach an item of this
135 type with an array of fds.
137 KDBUS_ITEM_BLOOM: the calculated bloom filter of this message, only
138 for undirected (broadcast) message.
140 KDBUS_DST_NAME: for messages that are directed to a well-known name
141 (instead of a unique name), this item contains the well-known name
144 A single message may consists of no, one or more payload items of type
145 PAYLOAD_VEC or PAYLOAD_MEMFD. D-Bus protocol implementations should
146 treat them as a single block that just happens to be split up into
147 multiple items. Some restrictions apply however:
149 The message header in its entirety must be contained in a single
152 You may only split your message up right in front of each GVariant
153 contained in the payload, as well is immediately before framing of a
154 Gvariant, as well after as any padding bytes if there are any. The
155 padding bytes must be wholly contained in the preceding
156 PAYLOAD_VEC/PAYLOAD_MEMFD item. You may not split up simple types
157 nor arrays of trivial types. The latter is necessary to allow APIs
158 to return direct pointers to linear chunks of fixed size trivial
159 arrays. Examples: The simple types "u", "s", "t" have to be in the
160 same payload item. The array of simple types "ay", "ai" have to be
161 fully in contained in the same payload item. For an array "as" or
162 "a(si)" the only restriction however is to keep each string
163 individually in an uninterrupted item, to keep the framing of each
164 element and the array in a single uninterrupted item, however the
165 various strings might end up in different items.
167 Note again, that splitting up messages into separate items is up to the
168 implementation. Also note that the kdbus kernel side might merge
169 separate items if it deems this to be useful. However, the order in
170 which items are contained in the message is left untouched.
172 PAYLOAD_MEMFD items allow zero-copy data transfer (see below regarding
173 the memfd concept). Note however that the overhead of mapping these
174 makes them relatively expensive, and only worth the trouble for memory
175 blocks > 512K (this value appears to be quite universal across
176 architectures, as we tested). Thus we recommend sending PAYLOAD_VEC
177 items over for small messages and restore to PAYLOAD_MEMFD items for
178 messages > 512K. Since while building up the message you might not
179 know yet whether it will grow beyond this boundary a good approach is
180 to simply build the message unconditionally in a memfd
181 object. However, when the message is sealed to be sent away check for
182 the size limit. If the size of the message is < 512K, then simply send
183 the data as PAYLOAD_VEC and reuse the memfd. If it is >= 512K, seal
184 the memfd and send it as PAYLOAD_MEMFD, and allocate a new memfd for
189 Use the MSG_RECV ioctl to read a message from kdbus. This will return
190 an offset into the pool memory map, relative to its beginning.
192 The received message structure more or less follows the structure of
193 the message originally sent. However, certain changes have been
194 made. In the header the src_id field will be filled in.
196 The payload items might have gotten merged and PAYLOAD_VEC items are
197 not used. Instead, you will only find PAYLOAD_OFF and PAYLOAD_MEMFD
198 items. The former contain an offset and size into your memory mapped
199 pool where you find the payload.
201 If during the HELLO ioctl you asked for getting metadata attached to
202 your message, you will find additional KDBUS_ITEM_CREDS,
203 KDBUS_ITEM_PID_COMM, KDBUS_ITEM_TID_COMM, KDBUS_ITEM_TIMESTAMP,
204 KDBUS_ITEM_EXE, KDBUS_ITEM_CMDLINE, KDBUS_ITEM_CGROUP,
205 KDBUS_ITEM_CAPS, KDBUS_ITEM_SECLABEL, KDBUS_ITEM_AUDIT items that
206 contain this metadata. This metadata will be gathered from the sender
207 at the point in time it sends the message. This information is
208 uncached, and since it is appended by the kernel, trustable. The
209 KDBUS_ITEM_SECLABEL item usually contains the SELinux security label,
212 After processing the message you need to call the KDBUS_CMD_FREE
213 ioctl, which releases the message from the pool, and allows the kernel
214 to store another message there. Note that the memory used by the pool
215 is ordinary anonymous, swappable memory that is backed by tmpfs. Hence
216 there is no need to copy the message out of it quickly, instead you
217 can just leave it there as long as you need it and release it via the
218 FREE ioctl only after that's done.
222 The kernel does not understand dbus marshaling, it will not look into
223 the message payload. To allow clients to subscribe to specific subsets
224 of the broadcast matches we employ bloom filters.
226 When broadcasting messages, a bloom filter needs to be attached to the
227 message in a KDBUS_ITEM_BLOOM item (and only for broadcasting
228 messages!). If you don't know what bloom filters are, read up now on
229 Wikipedia. In short: they are a very efficient way how to
230 probabilistically check whether a certain word is contained in a
231 vocabulary. It knows no false negatives, but it does know false
234 The bloom filter that needs to be included has the parameters m=512
235 (bits in the filter), k=8 (nr of hash functions). The underlying hash
236 function is SipHash-2-4. We calculate two hash values for an input
237 strings, one with the hash key b9660bf0467047c18875c49c54b9bd15 (this
238 is supposed to be read as a series of 16 hexadecimal formatted
239 bytes), and one with the hash key
240 aaa154a2e0714b39bfe1dd2e9fc54a3b. This results in two 64bit hash
241 values, A and B. The 8 hash functions for the bloom filter require a 9
242 bit output each (since m=512=2^9), to generate these we XOR combine
243 the first 8 bit of A shifted to the left by 1, with the first 8 bit of
244 B. Then, for the next hash function we use the second 8 bit pair, and
247 For each message to send across the bus we populate the bloom filter
248 with all possible matchable strings. If a client then wants to
249 subscribe to messages of this type, it simply tells the kernel to test
250 its own calculated bit mask against the bloom filter of each message.
252 More specifically, the following strings are added to the bloom filter
253 of each message that is broadcasted:
255 The string "interface:" suffixed by the interface name
257 The string "member:" suffixed by the member name
259 The string "path:" suffixed by the path name
261 The string "path-slash-prefix:" suffixed with the path name, and
262 also all prefixes of the path name (cut off at "/"), also prefixed
263 with "path-slash-prefix".
265 The string "message-type:" suffixed with the strings "signal",
266 "method_call", "error" or "method_return" for the respective message
269 If the first argument of the message is a string, "arg0:" suffixed
270 with the first argument.
272 If the first argument of the message is a string, "arg0-dot-prefix"
273 suffixed with the first argument, and also all prefixes of the
274 argument (cut off at "."), also prefixed with "arg0-dot-prefix".
276 If the first argument of the message is a string,
277 "arg0-slash-prefix" suffixed with the first argument, and also all
278 prefixes of the argument (cut off at "/"), also prefixed with
281 Similar for all further arguments that are strings up to 63, for the
282 arguments and their "dot" and "slash" prefixes. On the first
283 argument that is not a string, addition to the bloom filter should be
286 (Note that the bloom filter does not contain sender nor receiver
289 When a client wants to subscribe to messages matching a certain
290 expression, it should calculate the bloom mask following the same
291 algorithm. The kernel will then simply test the mask against the
292 attached bloom filters.
294 Note that bloom filters are probabilistic, which means that clients
295 might get messages they did not expect. Your bus protocol
296 implementation must be capable of dealing with these unexpected
297 messages (which it needs to anyway, given that transfers are
298 relatively unrestricted on kdbus and people can send you all kinds of
303 To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH
304 ioctl. It takes a structure that contains an encoded match expression,
305 and that is followed by one or more items, which are combined in an
306 AND way. (Meaning: a message is matched exactly when all items
307 attached to the original ioctl struct match).
309 To match against other user messages add a KDBUS_ITEM_BLOOM item in
310 the match (see above). Note that the bloom filter does not include
311 matches to the sender names. To additionally check against sender
312 names, use the KDBUS_ITEM_ID (for unique id matches) and
313 KDBUS_ITEM_NAME (for well-known name matches) item types.
315 To match against kernel generated messages (see below) you should add
316 items of the same type as the kernel messages include,
317 i.e. KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE,
318 KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD, KDBUS_ITEM_ID_REMOVE and
319 fill them out. Note however, that you have some wildcards in this
320 case, for example the .id field of KDBUS_ITEM_ADD/KDBUS_ITEM_REMOVE
321 structures may be set to 0 to match against any id addition/removal.
323 Note that dbus match strings do no map 1:1 to these ioctl() calls. In
324 many cases (where the match string is "underspecified") you might need
325 to issue up to six different ioctl() calls for the same match. For
326 example, the empty match (which matches against all messages), would
327 translate into one KDBUS_ITEM_BLOOM ioctl, one KDBUS_ITEM_NAME_ADD,
328 one KDBUS_ITEM_NAME_CHANGE, one KDBUS_ITEM_NAME_REMOVE, one
329 KDBUS_ITEM_ID_ADD and one KDBUS_ITEM_ID_REMOVE.
331 When creating a match, you may attach a "cookie" value to them, which
332 is used for deleting this match again. The cookie can be selected freely
333 by the client. When issuing KDBUS_CMD_REMOVE_MATCH, simply pass the
334 same cookie as before and all matches matching the same "cookie" value
335 will be removed. This is particularly handy for the case where multiple
336 ioctl()s are added for a single match strings.
340 The "memfd" concept is used for zero-copy data transfers (see
341 above). memfds are file descriptors to memory chunks of arbitrary
342 sizes. If you have a memfd you can mmap() it to get access to the data
343 it contains or write to it. They are comparable to file descriptors to
344 unlinked files on a tmpfs, or to anonymous memory that one may refer
345 to with an fd. They have one particular property: they can be
346 "sealed". A memfd that is "sealed" is protected from alteration. Only
347 memfds that are currently not mapped and to which a single fd refers
348 may be sealed (they may also be unsealed in that case).
350 The concept of "sealing" makes memfds useful for using them as
351 transport for kdbus messages: only when the receiver knows that the
352 message it has received cannot change while looking at, it can safely
353 parse it without having to copy it to a safe memory area. memfds can also
354 be reused in multiple messages. A sender may send the same memfd to
355 multiple peers, and since it is sealed, it can be sure that the receiver
356 will not be able to modify it. "Sealing" hence provides both sides of
357 a transaction with the guarantee that the data stays constant and is
360 memfds are a generic concept that can be used outside of the immediate
361 kdbus usecase. You can send them across AF_UNIX sockets too, sealed or
362 unsealed. In kdbus themselves, they can be used to send zero-copy
363 payloads, but may also be sent as normal fds.
365 memfds are allocated with the KDBUS_CMD_MEMFD_NEW ioctl. After allocation,
366 simply memory map them and write to them. To set their size, use
367 KDBUS_CMD_MEMFD_SIZE_SET. Note that memfds will be increased in size
368 automatically if you touch previously unallocated pages. However, the
369 size will only be increased in multiples of the page size in that
370 case. Thus, in almost all cases, an explicit KDBUS_CMD_MEMFD_SIZE_SET
371 is necessary, since it allows setting memfd sizes in finer
372 granularity. To seal a memfd use the KDBUS_CMD_MEMFD_SEAL_SET ioctl
373 call. It will only succeed if the caller has the only fd reference to
374 the memfd open, and if the memfd is currently unmapped.
376 If memfds are shared, keep in mind that the file pointer used by
377 write/read/seek is shared too, only pread/pwrite are safe to use
380 memfds may be sent across kdbus via KDBUS_ITEM_PAYLOAD_MEMFD items
381 attached to messages. If this is done, the data included in the memfd
382 is considered part of the payload stream of a message, and are treated
383 the same way as KDBUS_ITEM_PAYLOAD_VEC by the receiving side. It is
384 possible to interleave KDBUS_ITEM_PAYLOAD_MEMFD and
385 KDBUS_ITEM_PAYLOAD_VEC items freely, by the reader they will be
386 considered a single stream of bytes in the order these items appear in
387 the message, that just happens to be split up at various places
388 (regarding rules how they may be split up, see above). The kernel will
389 refuse taking KDBUS_ITEM_PAYLOAD_MEMFD items that refer to memfds that
392 Note that sealed memfds may be unsealed again if they are not mapped
393 you have the only fd reference to them.
395 Alternatively to sending memfds as KDBUS_ITEM_PAYLOAD_MEMFD items
396 (where they are just a part of the payload stream of a message) you can
397 also simply attach any memfd to a message using
398 KDBUS_ITEM_PAYLOAD_FDS. In this case, the memfd contents is not
399 considered part of the payload stream of the message, but simply fds
400 like any other, that happen to be attached to the message.
402 MESSAGES FROM THE KERNEL
404 A couple of messages previously generated by the dbus1 bus driver are
405 now generated by the kernel. Since the kernel does not understand the
406 payload marshaling, they are generated by the kernel in a different
407 format. This is indicated with the "payload type" field of the
408 messages set to 0. Library implementations should take these messages
409 and synthesize traditional driver messages for them on reception.
413 Instead of the NameOwnerChanged, NameLost, NameAcquired signals
414 there are kernel messages containing KDBUS_ITEM_NAME_ADD,
415 KDBUS_ITEM_NAME_REMOVE, KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD,
416 KDBUS_ITEM_ID_REMOVE items are generated (each message will contain
417 exactly one of these items). Note that in libsystemd we have
418 obsoleted NameLost/NameAcquired messages, since they are entirely
419 redundant to NameOwnerChanged. This library will hence only
420 synthesize NameOwnerChanged messages from these kernel messages,
421 and never generate NameLost/NameAcquired. If your library needs to
422 stay compatible to the old dbus1 userspace, you possibly might need
423 to synthesize both a NameOwnerChanged and NameLost/NameAcquired
424 message from the same kernel message.
426 When a method call times out, a KDBUS_ITEM_REPLY_TIMEOUT message is
427 generated. This should be synthesized into a method error reply
428 message to the original call.
430 When a method call fails because the peer terminated the connection
431 before responding, a KDBUS_ITEM_REPLY_DEAD message is
432 generated. Similarly, it should be synthesized into a method error
435 For synthesized messages we recommend setting the cookie field to
436 (uint32_t) -1 (and not (uint64_t) -1!), so that the cookie is not 0
437 (which the dbus1 spec does not allow), but clearly recognizable as
440 Note that the KDBUS_ITEM_NAME_XYZ messages will actually inform you
441 about all kinds of names, including activatable ones. Classic dbus1
442 NameOwnerChanged messages OTOH are only generated when a name is
443 really acquired on the bus and not just simply activatable. This means
444 you must explicitly check for the case where an activatable name
445 becomes acquired or an acquired name is lost and returns to be
450 To acquire names on the bus, use the KDBUS_CMD_NAME_ACQUIRE ioctl(). It
451 takes a flags field similar to dbus1's RequestName() bus driver call,
452 however the NO_QUEUE flag got inverted into a QUEUE flag instead.
454 To release a previously acquired name use the KDBUS_CMD_NAME_RELEASE
457 To list acquired names use the KDBUS_CMD_CONN_INFO ioctl. It may be
458 used to list unique names, well known names as well as activatable
459 names and clients currently queuing for ownership of a well-known
460 name. The ioctl will return an offset into the memory pool. After
461 reading all the data you need, you need to release this via the
462 KDBUS_CMD_FREE ioctl(), similar how you release a received message.
466 kdbus can optionally attach various kinds of metadata about the sender at
467 the point of time of sending ("credentials") to messages, on request
468 of the receiver. This is both supported on directed and undirected
469 (broadcast) messages. The metadata to attach is selected at time of
470 the HELLO ioctl of the receiver via a flags field (see above). Note
471 that clients must be able to handle that messages contain more
472 metadata than they asked for themselves, to simplify implementation of
473 broadcasting in the kernel. The receiver should not rely on this data
474 to be around though, even though it will be correct if it happens to
475 be attached. In order to avoid programming errors in applications, we
476 recommend though not passing this data on to clients that did not
477 explicitly ask for it.
479 Credentials may also be queried for a well-known or unique name. Use
480 the KDBUS_CMD_CONN_INFO for this. It will return an offset to the pool
481 area again, which will contain the same credential items as messages
482 have attached. Note that when issuing the ioctl, you can select a
483 different set of credentials to gather, than what was originally requested
484 for being attached to incoming messages.
486 Credentials are always specific to the sender namespace that was
487 current at the time of sending, and of the process that opened the
488 bus connection at the time of opening it. Note that this latter data
493 The kernel enforces only very limited policy on names. It will not do
494 access filtering by userspace payload, and thus not by interface or
497 This ultimately means that most fine-grained policy enforcement needs
498 to be done by the receiving process. We recommend using PolicyKit for
499 any more complex checks. However, libraries should make simple static
500 policy decisions regarding privileged/unprivileged method calls
501 easy. We recommend doing this by enabling KDBUS_ATTACH_CAPS and
502 KDBUS_ATTACH_CREDS for incoming messages, and then discerning client
503 access by some capability, or if sender and receiver UIDs match.
507 When connecting to kdbus use the "kernel:" protocol prefix in DBus
508 address strings. The device node path is encoded in its "path="
511 Client libraries should use the following connection string when
512 connecting to the system bus:
514 kernel:path=/dev/kdbus/0-system/bus;unix:path=/run/dbus/system_bus_socket
516 This will ensure that kdbus is preferred over the legacy AF_UNIX
517 socket, but compatibility is kept. For the user bus use:
519 kernel:path=/dev/kdbus/$UID-user/bus;unix:path=$XDG_RUNTIME_DIR/bus
521 With $UID replaced by the callers numer user ID, and $XDG_RUNTIME_DIR
522 following the XDG basedir spec.
524 Of course the $DBUS_SYSTEM_BUS_ADDRESS and $DBUS_SESSION_BUS_ADDRESS
525 variables should still take precedence.
529 Activatable services for kdbus may not use classic dbus1 service
530 activation files. Instead, programs should drop in native systemd
531 .service and .busname unit files, so that they are treated uniformly
532 with other types of units and activation of the system.
534 Note that this results in a major difference to classic dbus1:
535 activatable bus names can be established at any time in the boot process.
536 This is unlike dbus1 where activatable names are unconditionally available
537 as long as dbus-daemon is running. Being able to control when
538 activatable names are established is essential to allow usage of kdbus
539 during early boot and in initrds, without the risk of triggering
544 This all is so far just the status quo. We are putting this together, because
545 we are quite confident that further API changes will be smaller, but
546 to make this very clear: this is all subject to change, still!
548 We invite you to port over your favorite dbus library to this new
549 scheme, but please be prepared to make minor changes when we still
550 change these interfaces!