.\" Man page generated from reStructuredText.
.
.TH DBUS-BROKER 1 "" "" "User Commands"
.SH NAME
dbus-broker \- D-Bus message broker
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
\fBdbus\-broker\fP [ OPTIONS ]
\fBdbus\-broker\fP \fB\-\-version\fP
\fBdbus\-broker\fP \fB\-\-help\fP
.fi
.sp
.SH DESCRIPTION
.sp
\fBdbus\-broker\fP is an implementation of the D\-Bus Message Bus
Specification [1]\&. Each instance provides a single, unique message bus that
clients can connect to, and send messages over. The broker takes care of
message mediation, access control, subscriptions, and bus control, according to
the D\-Bus specification.
.sp
\fBdbus\-broker\fP is a \fIpure\fP implementation, meaning that it only implements the
message mediation. It needs a controlling process that performs the bus setup
and all external communication. \fBdbus\-broker\-launch\fP(1) is such a controller
aiming at perfect compatibility to \fBdbus\-daemon\fP(1), the D\-Bus Reference
Implementation. See \fBdbus\-broker\-launch\fP(1) for details how to spawn a
message bus.
.sp
This man\-page documents the interface between \fBdbus\-broker\fP and its
controller (e.g., \fBdbus\-broker\-launch\fP(1)).
.SH OPTIONS
.sp
The following command\-line options are supported. If an option is passed, which
is not listed here, the broker will deny startup and exit with an error.
.INDENT 0.0
.TP
.B \-h\fP,\fB  \-\-help
print usage information and exit immediately
.TP
.B \-\-version
print build\-version and exit immediately
.TP
.B \-\-audit
enable logging to the linux audit subsystem
(no\-op if audit support was not compiled in;
\fBDefault\fP: off)
.TP
.BI \-\-controller\fB= FD
use the inherited file\-descriptor with the
given number as the controlling socket (see
\fBCONTROLLER\fP section; this option is
mandatory)
.TP
.BI \-\-log \ FD
use the inherited file\-descriptor with the
given number to access the system log (see
\fBLOGGING\fP section; \fBDefault\fP: no logging)
.TP
.BI \-\-machine\-id\fB= ID
set the machine\-id to be advertised by the
broker via the org.freedesktop.DBus interface
(this option is mandatory and usually sourced
from /etc/machine\-id)
.TP
.BI \-\-max\-bytes\fB= BYTES
maximum number of bytes each user may
allocate in the broker (\fBDefault\fP: 16 MiB)
.TP
.BI \-\-max\-fds\fB= FDS
maximum number of file descriptors each user
may allocate in the broker (\fBDefault\fP: 64)
.TP
.BI \-\-max\-matches\fB= MATCHES
maximum number of match rules each user may
allocate in the broker (\fBDefault\fP: 16k)
.TP
.BI \-\-max\-objects\fB= OBJECTS
maximum total number of names, peers, pending
replies, etc each user may allocate in the
broker (\fBDefault\fP: 16k)
.UNINDENT
.SH CONTROLLER
.sp
Every instance of \fBdbus\-broker\fP inherits a \fBunix\fP(7) socket from its
parent process. This socket must be specified via the \fB\-\-controller\fP
option. The broker uses this socket to accept control commands from its parent
process (or from whomever owns the other side of this socket, also called \fIThe
Controller\fP). This socket uses normal D\-Bus P2P communication. The interfaces
provided on this socket are described in the \fBAPI\fP section.
.sp
By default, a broker instance is idle. That is, after forking and executing a
broker, it starts with an empty list of bus\-sockets to manage, as well as no
way for clients to connect to it. The controller must use the controller
interface to create listener sockets, specify the bus policy, create
activatable names, and react to bus events.
.sp
The \fBdbus\-broker\fP process never accesses any external resources other than
those passed in either via the command\-line or the controller interfaces. That
is, no file\-system access, no \fBnss\fP(5) calls, no external process
communication, is performed by the broker. On the contrary, the broker never
accesses any resources but the sockets provided to it by the controller. This
is guaranteed by the implementation. At the same time, this implies that the
controller is required to perform all external resource acquisitions and
communication on behalf of the broker (in case this is needed).
.SH LOGGING
.sp
If a logging FD is provided via the \fB\-\-log\fP command\-line option, the broker
will log some information through this FD. Two different log\-types are
supported:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
If the FD is a \fBunix\fP(7) \fBSOCK_STREAM\fP socket, information is logged
as human\-readable line\-based chunks.
.IP 2. 3
If the FD is a \fBunix\fP(7) \fBSOCK_DGRAM\fP socket, information is logged as
key/value based annotated data blocks. The format is compatible to the
format used by the systemd\-journal (though it is not dependent on systemd).
This key/value based logging is a lot more verbose as the stream based
logging. A lot of metadata is provided as separate keys, allowing precise
tracing and interpretation of the logged data.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The broker has strict rules when it logs data. It logs during startup and
shutdown, one message each to provide information on its setup and environment.
At runtime, the broker only ever logs in unexpected situations. That is, every
message the broker logs at runtime was triggered by a malfunctioning client. If
a system is properly set up, no runtime log\-message will be triggered.
.sp
The situations where the broker logs are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
During startup and shutdown, the broker submits a short message including
metadata about its controller, environment, and setup.
.IP 2. 3
Whenever a client\-request is denied by the policy, a message is logged
including the affected client and policies.
.IP 3. 3
Whenever a client exceeds its resource quota, a message is logged with
information on the client.
.UNINDENT
.UNINDENT
.UNINDENT
.SH API
.sp
The following interfaces are implemented by the broker on the respective nodes.
The controller is free to call these at any time. The controller connection is
considered trusted. No resource accounting, nor access control is performed.
.sp
The controller itself is also required to implement interfaces to be used by
the broker. See the section below for a list of interfaces on the controller.
.nf

\fBnode\fP /org/bus1/DBus/Broker {
.in +2
\fBinterface\fP org.bus1.DBus.Broker {

.in +2
# Create new activatable name @name, accounted on user @uid. The name
# will be exposed by the controller as @path (which must fit the
# template \fI/org/bus1/DBus/Name/%\fP).
\fBmethod\fP AddName(\fBo\fP \fIpath\fP, \fBs\fP \fIname\fP, \fBu\fP \fIuid\fP) \-> ()

# Add a listener socket to this bus. The listener socket must be
# ready in listening mode and specified as @socket. As soon as this
# call returns, incoming client connection attempts will be served
# on this socket.
# The listener is exposed by the controller as @path (which must fit
# the template \fI/org/bus1/DBus/Listener/%\fP).
# The policy for all clients connecting through this socket is
# provided as @policy. See \fBorg.bus1.DBus.Listener.SetPolicy()\fP for
# details.
\fBmethod\fP AddListener(\fBo\fP \fIpath\fP, \fBh\fP \fIsocket\fP, \fBv\fP \fIpolicy\fP) \-> ()

# This signal is raised according to client\-requests of
# \fBorg.freedesktop.DBus.UpdateActivationEnvironment()\fP\&.
\fBsignal\fP SetActivationEnvironment(\fBa{ss}\fP \fIenvironment\fP)

.in -2
}
.in -2
}

\fBnode\fP /org/bus1/DBus/Listener/% {
.in +2
\fBinterface\fP org.bus1.DBus.Listener {

.in +2
# Release this listener. It will immediately be removed by the broker
# and no more connections will be served on it. All clients connected
# through this listener are forcefully disconnected.
\fBmethod\fP Release() \-> ()

# Change the policy on this listener socket to @policy. The syntax of
# the policy is still subject to change and not stable, yet.
\fBmethod\fP SetPolicy(\fBv\fP \fIpolicy\fP) \-> ()

.in -2
}
.in -2
}

\fBnode\fP /org/bus1/DBus/Name/% {
.in +2
\fBinterface\fP org.bus1.DBus.Name {

.in +2
# Release this activatable name. It will be removed with immediate
# effect by the broker. Note that the name is still valid to be
# acquired by clients, though no activation\-features will be
# supported on this name.
\fBmethod\fP Release() \-> ()

# Reset the activation state of this name. Any pending activation
# requests are cancelled. The call requires a serial number to be
# passed along. This must be the serial number received by the last
# activation event on this name. Calls for other serial numbers are
# silently ignored and considered stale.
# A org.bus1.DBus.Name.Error string is also passed, giving a hint
# about the reason the activation was reset. The list is defined below.
\fBmethod\fP Reset(\fBt\fP \fIserial\fP, \fBs\fP \fIerror\fP) \-> ()

# Activation request failed: a concurrent deactivation request is already in progress
\fBerror\fP \fIorg.bus1.DBus.Name.Error.DestructiveTransaction\fP
# Activation request failed: unknown unit
\fBerror\fP \fIorg.bus1.DBus.Name.Error.UnknownUnit\fP
# Activation request failed: unit is masked
\fBerror\fP \fIorg.bus1.DBus.Name.Error.MaskedUnit\fP
# Activation request failed: unit is invalid
\fBerror\fP \fIorg.bus1.DBus.Name.Error.InvalidUnit\fP
# Unit activation job succeeded, but the unit failed afterwards
\fBerror\fP \fIorg.bus1.DBus.Name.Error.UnitFailure\fP
# The startup job was valid, but it failed during activation
\fBerror\fP \fIorg.bus1.DBus.Name.Error.StartupFailure\fP
# The startup job was valid, but it was skipped during activation
\fBerror\fP \fIorg.bus1.DBus.Name.Error.StartupSkipped\fP
# Activation request cancelled: bus name was released
\fBerror\fP \fIorg.bus1.DBus.Name.Error.NameReleased\fP

# This signal is sent whenever a client requests activation of this
# name. Note that multiple activation requests are coalesced by the
# broker. The controller can cancel outstanding requests via the
# \fBReset()\fP method.
# The broker sends a serial number with the event. This number
# represents the activation request and must be used when reacting
# to the request with methods like \fIReset()\fP\&. The serial number is
# unique for each event, and is never reused. A serial number of 0
# is never sent and considered invalid.
\fBsignal\fP Activate(\fBt\fP \fIserial\fP)

.in -2
}
.in -2
}

.fi
.sp
.sp
The controller itself is required to implement the following interfaces on the
given nodes. These interfaces are called by the broker to implement some parts
of the driver\-interface as defined by the D\-Bus specification.
.sp
Note that all method\-calls performed by the broker are always fully
asynchronous. That is, regardless how long it takes to serve the request, the
broker is still fully operational and might even send further requests to the
controller.
.sp
A controller is free to implement these calls in a blocking fashion. However,
it is up to the controller to make sure not to perform \fBblocking\fP recursive
calls back into the broker (via any means).
.nf

\fBnode\fP /org/bus1/DBus/Controller {
.in +2
\fBinterface\fP org.bus1.DBus.Controller {

.in +2
# This function is called for each client\-request of
# \fIorg.freedesktop.DBus.ReloadConfig()\fP\&.
\fBmethod\fP ReloadConfig() \-> ()

.in -2
}
.in -2
}

.fi
.sp
.SH SEE ALSO
.sp
\fBdbus\-broker\-launch\fP(1)
\fBdbus\-daemon\fP(1)
.SH NOTES
.IP [1] 5
D\-Bus Specification:
\fI\%https://dbus.freedesktop.org/doc/dbus\-specification.html\fP
.\" Generated by docutils manpage writer.
.