glfs/archive/hal.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY hal-download-http      "http://hal.freedesktop.org/releases/hal-&hal-version;.tar.bz2">
  <!ENTITY hal-download-ftp       " ">
  <!ENTITY hal-md5sum             "c627d8fb0f9afff94f3c687b5216bc06">
  <!ENTITY hal-size               "924 KB">
  <!ENTITY hal-buildsize          "25 MB">
  <!ENTITY hal-time               "0.5 SBU">

  <!ENTITY hal-info-version       "20091130">
  <!ENTITY hal-info-download-http "http://hal.freedesktop.org/releases/hal-info-&hal-info-version;.tar.bz2">
  <!ENTITY hal-info-download-ftp  " ">
  <!ENTITY hal-info-md5sum        "995b8d2dbfb0646b07c92bb8d23cbcf1">
  <!ENTITY hal-info-size          "108 KB">
]>

<sect1 id="hal" xreflabel="HAL-&hal-version;">
  <?dbhtml filename="hal.html"?>


  <title>HAL-&hal-version;</title>

  <indexterm zone="hal">
    <primary sortas="a-HAL">HAL</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to HAL</title>

    <para><application>HAL</application> is a hardware abstraction layer, which
    is a piece of software that provides a view of the various hardware
    attached to a system. In addition to this, <application>HAL</application>
    keeps detailed metadata for each piece of hardware and provides hooks such
    that system and desktop-level software can react to changes in the hardware
    configuration in order to maintain system policy.</para>

    <para>The most important goal of <application>HAL</application> is to
    provide plug-and-play facilities for UNIX-like desktops with focus on
    providing a rich and extensible description of device characteristics and
    features. One example of the functionality provided by
    <application>HAL</application> is when you plug in a USB storage device.
    <application>HAL</application> can automatically create a mount point in
    <filename class="directory">/media</filename> and mount the device.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&hal-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&hal-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &hal-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &hal-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &hal-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &hal-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Package Download</bridgehead>
    <itemizedlist spacing='compact'>
      <title>Required Hardware Data</title>
      <listitem>
        <para>Download (HTTP): <ulink url="&hal-info-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&hal-info-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &hal-info-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &hal-info-size;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">HAL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="dbus-glib"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="pciutils"/>
    (with a current <filename>pci.ids</filename> file) and
    <xref linkend="usbutils"/>
    (with a current <filename>usb.ids</filename> file)</para>

    <bridgehead renderas="sect4">Optional (to Create Documentation)</bridgehead>
    <para role="optional"><xref linkend="xmlto"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="gtk-doc"/>,
    <xref linkend="acl"/>,
    <xref linkend="gperf"/>,
    <ulink url="http://www.freedesktop.org/wiki/Software/PolicyKit">PolicyKit</ulink>,
    <xref linkend="consolekit"/>,
    <xref linkend="intltool"/>,
    <xref linkend="parted"/>, and
    <ulink url="https://fedorahosted.org/libsmbios/">libsmbios</ulink></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/hal"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of HAL</title>

    <para>You must create a dedicated user and group before installing the
    package. Though the default BLFS instructions run the
    <application>HAL</application> daemon as the
    <systemitem class="username">root</systemitem> user, a configuration file
    is installed which has the dedicated user's name hard-coded in it. This
    causes a confusing message to be generated when starting the
    <application>D-BUS</application> daemon. Issue the following commands as
    the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>groupadd -fg 19 haldaemon &amp;&amp;
useradd -c "HAL Daemon User" -d /dev/null -u 19 \
        -g haldaemon -s /bin/false haldaemon || [ $? == 9 ]</userinput></screen>

    <para>Install <application>HAL</application> by running the following
    commands:</para>

<screen><userinput>./configure --prefix=/usr \
            --sysconfdir=/etc \
            --libexecdir=/usr/lib/hal \
            --localstatedir=/var \
            --docdir=/usr/share/doc/hal-&hal-version; \
            --enable-policy-kit=no &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make check</command>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>Install the <application>HAL</application> hardware data with the
    following commands:</para>

<screen><userinput>tar -xf ../hal-info-&hal-info-version;.tar.bz2 &amp;&amp;
cd hal-info-&hal-info-version; &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc</userinput></screen>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--libexecdir=/usr/lib/hal</parameter>: This parameter
    forces the installation of libexec files to
    <filename class='directory'>/usr/lib/hal</filename> instead of
    <filename class='directory'>/usr/libexec</filename>.</para>

    <para><parameter>--localstatedir=/var</parameter>: This parameter forces
    the creation of the <filename>pid</filename> file to
    <filename class='directory'>/var/run/hald</filename> instead of
    <filename class='directory'>/usr/var/run/hald</filename>.</para>

    <para><parameter>--enable-policy-kit=no</parameter>: This parameter is
    required if PolicyKit is not installed. Remove it if PolicyKit is
    installed.</para>

    <para><parameter>--enable-docbook-docs
    --docdir=/usr/share/doc/hal-&hal-version;</parameter>: If <xref
    linkend="xmlto"/> is available, these parameters enable the
    <application>HAL</application> specification documentation to be
    built.</para>

  </sect2>

  <sect2>
    <title>Run-Time Dependencies</title>

    <para>A few more packages enable more functionality in
    <application>HAL</application> at run-time.
    These include <xref linkend="eject"/>, <ulink
    url="http://www.nongnu.org/dmidecode/">dmidecode</ulink>,
    <xref linkend="lvm2"/> (device-mapper),
    <ulink url="http://luks.endorphin.org/dm-crypt">Cryptsetup-LUKS</ulink>, and
    <ulink url="http://pm-utils.freedesktop.org/wiki/">pm-utils</ulink>.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring HAL</title>

    <sect3 id="hal-config">
      <title>Config Files</title>
      <para><filename>/etc/dbus-1/system.d/hal.conf</filename>,
      <filename>/etc/dbus-1/system.d/halusers.conf</filename> and
      <filename>/etc/hal/*</filename></para>

      <indexterm zone="hal hal-config">
        <primary sortas="e-etc-dbus-1-system.d-hal.conf">/etc/dbus-1/system.d/hal.conf</primary>
      </indexterm>

      <indexterm zone="hal hal-config">
        <primary sortas="e-etc-dbus-1-system.d-halusers.conf">/etc/dbus-1/system.d/halusers.conf</primary>
      </indexterm>

      <indexterm zone="hal hal-config">
        <primary sortas="e-etc-hal-star">/etc/hal/*</primary>
      </indexterm>
    </sect3>

    <sect3><title>Configuration Information</title>
    <sect4><title>Allowing users to invoke HAL methods</title>

      <para>The default setup for <application>HAL</application> is to allow
      only certain users to invoke methods such as Mount(). These are
      the <systemitem class="username">root</systemitem> user and the user
      determined to be at the active console using <ulink
      url="&blfs-wiki;/linux-pam">pam_console</ulink>. If you are not set
      up to use <xref linkend="linux-pam"/> and <ulink
      url="&blfs-wiki;/linux-pam">pam_console</ulink>, create a group that
      is allowed to invoke <application>HAL</application> methods with the
      following commands:</para>

<screen role="root"><userinput>groupadd -fg 61 halusers &amp;&amp;
cat &gt; /etc/dbus-1/system.d/halusers.conf &lt;&lt; "EOF"
<literal>&lt;!DOCTYPE busconfig PUBLIC
 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
&lt;busconfig&gt;

 &lt;!-- Allow users in the halusers group invoke HAL methods --&gt;
 &lt;policy group="halusers"&gt;
  &lt;allow send_interface="org.freedesktop.Hal.Device.SystemPowerManagement"/&gt;
  &lt;allow send_interface="org.freedesktop.Hal.Device.LaptopPanel"/&gt;
  &lt;allow send_interface="org.freedesktop.Hal.Device.Volume"/&gt;
  &lt;allow send_interface="org.freedesktop.Hal.Device.Volume.Crypto"/&gt;
 &lt;/policy&gt;

&lt;/busconfig&gt;</literal>
EOF</userinput></screen>

      <para>Now add the users you would like to the <systemitem
      class="groupname">halusers</systemitem> group to use
      <application>HAL</application>.</para>

<screen role="root"><userinput>usermod -a -G halusers <replaceable>&lt;username&gt;</replaceable></userinput></screen>

      <para>Note that these users still need
      to have appropriate permissions to access the devices that
      <application>HAL</application> will invoke its methods on.</para>

      <para>With the above configuration in place, authorized users now
      have the ability to unmount disk partitions mounted at non-standard
      locations such as <filename class='directory'>/pub</filename>. If
      you'd like to restrict this policy to only drives which are considered
      removable or hotpluggable, add the following configuration file as
      the <systemitem class='username'>root</systemitem> user:</para>

<screen role="root"><userinput>cat &gt; /etc/hal/fdi/policy/no-fixed-drives.fdi &lt;&lt; "EOF"
<literal>&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;!-- -*- SGML -*- --&gt;

&lt;!-- Don't allow HAL methods on disks that are not
     removable or hotpluggable --&gt;

&lt;deviceinfo version="0.2"&gt;
&lt;device&gt;
  &lt;match key="@block.storage_device:storage.hotpluggable" bool="false"&gt;
    &lt;match key="@block.storage_device:storage.removable" bool="false"&gt;
      &lt;merge key="volume.ignore" type="bool"&gt;true&lt;/merge&gt;
    &lt;/match&gt;
  &lt;/match&gt;
&lt;/device&gt;
&lt;/deviceinfo&gt;</literal>
EOF</userinput></screen>
      </sect4>

      <sect4><title>Installing mount helpers</title>
      <para><application>HAL</application> only provides the methods such
      as Mount() to act on hardware. In order to take advantage of these,
      a <application>HAL</application> event handler such as <ulink
      url="http://ivman.sourceforge.net/">Ivman</ulink> should be
      installed.</para>
      <!-- FIXME: is Ivman still alive? -->
      <!-- FIXME: explicitly name the mount helpers
           from KDE (???) and Xfce (exo-mount) -->
      </sect4>

      <sect4><title>Changing default mount options</title>
      <para>In some cases, it is necessary to specify some default mount
      options for filesystems. E.g., in non-English environments, the
      <option>iocharset</option> and <option>codepage</option> options
      are needed for filesystems of Windows origin in order to show
      national characters correctly. Also, due to a
      <ulink url="https://launchpad.net/bugs/133567">bug</ulink> in the
      Linux kernel version in LFS (2.6.22.x), you may want to pass the
      <option>usefree</option> option to vfat filesystems in order to reduce
      the time needed to determine the amount of free space on the
      filesystem.</para>

      <para>Google search results for <quote>hal default mount options</quote>
      are still full of recommendations to create <filename>*.fdi</filename>
      files mentioning either
      <option>volume.policy</option> or <option>storage.policy</option> keys.
      Such recommendations worked for HAL-0.4.x only and are invalid now.
      For HAL-&hal-version;, mount options are expected to be handled
      as follows:</para>

      <itemizedlist>
        <listitem>
          <para>An event handler from the desktop environment receives an
          event describing the newly-added storage device.</para>
        </listitem>
        <listitem>
          <para>If the storage device is not already mentioned in
          <filename>/etc/fstab</filename>, mount options are fetched from
          a database of user preferences, which is specific to the desktop
          environment, and passed back to HAL.
          This process can be influenced by the filesystem type
          and possibly other volume properties available from HAL.</para>
        </listitem>
        <listitem>
          <para>If the options are in the list of permitted ones, HAL
          mounts the volume.</para>
        </listitem>
      </itemizedlist>

      <para>The important point above is that the configuration procedure is
      desktop-specific. However, as of December, 2007, only GNOME allows the
      user to set default mount options on a per-filesystem basis,
      as described in the next paragraph.
      KDE allows the mount options to be set only on a per-volume basis,
      not per-filesystem, which is a
      <ulink url="http://bugs.kde.org/show_bug.cgi?id=133456">bug</ulink>,
      because, as mentioned in the report, <quote>for every new device (let's
      say your friend's USB stick) you have to first not mount it, then change
      options and then mount</quote>. Xfce, if compiled with HAL support,
      <ulink url="http://bugzilla.xfce.org/show_bug.cgi?id=2891">hard-codes</ulink>
      the mount options without any means to override them,
      which is even worse.
      <!-- (for BLFS editors only: they mention policy-kit as a future
           solution, but, from the description, policy-kit looks like
           an XML-ized sudo-like configuration parser, which has nothing
           common with the "default mount options" problem. -->
      In KDE and Xfce, if the built-in default mount options are not suitable,
      it is needed to mention every possible removable storage device in
      <filename>/etc/fstab</filename> with the correct options, thus mostly
      defeating the point of installing HAL.</para>

      <para>In order to adjust the default mount options, GNOME users should
      change the
      <systemitem>/system/storage/default_options/[fs_type]/mount_options</systemitem>
      GConf key <!--either using <xref linkend="gconf-editor"/>, or -->from the
      command line, as demonstrated in the following example:</para>

<screen><userinput>gconftool-2 --type list --list-type=string \
    --set /system/storage/default_options/vfat/mount_options \
    "[shortname=mixed,uid=,usefree,iocharset=koi8-r,codepage=866]"</userinput></screen>

      <para>See more details in the gnome-mount(1) manual page.</para>
      </sect4>

      <sect4><title>Adding allowed mount options</title>
      <para>The list of mount options permitted in the default HAL
      configuration resides in the
      <filename>/usr/share/hal/fdi/policy/10osvendor/20-storage-methods.fdi</filename>
      file. GNOME and KDE users may want to use options not in this
      list (in the above example, this applies to the <option>usefree</option>
      option). In this case, as <systemitem class="username">root</systemitem>
      user, create a custom policy file that mentions unknown mount
      options:</para>

<screen role="root"><userinput>cat &gt; /etc/hal/fdi/policy/user-options.fdi &lt;&lt; "EOF"
<literal>&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;!-- -*- SGML -*- --&gt;

&lt;!--
This file is used to set custom options to the HAL policy settings.
The default policy settings are defined in files contained in the
/usr/share/hal/fdi/policy subdirectories. User defined customizations
should be in files contained in the /etc/hal/fdi/policy directory.
--&gt;

&lt;deviceinfo version="0.2"&gt;
  &lt;device&gt;

    &lt;!-- this is to be able to mount media in drives we cannot poll,
         e.g. IDE Zip Drives and PC style floppy drives --&gt;
    &lt;match key="storage.media_check_enabled" bool="false"&gt;
      &lt;match key="storage.no_partitions_hint" bool="true"&gt;
        &lt;append key="volume.mount.valid_options" type="strlist"&gt;usefree&lt;/append&gt;
        &lt;!-- Insert other options here --&gt;
      &lt;/match&gt;
    &lt;/match&gt;

    &lt;match key="volume.fsusage" string="filesystem"&gt;

      &lt;!-- allow these mount options for vfat --&gt;
      &lt;match key="volume.fstype" string="vfat"&gt;
        &lt;append key="volume.mount.valid_options" type="strlist"&gt;usefree&lt;/append&gt;
        &lt;!-- Insert other options here --&gt;
      &lt;/match&gt;
    &lt;/match&gt;

  &lt;/device&gt;
&lt;/deviceinfo&gt;</literal>
EOF</userinput></screen>

    </sect4>
    </sect3>

    <sect3  id="hal-init">
      <title>Boot Script</title>

      <para>To automatically start the <command>hald</command> daemon
      when the system is rebooted, install the
      <filename>/etc/rc.d/init.d/haldaemon</filename>
      bootscript from the
      <xref linkend="bootscripts"/> package.</para>

      <indexterm zone="hal hal-init">
        <primary sortas="f-haldaemon">haldaemon</primary>
      </indexterm>

      <important>
        <para>If the system-wide <application>D-BUS</application> daemon was
        running during the installation of <application>HAL</application>,
        ensure you stop and restart the <application>D-BUS</application>
        daemon before attempting to start the <command>hald</command>
        daemon.</para>
      </important>

<screen role="root"><userinput>make install-haldaemon</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>hal-device, hal-disable-polling,
        hal-find-by-capability, hal-find-by-property, hal-get-property,
        hal-is-caller-locked-out, hal-lock, hal-set-property, hald and
        lshal</seg>
        <seg>libhal.{so,a} and libhal-storage,{so,a}</seg>
        <seg>/etc/hal, /usr/include/hal, /usr/lib/hal,
        /usr/share/doc/hal-&hal-version;, /usr/share/hal, /var/cache/hald,
        /var/lib/hal, and /var/run/hald</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="hal-device">
        <term><command>hal-device</command></term>
        <listitem>
          <para>is used to create, remove or show a
          <application>HAL</application> device.</para>
          <indexterm zone="hal hal-device">
            <primary sortas="b-hal-device">hal-device</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-disable-polling">
        <term><command>hal-disable-polling</command></term>
        <listitem>
          <para>can be used to to disable and enable media detection on
          drives with removable storage.</para>
          <indexterm zone="hal hal-disable-polling">
            <primary sortas="b-hal-disable-polling">hal-disable-polling</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-find-by-capability">
        <term><command>hal-find-by-capability</command></term>
        <listitem>
          <para>prints the Unique Device Identifiers for
          <application>HAL</application> device objects of a given
          capability.</para>
          <indexterm zone="hal hal-find-by-capability">
            <primary sortas="b-hal-find-by-capability">hal-find-by-capability</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-find-by-property">
        <term><command>hal-find-by-property</command></term>
        <listitem>
          <para>prints the Unique Device Identifiers for
          <application>HAL</application> device objects where a given property
          assumes a given value.</para>
          <indexterm zone="hal hal-find-by-property">
            <primary sortas="b-hal-find-by-property">hal-find-by-property</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-get-property">
        <term><command>hal-get-property</command></term>
        <listitem>
          <para>retrieves a property from a device.</para>
          <indexterm zone="hal hal-get-property">
            <primary sortas="b-hal-get-property">hal-get-property</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-set-property">
        <term><command>hal-set-property</command></term>
        <listitem>
          <para>attempts to set property for a device. Note that, due to
          security considerations, it may not be possible to set a
          property.</para>
          <indexterm zone="hal hal-set-property">
            <primary sortas="b-hal-set-property">hal-set-property</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hal-is-caller-locked-out">
        <term><command>hal-is-caller-locked-out</command></term>
        <listitem>
          <para>determines if a specific caller is locked out of a specific
          <application>D-Bus</application> interface on a specific device.</para>
          <indexterm zone="hal hal-is-caller-locked-out">
            <primary sortas="b-hal-is-caller-locked-out">hal-is-caller-locked-out</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="hald">
        <term><command>hald</command></term>
        <listitem>
          <para>is the <application>HAL</application> daemon program.</para>
          <indexterm zone="hal hald">
            <primary sortas="b-hald">hald</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lshal">
        <term><command>lshal</command></term>
        <listitem>
          <para>shows all devices and their properties. If the --monitor option
          is given then the device list and all devices are monitored for
          changes.</para>
          <indexterm zone="hal lshal">
            <primary sortas="b-lshal">lshal</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libhal">
        <term><filename class='libraryfile'>libhal.{so,a}</filename></term>
        <listitem>
          <para>contains the API functions required by the
          <application>HAL</application> programs.</para>
          <indexterm zone="hal libhal">
            <primary sortas="c-libhal">libhal.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libhal-storage">
        <term><filename class='libraryfile'>libhal-storage.{so,a}</filename></term>
        <listitem>
          <para>contains the API functions required by the
          <application>HAL</application> storage and volume utility
          programs.</para>
          <indexterm zone="hal libhal-storage">
            <primary sortas="c-libhal-storage">libhal-storage.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>