Halevt configuration

License of this document

Copyright (C) 2008, 2009 Patrice Dumas

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Other sources of information

The commands halevt and halevt-mount options and synopsis are given in the halevt and halevt-mount pages.

Some examples are provided in the Halevt distribution.

• Configuration file locations
• Halevt configuration syntax
• Discovering hal properties

1 Configuration file locations

The configuration file used can be set on the command line using -c file. Otherwise halevt will use all the files ending in ‘.xml’ located in the following directories, in that order:

1. $HOME/.halevt
2. @sysconfdir@/halevt
3. @datadir@/halevt

When in reporting mode, turned on by the -i option, no configuration file is used, halevt reports all the HAL events.

2 Halevt configuration syntax

• Basic syntax of halevt xml files
• Selecting devices and actions for hal events

2.1 Basic syntax of halevt xml files

Halevt configuration is in XML (described in-depth at http://www.w3.org/XML/). A configuration file should begin with:

     <?xml version="1.0" encoding="UTF-8"?>
     <halevt:Configuration version="0.1" xmlns:halevt="http://www.environnement.ens.fr/perso/dumas/halevt.html">

and end with

     </halevt:Configuration>

Comments are within ‘<!--’ and ‘-->’.

Basically, there are nested elements marked by ‘<...>’, either with a start tag and an end tag with a slash marking the end tag ‘</...>’, like the ‘halevt:Device’ element:

     <halevt:Device ...>
      ....
     </halevt:Device>

or standalone, like the ‘halevt:Insertion’ element, ending with a ‘/>’:

       <halevt:Insertion ..../>

In the element there may be attributes, with a name followed by an equal sign followed by a quoted string for the corresponding value. Here is an example of a ‘match’ attribute for the ‘halevt:Device’ element:

     <halevt:Device match="hal.block.device &amp; hal.block.is_volume">
      .....
     </halevt:Device>

Since they have special meanings, a literal ‘"’ should be escaped as ‘&quot;’, ‘&’ should be escaped as ‘&amp;’, ‘<’ as ‘&lt;’ and ‘>’ as ‘&gt;’.

For example the exec attribute here:

     <halevt:Device match="hal.block.device &amp; hal.block.is_volume">
       <halevt:Insertion exec="echo &quot;$hal.udi$&quot; &gt; file"/>
     </halevt:Device>

is

     echo "$hal.udi$" > file

2.2 Selecting devices and actions for hal events

The configuration of halevt allows to select device such that a command is run upon an hal event. The device selection is handled by the ‘halevt:Device’ element, it encloses an action element, among

halevt:OnInit

for an action to perform if the device is already there when halevt is started;

halevt:Insertion

for an action ot be performed on device insertion;

halevt:Removal

for an action ot be performed on device removal;

halevt:Condition

for an action to be performed when a condition is emitted by the device;

halevt:Property

for an action to be performed when a property changes. In that case the halevt:Action element is nested within the halevt:Property element to select an action based on the property value.

• Device selection syntax
• Specifying a command to be executed
• Actions

2.2.1 Device selection syntax

A halevt:Device has a match attribute, to select the device. The device match is done by selecting hal properties that should exist or properties matching a value. These items can be combined in boolean expressions, with ‘&’ for and, ‘|’ for or and ‘!’ for the negation and parenthesis for grouping.

A hal property that should exist is selected by prepending ‘hal.’ to the property, like ‘hal.block.device’. A property value match is specified by the property name with ‘hal.’ prepended followed by an equal sign followed by the value. For example, the following is true if the device property ‘block.is_volume’ has ‘true’ as a value:

     hal.block.is_volume = true

So, for example, the following selects devices with existing ‘block.device’ property, and a property ‘block.is_volume’ matching the value ‘true’:

     <halevt:Device match="hal.block.device &amp; hal.block.is_volume = true>
      ...
     </halevt:Device>

When a property is an UDI which specifies a device, it is possible to check a property of the device specified by this UDI, by inserting ‘hal.’ between the UDI device property and the property to check. For example the following checks that the device specified by the ‘block.storage_device’ property has the ‘storage.hotpluggable’ property set to ‘true’:

     hal.block.storage_device.hal.storage.hotpluggable = true

If the property to check is also an UDI, the UDI can be considered to be another device and so on and so forth.

2.2.2 Specifying a command to be executed

Every action leads to a command being executed when an HAL event happens for a selected device. The command to run is specified in an attribute, the exec attribute. It will be in an element corresponding with the HAL event. The exec attribute simply holds the command to be run, and it is possible to substitute a hal property value, by enclosing in ‘$..$’ the property name with hal prepended. Also $hal.udi$ is replaced by the device UDI. For example in:

     exec="halevt-mount -u $hal.udi$ -d $hal.block.device$ -o sync -m 002"

$hal.udi$ is replaced by the device UDI and $hal.block.device$ is replaced by the ‘block.device’ property value for the device.

2.2.3 Actions

An action is performed for a selected device, therefore action element should appear within halevt:Device elements. The following action possibility exist, each associated with a HAL event:

halevt:OnInit

This element is associated with an exec attribute, allowing to specify an action to perform if the device is already known by HAL when halevt is started. For example, the following leads to mounting all the block devices known by HAL by UDI.

          <halevt:Device match="hal.block.device">
            <halevt:OnInit exec="halevt-mount -u $hal.udi$"/>
          </halevt:Device>

halevt:Insertion

This element corresponds with an action to be performed on device insertion, specified by the exec attribute. This does exactly the same than above, but on device insertion:

          <halevt:Device match="hal.block.device">
            <halevt:Insertion exec="halevt-mount -u $hal.udi$"/>
          </halevt:Device>

halevt:Removal

This element corresponds with an action to be performed on device removal, specified by a exec attribute. For example:

          <halevt:Device match="hal.block.device">
            <halevt:Removal exec="halevt-umount -d $hal.block.device$"/>
          </halevt:Device>

halevt:Condition

This element corresponds with an action to be performed when a condition is emitted. The name attribute allows to specify the condition, while the exec attribute specifies the action. An optional value attribute may also be used to match only for a given condition detail value. For example:

          <halevt:Device match="hal.info.udi = /org/freedesktop/Hal/devices/acpi_PWRF">
              <halevt:Condition name="ButtonPressed" exec="sudo /sbin/shutdown"/>
          </halevt:Device>

With a value:

          <halevt:Device match="hal.input.originating_device.hal.info.linux.driver = atkbd">
              <halevt:Condition name="ButtonPressed" value="mute" exec="amixer -q set Master toggle"/>
          </halevt:Device>

halevt:Property

for an action to be performed when a property changes. The property name is specified in the name attribute of the halevt:Property element. An halevt:Action element is nested within the halevt:Property element to select an action based on the property value. In the halevt:Action element, the value attribute allows to specify which value for the property should lead to the action to be taken, and the exec attribute specifies the command to be run. ‘*’ as an halevt:Action value will match any value. For example:

          <halevt:Device match="hal.block.device &amp; hal.block.is_volume = true">
             <halevt:Property name="hal.volume.is_mounted">
                <halevt:Action value="true" exec="halevt-mount -s"/>
             </halevt:Property>
          </halevt:Device>

In that example, the property that changes is ‘volume.is_mounted’, and the action is executed when the value of ‘volume.is_mounted’ becomes ‘true’.

3 Tips and tricks for discovering hal properties

The hal properties are very important in halevt, but cannot necessarily be found easily. Here are some tricks.

To discover what changes when a device is inserted, one can use lshal -m. Once started, it will wait for hal events and will print all the changes emitted by the hald daemon, allowing to know which UDI was added and which property changed.

Also, one can use lshal to list the devices with their properties. The properties can then be used in match prepended by ‘hal.’, and also in exec, also prepended by ‘hal’ and enclosed in ‘$’, like:

     exec="halevt-mount -d $hal.block.device$"

Reference to other UDI are recognizable because they begin with

     /org/freedesktop/Hal/devices/

For example, one can have:

       info.parent = '/org/freedesktop/Hal/devices/usb_device_47b_2_noserial_if1'  (string)
       input.originating_device = '/org/freedesktop/Hal/devices/usb_device_47b_2_noserial_if1'  (string)

The properties of those devices can be used as explained in Device selection syntax.