]> git.ipfire.org Git - thirdparty/systemd.git/blame - src/libsystemd/sd-bus/PORTING-DBUS1
tmpfiles: accurately report creation results
[thirdparty/systemd.git] / src / libsystemd / sd-bus / PORTING-DBUS1
CommitLineData
6206f4b4 1A few hints on supporting kdbus as backend in your favorite D-Bus library.
00586799
LP
2
3~~~
4
5Before you read this, have a look at the DIFFERENCES and
0a6de115 6GVARIANT_SERIALIZATION texts you find in the same directory where you
00586799
LP
7found this.
8
6206f4b4 9We invite you to port your favorite D-Bus protocol implementation
00586799 10over to kdbus. However, there are a couple of complexities
6206f4b4
KS
11involved. On kdbus we only speak GVariant marshaling, kdbus clients
12ignore traffic in dbus1 marshaling. Thus, you need to add a second,
0a6de115 13GVariant compatible marshaler to your library first.
00586799
LP
14
15After you have done that: here's the basic principle how kdbus works:
16
63cc4c31 17You connect to a bus by opening its bus node in /sys/fs/kdbus/. All
0a6de115 18buses have a device node there, it starts with a numeric UID of the
00586799 19owner of the bus, followed by a dash and a string identifying the
63cc4c31
DM
20bus. The system bus is thus called /sys/fs/kdbus/0-system, and for user
21buses the device node is /sys/fs/kdbus/1000-user (if 1000 is your user
00586799
LP
22id).
23
6bb648a1 24(Before we proceed, please always keep a copy of libsystemd next
00586799
LP
25to you, ultimately that's where the details are, this document simply
26is a rough overview to help you grok things.)
27
28CONNECTING
29
0a6de115 30To connect to a bus, simply open() its device node and issue the
00586799
LP
31KDBUS_CMD_HELLO call. That's it. Now you are connected. Do not send
32Hello messages or so (as you would on dbus1), that does not exist for
33kdbus.
34
35The structure you pass to the ioctl will contain a couple of
0a6de115 36parameters that you need to know, to operate on the bus.
00586799
LP
37
38There are two flags fields, one indicating features of the kdbus
39kernel side ("conn_flags"), the other one ("bus_flags") indicating
40features of the bus owner (i.e. systemd). Both flags fields are 64bit
41in width.
42
43When calling into the ioctl, you need to place your own supported
44feature bits into these fields. This tells the kernel about the
061eab67 45features you support. When the ioctl returns, it will contain the
00586799
LP
46features the kernel supports.
47
48If any of the higher 32bit are set on the two flags fields and your
49client does not know what they mean, it must disconnect. The upper
5032bit are used to indicate "incompatible" feature additions on the bus
51system, the lower 32bit indicate "compatible" feature additions. A
52client that does not support a "compatible" feature addition can go on
53communicating with the bus, however a client that does not support an
847657c7
LP
54"incompatible" feature must not proceed with the connection. When a
55client encountes such an "incompatible" feature it should immediately
56try the next bus address configured in the bus address string.
00586799
LP
57
58The hello structure also contains another flags field "attach_flags"
0a6de115 59which indicates metadata that is optionally attached to all incoming
00586799
LP
60messages. You probably want to set KDBUS_ATTACH_NAMES unconditionally
61in it. This has the effect that all well-known names of a sender are
62attached to all incoming messages. You need this information to
63implement matches that match on a message sender name correctly. Of
061eab67 64course, you should only request the attachment of as little metadata
00586799
LP
65fields as you need.
66
67The kernel will return in the "id" field your unique id. This is a
68simple numeric value. For compatibility with classic dbus1 simply
e1ffdb90 69format this as string and prefix ":1.".
00586799 70
847657c7
LP
71The kernel will also return the bloom filter size and bloom filter
72hash function number used for the signal broadcast bloom filter (see
73below).
00586799 74
f000939e 75The kernel will also return the bus ID of the bus in a 128bit field.
00586799 76
0a6de115 77The pool size field specifies the size of the memory mapped buffer.
00586799 78After the calling the hello ioctl, you should memory map the kdbus
0a6de115
KS
79fd. In this memory mapped region, the kernel will place all your incoming
80messages.
00586799
LP
81
82SENDING MESSAGES
83
84Use the MSG_SEND ioctl to send a message to another peer. The ioctl
85takes a structure that contains a variety of fields:
86
87The flags field corresponds closely to the old dbus1 message header
88flags field, though the DONT_EXPECT_REPLY field got inverted into
89EXPECT_REPLY.
90
91The dst_id/src_id field contains the unique id of the destination and
6206f4b4 92the sender. The sender field is overridden by the kernel usually, hence
00586799
LP
93you shouldn't fill it in. The destination field can also take the
94special value KDBUS_DST_ID_BROADCAST for broadcast messages. For
95messages intended to a well-known name set the field to
96KDBUS_DST_ID_NAME, and attach the name in a special "items" entry to
97the message (see below).
98
99The payload field indicates the payload. For all dbus traffic it
100should carry the value 0x4442757344427573ULL. (Which encodes
101'DBusDBus').
102
103The cookie field corresponds with the "serial" field of classic
104dbus1. We simply renamed it here (and extended it to 64bit) since we
105didn't want to imply the monotonicity of the assignment the way the
106word "serial" indicates it.
107
108When sending a message that expects a reply, you need to set the
109EXPECT_REPLY flag in the message flag field. In this case you should
110also fill out the "timeout_ns" value which indicates the timeout in
111nsec for this call. If the peer does not respond in this time you will
6206f4b4 112get a notification of a timeout. Note that this is also used for
00586799
LP
113security purposes: a single reply messages is only allowed through the
114bus as long as the timeout has not ended. With this timeout value you
115hence "open a time window" in which the peer might respond to your
116request and the policy allows the response to go through.
117
118When sending a message that is a reply, you need to fill in the
119cookie_reply field, which is similar to the reply_serial field of
120dbus1. Note that a message cannot have EXPECT_REPLY and a reply_serial
121at the same time!
122
123This pretty much explains the ioctl header. The actual payload of the
124data is now referenced in additional items that are attached to this
125ioctl header structure at the end. When sending a message, you attach
5fa4ddb8
LS
126items of the type PAYLOAD_VEC, PAYLOAD_MEMFD, FDS, BLOOM_FILTER,
127DST_NAME to it:
00586799
LP
128
129 KDBUS_ITEM_PAYLOAD_VEC: contains a pointer + length pair for
130 referencing arbitrary user memory. This is how you reference most
131 of your data. It's a lot like the good old iovec structure of glibc.
132
6206f4b4
KS
133 KDBUS_ITEM_PAYLOAD_MEMFD: for large data blocks it is preferable
134 to send prepared "memfds" (see below) over. This item contains an
00586799
LP
135 fd for a memfd plus a size.
136
5fa4ddb8
LS
137 KDBUS_ITEM_FDS: for sending over fds attach an item of this type with
138 an array of fds.
00586799 139
5fa4ddb8
LS
140 KDBUS_ITEM_BLOOM_FILTER: the calculated bloom filter of this message,
141 only for undirected (broadcast) message.
00586799 142
5fa4ddb8
LS
143 KDBUS_ITEM_DST_NAME: for messages that are directed to a well-known
144 name (instead of a unique name), this item contains the well-known
145 name field.
00586799 146
6206f4b4 147A single message may consists of no, one or more payload items of type
00586799
LP
148PAYLOAD_VEC or PAYLOAD_MEMFD. D-Bus protocol implementations should
149treat them as a single block that just happens to be split up into
150multiple items. Some restrictions apply however:
151
152 The message header in its entirety must be contained in a single
6206f4b4 153 PAYLOAD_VEC item.
00586799 154
6206f4b4 155 You may only split your message up right in front of each GVariant
061eab67 156 contained in the payload, as well is immediately before framing of a
00586799
LP
157 Gvariant, as well after as any padding bytes if there are any. The
158 padding bytes must be wholly contained in the preceding
d20a3daa
SM
159 PAYLOAD_VEC/PAYLOAD_MEMFD item. You may not split up basic types
160 nor arrays of fixed types. The latter is necessary to allow APIs
161 to return direct pointers to linear arrays of numeric
162 values. Examples: The basic types "u", "s", "t" have to be in the
163 same payload item. The array of fixed types "ay", "ai" have to be
00586799
LP
164 fully in contained in the same payload item. For an array "as" or
165 "a(si)" the only restriction however is to keep each string
166 individually in an uninterrupted item, to keep the framing of each
167 element and the array in a single uninterrupted item, however the
168 various strings might end up in different items.
169
061eab67 170Note again, that splitting up messages into separate items is up to the
00586799 171implementation. Also note that the kdbus kernel side might merge
6206f4b4 172separate items if it deems this to be useful. However, the order in
00586799
LP
173which items are contained in the message is left untouched.
174
175PAYLOAD_MEMFD items allow zero-copy data transfer (see below regarding
176the memfd concept). Note however that the overhead of mapping these
177makes them relatively expensive, and only worth the trouble for memory
1fa13293 178blocks > 512K (this value appears to be quite universal across
00586799
LP
179architectures, as we tested). Thus we recommend sending PAYLOAD_VEC
180items over for small messages and restore to PAYLOAD_MEMFD items for
1fa13293 181messages > 512K. Since while building up the message you might not
00586799
LP
182know yet whether it will grow beyond this boundary a good approach is
183to simply build the message unconditionally in a memfd
184object. However, when the message is sealed to be sent away check for
1fa13293
KS
185the size limit. If the size of the message is < 512K, then simply send
186the data as PAYLOAD_VEC and reuse the memfd. If it is >= 512K, seal
00586799
LP
187the memfd and send it as PAYLOAD_MEMFD, and allocate a new memfd for
188the next message.
189
190RECEIVING MESSAGES
191
192Use the MSG_RECV ioctl to read a message from kdbus. This will return
193an offset into the pool memory map, relative to its beginning.
194
195The received message structure more or less follows the structure of
196the message originally sent. However, certain changes have been
197made. In the header the src_id field will be filled in.
198
199The payload items might have gotten merged and PAYLOAD_VEC items are
061eab67 200not used. Instead, you will only find PAYLOAD_OFF and PAYLOAD_MEMFD
00586799
LP
201items. The former contain an offset and size into your memory mapped
202pool where you find the payload.
203
0a6de115 204If during the HELLO ioctl you asked for getting metadata attached to
061eab67 205your message, you will find additional KDBUS_ITEM_CREDS,
00586799
LP
206KDBUS_ITEM_PID_COMM, KDBUS_ITEM_TID_COMM, KDBUS_ITEM_TIMESTAMP,
207KDBUS_ITEM_EXE, KDBUS_ITEM_CMDLINE, KDBUS_ITEM_CGROUP,
208KDBUS_ITEM_CAPS, KDBUS_ITEM_SECLABEL, KDBUS_ITEM_AUDIT items that
061eab67
KS
209contain this metadata. This metadata will be gathered from the sender
210at the point in time it sends the message. This information is
211uncached, and since it is appended by the kernel, trustable. The
212KDBUS_ITEM_SECLABEL item usually contains the SELinux security label,
00586799
LP
213if it is used.
214
215After processing the message you need to call the KDBUS_CMD_FREE
216ioctl, which releases the message from the pool, and allows the kernel
217to store another message there. Note that the memory used by the pool
061eab67 218is ordinary anonymous, swappable memory that is backed by tmpfs. Hence
00586799
LP
219there is no need to copy the message out of it quickly, instead you
220can just leave it there as long as you need it and release it via the
221FREE ioctl only after that's done.
222
223BLOOM FILTERS
224
6206f4b4 225The kernel does not understand dbus marshaling, it will not look into
00586799 226the message payload. To allow clients to subscribe to specific subsets
6206f4b4 227of the broadcast matches we employ bloom filters.
00586799 228
061eab67 229When broadcasting messages, a bloom filter needs to be attached to the
00586799
LP
230message in a KDBUS_ITEM_BLOOM item (and only for broadcasting
231messages!). If you don't know what bloom filters are, read up now on
232Wikipedia. In short: they are a very efficient way how to
233probabilistically check whether a certain word is contained in a
234vocabulary. It knows no false negatives, but it does know false
235positives.
236
b28ff39f
LP
237The parameters for the bloom filters that need to be included in
238broadcast message is communicated to userspace as part of the hello
847657c7
LP
239response structure (see above). By default it has the parameters m=512
240(bits in the filter), k=8 (nr of hash functions). Note however, that
241this is subject to change in later versions, and userspace
242implementations must be capable of handling m values between at least
243m=8 and m=2^32, and k values between at least k=1 and k=32. The
244underlying hash function is SipHash-2-4. It is used with a number of
245constant (yet originally randomly generated) 128bit hash keys, more
246specifically:
b28ff39f
LP
247
248 b9,66,0b,f0,46,70,47,c1,88,75,c4,9c,54,b9,bd,15,
249 aa,a1,54,a2,e0,71,4b,39,bf,e1,dd,2e,9f,c5,4a,3b,
250 63,fd,ae,be,cd,82,48,12,a1,6e,41,26,cb,fa,a0,c8,
251 23,be,45,29,32,d2,46,2d,82,03,52,28,fe,37,17,f5,
252 56,3b,bf,ee,5a,4f,43,39,af,aa,94,08,df,f0,fc,10,
253 31,80,c8,73,c7,ea,46,d3,aa,25,75,0f,9e,4c,09,29,
254 7d,f7,18,4b,7b,a4,44,d5,85,3c,06,e0,65,53,96,6d,
255 f2,77,e9,6f,93,b5,4e,71,9a,0c,34,88,39,25,bf,35
256
257When calculating the first bit index into the bloom filter, the
258SipHash-2-4 hash value is calculated for the input data and the first
25916 bytes of the array above as hash key. Of the resulting 8 bytes of
847657c7 260output, as many full bytes are taken for the bit index as necessary,
b28ff39f
LP
261starting from the output's first byte. For the second bit index the
262same hash value is used, continuing with the next unused output byte,
263and so on. Each time the bytes returned by the hash function are
264depleted it is recalculated with the next 16 byte hash key from the
265array above and the same input data.
00586799
LP
266
267For each message to send across the bus we populate the bloom filter
268with all possible matchable strings. If a client then wants to
061eab67 269subscribe to messages of this type, it simply tells the kernel to test
00586799
LP
270its own calculated bit mask against the bloom filter of each message.
271
061eab67
KS
272More specifically, the following strings are added to the bloom filter
273of each message that is broadcasted:
00586799
LP
274
275 The string "interface:" suffixed by the interface name
276
277 The string "member:" suffixed by the member name
278
279 The string "path:" suffixed by the path name
280
281 The string "path-slash-prefix:" suffixed with the path name, and
282 also all prefixes of the path name (cut off at "/"), also prefixed
283 with "path-slash-prefix".
284
285 The string "message-type:" suffixed with the strings "signal",
286 "method_call", "error" or "method_return" for the respective message
287 type of the message.
288
289 If the first argument of the message is a string, "arg0:" suffixed
290 with the first argument.
291
292 If the first argument of the message is a string, "arg0-dot-prefix"
293 suffixed with the first argument, and also all prefixes of the
294 argument (cut off at "."), also prefixed with "arg0-dot-prefix".
295
296 If the first argument of the message is a string,
297 "arg0-slash-prefix" suffixed with the first argument, and also all
298 prefixes of the argument (cut off at "/"), also prefixed with
299 "arg0-slash-prefix".
300
301 Similar for all further arguments that are strings up to 63, for the
302 arguments and their "dot" and "slash" prefixes. On the first
061eab67 303 argument that is not a string, addition to the bloom filter should be
00586799
LP
304 stopped however.
305
061eab67 306(Note that the bloom filter does not contain sender nor receiver
00586799
LP
307names!)
308
309When a client wants to subscribe to messages matching a certain
061eab67 310expression, it should calculate the bloom mask following the same
6206f4b4 311algorithm. The kernel will then simply test the mask against the
00586799
LP
312attached bloom filters.
313
314Note that bloom filters are probabilistic, which means that clients
6206f4b4 315might get messages they did not expect. Your bus protocol
00586799
LP
316implementation must be capable of dealing with these unexpected
317messages (which it needs to anyway, given that transfers are
318relatively unrestricted on kdbus and people can send you all kinds of
061eab67 319non-sense).
00586799 320
847657c7
LP
321If a client connects to a bus whose bloom filter metrics (i.e. filter
322size and number of hash functions) are outside of the range the client
323supports it must immediately disconnect and continue connection with
324the next bus address of the bus connection string.
325
00586799
LP
326INSTALLING MATCHES
327
061eab67 328To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH
00586799
LP
329ioctl. It takes a structure that contains an encoded match expression,
330and that is followed by one or more items, which are combined in an
061eab67 331AND way. (Meaning: a message is matched exactly when all items
00586799
LP
332attached to the original ioctl struct match).
333
334To match against other user messages add a KDBUS_ITEM_BLOOM item in
335the match (see above). Note that the bloom filter does not include
336matches to the sender names. To additionally check against sender
337names, use the KDBUS_ITEM_ID (for unique id matches) and
338KDBUS_ITEM_NAME (for well-known name matches) item types.
339
340To match against kernel generated messages (see below) you should add
341items of the same type as the kernel messages include,
342i.e. KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE,
343KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD, KDBUS_ITEM_ID_REMOVE and
344fill them out. Note however, that you have some wildcards in this
6d6c604a 345case, for example the .id field of KDBUS_ITEM_ID_ADD/KDBUS_ITEM_ID_REMOVE
00586799
LP
346structures may be set to 0 to match against any id addition/removal.
347
348Note that dbus match strings do no map 1:1 to these ioctl() calls. In
349many cases (where the match string is "underspecified") you might need
350to issue up to six different ioctl() calls for the same match. For
351example, the empty match (which matches against all messages), would
352translate into one KDBUS_ITEM_BLOOM ioctl, one KDBUS_ITEM_NAME_ADD,
353one KDBUS_ITEM_NAME_CHANGE, one KDBUS_ITEM_NAME_REMOVE, one
354KDBUS_ITEM_ID_ADD and one KDBUS_ITEM_ID_REMOVE.
355
061eab67
KS
356When creating a match, you may attach a "cookie" value to them, which
357is used for deleting this match again. The cookie can be selected freely
358by the client. When issuing KDBUS_CMD_REMOVE_MATCH, simply pass the
00586799 359same cookie as before and all matches matching the same "cookie" value
6206f4b4 360will be removed. This is particularly handy for the case where multiple
00586799
LP
361ioctl()s are added for a single match strings.
362
363MEMFDS
364
00586799 365memfds may be sent across kdbus via KDBUS_ITEM_PAYLOAD_MEMFD items
061eab67 366attached to messages. If this is done, the data included in the memfd
00586799
LP
367is considered part of the payload stream of a message, and are treated
368the same way as KDBUS_ITEM_PAYLOAD_VEC by the receiving side. It is
369possible to interleave KDBUS_ITEM_PAYLOAD_MEMFD and
370KDBUS_ITEM_PAYLOAD_VEC items freely, by the reader they will be
371considered a single stream of bytes in the order these items appear in
372the message, that just happens to be split up at various places
373(regarding rules how they may be split up, see above). The kernel will
374refuse taking KDBUS_ITEM_PAYLOAD_MEMFD items that refer to memfds that
375are not sealed.
376
377Note that sealed memfds may be unsealed again if they are not mapped
378you have the only fd reference to them.
379
380Alternatively to sending memfds as KDBUS_ITEM_PAYLOAD_MEMFD items
061eab67
KS
381(where they are just a part of the payload stream of a message) you can
382also simply attach any memfd to a message using
383KDBUS_ITEM_PAYLOAD_FDS. In this case, the memfd contents is not
00586799 384considered part of the payload stream of the message, but simply fds
061eab67 385like any other, that happen to be attached to the message.
00586799
LP
386
387MESSAGES FROM THE KERNEL
388
6206f4b4 389A couple of messages previously generated by the dbus1 bus driver are
00586799 390now generated by the kernel. Since the kernel does not understand the
061eab67 391payload marshaling, they are generated by the kernel in a different
f000939e 392format. This is indicated with the "payload type" field of the
00586799
LP
393messages set to 0. Library implementations should take these messages
394and synthesize traditional driver messages for them on reception.
395
396More specifically:
397
398 Instead of the NameOwnerChanged, NameLost, NameAcquired signals
399 there are kernel messages containing KDBUS_ITEM_NAME_ADD,
400 KDBUS_ITEM_NAME_REMOVE, KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD,
401 KDBUS_ITEM_ID_REMOVE items are generated (each message will contain
6bb648a1 402 exactly one of these items). Note that in libsystemd we have
00586799
LP
403 obsoleted NameLost/NameAcquired messages, since they are entirely
404 redundant to NameOwnerChanged. This library will hence only
405 synthesize NameOwnerChanged messages from these kernel messages,
061eab67 406 and never generate NameLost/NameAcquired. If your library needs to
00586799
LP
407 stay compatible to the old dbus1 userspace, you possibly might need
408 to synthesize both a NameOwnerChanged and NameLost/NameAcquired
409 message from the same kernel message.
410
061eab67 411 When a method call times out, a KDBUS_ITEM_REPLY_TIMEOUT message is
00586799
LP
412 generated. This should be synthesized into a method error reply
413 message to the original call.
414
415 When a method call fails because the peer terminated the connection
061eab67 416 before responding, a KDBUS_ITEM_REPLY_DEAD message is
0a6de115 417 generated. Similarly, it should be synthesized into a method error
00586799
LP
418 reply message.
419
420For synthesized messages we recommend setting the cookie field to
421(uint32_t) -1 (and not (uint64_t) -1!), so that the cookie is not 0
422(which the dbus1 spec does not allow), but clearly recognizable as
423synthetic.
424
425Note that the KDBUS_ITEM_NAME_XYZ messages will actually inform you
426about all kinds of names, including activatable ones. Classic dbus1
427NameOwnerChanged messages OTOH are only generated when a name is
428really acquired on the bus and not just simply activatable. This means
6206f4b4 429you must explicitly check for the case where an activatable name
00586799
LP
430becomes acquired or an acquired name is lost and returns to be
431activatable.
432
433NAME REGISTRY
434
061eab67 435To acquire names on the bus, use the KDBUS_CMD_NAME_ACQUIRE ioctl(). It
00586799
LP
436takes a flags field similar to dbus1's RequestName() bus driver call,
437however the NO_QUEUE flag got inverted into a QUEUE flag instead.
438
6206f4b4 439To release a previously acquired name use the KDBUS_CMD_NAME_RELEASE
00586799
LP
440ioctl().
441
442To list acquired names use the KDBUS_CMD_CONN_INFO ioctl. It may be
443used to list unique names, well known names as well as activatable
6206f4b4 444names and clients currently queuing for ownership of a well-known
00586799 445name. The ioctl will return an offset into the memory pool. After
061eab67 446reading all the data you need, you need to release this via the
00586799
LP
447KDBUS_CMD_FREE ioctl(), similar how you release a received message.
448
00586799
LP
449CREDENTIALS
450
061eab67 451kdbus can optionally attach various kinds of metadata about the sender at
00586799
LP
452the point of time of sending ("credentials") to messages, on request
453of the receiver. This is both supported on directed and undirected
454(broadcast) messages. The metadata to attach is selected at time of
455the HELLO ioctl of the receiver via a flags field (see above). Note
456that clients must be able to handle that messages contain more
457metadata than they asked for themselves, to simplify implementation of
458broadcasting in the kernel. The receiver should not rely on this data
459to be around though, even though it will be correct if it happens to
061eab67 460be attached. In order to avoid programming errors in applications, we
f000939e 461recommend though not passing this data on to clients that did not
00586799
LP
462explicitly ask for it.
463
464Credentials may also be queried for a well-known or unique name. Use
465the KDBUS_CMD_CONN_INFO for this. It will return an offset to the pool
466area again, which will contain the same credential items as messages
061eab67
KS
467have attached. Note that when issuing the ioctl, you can select a
468different set of credentials to gather, than what was originally requested
00586799
LP
469for being attached to incoming messages.
470
486e99a3 471Credentials are always specific to the sender's domain that was
6206f4b4 472current at the time of sending, and of the process that opened the
00586799
LP
473bus connection at the time of opening it. Note that this latter data
474is cached!
475
476POLICY
477
478The kernel enforces only very limited policy on names. It will not do
479access filtering by userspace payload, and thus not by interface or
480method name.
481
6206f4b4 482This ultimately means that most fine-grained policy enforcement needs
00586799
LP
483to be done by the receiving process. We recommend using PolicyKit for
484any more complex checks. However, libraries should make simple static
485policy decisions regarding privileged/unprivileged method calls
486easy. We recommend doing this by enabling KDBUS_ATTACH_CAPS and
487KDBUS_ATTACH_CREDS for incoming messages, and then discerning client
061eab67 488access by some capability, or if sender and receiver UIDs match.
00586799
LP
489
490BUS ADDRESSES
491
492When connecting to kdbus use the "kernel:" protocol prefix in DBus
493address strings. The device node path is encoded in its "path="
494parameter.
495
496Client libraries should use the following connection string when
497connecting to the system bus:
498
63cc4c31 499 kernel:path=/sys/fs/kdbus/0-system/bus;unix:path=/var/run/dbus/system_bus_socket
00586799
LP
500
501This will ensure that kdbus is preferred over the legacy AF_UNIX
502socket, but compatibility is kept. For the user bus use:
503
63cc4c31 504 kernel:path=/sys/fs/kdbus/$UID-user/bus;unix:path=$XDG_RUNTIME_DIR/bus
00586799
LP
505
506With $UID replaced by the callers numer user ID, and $XDG_RUNTIME_DIR
507following the XDG basedir spec.
508
509Of course the $DBUS_SYSTEM_BUS_ADDRESS and $DBUS_SESSION_BUS_ADDRESS
510variables should still take precedence.
511
9129246b
LP
512DBUS SERVICE FILES
513
514Activatable services for kdbus may not use classic dbus1 service
515activation files. Instead, programs should drop in native systemd
516.service and .busname unit files, so that they are treated uniformly
517with other types of units and activation of the system.
518
519Note that this results in a major difference to classic dbus1:
061eab67
KS
520activatable bus names can be established at any time in the boot process.
521This is unlike dbus1 where activatable names are unconditionally available
9129246b
LP
522as long as dbus-daemon is running. Being able to control when
523activatable names are established is essential to allow usage of kdbus
524during early boot and in initrds, without the risk of triggering
525services too early.
526
00586799
LP
527DISCLAIMER
528
061eab67 529This all is so far just the status quo. We are putting this together, because
00586799
LP
530we are quite confident that further API changes will be smaller, but
531to make this very clear: this is all subject to change, still!
532
6206f4b4 533We invite you to port over your favorite dbus library to this new
00586799
LP
534scheme, but please be prepared to make minor changes when we still
535change these interfaces!