source: general/sysutils/dbus.xml@ da167e4

<?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 dbus-download-http "http://dbus.freedesktop.org/releases/dbus/dbus-&dbus-version;.tar.gz">
  <!--<!ENTITY dbus-download-ftp  "&gentoo-ftp-repo;/dbus-&dbus-version;.tar.gz">-->
  <!ENTITY dbus-download-ftp  " ">
  <!ENTITY dbus-md5sum        "2e643910a09f44b000a0d76038637999">
  <!ENTITY dbus-size          "1.5 MB">
  <!ENTITY dbus-buildsize     "24 MB">
  <!ENTITY dbus-time          "0.5 SBU">
]>

<sect1 id="dbus" xreflabel="D-BUS-&dbus-version;">
  <?dbhtml filename="dbus.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>D-BUS-&dbus-version;</title>

  <indexterm zone="dbus">
    <primary sortas="a-D-BUS">D-BUS</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to D-BUS</title>

    <para><application>D-BUS</application> is a message bus system, a simple
    way for applications to talk to one another.
    <application>D-BUS</application> supplies both a system daemon (for events
    such as <quote>new hardware device added</quote> or <quote>printer queue
    changed</quote>) and a per-user-login-session daemon (for general IPC needs
    among user applications). Also, the message bus is built on top of a
    general one-to-one message passing framework, which can be used by any two
    applications to communicate directly (without going through the message bus
    daemon).</para>

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

    <bridgehead renderas="sect3">D-BUS Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="expat"/> or both
    <xref linkend="pkgconfig"/>
    and <xref linkend="libxml2"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="x-window-system"/>,
    <xref linkend="doxygen"/> (to generate the API documentation)
    </para>

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

  </sect2>

  <sect2 role="kernel" id='dbus-kernel'>
    <title>Kernel Configuration</title>

    <para>Ensure the following option is enabled in the kernel configuration
    and recompile the kernel if necessary:</para>

<screen><literal>General Setup
  System V IPC</literal></screen>

    <indexterm zone="dbus dbus-kernel">
      <primary sortas="d-dbus">dbus</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of D-BUS</title>

    <para>As the <systemitem class="username">root</systemitem> user, create a
    system user and group to handle the system message bus activity:</para>

<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
useradd -c "D-BUS Message Daemon User" -d /dev/null \
        -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>

    <para>This package's test suite cannot be run without passing additional
    parameters to <command>configure</command> and exposing additional
    functionality in the binaries. These interfaces are not intended to be
    used in a production build of <application>D-BUS</application>, so it
    will have to be built twice in this situation. If you would like to run
    the unit tests, issue the following commands:</para>

<screen><userinput>./configure --enable-tests --enable-asserts &amp;&amp;
make &amp;&amp;
make check &amp;&amp;
make distclean</userinput></screen>

    <para>Install <application>D-BUS</application> by running the following
    commands (you may wish to review the output from
    <command>./configure --help</command> first and add any desired parameters
    to the <command>configure</command> command shown below):</para>

<screen><userinput>./configure --prefix=/usr \
            --sysconfdir=/etc \
            ----libexecdir=/usr/lib/dbus-1.0  \
            --localstatedir=/var &amp;&amp;
make</userinput></screen>

    <para>The <option>--enable-doxygen-docs</option> parameter does not work
    properly. If you have <application>Doxygen</application> installed and you
    wish to build the API documentation, issue
    <command>doxygen Doxyfile</command>.</para>

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

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/dbus-&dbus-version; &amp;&amp;
install -v -m644 doc/{TODO,*.{dtd,html,xml,xsl,txt,c}} \
    /usr/share/doc/dbus-&dbus-version; &amp;&amp;</userinput></screen>

    <para>If you built the API documentation, install it by issuing the
    following commands as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m755 -d /usr/share/doc/dbus-&dbus-version;/api \
    /usr/share/man/man3dbus &amp;&amp;
install -v -m644 doc/api/html/* \
    /usr/share/doc/dbus-&dbus-version;/api &amp;&amp;
install -v -m644 doc/api/man/man3dbus/* \
    /usr/share/man/man3dbus</userinput></screen>

  </sect2>

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

    <para><parameter>--libexecdir=/usr/lib/dbus-1.0 </parameter>: This will
    install the file <filename>dbus-daemon-launch-helper</filename> and the
    directory <filename class="directory">dbus-1</filename> into
    <filename class="directory">/usr/lib/dbus-1.0</filename> instead of
    into <filename class="directory">/usr/libexec</filename>.</para>

    <para><parameter>--localstatedir=/var</parameter>: This parameter causes
    the daemon PID file, system bus socket and machine uuid file to be
    created in the <filename class="directory">/var</filename> directory
    instead of the <filename class="directory">/usr/var</filename>
    directory.</para>

    <para><parameter>--enable-tests</parameter>: Build extra parts of the code
    to support testing. Configure will end with a NOTE warning about this.</para>

    <para><parameter>--enable-asserts</parameter>: Enable debugging code to run
    assertions for statements normally assumed to be true. This prevents a
    warning that '<parameter>--enable-tests</parameter>' on its own is only useful
    for profiling and might not give true results for all tests, but adds its own
    NOTE that this should not be used in a production build.
    </para>

    <para><parameter>--disable-static</parameter>: Prevent the static libraries
    being built.</para>

  </sect2>

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

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

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

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

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

    </sect3>

    <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
      <title>Configuration Information</title>

      <para>The configuration files listed above should probably not be
      modified. If changes are required, you should create
      <filename>/etc/dbus-1/session-local.conf</filename> and/or
      <filename>/etc/dbus-1/system-local.conf</filename> and make any
      desired changes to these files.</para>

      <para>If any packages install a
      <application>D-Bus</application> <filename>.service</filename>
      file outside of the standard <filename
      class="directory">/usr/share/dbus-1/services</filename> directory,
      that directory should be added to the local session configuration.
      For instance, <filename
      class="directory">/usr/local/share/dbus-1/services</filename> can
      be added by performing the following commands as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.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;!-- Search for .service files in /usr/local --&gt;
  &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;

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

      <para>Many packages will refuse to run if the file
      <literal>/var/lib/dbus/machine-id</literal> does not exist, and
      complain that <application>dbus</application> has not been properly
      installed. To prevent this, run the following command as the
       <systemitem class="username">root</systemitem> user:</para>

<screen><userinput>dbus-uuidgen --ensure</userinput></screen>

      <para>This will create a unique identifier for the machine.</para>

    </sect3>

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

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

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

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

      <para>Note that this boot script only starts the system-wide
      <application>D-BUS</application> daemon. Each user requiring access to
      <application>D-BUS</application> services will also need to run a
      session daemon as well. There are many methods you can use to start a
      session daemon using the <command>dbus-launch</command> command. Review
      the <command>dbus-launch</command> man page for details about the
      available parameters and options. Here are some suggestions and
      examples:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>Add <command>dbus-launch</command> to the line in the
          <filename>~/.xinitrc</filename> file that starts your graphical
          desktop environment as shown in <xref linkend="gnome-config"/>.</para>
        </listitem>
        <listitem>
          <para>If you use <command>xdm</command> or some other display manager
          that calls the <filename>~/.xsession</filename> file, you can add
          <command>dbus-launch</command> to the line in your
          <filename>~/.xsession</filename> file that starts your graphical
          desktop environment. The syntax would be similar to the example in
          the <filename>~/.xinitrc</filename> file.</para>
        </listitem>
        <listitem>
          <para>If you use <command>gdm</command> or some other display manager
          that utilizes custom files to initiate sessions, use the example in
          <xref linkend="gdm-config-dbus"/> of the
          <application>GDM</application> instructions to create a file
          containing <command>dbus-launch</command>.</para>
        </listitem>
        <listitem>
          <para>The examples shown previously use
          <command>dbus-launch</command> to specify a program to be run. This
          has the benefit (when also using the
          <parameter>--exit-with-session</parameter> parameter) of stopping the
          session daemon when the specified program is stopped. You can also
          start the session daemon in your system or personal startup scripts
          by adding the following lines:</para>

<screen><userinput><literal># Start the D-BUS session daemon
eval `dbus-launch`
export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>

          <para>This method will not stop the session daemon when you exit
          your shell, therefore you should add the following line to your
          <filename>~/.bash_logout</filename> file:</para>

<screen><userinput><literal># Kill the D-BUS session daemon
kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
        </listitem>

        <listitem>
          <para>A hint has been written that provides ways to start scripts
          using the KDM session manager of KDE. The concepts in this hint could
          possibly used with other session managers as well. The hint is
          located at <ulink
          url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
          </para>
        </listitem>

      </itemizedlist>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
        dbus-send, dbus-uuidgen</seg>
        <seg>libdbus-1.{so,a}</seg>
        <seg>/etc/dbus-1, /usr/include/dbus-1.0, /usr/lib/dbus-1.0,
        /usr/share/dbus-1, /usr/share/doc/dbus-&dbus-version;,
        /usr/share/man/man3dbus, /var/lib/dbus and /var/run/dbus</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="dbus-cleanup-sockets">
        <term><command>dbus-cleanup-sockets</command></term>
        <listitem>
          <para>is used to clean up leftover sockets in a directory.</para>
          <indexterm zone="dbus dbus-cleanup-sockets">
            <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-daemon">
        <term><command>dbus-daemon</command></term>
        <listitem>
          <para>is the <application>D-BUS</application> message bus
          daemon.</para>
          <indexterm zone="dbus dbus-daemon">
            <primary sortas="b-dbus-daemon">dbus-daemon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-launch">
        <term><command>dbus-launch</command></term>
        <listitem>
          <para>is used to start <command>dbus-daemon</command> from a shell
          script. It  would  normally be called from a user's login
          scripts.</para>
          <indexterm zone="dbus dbus-launch">
            <primary sortas="b-dbus-launch">dbus-launch</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-monitor">
        <term><command>dbus-monitor</command></term>
        <listitem>
          <para>is used to monitor messages going through a
          <application>D-BUS</application> message bus.</para>
          <indexterm zone="dbus dbus-monitor">
            <primary sortas="b-dbus-monitor">dbus-monitor</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-send">
        <term><command>dbus-send</command></term>
        <listitem>
          <para>is used to send a message to a <application>D-BUS</application>
          message bus.</para>
          <indexterm zone="dbus dbus-send">
            <primary sortas="b-dbus-send">dbus-send</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-uuidgen">
        <term><command>dbus-uuidgen</command></term>
        <listitem>
          <para>is used to generate or read a universally unique ID.</para>
          <indexterm zone="dbus dbus-uuidgen">
            <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdbus-1">
        <term><filename class='libraryfile'>libdbus-1.{so,a}</filename></term>
        <listitem>
          <para>contains the API functions used by the
          <application>D-BUS</application> message daemon.
          <application>D-BUS</application> is first a library that provides
          one-to-one communication between any two applications;
          <command>dbus-daemon</command> is an application that uses this
          library to implement a message bus daemon.</para>
          <indexterm zone="dbus libdbus-1">
            <primary sortas="c-libdbus-1">libdbus-1.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>