<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [

<!--ArborText, Inc., 1988-1999, v.4002-->

<!ENTITY cmd "dbus-daemon">

<!ENTITY % commonents SYSTEM "smancommon.ent">

%commonents;

<!ENTITY % booktitles SYSTEM "booktitles.ent">

%booktitles;

<!ENTITY suncopy "Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.">

]>

<?Pub UDT _bookmark _target>

<?Pub Inc>

<refentry id="dbus-daemon-1">

<!-- %Z%%M% %I% %E% SMI; -->

<refmeta><refentrytitle>&cmd;</refentrytitle><manvolnum>3</manvolnum>

<refmiscinfo class="date">19 Nov 2007</refmiscinfo>

<refmiscinfo class="sectdesc">&man3;</refmiscinfo>

<refmiscinfo class="software">&release;</refmiscinfo>

<refmiscinfo class="arch">generic</refmiscinfo>

<refmiscinfo class="copyright">&suncopy;</refmiscinfo>

</refmeta>

<indexterm><primary>&cmd;</primary></indexterm><indexterm><primary>

Message bus daemon

</primary></indexterm><refnamediv id="dbus-daemon-1-name">

<refname>&cmd;</refname><refpurpose>

Message bus daemon

</refpurpose></refnamediv>

<refsynopsisdiv id="dbus-daemon-1-synp"><title>&synp-tt;</title>

<cmdsynopsis><command>&cmd;</command>

<arg choice="opt"><option>-config-file=<replaceable>file</replaceable></option></arg>

<arg choice="opt"><option>-fork</option> | <option>-nofork</option></arg>

<arg choice="opt"><option>-introspect</option></arg>

<arg choice="opt"><option>-print-address[=<replaceable>descriptor</replaceable>]</option></arg>

<arg choice="opt"><option>-print-pid[=<replaceable>descriptor</replaceable>]</option></arg>

<arg choice="opt"><option>-session</option></arg>

<arg choice="opt"><option>-system</option></arg>

<arg choice="opt"><option>-version</option></arg>

</cmdsynopsis></refsynopsisdiv>

<refsect1 id="dbus-daemon-1-desc"><title>&desc-tt;</title>

<para>

&cmd; is the D\-Bus message bus daemon.  See

<literal>http://www.freedesktop.org/software/dbus/</literal>

for more information.  D\-Bus is first a library that provides one\-to\-one

communication between any two applications; &cmd; is an application that uses

this library to implement a message bus daemon.  Multiple programs connect to

the message bus daemon and can exchange messages with one another.

</para>

<para>

There are two standard message bus instances.  &cmd; is used for both of these

instances, but with a different configuration file.

</para>

<itemizedlist>

<listitem><para>

systemwide message bus - Disabled and not supported on Solaris, but installed

on many systems as the "messagebus" init service.  Note that the

<option>-system</option> option is equivalent to:

</para>

<para>

"<option>-config\-file=/etc/dbus\-1/system.conf</option>"

</para></listitem>

<listitem><para>

per-user-login-session message bus - Enabled and supported on Solaris, and

started each time a user logs in.  Note that the 

<option>-session</option> option is equivalent to:

</para>

<para>

"<option>-config\-file=/etc/dbus\-1/session.conf</option>"

</para></listitem>

</itemizedlist>

<para>

By creating additional configuration files and using the

<option>-config\-file</option> option, additional special-purpose message bus

daemons could be created.

</para>

<para>

On Solaris, D\-Bus is configured with the systemwide message bus disabled.

The systemwide message bus is not used by any applications that are currently

shipped with Solaris.

</para>

<para>

The systemwide daemon is normally launched by an init script, standardly called

simply "messagebus".

</para>

<para>

The systemwide daemon is largely used for broadcasting system events, such as

changes to the printer queue, or adding/removing devices.

</para>

<para>

The per-session daemon is used for various interprocess communication among

desktop applications (however, it is not tied to X or the GUI in any way).

</para>

<para>

SIGHUP will cause the D\-Bus daemon to PARTIALLY reload its configuration file

and to flush its user/group information caches.  Some configuration changes

would require kicking all apps off the bus; so they will only take effect if

you restart the daemon. Policy changes should take effect with SIGHUP.

</para>

</refsect1>

<refsect1 id="dbus-daemon-1-opts"><title>&opts-tt;</title>

<para>The following options are supported:</para>

<variablelist termlength="wholescreen">

<varlistentry>

<term><option>-config-file=<replaceable>file</replaceable></option></term>

<listitem><para>

Use the given configuration <replaceable>file</replaceable>.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-fork</option></term>

<listitem><para>

Force the message bus to fork and become a daemon, regardless of configuration

file settings.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-introspect</option></term>

<listitem><para>

Print introspect data and exit.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-nofork</option></term>

<listitem><para>

Avoid running the message bus as a daemon, regardless of configuration file

settings.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-print-address[=<replaceable>descriptor</replaceable>]</option></term>

<listitem><para>

Print the address of the message bus to standard output, or to the given file

<replaceable>descriptor</replaceable>.  This is used by programs that launch

the message bus.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-print-pid[=<replaceable>descriptor</replaceable>]</option></term>

<listitem><para>

Print the process ID of the message bus to standard output, or to the given

file <replaceable>descriptor</replaceable>.  This is used by programs that

launch the message bus.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-session</option></term>

<listitem><para>

Use the standard configuration file for the per-login-session message bus.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-system</option></term>

<listitem><para>

Use the standard configuration file for the systemwide message bus.

</para>

</listitem></varlistentry>

<varlistentry>

<term><option>-version</option></term>

<listitem><para>

Print the version of the daemon.

</para>

</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="dbus-daemon-1-exde"><title>&exde-tt;</title>

<refsect2>

<title>CONFIGURATION FILE</title>

<para>

A message bus daemon has a configuration file that specializes it for a

particular application. For example, one configuration file might set up the

message bus to be a systemwide message bus, while another might set it

up to be a per-user-login-session bus.

</para>

<para>

The configuration file also establishes resource limits, security parameters,

and so forth.

</para>

<para>

The configuration file is not part of any interoperability specification and

its backward compatibility is not guaranteed; this document is documentation,

not specification.

</para>

<para>

The standard systemwide and per-session message bus setups are configured in

the files "<filename>/etc/dbus-1/system.conf</filename>" and

"<filename>/etc/dbus-1/session.conf</filename>".  These files normally

&lt;include&gt; a <filename>system-local.conf</filename> or

<filename>session-local.conf</filename>; you can put local overrides in those

files to avoid modifying the primary configuration files.

</para>

<para>

The configuration file is an XML document.  It must have the following doctype

declaration:

</para>

<screen>

   <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D\-Bus Bus Configuration 1.0//EN"

    "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">

</screen>

<para>

The following elements may be present in the configuration file.

Note that some configuration file options are only meaningful with 

the systemwide message bus, which is disabled on Solaris.  Such options

are only documented for reference.

</para>

<para>

<busconfig>

</para>

<para>

Root element.

</para>

<para>

<type>

</para>

<para>

The well-known type of the message bus.  Currently known values are "system"

and "session"; if other values are set, they should be either added to the

D\-Bus specification, or namespaced.  The last <type> element "wins"

(previous values are ignored).

</para>

<para>

Example: <type>session</type>

</para>

<para>

<include>

</para>

<para>

Include a file <include>filename.conf</include> at this point.  If

the filename is relative, it is located relative to the configuration file

doing the including.

</para>

<para>

<include> has an optional attribute "ignore_missing=(yes|no)" which

defaults to "no" if not provided.  This attribute controls whether it is a

fatal error for the included file to be absent.

</para>

<para>

<includedir>

</para>

<para>

Include all files in <includedir>foo.d</includedir> at this point.

Files in the directory are included in undefined order.  Only files ending in

".conf" are included.

</para>

<para>

This is intended to allow extension of the system bus by particular packages.

For example, if CUPS wants to be able to send out notification of printer queue

changes, it could install a file to /etc/dbus-1/system.d that allowed all apps

to receive this message and allowed the printer daemon user to send it.

</para>

<para>

<user>

</para>

<para>

The user account the daemon should run as, as either a username or a UID.

If the daemon cannot change to this UID on startup, it will exit.  If this

element is not present, the daemon will not change or care about its UID.

</para>

<para>

The last <user> entry in the file "wins", the others are ignored.

</para>

<para>

The user is changed after the bus has completed initialization.  So sockets

etc. will be created before changing user, but no data will be read from

clients before changing user.  This means that sockets and PID files can be

created in a location that requires root privileges for writing.

</para>

<para>

<fork>

</para>

<para>

If present, the bus daemon becomes a real daemon (forks into the background,

etc.).  This is generally used rather than the <option>-fork</option> command

line option.

</para>

<para>

<listen>

</para>

<para>

Add an address that the bus should listen on. The address is in the standard

D\-Bus format that contains a transport name plus possible parameters/options.

</para>

<screen>

     Example: <listen>unix:path=/tmp/foo</listen>

     Example: <listen>tcp:host=localhost,port=1234</listen>

</screen>

<para>

If there are multiple <listen> elements, then the bus listens on multiple

addresses.  The bus will pass its address to started services or other

interested parties with the last address given in <listen> first. That

is, apps will try to connect to the last <listen> address first.

</para>

<para>

tcp sockets can accept IPv4 addresses, IPv6 addresses or hostnames.  If a

hostname resolves to multiple addresses, the server will bind to all of them.

The family=ipv4 or family=ipv6 options can be used to force it to bind to a

subset of addresses.

</para>

<screen>

     Example:

     <listen>tcp:host=localhost,port=0,family=ipv4</listen>

</screen>

<para>

A special case is using a port number of zero (or omitting the port), which

means to choose an available port selected by the operating system.  The port

number chosen can be obtained with the <option>-print-address</option> command

line parameter and will be present in other cases where the server reports its

own address, such as when DBUS_SESSION_BUS_ADDRESS is set.

</para>

<screen>

     Example: <listen>tcp:host=localhost,port=0</listen>

</screen>

<para>

tcp addresses also allow a bind=hostname option, which will override the host

option specifying what address to bind to, without changing the address

reported by the bus.  The bind option can also take a special name '*' to

cause the bus to listen on all local address (INADDR_ANY). The specified host

should be a valid name of the local machine or weird stuff will happen.

</para>

<screen>

     Example: <listen>tcp:host=localhost,bind=*,port=0</listen>

</screen>

<para>

<auth>

</para>

<para>

Lists permitted authorization mechanisms.  If this element does not exist, then

all known mechanisms are allowed.  If there are multiple <auth> elements,

all the listed mechanisms are allowed.  The order in which mechanisms are

listed is not meaningful.

</para>

<screen>

     Example: <auth>EXTERNAL</auth>

     Example: <auth>DBUS_COOKIE_SHA1</auth>

</screen>

<para>

<servicedir>

</para>

<para>

Adds a directory to scan for <filename>.service</filename> files.  Directories

are scanned starting with the last to appear in the config file (the first

<filename>.service</filename> file found that provides a particular service

will be used).

</para>

<para>

Service files tell the bus how to automatically start a program.  They are

primarily used with the per-user-session bus, not the systemwide bus.

</para>

<para>

<standard session servicedirs/>

</para>

<para>

<standard_session_servicedirs/> is equivalent to specifying a series of

<servicedir/> elements for each of the data directories in the "XDG Base

Directory Specification" with the subdirectory "dbus-1/services", so for

example "/usr/share/dbus-1/services" would be among the directories searched.

</para>

<para>

The "XDG Base Directory Specification" should be found at

<literal>http://freedesktop.org/wiki/Standards/basedir-spec</literal>.

</para>

<para>

The <standard_session_servicedirs/> option is only relevant to the

per-user-session bus daemon defined in

<filename>/etc/dbus\-1/session.conf</filename>.  Putting it in any other

configuration file would probably be nonsense.

</para>

<para>

<standard system servicedirs/>

</para>

<para>

<standard_system_servicedirs/> specifies the standard systemwide

activation directories that should be searched for service files.  This option

defaults to <filename>/usr/share/dbus-1/system-services</filename>.

</para>

<para>

The <standard_system_servicedirs/> option is only relevant

to the per-system bus daemon defined in

<filename>/etc/dbus\-1/system.conf</filename>.  Putting it in any other

configuration file would probably be nonsense.

</para>

<para>

<servicehelper/>

</para>

<para>

<servicehelper/> specifies the setuid helper that is used to launch

system daemons with an alternate user.  Typically this would be the

<command>dbus-daemon-launch-helper</command> executable.  Because the

systemwide message bus is disabled on Solaris, the

<command>dbus-daemon-launch-helper</command> executable is not distributed

with Solaris.

</para>

<para>

The <servicehelper/> option is only relevant to the per-system bus

daemon defined in <filename>/etc/dbus-1/system.conf</filename>.  Putting it in

any other configuration file would probably be nonsense.

</para>

<para>

<limit>

</para>

<para>

<limit> establishes a resource limit. For example:

</para>

<screen>

       <limit name="max_message_size">64</limit>

       <limit name="max_completed_connections">512</limit>

</screen>

<para>

The name attribute is mandatory.  Available limit names are:

</para>

<screen>

    "max_incoming_bytes"             : total size in bytes

                                       of messages incoming

                                       from a single

                                       connection

    "max_outgoing_bytes"             : total size in bytes

                                       of messages queued up

                                       for a single

                                       connection

    "max_message_size"               : max size of a single

                                       message in bytes

    "service_start_timeout"          : milliseconds

                                       (thousandths) until

                                       a started service has

                                       to connect

    "auth_timeout"                   : milliseconds

                                       (thousandths) a

                                       connection is given

                                       to authenticate

    "max_completed_connections"      : max number of

                                       authenticated

                                       connections

    "max_incomplete_connections"     : max number of

                                       unauthenticated

                                       connections

    "max_connections_per_user"       : max number of

                                       completed connections

                                       from the same user

    "max_pending_service_starts"     : max number of service

                                       launches in progress

                                       at the same time

    "max_names_per_connection"       : max number of names a

                                       single connection can

                                       own

    "max_match_rules_per_connection" : max number of match

                                       rules for a single

                                       connection

    "max_replies_per_connection"     : max number of pending

                                       method replies per

                                       connection (number of

                                       calls-in-progress)

    "reply_timeout"                  : milliseconds

                                       (thousandths) until a

                                       method call times out

</screen>

<para>

The max incoming/outgoing queue sizes allow a new message to be queued if one

byte remains below the max.  So you can in fact exceed the max by

max_message_size.

</para>

<para>

max_completed_connections divided by max_connections_per_user is the number of

users that can work together to denial-of-service all other users by using up

all connections on the systemwide bus.

</para>

<para>

Limits are normally only of interest on the systemwide bus, not the user

session buses.

</para>

<para>

<policy>

</para>

<para>

The <policy> element defines a security policy to be applied to a

particular set of connections to the bus. A policy is made up of <allow>

and <deny> elements.  Policies are normally used with the systemwide bus;

they are analogous to a firewall in that they allow expected traffic and

prevent unexpected traffic.

</para>

<para>

The <policy> element has one of three attributes:

</para>

<itemizedlist>

<listitem><para>

context="(default|mandatory)"

</para></listitem>

<listitem><para>

user="username or userid"

</para></listitem>

<listitem><para>

group="group name or gid"

</para></listitem>

</itemizedlist>

<para>

Policies are applied to a connection as follows:

</para>

<itemizedlist>

<listitem><para>