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