D-Bus

From Gentoo Wiki
Jump to:navigation Jump to:search

D-Bus is an interprocess communication (IPC) system for software applications. Software makes use of D-Bus to communicate information between services.

Important
There are two distinct D-Bus buses: the system bus and the session bus. The system bus is for messages related to the system as a whole, e.g. hardware connects and disconnects. The session bus, on the other hand, is for messages related to a specific user session, e.g. an X or Wayland session. The dbus service provided by OpenRC and systemd only provides the system bus, not a session bus.

Installation

USE flags

Portage knows the global dbus USE flag for enabling support for D-Bus in other packages. Enabling this flag will pull in sys-apps/dbus automatically. This is the default for desktop profiles:

FILE /etc/portage/make.confEnabling D-Bus globally
USE="dbus"

USE flags for sys-apps/dbus A message bus system, a simple way for applications to talk to each other

X Add support for X11
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
elogind Use sys-auth/elogind for session tracking.
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
static-libs Build static versions of dynamic libraries as well
systemd Build with sys-apps/systemd at_console support
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
valgrind Enable annotations for accuracy. May slow down runtime slightly. Safe to use even if not currently using dev-debug/valgrind

Emerge

After setting the dbus global USE flag be sure to update the system using the --changed-use option:

root #emerge --ask --changed-use --deep @world

Configuration

Files

The main configuration files include:

  • /usr/share/dbus-1/system.conf for the system bus
  • /usr/share/dbus-1/session.conf for the session bus

The system bus: the dbus service

A D-Bus service, such as the OpenRC service described below, typically provides the system bus, but not a session bus. Depending on system configuration, a session bus may need to be manually started in order for certain 'desktop' functionality to be available. For further details, refer to the session bus, below.

OpenRC

After configuration step, start the D-Bus system bus with:

root #/etc/init.d/dbus start

To start the D-Bus system bus at boot time, add it the default run level:

root #rc-update add dbus default
Tip
Even without adding D-Bus to the default runlevel it often will get started by D-Bus dependent services. This should explain why D-Bus mysteriously gets started even though it has not been formally added to a system runlevel.

The session bus

If using a desktop environment such as KDE or GNOME, a session bus should be created automatically. More generally, however, a session bus might not get created automatically. In particular, this is the case when using startx / .xinitrc.

To check whether a session bus is available within the X or Wayland session, open a terminal in that session and do:

user $echo $DBUS_SESSION_BUS_ADDRESS

This should output a string beginning with unix:path=, e.g. unix:path=/tmp/dbus-a77380e2b9,guid=90c8f55c7e7745be8f35a31b977085fc. If no such string is displayed, there is no D-Bus session bus visible to the session.

Executing a window manager, like i3 or bspwm, via dbus-launch grants a D-Bus session to the X or Wayland session.

Warning
When not using a login manager, security issues arise when relying on a screen lock program. Lock programs only prevent access to the running X session and the tty where X was launched may still be accessible. This makes it possible to kill X and gain access to logged-in user's shell. Make sure the X session is launched with the exec command to ensure a user is logged out if X is terminated for any reason.
FILE ~/.xinitrc
exec dbus-launch --exit-with-session i3

Important things to note:

  1. The session bus thus created will only be visible to programs created as child processes of the program launched by dbus-launch. Thus, any programs needing access to the session bus will need to be started via the startup procedure of that program (e.g. for i3, via ~/.config/i3/config).
  2. The use of exec here means that no subsequent lines of the .xinitrc file will be executed. exec is typically a shell builtin; for details, refer to the documentation for the shell being used to run the .xinitrc script. This is not the same behavior as some might expect from e.g. Sway, where the rest of the file/script continues after exec.

Usage

Some useful commands include:

  • dbus-monitor --system - To monitor the activities in the system bus.
  • dbus-monitor --session - To monitor the activities in the session bus.
  • dbus-send <PARAMETER> - To send a message. See the dbus-send man page (man dbus-send) for more information.

To view dbus services:

user $dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames

Users of systemd or elogind can use busctl(1) to list objects on a given bus, e.g.:

user $busctl --user tree
Service org.freedesktop.DBus:
└─/org/freedesktop/DBus

Service org.freedesktop.Notifications:
└─/org
  └─/org/freedesktop
    └─/org/freedesktop/Notifications
...

To shutdown and reboot as a regular user when using elogind:

user $dbus-send --system --print-reply --dest=org.freedesktop.login1 /org/freedesktop/login1 org.freedesktop.login1.Manager.PowerOff boolean:false
user $dbus-send --system --print-reply --dest=org.freedesktop.login1 /org/freedesktop/login1 org.freedesktop.login1.Manager.Reboot boolean:false

Changing the last argument to boolean:true should make polkit interactively ask the user for authentication credentials if it needs to.

The dev-debug/d-feet package provides a GUI to explore available D-Bus services and objects on the system and session buses, and to call methods of D-Bus interfaces.

Troubleshooting

Use the dbus-monitor command to monitor the buses. Errors are also redirected to the syslog (/var/log/messages).

See also

External resources