This is useful when an asset manager wants to install a system
service while /usr/ is read-only (e.g.: portable services running
on a different namespaced image). Also recommend searching in /run/
following the now-standard pattern, for ephemeral services.
Signed-off-by: Luca Boccassi <bluca@debian.org>
Readers of the message bus specification might be encountering Properties
for the first time, so for the basic properties in the o.fd.DBus
interface, link to the interface definition.
I'm not intending to add similar text for extension interfaces like
Containers.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Previously, we arbitrarily divided o.fd.DBus into "messages"
(methods and signals), in one sect2, and Properties, in another sect2;
and for the only extended interface that is documented so far,
o.fd.DBus.Monitoring, we included its single method in the list of
o.fd.DBus methods.
This is putting too much weight on implementation details of how the
D-Bus protocol is implemented (with Properties being "less core" than
methods and signals), and not enough weight on how interfaces are
conceptually structured. It's more usual to group together all aspects
of an interface into one document or section, and the current arbitrary
separation is going to look more and more odd as we start documenting
more interfaces like Containers (dbus!449), Stats and Verbose.
Instead, repurpose the "Message Bus Messages" section to become the
documentation for the o.fd.DBus interface, and introduce a separate
section for each other interface that the message bus provides.
Each one contains a full list of methods, signals and properties (if any)
if it is specific to the message bus, or a cross-reference to a more
generic interface description if it is equally applicable to the message
bus and its clients.
Prompted by discussion on dbus!449.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The newest release of the reference message bus that did not support
GetConnectionCredentials was 1.6.30, almost a decade ago.
It's entirely reasonable for new code to assume that
GetConnectionCredentials will succeed, and not implement a fallback.
Signed-off-by: Simon McVittie <smcv@collabora.com>
`<xref>` will typically be replaced by something like
"the section called “Foo”", so if we want to name a specific method
in running text, we need to use `<link>`.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The `AppArmor` feature flag is a case-sensitive string literal,
so consistently use its correct case-combination.
Signed-off-by: Simon McVittie <smcv@collabora.com>
There's no need to make readers go looking for these in a larger section,
we can link directly to the individual interfaces.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Make D-Bus implementations return a file descriptor
pinning the process as part of the credentials on
platforms that implement such concept, like Linux.
Pinning the process allows to defend against PID
reuse attacks, making authentication by
service/cgroup possible.
Signed-off-by: Luca Boccassi <bluca@debian.org>
The interoperable address is unix:path=/var/run/dbus/system_bus_socket.
However, in most (perhaps all) current Linux distributions, /var/run
is guaranteed to be a symbolic link to /run, and using the path in /run
has some advantages (particularly if automounters are used).
Implementations that intend to be interoperable are not required to
listen on exactly /var/run/dbus/system_bus_socket, as long as clients
that connect to that socket will work correctly. Similarly, clients
are not required to connect to exactly /var/run/dbus/system_bus_socket,
as long as the overall system (consisting of the client and the OSs
that it supports) ensures that it ends up connecting to the same
well-known system bus that is available at
/var/run/dbus/system_bus_socket.
Because of the Unix conventions for how software installs into a prefix,
building a D-Bus implementation with its default build-time
configuration options will not necessarily result in an interoperable
system bus. The system bus is normally shipped by OS distributors,
who should ensure that they have configured it in a way that is
interoperable.
Resolves: https://gitlab.freedesktop.org/dbus/dbus/-/issues/180
Signed-off-by: Simon McVittie <smcv@collabora.com>
The comment refers to the nul-padding of sockaddr_un member sun_path and
using an addrlen of sizeof(sockaddr_un). There is not much need to
document an old now "broken" behaviour.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
D-Bus names are in an ASCII subset, so IDNs have to be in their ACE
encoding (Punycode). ACE-encoded labels contain hyphen/minus characters,
and like any other label containing a hyphen/minus, we recommend
replacing those with underscores, to improve interoperability with
contexts that allow underscores but not hyphen/minus, such as
D-Bus object paths and Flatpak app-IDs.
Prompted by <https://github.com/flatpak/flatpak/issues/4974>.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Nothing changed in v0.39 yet, and it would be confusing to have the
version uploaded alongside dbus 1.14.0 say "not yet finalized".
Signed-off-by: Simon McVittie <smcv@collabora.com>
Commit ee71e1ff60 added * to the list of optionally escaped bytes
set, but did not update the documentation. I guess this happened because
the change is not backward compatible.
It seems that the period of 14+ years should be enough to not cause any
backward compatibility issues, so let's document this.
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Since we're heading for a 1.14.x branch (dbus#350), also draft the
summary of what has changed since 1.12.x.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This had two issues that could damage interoperability.
First, the spec wording suggested that any cookie that had not been
deleted was suitable for use in authentication. However, this introduces
a race condition, which is called out in comments in both the reference
implementation and GDBus: the newest cookie might be less old than the
arbitrary lifetime when authentication *begins*, but older than the
lifetime at the time authentication *ends*. As a result, we need a grace
period during which an old cookie will still be accepted, but a newer
cookie exists and will be used for new authentication operations.
Second, the spec wording implied that the arbitrary timeouts were
completely up to the implementor. However, GLib bug
https://gitlab.gnome.org/GNOME/glib/-/issues/2164 indicates that they
need to be reasonably compatible: in particular, GDBus servers
historically didn't allocate new cookies until 10 minutes had passed,
but libdbus clients would decline to use a cookie older than 5 minutes,
causing authentication to fail if the gdbus-server test-case (in which
GDBus and libdbus clients connect to a GDBus server) happened to take
longer than 5 minutes to run.
While I'm here, also be consistent about calling the secrets "cookies"
(consistent with the name of the mechanism) rather than "keys" (which
is what they are called in libdbus' dbus-keyring.c).
Signed-off-by: Simon McVittie <smcv@collabora.com>
