]>
Commit | Line | Data |
---|---|---|
6206f4b4 | 1 | A few hints on supporting kdbus as backend in your favorite D-Bus library. |
00586799 LP |
2 | |
3 | ~~~ | |
4 | ||
5 | Before you read this, have a look at the DIFFERENCES and | |
0a6de115 | 6 | GVARIANT_SERIALIZATION texts you find in the same directory where you |
00586799 LP |
7 | found this. |
8 | ||
6206f4b4 | 9 | We invite you to port your favorite D-Bus protocol implementation |
00586799 | 10 | over to kdbus. However, there are a couple of complexities |
6206f4b4 KS |
11 | involved. On kdbus we only speak GVariant marshaling, kdbus clients |
12 | ignore traffic in dbus1 marshaling. Thus, you need to add a second, | |
0a6de115 | 13 | GVariant compatible marshaler to your library first. |
00586799 LP |
14 | |
15 | After you have done that: here's the basic principle how kdbus works: | |
16 | ||
63cc4c31 | 17 | You connect to a bus by opening its bus node in /sys/fs/kdbus/. All |
0a6de115 | 18 | buses have a device node there, it starts with a numeric UID of the |
00586799 | 19 | owner of the bus, followed by a dash and a string identifying the |
63cc4c31 DM |
20 | bus. The system bus is thus called /sys/fs/kdbus/0-system, and for user |
21 | buses the device node is /sys/fs/kdbus/1000-user (if 1000 is your user | |
00586799 LP |
22 | id). |
23 | ||
6bb648a1 | 24 | (Before we proceed, please always keep a copy of libsystemd next |
00586799 LP |
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 | ||
0a6de115 | 30 | To connect to a bus, simply open() its device node and issue the |
00586799 LP |
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 | |
0a6de115 | 36 | parameters that you need to know, to operate on the bus. |
00586799 LP |
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 | |
061eab67 | 45 | features you support. When the ioctl returns, it will contain the |
00586799 LP |
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 | |
847657c7 LP |
54 | "incompatible" feature must not proceed with the connection. When a |
55 | client encountes such an "incompatible" feature it should immediately | |
56 | try the next bus address configured in the bus address string. | |
00586799 LP |
57 | |
58 | The hello structure also contains another flags field "attach_flags" | |
0a6de115 | 59 | which indicates metadata that is optionally attached to all incoming |
00586799 LP |
60 | messages. You probably want to set KDBUS_ATTACH_NAMES unconditionally |
61 | in it. This has the effect that all well-known names of a sender are | |
62 | attached to all incoming messages. You need this information to | |
63 | implement matches that match on a message sender name correctly. Of | |
061eab67 | 64 | course, you should only request the attachment of as little metadata |
00586799 LP |
65 | fields as you need. |
66 | ||
67 | The kernel will return in the "id" field your unique id. This is a | |
68 | simple numeric value. For compatibility with classic dbus1 simply | |
e1ffdb90 | 69 | format this as string and prefix ":1.". |
00586799 | 70 | |
847657c7 LP |
71 | The kernel will also return the bloom filter size and bloom filter |
72 | hash function number used for the signal broadcast bloom filter (see | |
73 | below). | |
00586799 | 74 | |
f000939e | 75 | The kernel will also return the bus ID of the bus in a 128bit field. |
00586799 | 76 | |
0a6de115 | 77 | The pool size field specifies the size of the memory mapped buffer. |
00586799 | 78 | After the calling the hello ioctl, you should memory map the kdbus |
0a6de115 KS |
79 | fd. In this memory mapped region, the kernel will place all your incoming |
80 | messages. | |
00586799 LP |
81 | |
82 | SENDING MESSAGES | |
83 | ||
84 | Use the MSG_SEND ioctl to send a message to another peer. The ioctl | |
85 | takes a structure that contains a variety of fields: | |
86 | ||
87 | The flags field corresponds closely to the old dbus1 message header | |
88 | flags field, though the DONT_EXPECT_REPLY field got inverted into | |
89 | EXPECT_REPLY. | |
90 | ||
91 | The dst_id/src_id field contains the unique id of the destination and | |
6206f4b4 | 92 | the sender. The sender field is overridden by the kernel usually, hence |
00586799 LP |
93 | you shouldn't fill it in. The destination field can also take the |
94 | special value KDBUS_DST_ID_BROADCAST for broadcast messages. For | |
95 | messages intended to a well-known name set the field to | |
96 | KDBUS_DST_ID_NAME, and attach the name in a special "items" entry to | |
97 | the message (see below). | |
98 | ||
99 | The payload field indicates the payload. For all dbus traffic it | |
100 | should carry the value 0x4442757344427573ULL. (Which encodes | |
101 | 'DBusDBus'). | |
102 | ||
103 | The cookie field corresponds with the "serial" field of classic | |
104 | dbus1. We simply renamed it here (and extended it to 64bit) since we | |
105 | didn't want to imply the monotonicity of the assignment the way the | |
106 | word "serial" indicates it. | |
107 | ||
108 | When sending a message that expects a reply, you need to set the | |
109 | EXPECT_REPLY flag in the message flag field. In this case you should | |
110 | also fill out the "timeout_ns" value which indicates the timeout in | |
111 | nsec for this call. If the peer does not respond in this time you will | |
6206f4b4 | 112 | get a notification of a timeout. Note that this is also used for |
00586799 LP |
113 | security purposes: a single reply messages is only allowed through the |
114 | bus as long as the timeout has not ended. With this timeout value you | |
115 | hence "open a time window" in which the peer might respond to your | |
116 | request and the policy allows the response to go through. | |
117 | ||
118 | When sending a message that is a reply, you need to fill in the | |
119 | cookie_reply field, which is similar to the reply_serial field of | |
120 | dbus1. Note that a message cannot have EXPECT_REPLY and a reply_serial | |
121 | at the same time! | |
122 | ||
123 | This pretty much explains the ioctl header. The actual payload of the | |
124 | data is now referenced in additional items that are attached to this | |
125 | ioctl header structure at the end. When sending a message, you attach | |
5fa4ddb8 LS |
126 | items of the type PAYLOAD_VEC, PAYLOAD_MEMFD, FDS, BLOOM_FILTER, |
127 | DST_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 | 147 | A single message may consists of no, one or more payload items of type |
00586799 LP |
148 | PAYLOAD_VEC or PAYLOAD_MEMFD. D-Bus protocol implementations should |
149 | treat them as a single block that just happens to be split up into | |
150 | multiple 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 | 170 | Note again, that splitting up messages into separate items is up to the |
00586799 | 171 | implementation. Also note that the kdbus kernel side might merge |
6206f4b4 | 172 | separate items if it deems this to be useful. However, the order in |
00586799 LP |
173 | which items are contained in the message is left untouched. |
174 | ||
175 | PAYLOAD_MEMFD items allow zero-copy data transfer (see below regarding | |
176 | the memfd concept). Note however that the overhead of mapping these | |
177 | makes them relatively expensive, and only worth the trouble for memory | |
1fa13293 | 178 | blocks > 512K (this value appears to be quite universal across |
00586799 LP |
179 | architectures, as we tested). Thus we recommend sending PAYLOAD_VEC |
180 | items over for small messages and restore to PAYLOAD_MEMFD items for | |
1fa13293 | 181 | messages > 512K. Since while building up the message you might not |
00586799 LP |
182 | know yet whether it will grow beyond this boundary a good approach is |
183 | to simply build the message unconditionally in a memfd | |
184 | object. However, when the message is sealed to be sent away check for | |
1fa13293 KS |
185 | the size limit. If the size of the message is < 512K, then simply send |
186 | the data as PAYLOAD_VEC and reuse the memfd. If it is >= 512K, seal | |
00586799 LP |
187 | the memfd and send it as PAYLOAD_MEMFD, and allocate a new memfd for |
188 | the next message. | |
189 | ||
190 | RECEIVING MESSAGES | |
191 | ||
192 | Use the MSG_RECV ioctl to read a message from kdbus. This will return | |
193 | an offset into the pool memory map, relative to its beginning. | |
194 | ||
195 | The received message structure more or less follows the structure of | |
196 | the message originally sent. However, certain changes have been | |
197 | made. In the header the src_id field will be filled in. | |
198 | ||
199 | The payload items might have gotten merged and PAYLOAD_VEC items are | |
061eab67 | 200 | not used. Instead, you will only find PAYLOAD_OFF and PAYLOAD_MEMFD |
00586799 LP |
201 | items. The former contain an offset and size into your memory mapped |
202 | pool where you find the payload. | |
203 | ||
0a6de115 | 204 | If during the HELLO ioctl you asked for getting metadata attached to |
061eab67 | 205 | your message, you will find additional KDBUS_ITEM_CREDS, |
00586799 LP |
206 | KDBUS_ITEM_PID_COMM, KDBUS_ITEM_TID_COMM, KDBUS_ITEM_TIMESTAMP, |
207 | KDBUS_ITEM_EXE, KDBUS_ITEM_CMDLINE, KDBUS_ITEM_CGROUP, | |
208 | KDBUS_ITEM_CAPS, KDBUS_ITEM_SECLABEL, KDBUS_ITEM_AUDIT items that | |
061eab67 KS |
209 | contain this metadata. This metadata will be gathered from the sender |
210 | at the point in time it sends the message. This information is | |
211 | uncached, and since it is appended by the kernel, trustable. The | |
212 | KDBUS_ITEM_SECLABEL item usually contains the SELinux security label, | |
00586799 LP |
213 | if it is used. |
214 | ||
215 | After processing the message you need to call the KDBUS_CMD_FREE | |
216 | ioctl, which releases the message from the pool, and allows the kernel | |
217 | to store another message there. Note that the memory used by the pool | |
061eab67 | 218 | is ordinary anonymous, swappable memory that is backed by tmpfs. Hence |
00586799 LP |
219 | there is no need to copy the message out of it quickly, instead you |
220 | can just leave it there as long as you need it and release it via the | |
221 | FREE ioctl only after that's done. | |
222 | ||
223 | BLOOM FILTERS | |
224 | ||
6206f4b4 | 225 | The kernel does not understand dbus marshaling, it will not look into |
00586799 | 226 | the message payload. To allow clients to subscribe to specific subsets |
6206f4b4 | 227 | of the broadcast matches we employ bloom filters. |
00586799 | 228 | |
061eab67 | 229 | When broadcasting messages, a bloom filter needs to be attached to the |
00586799 LP |
230 | message in a KDBUS_ITEM_BLOOM item (and only for broadcasting |
231 | messages!). If you don't know what bloom filters are, read up now on | |
232 | Wikipedia. In short: they are a very efficient way how to | |
233 | probabilistically check whether a certain word is contained in a | |
234 | vocabulary. It knows no false negatives, but it does know false | |
235 | positives. | |
236 | ||
b28ff39f LP |
237 | The parameters for the bloom filters that need to be included in |
238 | broadcast message is communicated to userspace as part of the hello | |
847657c7 LP |
239 | response 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 | |
241 | this is subject to change in later versions, and userspace | |
242 | implementations must be capable of handling m values between at least | |
243 | m=8 and m=2^32, and k values between at least k=1 and k=32. The | |
244 | underlying hash function is SipHash-2-4. It is used with a number of | |
245 | constant (yet originally randomly generated) 128bit hash keys, more | |
246 | specifically: | |
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 | ||
257 | When calculating the first bit index into the bloom filter, the | |
258 | SipHash-2-4 hash value is calculated for the input data and the first | |
259 | 16 bytes of the array above as hash key. Of the resulting 8 bytes of | |
847657c7 | 260 | output, as many full bytes are taken for the bit index as necessary, |
b28ff39f LP |
261 | starting from the output's first byte. For the second bit index the |
262 | same hash value is used, continuing with the next unused output byte, | |
263 | and so on. Each time the bytes returned by the hash function are | |
264 | depleted it is recalculated with the next 16 byte hash key from the | |
265 | array above and the same input data. | |
00586799 LP |
266 | |
267 | For each message to send across the bus we populate the bloom filter | |
268 | with all possible matchable strings. If a client then wants to | |
061eab67 | 269 | subscribe to messages of this type, it simply tells the kernel to test |
00586799 LP |
270 | its own calculated bit mask against the bloom filter of each message. |
271 | ||
061eab67 KS |
272 | More specifically, the following strings are added to the bloom filter |
273 | of 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 |
307 | names!) |
308 | ||
309 | When a client wants to subscribe to messages matching a certain | |
061eab67 | 310 | expression, it should calculate the bloom mask following the same |
6206f4b4 | 311 | algorithm. The kernel will then simply test the mask against the |
00586799 LP |
312 | attached bloom filters. |
313 | ||
314 | Note that bloom filters are probabilistic, which means that clients | |
6206f4b4 | 315 | might get messages they did not expect. Your bus protocol |
00586799 LP |
316 | implementation must be capable of dealing with these unexpected |
317 | messages (which it needs to anyway, given that transfers are | |
318 | relatively unrestricted on kdbus and people can send you all kinds of | |
061eab67 | 319 | non-sense). |
00586799 | 320 | |
847657c7 LP |
321 | If a client connects to a bus whose bloom filter metrics (i.e. filter |
322 | size and number of hash functions) are outside of the range the client | |
323 | supports it must immediately disconnect and continue connection with | |
324 | the next bus address of the bus connection string. | |
325 | ||
00586799 LP |
326 | INSTALLING MATCHES |
327 | ||
061eab67 | 328 | To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH |
00586799 LP |
329 | ioctl. It takes a structure that contains an encoded match expression, |
330 | and that is followed by one or more items, which are combined in an | |
061eab67 | 331 | AND way. (Meaning: a message is matched exactly when all items |
00586799 LP |
332 | attached to the original ioctl struct match). |
333 | ||
334 | To match against other user messages add a KDBUS_ITEM_BLOOM item in | |
335 | the match (see above). Note that the bloom filter does not include | |
336 | matches to the sender names. To additionally check against sender | |
337 | names, use the KDBUS_ITEM_ID (for unique id matches) and | |
338 | KDBUS_ITEM_NAME (for well-known name matches) item types. | |
339 | ||
340 | To match against kernel generated messages (see below) you should add | |
341 | items of the same type as the kernel messages include, | |
342 | i.e. KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE, | |
343 | KDBUS_ITEM_NAME_CHANGE, KDBUS_ITEM_ID_ADD, KDBUS_ITEM_ID_REMOVE and | |
344 | fill them out. Note however, that you have some wildcards in this | |
6d6c604a | 345 | case, for example the .id field of KDBUS_ITEM_ID_ADD/KDBUS_ITEM_ID_REMOVE |
00586799 LP |
346 | structures may be set to 0 to match against any id addition/removal. |
347 | ||
348 | Note that dbus match strings do no map 1:1 to these ioctl() calls. In | |
349 | many cases (where the match string is "underspecified") you might need | |
350 | to issue up to six different ioctl() calls for the same match. For | |
351 | example, the empty match (which matches against all messages), would | |
352 | translate into one KDBUS_ITEM_BLOOM ioctl, one KDBUS_ITEM_NAME_ADD, | |
353 | one KDBUS_ITEM_NAME_CHANGE, one KDBUS_ITEM_NAME_REMOVE, one | |
354 | KDBUS_ITEM_ID_ADD and one KDBUS_ITEM_ID_REMOVE. | |
355 | ||
061eab67 KS |
356 | When creating a match, you may attach a "cookie" value to them, which |
357 | is used for deleting this match again. The cookie can be selected freely | |
358 | by the client. When issuing KDBUS_CMD_REMOVE_MATCH, simply pass the | |
00586799 | 359 | same cookie as before and all matches matching the same "cookie" value |
6206f4b4 | 360 | will be removed. This is particularly handy for the case where multiple |
00586799 LP |
361 | ioctl()s are added for a single match strings. |
362 | ||
363 | MEMFDS | |
364 | ||
00586799 | 365 | memfds may be sent across kdbus via KDBUS_ITEM_PAYLOAD_MEMFD items |
061eab67 | 366 | attached to messages. If this is done, the data included in the memfd |
00586799 LP |
367 | is considered part of the payload stream of a message, and are treated |
368 | the same way as KDBUS_ITEM_PAYLOAD_VEC by the receiving side. It is | |
369 | possible to interleave KDBUS_ITEM_PAYLOAD_MEMFD and | |
370 | KDBUS_ITEM_PAYLOAD_VEC items freely, by the reader they will be | |
371 | considered a single stream of bytes in the order these items appear in | |
372 | the 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 | |
374 | refuse taking KDBUS_ITEM_PAYLOAD_MEMFD items that refer to memfds that | |
375 | are not sealed. | |
376 | ||
377 | Note that sealed memfds may be unsealed again if they are not mapped | |
378 | you have the only fd reference to them. | |
379 | ||
380 | Alternatively 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 |
382 | also simply attach any memfd to a message using | |
383 | KDBUS_ITEM_PAYLOAD_FDS. In this case, the memfd contents is not | |
00586799 | 384 | considered part of the payload stream of the message, but simply fds |
061eab67 | 385 | like any other, that happen to be attached to the message. |
00586799 LP |
386 | |
387 | MESSAGES FROM THE KERNEL | |
388 | ||
6206f4b4 | 389 | A couple of messages previously generated by the dbus1 bus driver are |
00586799 | 390 | now generated by the kernel. Since the kernel does not understand the |
061eab67 | 391 | payload marshaling, they are generated by the kernel in a different |
f000939e | 392 | format. This is indicated with the "payload type" field of the |
00586799 LP |
393 | messages set to 0. Library implementations should take these messages |
394 | and synthesize traditional driver messages for them on reception. | |
395 | ||
396 | More 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 | ||
420 | For 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 | |
423 | synthetic. | |
424 | ||
425 | Note that the KDBUS_ITEM_NAME_XYZ messages will actually inform you | |
426 | about all kinds of names, including activatable ones. Classic dbus1 | |
427 | NameOwnerChanged messages OTOH are only generated when a name is | |
428 | really acquired on the bus and not just simply activatable. This means | |
6206f4b4 | 429 | you must explicitly check for the case where an activatable name |
00586799 LP |
430 | becomes acquired or an acquired name is lost and returns to be |
431 | activatable. | |
432 | ||
433 | NAME REGISTRY | |
434 | ||
061eab67 | 435 | To acquire names on the bus, use the KDBUS_CMD_NAME_ACQUIRE ioctl(). It |
00586799 LP |
436 | takes a flags field similar to dbus1's RequestName() bus driver call, |
437 | however the NO_QUEUE flag got inverted into a QUEUE flag instead. | |
438 | ||
6206f4b4 | 439 | To release a previously acquired name use the KDBUS_CMD_NAME_RELEASE |
00586799 LP |
440 | ioctl(). |
441 | ||
442 | To list acquired names use the KDBUS_CMD_CONN_INFO ioctl. It may be | |
443 | used to list unique names, well known names as well as activatable | |
6206f4b4 | 444 | names and clients currently queuing for ownership of a well-known |
00586799 | 445 | name. The ioctl will return an offset into the memory pool. After |
061eab67 | 446 | reading all the data you need, you need to release this via the |
00586799 LP |
447 | KDBUS_CMD_FREE ioctl(), similar how you release a received message. |
448 | ||
00586799 LP |
449 | CREDENTIALS |
450 | ||
061eab67 | 451 | kdbus can optionally attach various kinds of metadata about the sender at |
00586799 LP |
452 | the point of time of sending ("credentials") to messages, on request |
453 | of the receiver. This is both supported on directed and undirected | |
454 | (broadcast) messages. The metadata to attach is selected at time of | |
455 | the HELLO ioctl of the receiver via a flags field (see above). Note | |
456 | that clients must be able to handle that messages contain more | |
457 | metadata than they asked for themselves, to simplify implementation of | |
458 | broadcasting in the kernel. The receiver should not rely on this data | |
459 | to be around though, even though it will be correct if it happens to | |
061eab67 | 460 | be attached. In order to avoid programming errors in applications, we |
f000939e | 461 | recommend though not passing this data on to clients that did not |
00586799 LP |
462 | explicitly ask for it. |
463 | ||
464 | Credentials may also be queried for a well-known or unique name. Use | |
465 | the KDBUS_CMD_CONN_INFO for this. It will return an offset to the pool | |
466 | area again, which will contain the same credential items as messages | |
061eab67 KS |
467 | have attached. Note that when issuing the ioctl, you can select a |
468 | different set of credentials to gather, than what was originally requested | |
00586799 LP |
469 | for being attached to incoming messages. |
470 | ||
486e99a3 | 471 | Credentials are always specific to the sender's domain that was |
6206f4b4 | 472 | current at the time of sending, and of the process that opened the |
00586799 LP |
473 | bus connection at the time of opening it. Note that this latter data |
474 | is cached! | |
475 | ||
476 | POLICY | |
477 | ||
478 | The kernel enforces only very limited policy on names. It will not do | |
479 | access filtering by userspace payload, and thus not by interface or | |
480 | method name. | |
481 | ||
6206f4b4 | 482 | This ultimately means that most fine-grained policy enforcement needs |
00586799 LP |
483 | to be done by the receiving process. We recommend using PolicyKit for |
484 | any more complex checks. However, libraries should make simple static | |
485 | policy decisions regarding privileged/unprivileged method calls | |
486 | easy. We recommend doing this by enabling KDBUS_ATTACH_CAPS and | |
487 | KDBUS_ATTACH_CREDS for incoming messages, and then discerning client | |
061eab67 | 488 | access by some capability, or if sender and receiver UIDs match. |
00586799 LP |
489 | |
490 | BUS ADDRESSES | |
491 | ||
492 | When connecting to kdbus use the "kernel:" protocol prefix in DBus | |
493 | address strings. The device node path is encoded in its "path=" | |
494 | parameter. | |
495 | ||
496 | Client libraries should use the following connection string when | |
497 | connecting 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 | |
501 | This will ensure that kdbus is preferred over the legacy AF_UNIX | |
502 | socket, 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 | |
506 | With $UID replaced by the callers numer user ID, and $XDG_RUNTIME_DIR | |
507 | following the XDG basedir spec. | |
508 | ||
509 | Of course the $DBUS_SYSTEM_BUS_ADDRESS and $DBUS_SESSION_BUS_ADDRESS | |
510 | variables should still take precedence. | |
511 | ||
9129246b LP |
512 | DBUS SERVICE FILES |
513 | ||
514 | Activatable services for kdbus may not use classic dbus1 service | |
515 | activation files. Instead, programs should drop in native systemd | |
516 | .service and .busname unit files, so that they are treated uniformly | |
517 | with other types of units and activation of the system. | |
518 | ||
519 | Note that this results in a major difference to classic dbus1: | |
061eab67 KS |
520 | activatable bus names can be established at any time in the boot process. |
521 | This is unlike dbus1 where activatable names are unconditionally available | |
9129246b LP |
522 | as long as dbus-daemon is running. Being able to control when |
523 | activatable names are established is essential to allow usage of kdbus | |
524 | during early boot and in initrds, without the risk of triggering | |
525 | services too early. | |
526 | ||
00586799 LP |
527 | DISCLAIMER |
528 | ||
061eab67 | 529 | This all is so far just the status quo. We are putting this together, because |
00586799 LP |
530 | we are quite confident that further API changes will be smaller, but |
531 | to make this very clear: this is all subject to change, still! | |
532 | ||
6206f4b4 | 533 | We invite you to port over your favorite dbus library to this new |
00586799 LP |
534 | scheme, but please be prepared to make minor changes when we still |
535 | change these interfaces! |