attachment upload

[reminder] / Harnessing_DBus.mdwn

# Harnessing DBus

## Introduction

I will discuss here how to run some script when specific DBus events
happen. The subject has already been covered by various tutorials, see
for instance:
[how-do-i-run-a-script-on-a-dbus-signal](http://ubuntu.aspcode.net/view/635400140124705175242338/how-do-i-run-a-script-on-a-dbus-signal)
or
[using-dbus-to-take-action-on-a-usb-storage-device](http://www.danplanet.com/blog/2007/11/11/using-dbus-to-take-action-on-a-usb-storage-device/)
but most of them are of the recipe type or need programming skills.  

I will explore a bit more deeply the subject here, using nothing more
than shell scripts. I hope you will learn in the process useful stuff
about how a modern Linux system works under the hood. Even if projects
like
[kdbus](http://www.linuxuser.co.uk/features/kernel-3-17-and-kdbus-the-kernel-column)
take ground, the method described below will stay valid with only
minor adjustements needed.

More specifically, I will try to **trigger a script as soon as you
switch [virtual
consoles](https://en.wikipedia.org/wiki/Linux_Virtual_Consoles)**.

I become interested in that subject because, due to some faulty video
hardware or driver or what else, the
[gamma](http://www.cambridgeincolour.com/tutorials/gamma-correction.htm)
tuning of my latest screen becomes always too high when switching
virtual consoles. The problem is not really visible in text mode, but
it's obvious when going from text mode to graphic mode, or switching
between two X sessions. No screen or video driver settings
help. Manually issuing
[xgamma](http://www.x.org/releases/X11R7.7/doc/man/man1/xgamma.1.xhtml)
like that:

    xgamma -gamma 0.5 

will solve the issue, but a way to automate that would be welcome. You
probably don't have that specific problem, so in the script I will
describe below you should perform some other useful action you may see
fit: popup some message, play a tune...

As a prerequisite, you are supposed to be a bit familiar with DBus
concepts. If not, look first here:
<http://www.freedesktop.org/wiki/Software/dbus/> and the tutorial
links there. If after reading this, you still have only an incomplete
picture of DBus, don't worry: fuzzy specifications and poor
documentation can be observed in most system tools in Linux today, and
courtesy of systemd, that trend is not showing any sign of going away.

I will use these DBus tools: dbus-monitor and dbus-send. You quite
certainly have them and their (terse) man pages; if not, they can be
found for instance in Debian package dbus.

## Details of the problem

I have hinted above that DBus will be used in the solution to our
problem. But a DBus daemon will run only if you have some advanced X
environnement, which excludes pure startx/xinit environnement from the
last millenium. So if you have some modern destkop environnement (be it
a bare one like XFCE or a bloated one like Gnome) you can use the
method below. 

In addition, a DBus session alone with no services will not allow us
to catch interesting events (a.k.a. DBus signals send by processes or
calls made by processes), and here we will need the DBus aware
application [ConsoleKit or
systemd-logind](http://www.freedesktop.org/wiki/Software/ConsoleKit/)
running. No problem, it runs on every modern destkop environnement.

It should be noted that switching virtual consoles happens in 4 cases:

1. At boot time when you are starting your X server: this triggers a
switch to the virtual console (often /dev/tty7) where the X server
runs; and then the gamma problem happens

2. When switching to a text console; going back to the X
server screen will trigger the gamma problem

3. When switching between several X sessions (if the first X session
starts in /dev/tty7 as said above, the second one will use the virtual
console /dev/tty8 etc...); the new visible X session will exhibit the
gamma problem

4. When resuming from suspended state; not sure if all video hardware
goes first to text mode when resuming, but my hardware does, and the
gamma problem becomes visible when the switch to graphical mode is
triggered

Some remarks about the 4 cases above:

* Case 1: for the boot time case, putting in your $HOME/.xsessionrc that line:

    xgamma -gamma 0.5 

is enough. But won't work for cases 2, 3 and 4. In a multiuser
environment, it doesn't scale well.

* Case 2 and 3: you can switch to a given virtual console using the command
 [chvt](http://nixdoc.net/man-pages/Linux/chvt.1.html), or with some
 [keyboard
 combination](http://www.tldp.org/HOWTO/Keyboard-and-Console-HOWTO-7.html).

* Case 4: the suspend/hibernate system offers some hook points where
commands can be run when resuming. But you must be sure when running
that command that you are indeed in graphical mode: if not, the xgamma
command won't work. 

But there is more. In a multiuser environment, you have to find out
the correct X display (the one active and visible when suspended), and
feed it to xgamma as an argument. So the correct command to run in my
case is actually:

    XAUTHORITY=$USERHOME/.Xauthority xgamma -gamma 0.5 -display $DISPLAY

where you cannot assume that DISPLAY has value :0. Here USERHOME is
the home directory of the user logged in the X session of the active
display, and XAUTHORITY will allow root (which is the user running
the resume script) to access the credentials to connect to that
display.

And no, issuing xgamma on a non-visible and non-active display will not
restore gamma for the active display.

Actually, there is no easy way to find out the active display and it's
corresponding session user while staying inside traditional X and the
suspend/hibernate system. A workaround would be to loop over all
active X displays; this is feasable (they can be found in
/tmp/.X11-unix). You will also need to loop over all possible
$HOME/.Xauthority, which is easy because you are root. 

At that point I hope you are convinced that that solution is clunky.
I will present something more general below.

## Looking for interesting DBus events when switching virtual consoles

Let's run dbus-monitor on the system DBus daemon (you need to do that
as root in a terminal), and let's observe what happens when we switch
to a different virtual console and back. The output looks somethink
like (# being the root shell prompt):

    # dbus-monitor --system
    signal sender=org.freedesktop.DBus -> dest=:1.67 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
       string ":1.67"

Now switch to a text console with the key combo Ctrl+Alt+F1, and back
to your session (supposed running at /dev/tty7) with the combo
Alt+F7. Something happened, we now have on the terminal:

    # dbus-monitor --system
    signal sender=org.freedesktop.DBus -> dest=:1.67 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
       string ":1.67"
    signal sender=:1.7 -> dest=(null destination) serial=418 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean false
    signal sender=:1.7 -> dest=(null destination) serial=419 path=/org/freedesktop/ConsoleKit/Seat1; interface=org.freedesktop.ConsoleKit.Seat; member=ActiveSessionChanged
       string ""
    signal sender=:1.6 -> dest=(null destination) serial=195 path=/org/freedesktop/PolicyKit1/Authority; interface=org.freedesktop.PolicyKit1.Authority; member=Changed
    signal sender=:1.6 -> dest=(null destination) serial=196 path=/org/freedesktop/PolicyKit1/Authority; interface=org.freedesktop.PolicyKit1.Authority; member=Changed
    signal sender=:1.7 -> dest=(null destination) serial=430 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean true
    signal sender=:1.7 -> dest=(null destination) serial=431 path=/org/freedesktop/ConsoleKit/Seat1; interface=org.freedesktop.ConsoleKit.Seat; member=ActiveSessionChanged
       string "/org/freedesktop/ConsoleKit/Session4"
    signal sender=:1.6 -> dest=(null destination) serial=203 path=/org/freedesktop/PolicyKit1/Authority; interface=org.freedesktop.PolicyKit1.Authority; member=Changed
    signal sender=:1.6 -> dest=(null destination) serial=204 path=/org/freedesktop/PolicyKit1/Authority; interface=org.freedesktop.PolicyKit1.Authority; member=Changed

*Disclaimer: I will handle here the case where you use ConsoleKit. If
you use a very recent desktop, you may be using the systemd equivalent
of ConsoleKit called systemd-logind, where the messages below look a
bit different, with interfaces like: org.freedesktop.login1 and paths
like: /org/freedesktop/login1/session. I have so far only virtual
machines running with systemd, so unable to explore console switching
on them; I will update that page as soon as possible to cover the
systemd case.*

To not be flooded with messages, we can print only messages related to
the org.freedesktop.ConsoleKit.Session interface by adding a watch
expression argument to dbus-monitor. Redoing the previous experiment,
we get now something much more short:

    # dbus-monitor --system interface=org.freedesktop.ConsoleKit.Session
    signal sender=org.freedesktop.DBus -> dest=:1.68 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
       string ":1.68"
    signal sender=:1.7 -> dest=(null destination) serial=450 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean false
    signal sender=:1.7 -> dest=(null destination) serial=462 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean true

There are three 2 lines messages above. The first one is noise due to
dbus-monitore registering on the DBus daemon. The second one signals
to the world that your current session (called Session4) is no more
active (boolean false) because no more visible as you switched to
/dev/tty1. And the third one says it's visible and active again
(boolean true).

You will be able to verify that the same kind of message is triggered
when switching to another X session runningfor instance on /dev/tty8,
then going back:

    # dbus-monitor --system interface=org.freedesktop.ConsoleKit.Session
    signal sender=org.freedesktop.DBus -> dest=:1.82 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
       string ":1.82"
    signal sender=:1.7 -> dest=(null destination) serial=850 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean false
    signal sender=:1.7 -> dest=(null destination) serial=851 path=/org/freedesktop/ConsoleKit/Session6; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean true
    signal sender=:1.7 -> dest=(null destination) serial=873 path=/org/freedesktop/ConsoleKit/Session6; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean false
    signal sender=:1.7 -> dest=(null destination) serial=874 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=ActiveChanged
       boolean true
    
Here the second X session is called Session6. You should now
understand that the third and fourth messages happen when you hit
Ctrl+Alt+F8: Session4 signals it becomes inactive because invisible,
then Session6 becomes visible and active. And the last two 2 lines
messages happen when you hit Ctrl+Alt+F7, always ending with Session4
signaling it's visible and active again.

So our solution would be to run our xgamma command as soon as that
last DBus signal is caught.

## Looking for interesting DBus events when resuming, and reacting on
   these events

But wait, what about suspend/resume? Lets run dbus-monitor again and
see what happens when you suspend, the resume:

    # dbus-monitor --system interface=org.freedesktop.ConsoleKit.Session
    signal sender=org.freedesktop.DBus -> dest=:1.83 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
       string ":1.83"
    signal sender=:1.7 -> dest=(null destination) serial=948 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=IdleHintChanged
       boolean true
    signal sender=:1.7 -> dest=(null destination) serial=962 path=/org/freedesktop/ConsoleKit/Session4; interface=org.freedesktop.ConsoleKit.Session; member=IdleHintChanged
       boolean false

That's even simpler, the second signal says we are going idle
a.k.a. suspend state (boolean true) and then going live again (not
idle, so boolean false).

So we have two signals to monitor: ActiveChanged for direct console
switching (and boot) and IdleHintChanged for console switching
triggered by resume.

To be completely sure to work only on those signals, we will use two
specific watch expressions as arguments to dbus-monitor; several such
watch arguments are or-ed, that is not obvious from dbus-monitor man
page. Our final dbus-monitor becomes then:

    dbus-monitor --system "interface='org.freedesktop.ConsoleKit.Session',member='ActiveChanged'" "interface='org.freedesktop.ConsoleKit.Session',member='IdleHintChanged'"

Following that [tutorial
method](http://ubuntu.aspcode.net/view/635400140124705175242338/how-do-i-run-a-script-on-a-dbus-signal),
plus some bashism like =~ and \[[ ]], we end-up with the following
script, which will also use logger to trace what happens in syslog:

    #!/bin/bash
    
    interface=org.freedesktop.ConsoleKit.Session
    member=ActiveChanged
    resume=IdleHintChanged
    
    # beware the pipe | at end of next line
    dbus-monitor --system "interface='$interface',member='$member'" "interface='$interface',member='$resume'" |
    while read -r line; do # we loop over all messages; get first line of message in variable 'line'
        # reading second line of message in variables 'type' and 'value'
        read type value
        # 'ret' is 0 if 'line' contains string $member
        \[[ "$line" =~ "$member" ]]; ret=$? 
        # test ActiveChanged to be true
        if [ "$ret" = "0" -a "$type" = "boolean" -a "$value" = "true" ]; then
        echo Boot or virtual console switching case: $line |& logger
        xgamma -gamma 0.5 |& logger
        fi
        # 'ret' is 0 if 'line' contains string $resume
        \[[ "$line" =~ "$resume" ]]; ret=$? 
        # test IdleHintChanged to be false
        if [ "$ret" = "0" -a "$type" = "boolean" -a "$value" = "false" ]; then
        echo Resume case: $line |& logger
        xgamma -gamma 0.5 |& logger
        fi
    done
    
If you start this script in background as root while in your X
session, things will work fine. But not in X sessions owned by other
users: because, as said above, you will be running it with the DISPLAY
and XAUTHORITY of your session. But DBus can help you find out these
values as we will see now.

## Obtaining information through DBus

Let's interrogate the ConsoleKit session object for our current X
session, which is in the example above has path
/org/freedesktop/ConsoleKit/Session4. We will use for that dbus-send,
and the requests and answers will look like this:

    # dbus-send --system --print-reply --type=method_call --dest=org.freedesktop.ConsoleKit "/org/freedesktop/ConsoleKit/Session4" org.freedesktop.ConsoleKit.Session.GetUser
    method return sender=:1.7 -> dest=:1.108 reply_serial=2
       uint32 1000
    # dbus-send --system --print-reply --type=method_call --dest=org.freedesktop.ConsoleKit "/org/freedesktop/ConsoleKit/Session4" org.freedesktop.ConsoleKit.Session.GetX11Display
    method return sender=:1.7 -> dest=:1.109 reply_serial=2
       string ":0"

It should be obvious that the first dbus-send command obtains the UID
of the X session owner (1000), and the second one get's the X display,
here ":0".

So our final version of the script becomes:

    #!/bin/bash
    
    interface=org.freedesktop.ConsoleKit.Session
    member=ActiveChanged
    resume=IdleHintChanged
    
    run() {
        DISPLAY=`dbus-send --system --print-reply --type=method_call --dest=org.freedesktop.ConsoleKit $object_path ${interface}.GetX11Display | grep string | cut -d ' ' -f 5 | cut -d '"' -f 2`
        XUID=`dbus-send --system --print-reply --type=method_call --dest=org.freedesktop.ConsoleKit $object_path ${interface}.GetUser | grep uint32 | cut -d ' ' -f 5`
        if [ "$DISPLAY" = "" -o "$XUID" = "" ]; then
        echo DISPLAY=$DISPLAY and user-uid=$XUID not both non empty, impossible to run xgamma |& logger -t logger
        else
        XAUTHORITY=`grep :x:${XUID}: /etc/passwd | cut -d ':' -f 6`/.Xauthority
        # we don't run any X app if XAUTHORITY doesn't exist or is empty 
        if [ -f $XAUTHORITY -a "`wc -c $XAUTHORITY | cut -d ' ' -f 1`" != "0" ]; then
            echo Running "XAUTHORITY=$XAUTHORITY xgamma -gamma 0.5 -display $DISPLAY" |& logger -t logger
            XAUTHORITY=$XAUTHORITY xgamma -gamma 0.5 -display $DISPLAY |& logger -t logger
            # in case your gamma stays ok, you can still test this script by uncommenting the next line
            #XAUTHORITY=$XAUTHORITY xeyes -display $DISPLAY &
        else
             echo $XAUTHORITY file non-existent or empty, impossible to run xgamma |& logger -t logger
        fi
        fi
    }
    
    # beware the pipe | at end of next line
    dbus-monitor --system "interface='$interface',member='$member'" "interface='$interface',member='$resume'" |
    while read -r line; do # we loop over all messages; get first line of message in variable 'line'
        # reading second line of message in variables 'type' and 'value'
        read type value
        # 'ret' is 0 if 'line' contains string $member
        \[[ "$line" =~ "$member" ]]; ret=$? 
        # test ActiveChanged to be true
        if [ "$ret" = "0" -a "$type" = "boolean" -a "$value" = "true" ]; then
        object_path=`echo "$line" | cut -d ' ' -f 7 | cut -d '=' -f 2 | cut -d ';' -f 1`
        echo Boot or virtual console switching case for session $object_path |& logger -t logger
        run
        fi
        # 'ret' is 0 if 'line' contains string $resume
        \[[ "$line" =~ "$resume" ]]; ret=$? 
        # test IdleHintChanged to be false
        if [ "$ret" = "0" -a "$type" = "boolean" -a "$value" = "false" ]; then
        object_path=`echo "$line" | cut -d ' ' -f 7 | cut -d '=' -f 2 | cut -d ';' -f 1`
        echo Resume case for session $object_path |& logger -t logger
        run
         fi
    done

We finally have to start the script at boot time, which has to be done
after the system DBus daemon is started, which in current stable
Debian is done through /etc/init.d/dbus. I suggest to simply drop the
path of the above script there, backgrounded with &.

If you do that, reboot and look at /var/log/syslog, you will notice
that the first call to xgamma (and xeyes) happens under the desktop
manager user (this is for sure the case for lightdm which I use).

Then, when you have logged in, xgamma (and xeyes) won't run because
XAUTHORITY is empty. I suspect this is due to a lack of synchronicity
between setting the DISPLAY in PolicyKit and setting it fully (with
valid XAUTHORITY) in X. The $HOME/.xsessionrc trick discussed at the
beginning above will save that case for you.

After this first logon, things work as expected on resume and console
switch. Notice that the screeensaver authorization screen never shows
xeyes, if you have uncommented that line in the script.

## Conclusion

We have gone a long way to finally devise a general solution to our
problem of running a script when changing virtual consoles. It is
fundamentally based on ConsoleKit or systemd-logind tracking these
virtual consoles changes, and announcing them on the DBus. 

An improvement to the script would be to write it using a language
with a DBus binding, like Python.

## Other interesting links:

An in-depth view of the virtual consoles: <http://www.phoronix.com/scan.php?page=news_item&px=MTQ0NDg>

A useful exploratory DBus tool is
[d-feet](http://live.gnome.org/DFeet/). A d-feet Debian
package exists.

Programmers may be interested in [gdbus](http://dev.man-online.org/man1/gdbus/) available in Debian package 
libglib2.0-dev.

[userland-dbus-event-manager](https://github.com/airtonix/userland-dbus-event-manager)
is a general tool to react on DBus events.