source: general/sysutils/dbus.xml@ 816dc876

<?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  " ">
  <!ENTITY dbus-md5sum        "020824a38850501e7d6ba8307a7c5ac3">
  <!ENTITY dbus-size          "1.8 MB">
  <!ENTITY dbus-buildsize     "28 MB (additional 81 MB for the documentations and 8 MB for the tests)">
  <!ENTITY dbus-time          "0.4 SBU (additional 0.6 SBU for the tests)">
]>

<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>

    &lfs77_checked;

    <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"/>
    </para>
-->
    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="xorg7-lib"/> (for <command>dbus-launch</command> program)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      For the tests:
      <xref linkend="dbus-glib"/>,
      <xref linkend="dbus-python"/>, and
      <xref linkend="pygobject2"/>; 
      
      for the development documentation:
      <xref linkend="doxygen"/>; 
      
      for man pages and XML/HTML documentation:
      <xref linkend="xmlto"/>
    </para>

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

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

    <para>
      If they do not already exist,
      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 /var/run/dbus \
        -u 18 -g messagebus -s /bin/false messagebus</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              \
            --localstatedir=/var           \
            --disable-doxygen-docs         \
            --disable-xml-docs             \
            --disable-static               \
            --disable-systemd              \
            --without-systemdsystemunitdir \
            --with-console-auth-dir=/run/console/ \
            --docdir=/usr/share/doc/dbus-&dbus-version;   &amp;&amp;
make</userinput></screen>

    <para>
      See below for test instructions.
    </para>

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

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

    <para>
      If you are still building your system in chroot or you did not start the
      daemon yet, but you want to compile some packages that require
      <application>D-Bus</application>, generate
      <application>D-Bus</application> UUID to avoid warnings when compiling
      some packages with the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>dbus-uuidgen --ensure</userinput></screen>

    <para>
      The dbus tests cannot be run until after <xref linkend="dbus-glib"/> has
      been installed.  They must be run as an unprivileged user from a local
      session with bus address. Tests fail through ssh. If you want to run only
      the unit tests, replace, below, <parameter>--enable-tests</parameter> by
      <parameter>--enable-embedded-tests</parameter>, otherwise, <xref
      linkend="dbus-python"/> has to be installed, before.  The tests require
      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>.  If you would like to run the tests,
      issue the following commands (for the tests, you don't need to build the
      docs):
    </para>

<screen><userinput>make distclean                     &amp;&amp;
./configure --enable-tests         \
            --enable-asserts       \
            --disable-doxygen-docs \
            --disable-xml-docs     &amp;&amp;
make                               &amp;&amp;
make check</userinput></screen>

    <para>
      If <command>run-test.sh</command> fails, it can be disabled with the
      following sed, before running the commands for the tests:
    </para>

<screen><userinput>sed -i -e 's:run-test.sh:$(NULL):g' test/name-test/Makefile.in</userinput></screen>

    <para>
      Note there has been a report that the tests may fail if running
      inside a Midnight Commander shell.
      You may get out-of-memory error messages when running the tests.
      These are normal and can be safely ignored.
    </para>

  </sect2>

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

    <para>
      <parameter>--disable-doxygen-docs</parameter>: This switch disables
      doxygen documentation build and install, if you have
      <application>doxygen</application> installed. Delete, if
      <application>doxygen</application> is installed and you wish to build and
      install them.
    </para>

    <para>
      <parameter>--disable-xml-docs</parameter>: This switch disables html
      documentation build and install, if you have
      <application>xmlto</application> installed. Delete, if
      <application>xmlto</application> is installed and you wish to build and
      install them.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

    <para>
      <parameter>--disable-systemd</parameter>: This switch disables systemd
      support in <application>D-Bus</application>.
    </para>

    <para>
      <parameter>--without-systemdsystemunitdir</parameter>: This switch
      prevents installation of systemd unit files.
    </para>

    <para>
      <parameter>--with-console-auth-dir=/run/console/</parameter>: This
      parameter specifies location of the
      <application>ConsoleKit</application> auth dir.
    </para>

    <para>
      <parameter>--enable-tests</parameter>: Build extra parts of the code to
      support all tests. Configure will end with a NOTE warning about increased
      size of libraries and decreased security.
    </para>

    <para>
      <parameter>--enable-embedded-tests</parameter>: Build extra parts of the
      code to support only unit tests. Configure will end with a NOTE warning
      about increased size of libraries and decreased security.
    </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>

  </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>

    </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.
          </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>
            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 be 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-run-session, dbus-send and dbus-uuidgen
        </seg>
        <seg>
           libdbus-1.so
        </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;,
          /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-run-session">
        <term><command>dbus-run-session</command></term>
        <listitem>
          <para>
            start a process as a new <application>D-Bus</application> session.
          </para>
          <indexterm zone="dbus dbus-run-session">
            <primary sortas="b-dbus-run-session">dbus-run-session</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 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</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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>