kdbus.connection kdbus.connection 7 kdbus.connection kdbus connection Connections are identified by their connection ID, internally implemented as a uint64_t counter. The IDs of every newly created bus start at 1, and every new connection will increment the counter by 1. The IDs are not reused. In higher level tools, the user visible representation of a connection is defined by the D-Bus protocol specification as ":1.<ID>". Messages with a specific uint64_t destination ID are directly delivered to the connection with the corresponding ID. Signal messages (see kdbus.message 7 ) may be addressed to the special destination ID KDBUS_DST_ID_BROADCAST (~0ULL) and will then potentially be delivered to all currently active connections on the bus. However, in order to receive any signal messages, clients must subscribe to them by installing a match (see kdbus.match 7 ). Messages synthesized and sent directly by the kernel will carry the special source ID KDBUS_SRC_ID_KERNEL (0). In addition to the unique uint64_t connection ID, established connections can request the ownership of well-known names, under which they can be found and addressed by other bus clients. A well-known name is associated with one and only one connection at a time. See kdbus.name 7 on name acquisition, the name registry, and the validity of names. Messages can specify the special destination ID KDBUS_DST_ID_NAME (0) and carry a well-known name in the message data. Such a message is delivered to the destination connection which owns that well-known name. | src: 22 | | | | | | | dst: 25 | | | | | | | | | | | | | | | | | | | | +---------------------------+ | | | | | | | | | | <--------------------------------------+ | | | +---------------+ | | | | | | | | +---------------+ +---------------------------+ | | | | | Connection | | Message | -----+ | | | | :1.25 | --> | src: 25 | | | | | | | dst: 0xffffffffffffffff | -------------+ | | | | | | (KDBUS_DST_ID_BROADCAST) | | | | | | | | | ---------+ | | | | | | +---------------------------+ | | | | | | | | | | | | | | <--------------------------------------------------+ | | +---------------+ | | | | | | | | +---------------+ +---------------------------+ | | | | | Connection | | Message | --+ | | | | | :1.55 | --> | src: 55 | | | | | | | | | dst: 0 / org.foo.bar | | | | | | | | | | | | | | | | | | | | | | | | | | +---------------------------+ | | | | | | | | | | | | | | <------------------------------------------+ | | | +---------------+ | | | | | | | | +---------------+ | | | | | Connection | | | | | | :1.81 | | | | | | org.foo.bar | | | | | | | | | | | | | | | | | | | <-----------------------------------+ | | | | | | | | | | <----------------------------------------------+ | | +---------------+ | +-------------------------------------------------------------------------+ ]]> A connection is considered privileged if the user it was created by is the same that created the bus, or if the creating task had CAP_IPC_OWNER set when it called KDBUS_CMD_HELLO (see below). Privileged connections have permission to employ certain restricted functions and commands, which are explained below and in other kdbus man-pages. An activator connection is a placeholder for a well-known name. Messages sent to such a connection can be used to start an implementer connection, which will then get all the messages from the activator copied over. An activator connection cannot be used to send any message. A policy holder connection only installs a policy for one or more names. These policy entries are kept active as long as the connection is alive, and are removed once it terminates. Such a policy connection type can be used to deploy restrictions for names that are not yet active on the bus. A policy holder connection cannot be used to send any message. The creation of activator or policy holder connections is restricted to privileged users on the bus (see above). Monitors are eavesdropping connections that receive all the traffic on the bus, but is invisible to other connections. Such connections have all properties of any other, regular connection, except for the following details: They will get every message sent over the bus, both unicasts and broadcasts. Installing matches for signal messages is neither necessary nor allowed. They cannot send messages or be directly addressed as receiver. They cannot own well-known names. Therefore, they also can't operate as activators. Their creation and destruction will not cause KDBUS_ITEM_ID_{ADD,REMOVE} (see kdbus.item 7 ). They are not listed with their unique name in name registry dumps (see KDBUS_CMD_NAME_LIST in kdbus.name 7 ), so other connections cannot detect the presence of a monitor. The creation of monitor connections is restricted to privileged users on the bus (see above). A connection to a bus is created by opening an endpoint file (see kdbus.endpoint 7 ) of a bus and becoming an active client with the KDBUS_CMD_HELLO ioctl. Every 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. The KDBUS_CMD_HELLO ioctl takes a struct kdbus_cmd_hello as argument. struct kdbus_cmd_hello { __u64 size; __u64 flags; __u64 return_flags; __u64 attach_flags_send; __u64 attach_flags_recv; __u64 bus_flags; __u64 id; __u64 pool_size; __u64 offset; __u8 id128[16]; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags to apply to this connection KDBUS_HELLO_ACCEPT_FD When this flag is set, the connection can be sent file descriptors as message payload of unicast messages. If it's not set, an attempt to send file descriptors will result in -ECOMM on the sender's side. KDBUS_HELLO_ACTIVATOR Make this connection an activator (see above). With this bit set, an item of type KDBUS_ITEM_NAME has to be attached. This item describes the well-known name this connection should be an activator for. A connection can not be an activator and a policy holder at the same time time, so this bit is not allowed together with KDBUS_HELLO_POLICY_HOLDER. KDBUS_HELLO_POLICY_HOLDER Make this connection a policy holder (see above). With this bit set, an item of type KDBUS_ITEM_NAME has to be attached. This item describes the well-known name this connection should hold a policy for. A connection can not be an activator and a policy holder at the same time time, so this bit is not allowed together with KDBUS_HELLO_ACTIVATOR. KDBUS_HELLO_MONITOR Make this connection a monitor connection (see above). This flag can only be set by privileged bus connections. See below for more information. A connection can not be monitor and an activator or a policy holder at the same time time, so this bit is not allowed together with KDBUS_HELLO_ACTIVATOR or KDBUS_HELLO_POLICY_HOLDER. KDBUS_FLAG_NEGOTIATE Requests a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will return 0, and the flags field will have all bits set that are valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. attach_flags_send Set the bits for metadata this connection permits to be sent to the receiving peer. Only metadata items that are both allowed to be sent by the sender and that are requested by the receiver will be attached to the message. Note, however, that the bus may optionally require some of those bits to be set. If the match fails, the ioctl will fail with errno set to ECONNREFUSED. In either case, when returning the field will be set to the mask of metadata items that are enforced by the bus with the KDBUS_FLAGS_KERNEL bit set as well. attach_flags_recv Request the attachment of metadata for each message received by this connection. See kdbus 7 for information about metadata, and kdbus.item 7 regarding items in general. bus_flags Upon successful completion of the ioctl, this member will contain the flags of the bus it connected to. id Upon successful completion of the command, this member will contain the numerical ID of the new connection. pool_size The size of the communication pool, in bytes. The pool can be accessed by calling mmap 2 on the file descriptor that was used to issue the KDBUS_CMD_HELLO ioctl. The pool size of a connection must be greater than 0 and a multiple of PAGE_SIZE. See kdbus.pool 7 for more information. offset The kernel will return the offset in the pool where returned details will be stored. See below. id128 Upon successful completion of the ioctl, this member will contain the 128-bit UUID of the connected bus. items Variable list of items containing optional additional information. The following items are currently expected/valid: KDBUS_ITEM_CONN_DESCRIPTION Contains a string that describes this connection, so it can be identified later. KDBUS_ITEM_NAME KDBUS_ITEM_POLICY_ACCESS For activators and policy holders only, combinations of these two items describe policy access entries. See kdbus.policy 7 for further details. KDBUS_ITEM_CREDS KDBUS_ITEM_PIDS KDBUS_ITEM_SECLABEL Privileged bus users may submit these types in order to create connections with faked credentials. This information will be returned when peer information is queried by KDBUS_CMD_CONN_INFO. See below for more information on retrieving information on connections. KDBUS_ITEM_NEGOTIATE With this item, programs can probe the kernel for known item types. See kdbus.item 7 for more details. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. At the offset returned in the offset field of struct kdbus_cmd_hello, the kernel will store items of the following types: KDBUS_ITEM_BLOOM_PARAMETER Bloom filter parameter as defined by the bus creator. The offset in the pool has to be freed with the KDBUS_CMD_FREE ioctl. See kdbus.pool 7 for further information. The KDBUS_CMD_CONN_INFO ioctl can be used to retrieve credentials and properties of the initial creator of a connection. This ioctl uses the following struct. struct kdbus_cmd_info { __u64 size; __u64 flags; __u64 return_flags; __u64 id; __u64 attach_flags; __u64 offset; __u64 info_size; struct kdbus_item items[0]; }; size The overall size of the struct, including its items. flags Currently, no flags are supported. KDBUS_FLAG_NEGOTIATE is accepted to probe for valid flags. If set, the ioctl will return 0, and the flags field is set to 0. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. id The numerical ID of the connection for which information is to be retrieved. If set to a non-zero value, the KDBUS_ITEM_OWNED_NAME item is ignored. attach_flags Specifies which metadata items should be attached to the answer. See kdbus.message 7 . offset When the ioctl returns, this field will contain the offset of the connection information inside the caller's pool. See kdbus.pool 7 for further information. info_size The kernel will return the size of the returned information, so applications can optionally mmap 2 specific parts of the pool. See kdbus.pool 7 for further information. items The following items are expected for KDBUS_CMD_CONN_INFO. KDBUS_ITEM_OWNED_NAME Contains the well-known name of the connection to look up as. This item is mandatory if the id field is set to 0. KDBUS_ITEM_NEGOTIATE With this item, programs can probe the kernel for known item types. See kdbus.item 7 for more details. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. When the ioctl returns, the following struct will be stored in the caller's pool at offset. The fields in this struct are described below. struct kdbus_info { __u64 size; __u64 id; __u64 flags; struct kdbus_item items[0]; }; size The overall size of the struct, including its items. id The connection's unique ID. flags The connection's flags as specified when it was created. items Depending on the flags field in struct kdbus_cmd_info, items of types KDBUS_ITEM_OWNED_NAME and KDBUS_ITEM_CONN_DESCRIPTION may follow here. KDBUS_ITEM_NEGOTIATE is also allowed. Once the caller is finished with parsing the return buffer, it needs to employ the KDBUS_CMD_FREE command for the offset, in order to free the buffer part. See kdbus.pool 7 for further information. The KDBUS_CMD_BUS_CREATOR_INFO ioctl takes the same struct as KDBUS_CMD_CONN_INFO, but is used to retrieve information about the creator of the bus the connection is attached to. The metadata returned by this call is collected during the creation of the bus and is never altered afterwards, so it provides pristine information on the task that created the bus, at the moment when it did so. In response to this call, a slice in the connection's pool is allocated and filled with an object of type struct kdbus_info, pointed to by the ioctl's offset field. struct kdbus_info { __u64 size; __u64 id; __u64 flags; struct kdbus_item items[0]; }; size The overall size of the struct, including its items. id The bus ID. flags The bus flags as specified when it was created. items Metadata information is stored in items here. The item list contains a KDBUS_ITEM_MAKE_NAME item that indicates the bus name of the calling connection. KDBUS_ITEM_NEGOTIATE is allowed to probe for known item types. Once the caller is finished with parsing the return buffer, it needs to employ the KDBUS_CMD_FREE command for the offset, in order to free the buffer part. See kdbus.pool 7 for further information. Some of a connection's details can be updated with the KDBUS_CMD_CONN_UPDATE ioctl, using the file descriptor that was used to create the connection. The update command uses the following struct. struct kdbus_cmd { __u64 size; __u64 flags; __u64 return_flags; struct kdbus_item items[0]; }; size The overall size of the struct, including its items. flags Currently, no flags are supported. KDBUS_FLAG_NEGOTIATE is accepted to probe for valid flags. If set, the ioctl will return 0, and the flags field is set to 0. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. items Items to describe the connection details to be updated. The following item types are supported. KDBUS_ITEM_ATTACH_FLAGS_SEND Supply a new set of metadata items that this connection permits to be sent along with messages. KDBUS_ITEM_ATTACH_FLAGS_RECV Supply a new set of metadata items that this connection requests to be attached to each message. KDBUS_ITEM_NAME KDBUS_ITEM_POLICY_ACCESS Policy holder connections may supply a new set of policy information with these items. For other connection types, EOPNOTSUPP is returned in errno. KDBUS_ITEM_NEGOTIATE With this item, programs can probe the kernel for known item types. See kdbus.item 7 for more details. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. A connection can be terminated by simply calling close 2 on its file descriptor. All pending incoming messages will be discarded, and the memory allocated by the pool will be freed. An alternative way of closing down a connection is via the KDBUS_CMD_BYEBYE ioctl. This ioctl will succeed only if the message queue of the connection is empty at the time of closing; otherwise, the ioctl will fail with errno set to EBUSY. When this ioctl returns successfully, the connection has been terminated and won't accept any new messages from remote peers. This way, a connection can be terminated race-free, without losing any messages. The ioctl takes an argument of type struct kdbus_cmd. struct kdbus_cmd { __u64 size; __u64 flags; __u64 return_flags; struct kdbus_item items[0]; }; size The overall size of the struct, including its items. flags Currently, no flags are supported. KDBUS_FLAG_NEGOTIATE is accepted to probe for valid flags. If set, the ioctl will fail with errno set to EPROTO, and the flags field is set to 0. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. items The following item types are supported. KDBUS_ITEM_NEGOTIATE With this item, programs can probe the kernel for known item types. See kdbus.item 7 for more details. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. On success, all mentioned ioctl commands return 0; on error, -1 is returned, and errno is set to indicate the error. If the issued ioctl is illegal for the file descriptor used, errno will be set to ENOTTY. EFAULT The supplied pool size was 0 or not a multiple of the page size. EINVAL The flags supplied in struct kdbus_cmd_hello are invalid. EINVAL An illegal combination of KDBUS_HELLO_MONITOR, KDBUS_HELLO_ACTIVATOR and KDBUS_HELLO_POLICY_HOLDER was passed in flags. EINVAL An invalid set of items was supplied. ECONNREFUSED The attach_flags_send field did not satisfy the requirements of the bus. EPERM A KDBUS_ITEM_CREDS items was supplied, but the current user is not privileged. ESHUTDOWN The bus you were trying to connect to has already been shut down. EMFILE The maximum number of connections on the bus has been reached. EOPNOTSUPP The endpoint does not support the connection flags supplied in struct kdbus_cmd_hello. EALREADY The connection has already been shut down. EBUSY There are still messages queued up in the connection's pool. EINVAL Invalid flags, or neither an ID nor a name was provided, or the name is invalid. ESRCH Connection lookup by name failed. ENXIO No connection with the provided connection ID found. EINVAL Illegal flags or items. EINVAL Wildcards submitted in policy entries, or illegal sequence of policy items. EOPNOTSUPP Operation not supported by connection. E2BIG Too many policy items attached. kdbus 7 kdbus.bus 7 kdbus.endpoint 7 kdbus.message 7 kdbus.name 7 kdbus.policy 7 kdbus.pool 7 kdbus.item 7