From 6d461a4fe7896faa1aec5a5417888cf179e46b9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fabian=20Silva=20Delgado?= Date: Mon, 22 Feb 2016 01:12:47 -0300 Subject: Linux-libre 4.4.2-gnu --- Documentation/kdbus/kdbus.xml | 1012 ----------------------------------------- 1 file changed, 1012 deletions(-) delete mode 100644 Documentation/kdbus/kdbus.xml (limited to 'Documentation/kdbus/kdbus.xml') diff --git a/Documentation/kdbus/kdbus.xml b/Documentation/kdbus/kdbus.xml deleted file mode 100644 index d8e7400df..000000000 --- a/Documentation/kdbus/kdbus.xml +++ /dev/null @@ -1,1012 +0,0 @@ - - - - - - - kdbus - kdbus - - - - kdbus - 7 - - - - kdbus - Kernel Message Bus - - - - Synopsis - - 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. - - - - - Description - - 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. - - - - - - Terminology - - - Domain - - A domain is a kdbusfs mount-point containing all - the bus primitives. Each domain is independent, and separate domains - do not affect each other. - - - - - Bus - - 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. - - - - - Endpoint - - 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. - - - - - Connection - - 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. - - - - - Pool - - 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. - - - - - Well-known Name - - 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. - - - - - Message - - 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. - - - - - Item - - 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. - - - - - Broadcast, signal, filter, match - - 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. - - - - - Policy - - 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. - - - - - Privileged bus users - - 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. - - - - - - Bus Layout - - - 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: - - - - - - - - Data structures and interconnections - - - - - Metadata - - - When metadata is collected - - 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. - - - - - Benefits and heads-up - - 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). - - - - - Attach flags for metadata items - - 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. - - - - - - The ioctl interface - - - 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. - - - - - See Also - - - - 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 - - - - - -- cgit v1.2.3