kdbus kdbus 7 kdbus Kernel Message Bus kdbus is an inter-process communication bus system controlled by the kernel. It provides user-space with an API to create buses and send unicast and multicast messages to one, or many, peers connected to the same bus. It does not enforce any layout on the transmitted data, but only provides the transport layer used for message interchange between peers. This set of man-pages gives a comprehensive overview of the kernel-level API, with all ioctl commands, associated structs and bit masks. However, most people will not use this API level directly, but rather let one of the high-level abstraction libraries help them integrate D-Bus functionality into their applications. kdbus provides a pseudo filesystem called kdbusfs, which is usually mounted on /sys/fs/kdbus. Bus primitives can be accessed as files and sub-directories underneath this mount-point. Any advanced operations are done via ioctl() on files created by kdbusfs. Multiple mount-points of kdbusfs are independent of each other. This allows namespacing of kdbus by mounting a new instance of kdbusfs in a new mount-namespace. kdbus calls these mount instances domains and each bus belongs to exactly one domain. kdbus was designed as a transport layer for D-Bus, but is in no way limited, nor controlled by the D-Bus protocol specification. The D-Bus protocol is one possible application layer on top of kdbus. For the general D-Bus protocol specification, its payload format, its marshaling, and its communication semantics, please refer to the D-Bus specification. A domain is a kdbusfs mount-point containing all the bus primitives. Each domain is independent, and separate domains do not affect each other. A bus is a named object inside a domain. Clients exchange messages over a bus. Multiple buses themselves have no connection to each other; messages can only be exchanged on the same bus. The default endpoint of a bus, to which clients establish connections, is the "bus" file /sys/fs/kdbus/<bus name>/bus. Common operating system setups create one "system bus" per system, and one "user bus" for every logged-in user. Applications or services may create their own private buses. The kernel driver does not distinguish between different bus types, they are all handled the same way. See kdbus.bus 7 for more details. An endpoint provides a file to talk to a bus. Opening an endpoint creates a new connection to the bus to which the endpoint belongs. All endpoints have unique names and are accessible as files underneath the directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint> Every bus has a default endpoint called "bus". A bus can optionally offer additional endpoints with custom names to provide restricted access to the bus. Custom endpoints carry additional policy which can be used to create sandboxes with locked-down, limited, filtered access to a bus. See kdbus.endpoint 7 for more details. A connection to a bus is created by opening an endpoint file of a bus. Every ordinary client connection has a unique identifier on the bus and can address messages to every other connection on the same bus by using the peer's connection ID as the destination. See kdbus.connection 7 for more details. Each connection allocates a piece of shmem-backed memory that is used to receive messages and answers to ioctl commands from the kernel. It is never used to send anything to the kernel. In order to access that memory, an application must mmap() it into its address space. See kdbus.pool 7 for more details. A connection can, in addition to its implicit unique connection ID, request the ownership of a textual well-known name. Well-known names are noted in reverse-domain notation, such as com.example.service1. A connection that offers a service on a bus is usually reached by its well-known name. An analogy of connection ID and well-known name is an IP address and a DNS name associated with that address. See kdbus.name 7 for more details. Connections can exchange messages with other connections by addressing the peers with their connection ID or well-known name. A message consists of a message header with information on how to route the message, and the message payload, which is a logical byte stream of arbitrary size. Messages can carry additional file descriptors to be passed from one connection to another, just like passing file descriptors over UNIX domain sockets. Every connection can specify which set of metadata the kernel should attach to the message when it is delivered to the receiving connection. Metadata contains information like: system time stamps, UID, GID, TID, proc-starttime, well-known names, process comm, process exe, process argv, cgroup, capabilities, seclabel, audit session, loginuid and the connection's human-readable name. See kdbus.message 7 for more details. The API of kdbus implements the notion of items, submitted through and returned by most ioctls, and stored inside data structures in the connection's pool. See kdbus.item 7 for more details. Signals are messages that a receiver opts in for by installing a blob of bytes, called a 'match'. Signal messages must always carry a counter-part blob, called a 'filter', and signals are only delivered to peers which have a match that white-lists the message's filter. Senders of signal messages can use either a single connection ID as receiver, or the special connection ID KDBUS_DST_ID_BROADCAST to potentially send it to all connections of a bus, following the logic described above. See kdbus.match 7 and kdbus.message 7 for more details. A policy is a set of rules that define which connections can see, talk to, or register a well-known name on the bus. A policy is attached to buses and custom endpoints, and modified by policy holder connections or owners of custom endpoints. See kdbus.policy 7 for more details. A user connecting to the bus is considered privileged if it is either the creator of the bus, or if it has the CAP_IPC_OWNER capability flag set. See kdbus.connection 7 for more details. A bus provides and defines an environment that peers can connect to for message interchange. A bus is created via the kdbus control interface and can be modified by the bus creator. It applies the policy that control all bus operations. The bus creator itself does not participate as a peer. To establish a peer connection, you have to open one of the endpoints of a bus. Each bus provides a default endpoint, but further endpoints can be created on-demand. Endpoints are used to apply additional policies for all connections on this endpoint. Thus, they provide additional filters to further restrict access of specific connections to the bus. Following, you can see an example bus layout: kdbus records data about the system in certain situations. Such metadata can refer to the currently active process (creds, PIDs, current user groups, process names and its executable path, cgroup membership, capabilities, security label and audit information), connection information (description string, currently owned names) and time stamps. Metadata is collected at the following times. When a bus is created (KDBUS_CMD_MAKE), information about the calling task is collected. This data is returned by the kernel via the KDBUS_CMD_BUS_CREATOR_INFO call. When a connection is created (KDBUS_CMD_HELLO), information about the calling task is collected. Alternatively, a privileged connection may provide 'faked' information about credentials, PIDs and security labels which will be stored instead. This data is returned by the kernel as information on a connection (KDBUS_CMD_CONN_INFO). Only metadata that a connection allowed to be sent (by setting its bit in attach_flags_send) will be exported in this way. When a message is sent (KDBUS_CMD_SEND), information about the sending task and the sending connection is collected. This metadata will be attached to the message when it arrives in the receiver's pool. If the connection sending the message installed faked credentials (see kdbus.connection 7 ), the message will not be augmented by any information about the currently sending task. Note that only metadata that was requested by the receiving connection will be collected and attached to messages. Which metadata items are actually delivered depends on the following sets and masks: (a) the system-wide kmod creds mask (module parameter attach_flags_mask) (b) the per-connection send creds mask, set by the connecting client (c) the per-connection receive creds mask, set by the connecting client (d) the per-bus minimal creds mask, set by the bus creator (e) the per-bus owner creds mask, set by the bus creator (f) the mask specified when querying creds of a bus peer (g) the mask specified when querying creds of a bus owner With the following rules: [1] The creds attached to messages are determined as a & b & c. [2] When connecting to a bus (KDBUS_CMD_HELLO), and ~b & d != 0, the call will fail with, -1, and errno is set to ECONNREFUSED. [3] When querying creds of a bus peer, the creds returned are a & b & f. [4] When querying creds of a bus owner, the creds returned are a & e & g. Hence, programs might not always get all requested metadata items that it requested. Code must be written so that it can cope with this fact. Attaching metadata to messages has two major benefits. Metadata attached to messages is gathered at the moment when the other side calls KDBUS_CMD_SEND, or, respectively, then the kernel notification is generated. There is no need for the receiving peer to retrieve information about the task in a second step. This closes a race gap that would otherwise be inherent. As metadata is delivered along with messages in the same data blob, no extra calls to kernel functions etc. are needed to gather them. Note, however, that collecting metadata does come at a price for performance, so developers should carefully assess which metadata to really opt-in for. For best practice, data that is not needed as part of a message should not be requested by the connection in the first place (see attach_flags_recv in KDBUS_CMD_HELLO). To let the kernel know which metadata information to attach as items to the aforementioned commands, it uses a bitmask. In those, the following attach flags are currently supported. Both the attach_flags_recv and attach_flags_send fields of struct kdbus_cmd_hello, as well as the payload of the KDBUS_ITEM_ATTACH_FLAGS_SEND and KDBUS_ITEM_ATTACH_FLAGS_RECV items follow this scheme. KDBUS_ATTACH_TIMESTAMP Requests the attachment of an item of type KDBUS_ITEM_TIMESTAMP. KDBUS_ATTACH_CREDS Requests the attachment of an item of type KDBUS_ITEM_CREDS. KDBUS_ATTACH_PIDS Requests the attachment of an item of type KDBUS_ITEM_PIDS. KDBUS_ATTACH_AUXGROUPS Requests the attachment of an item of type KDBUS_ITEM_AUXGROUPS. KDBUS_ATTACH_NAMES Requests the attachment of an item of type KDBUS_ITEM_OWNED_NAME. KDBUS_ATTACH_TID_COMM Requests the attachment of an item of type KDBUS_ITEM_TID_COMM. KDBUS_ATTACH_PID_COMM Requests the attachment of an item of type KDBUS_ITEM_PID_COMM. KDBUS_ATTACH_EXE Requests the attachment of an item of type KDBUS_ITEM_EXE. KDBUS_ATTACH_CMDLINE Requests the attachment of an item of type KDBUS_ITEM_CMDLINE. KDBUS_ATTACH_CGROUP Requests the attachment of an item of type KDBUS_ITEM_CGROUP. KDBUS_ATTACH_CAPS Requests the attachment of an item of type KDBUS_ITEM_CAPS. KDBUS_ATTACH_SECLABEL Requests the attachment of an item of type KDBUS_ITEM_SECLABEL. KDBUS_ATTACH_AUDIT Requests the attachment of an item of type KDBUS_ITEM_AUDIT. KDBUS_ATTACH_CONN_DESCRIPTION Requests the attachment of an item of type KDBUS_ITEM_CONN_DESCRIPTION. Please refer to kdbus.item 7 for detailed information about the layout and payload of items and what metadata should be used to. As stated in the 'synopsis' section above, application developers are strongly encouraged to use kdbus through one of the high-level D-Bus abstraction libraries, rather than using the low-level API directly. kdbus on the kernel level exposes its functions exclusively through ioctl 2 , employed on file descriptors returned by open 2 on pseudo files exposed by kdbus.fs 7 . Following is a list of all the ioctls, along with the command structs they must be used with. ioctl signature command transported struct 0x40189500 KDBUS_CMD_BUS_MAKE struct kdbus_cmd * 0x40189510 KDBUS_CMD_ENDPOINT_MAKE struct kdbus_cmd * 0xc0609580 KDBUS_CMD_HELLO struct kdbus_cmd_hello * 0x40189582 KDBUS_CMD_BYEBYE struct kdbus_cmd * 0x40389590 KDBUS_CMD_SEND struct kdbus_cmd_send * 0x80409591 KDBUS_CMD_RECV struct kdbus_cmd_recv * 0x40209583 KDBUS_CMD_FREE struct kdbus_cmd_free * 0x401895a0 KDBUS_CMD_NAME_ACQUIRE struct kdbus_cmd * 0x401895a1 KDBUS_CMD_NAME_RELEASE struct kdbus_cmd * 0x80289586 KDBUS_CMD_LIST struct kdbus_cmd_list * 0x80309584 KDBUS_CMD_CONN_INFO struct kdbus_cmd_info * 0x40209551 KDBUS_CMD_UPDATE struct kdbus_cmd * 0x80309585 KDBUS_CMD_BUS_CREATOR_INFO struct kdbus_cmd_info * 0x40189511 KDBUS_CMD_ENDPOINT_UPDATE struct kdbus_cmd * 0x402095b0 KDBUS_CMD_MATCH_ADD struct kdbus_cmd_match * 0x402095b1 KDBUS_CMD_MATCH_REMOVE struct kdbus_cmd_match * Depending on the type of kdbusfs node that was opened and what ioctls have been executed on a file descriptor before, a different sub-set of ioctl commands is allowed. On a file descriptor resulting from opening a control node, only the KDBUS_CMD_BUS_MAKE ioctl may be executed. On a file descriptor resulting from opening a bus endpoint node, only the KDBUS_CMD_ENDPOINT_MAKE and KDBUS_CMD_HELLO ioctls may be executed. A file descriptor that was used to create a bus (via KDBUS_CMD_BUS_MAKE) is called a bus owner file descriptor. The bus will be active as long as the file descriptor is kept open. A bus owner file descriptor can not be used to employ any further ioctls. As soon as close 2 is called on it, the bus will be shut down, along will all associated endpoints and connections. See kdbus.bus 7 for more details. A file descriptor that was used to create an endpoint (via KDBUS_CMD_ENDPOINT_MAKE) is called an endpoint owner file descriptor. The endpoint will be active as long as the file descriptor is kept open. An endpoint owner file descriptor can only be used to update details of an endpoint through the KDBUS_CMD_ENDPOINT_UPDATE ioctl. As soon as close 2 is called on it, the endpoint will be removed from the bus, and all connections that are connected to the bus through it are shut down. See kdbus.endpoint 7 for more details. A file descriptor that was used to create a connection (via KDBUS_CMD_HELLO) is called a connection owner file descriptor. The connection will be active as long as the file descriptor is kept open. A connection owner file descriptor may be used to issue any of the following ioctls. KDBUS_CMD_UPDATE to tweak details of the connection. See kdbus.connection 7 . KDBUS_CMD_BYEBYE to shut down a connection without losing messages. See kdbus.connection 7 . KDBUS_CMD_FREE to free a slice of memory in the pool. See kdbus.pool 7 . KDBUS_CMD_CONN_INFO to retrieve information on other connections on the bus. See kdbus.connection 7 . KDBUS_CMD_BUS_CREATOR_INFO to retrieve information on the bus creator. See kdbus.connection 7 . KDBUS_CMD_LIST to retrieve a list of currently active well-known names and unique IDs on the bus. See kdbus.name 7 . KDBUS_CMD_SEND and KDBUS_CMD_RECV to send or receive a message. See kdbus.message 7 . KDBUS_CMD_NAME_ACQUIRE and KDBUS_CMD_NAME_RELEASE to acquire or release a well-known name on the bus. See kdbus.name 7 . KDBUS_CMD_MATCH_ADD and KDBUS_CMD_MATCH_REMOVE to add or remove a match for signal messages. See kdbus.match 7 . These ioctls, along with the structs they transport, are explained in detail in the other documents linked to in the "See Also" section below. kdbus.bus 7 kdbus.connection 7 kdbus.endpoint 7 kdbus.fs 7 kdbus.item 7 kdbus.message 7 kdbus.name 7 kdbus.pool 7 ioctl 2 mmap 2 open 2 close 2 D-Bus