dbus-action is a program which listens to D-Bus and actions configured commands on specified messages. A message is specifying using bus + interface + member + response value, and this can be mapped to trigger any arbitrary command. You can choose to automatically start dbus-action in your desktop environment to action commands in response to events in that environment.
The latest version and documentation is available at https://github.com/bulletmark/dbus-action.
NOTE: Arch users can just install dbus-action from the AUR. Then skip to the next CONFIGURATION section.
You need python 3.6 or later, python2 is not supported. You also need PyGObject, python3-dbus, and python3-ruamel-yaml packages.
Install this software:
git clone https://github.com/bulletmark/dbus-action.git
cd dbus-action
sudo make install (or sudo ./dbus-action-setup install)
The default configuration file is in /etc/dbus-action.conf. You will
want to create your own custom triggers and actions so copy that file to
~/.config/dbus-action.conf and edit it. Options and an example are
described in comments within that file. The example shows how to action
a command when your machine suspends, and then another command when it
resumes from suspend.
For other custom actions, most likely you will first need to determine
the interface, member, and responses you want to trigger on. To help
with this, you can run dbus-action in monitor mode to view all
messages. Run the following as your normal user in your normal session
(DO NOT use root/sudo):
dbus-action -m all
Note, instead of -m all, you can choose -m session or -m system to
limit listening to those specific buses only. You can also add -i interface to further limit output to a specific interface.
Then perform the action you would like to intercept and capture the
D-Bus message. In your ~/.config/dbus-action.conf, configure the bus,
interface, member, and response values to commands which you would like
to trigger. Note that the response is a list of values (although often
only a list of 1) so you must set value_index in your configuration to
the index of the value in the returned list you want to compare. It
defaults to 0, i.e. the first value returned.
You must choose between starting the application as a systemd user service, or as a desktop application (with an XDG compliant DE such as GNOME and KDE). The systemd user service provides more robust management and better logging than the desktop so is the preferred choice. Choose one of the two following options:
- To set up the application as a systemd user service:
dbus-action-setup service
- Or instead, to set up the application using your DE:
dbus-action-setup desktop
After choosing one of the above, you can use then run the following commands:
Enable the app to start automatically in the background when you log in with:
dbus-action-setup autostart
Disable the app from starting automatically with:
dbus-action-setup autostop
Start the app immediately in the background:
dbus-action-setup start
Stop the background app immediately with:
dbus-action-setup stop
Restart the app, e.g. to reload the configuration file, with:
dbus-action-setup restart
Check the status of the app with:
dbus-action-setup status
Note if you are starting using the DE option and you are using some
uncommon systems then dbus-action-setup start may fail
to start the application returning you a message Don't know how to
invoke dbus-action.desktop. If you get this error message,
install the dex package, preferably from your system packages
repository, and try again.
# cd to source dir, as above
git pull
sudo make install (or sudo ./dbus-action-setup install)
dbus-action-setup restart
dbus-action-setup stop
dbus-action-setup autostop
sudo dbus-action-setup uninstall
usage: dbus-action [-h] [-c CONFFILE] [-v] [-m MONITOR] [-i INTERFACE]
Watch D-Bus to action configured commands on specific events.
optional arguments:
-h, --help show this help message and exit
-c CONFFILE, --conffile CONFFILE
alternative configuration file
-v, --verbose verbose output
-m MONITOR, --monitor MONITOR
just monitor given bus, or "all" buses
(session,system)
-i INTERFACE, --interface INTERFACE
limit monitor output to specific interface
Copyright (C) 2020 Mark Blakeney. This program is distributed under the terms of the GNU General Public License. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at https://www.gnu.org/licenses/ for more details.