dbus-daemon.1 revision 13931
13931N/A<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
13931N/A<!--ArborText, Inc., 1988-1999, v.4002-->
13931N/A<!ENTITY cmd "dbus-daemon">
13931N/A<!ENTITY % commonents SYSTEM "smancommon.ent">
13931N/A%commonents;
13931N/A<!ENTITY % booktitles SYSTEM "booktitles.ent">
13931N/A%booktitles;
13931N/A<!ENTITY suncopy "Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.">
13931N/A]>
13931N/A<?Pub UDT _bookmark _target>
13931N/A<?Pub Inc>
13931N/A<refentry id="dbus-daemon-1">
13931N/A<!-- %Z%%M% %I% %E% SMI; -->
13931N/A<refmeta><refentrytitle>&cmd;</refentrytitle><manvolnum>3</manvolnum>
13931N/A<refmiscinfo class="date">19 Nov 2007</refmiscinfo>
13931N/A<refmiscinfo class="sectdesc">&man3;</refmiscinfo>
13931N/A<refmiscinfo class="software">&release;</refmiscinfo>
13931N/A<refmiscinfo class="arch">generic</refmiscinfo>
13931N/A<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
13931N/A</refmeta>
13931N/A<indexterm><primary>&cmd;</primary></indexterm><indexterm><primary>
13931N/AMessage bus daemon
13931N/A</primary></indexterm><refnamediv id="dbus-daemon-1-name">
13931N/A<refname>&cmd;</refname><refpurpose>
13931N/AMessage bus daemon
13931N/A</refpurpose></refnamediv>
13931N/A<refsynopsisdiv id="dbus-daemon-1-synp"><title>&synp-tt;</title>
13931N/A<cmdsynopsis><command>&cmd;</command>
13931N/A<arg choice="opt"><option>-config-file=<replaceable>file</replaceable></option></arg>
13931N/A<arg choice="opt"><option>-fork</option> | <option>-nofork</option></arg>
13931N/A<arg choice="opt"><option>-introspect</option></arg>
13931N/A<arg choice="opt"><option>-print-address[=<replaceable>descriptor</replaceable>]</option></arg>
13931N/A<arg choice="opt"><option>-print-pid[=<replaceable>descriptor</replaceable>]</option></arg>
13931N/A<arg choice="opt"><option>-session</option></arg>
13931N/A<arg choice="opt"><option>-system</option></arg>
13931N/A<arg choice="opt"><option>-version</option></arg>
13931N/A</cmdsynopsis></refsynopsisdiv>
13931N/A<refsect1 id="dbus-daemon-1-desc"><title>&desc-tt;</title>
13931N/A<para>
13931N/A&cmd; is the D\-Bus message bus daemon. See
13931N/A<literal>http://www.freedesktop.org/software/dbus/</literal>
13931N/Afor more information. D\-Bus is first a library that provides one\-to\-one
13931N/Acommunication between any two applications; &cmd; is an application that uses
13931N/Athis library to implement a message bus daemon. Multiple programs connect to
13931N/Athe message bus daemon and can exchange messages with one another.
13931N/A</para>
13931N/A<para>
13931N/AThere are two standard message bus instances. &cmd; is used for both of these
13931N/Ainstances, but with a different configuration file.
13931N/A</para>
13931N/A<itemizedlist>
13931N/A<listitem><para>
13931N/Asystemwide message bus - Disabled and not supported on Solaris, but installed
13931N/Aon many systems as the "messagebus" init service. Note that the
13931N/A<option>-system</option> option is equivalent to:
13931N/A</para>
13931N/A<para>
13931N/A"<option>-config\-file=/etc/dbus\-1/system.conf</option>"
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Aper-user-login-session message bus - Enabled and supported on Solaris, and
13931N/Astarted each time a user logs in. Note that the
13931N/A<option>-session</option> option is equivalent to:
13931N/A</para>
13931N/A<para>
13931N/A"<option>-config\-file=/etc/dbus\-1/session.conf</option>"
13931N/A</para></listitem>
13931N/A</itemizedlist>
13931N/A<para>
13931N/ABy creating additional configuration files and using the
13931N/A<option>-config\-file</option> option, additional special-purpose message bus
13931N/Adaemons could be created.
13931N/A</para>
13931N/A<para>
13931N/AOn Solaris, D\-Bus is configured with the systemwide message bus disabled.
13931N/AThe systemwide message bus is not used by any applications that are currently
13931N/Ashipped with Solaris.
13931N/A</para>
13931N/A<para>
13931N/AThe systemwide daemon is normally launched by an init script, standardly called
13931N/Asimply "messagebus".
13931N/A</para>
13931N/A<para>
13931N/AThe systemwide daemon is largely used for broadcasting system events, such as
13931N/Achanges to the printer queue, or adding/removing devices.
13931N/A</para>
13931N/A<para>
13931N/AThe per-session daemon is used for various interprocess communication among
13931N/Adesktop applications (however, it is not tied to X or the GUI in any way).
13931N/A</para>
13931N/A<para>
13931N/ASIGHUP will cause the D\-Bus daemon to PARTIALLY reload its configuration file
13931N/Aand to flush its user/group information caches. Some configuration changes
13931N/Awould require kicking all apps off the bus; so they will only take effect if
13931N/Ayou restart the daemon. Policy changes should take effect with SIGHUP.
13931N/A</para>
13931N/A</refsect1>
13931N/A<refsect1 id="dbus-daemon-1-opts"><title>&opts-tt;</title>
13931N/A<para>The following options are supported:</para>
13931N/A<variablelist termlength="wholescreen">
13931N/A<varlistentry>
13931N/A<term><option>-config-file=<replaceable>file</replaceable></option></term>
13931N/A<listitem><para>
13931N/AUse the given configuration <replaceable>file</replaceable>.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-fork</option></term>
13931N/A<listitem><para>
13931N/AForce the message bus to fork and become a daemon, regardless of configuration
13931N/Afile settings.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-introspect</option></term>
13931N/A<listitem><para>
13931N/APrint introspect data and exit.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-nofork</option></term>
13931N/A<listitem><para>
13931N/AAvoid running the message bus as a daemon, regardless of configuration file
13931N/Asettings.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-print-address[=<replaceable>descriptor</replaceable>]</option></term>
13931N/A<listitem><para>
13931N/APrint the address of the message bus to standard output, or to the given file
13931N/A<replaceable>descriptor</replaceable>. This is used by programs that launch
13931N/Athe message bus.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-print-pid[=<replaceable>descriptor</replaceable>]</option></term>
13931N/A<listitem><para>
13931N/APrint the process ID of the message bus to standard output, or to the given
13931N/Afile <replaceable>descriptor</replaceable>. This is used by programs that
13931N/Alaunch the message bus.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-session</option></term>
13931N/A<listitem><para>
13931N/AUse the standard configuration file for the per-login-session message bus.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-system</option></term>
13931N/A<listitem><para>
13931N/AUse the standard configuration file for the systemwide message bus.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><option>-version</option></term>
13931N/A<listitem><para>
13931N/APrint the version of the daemon.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A</variablelist></refsect1>
13931N/A<refsect1 id="dbus-daemon-1-exde"><title>&exde-tt;</title>
13931N/A<refsect2>
13931N/A<title>CONFIGURATION FILE</title>
13931N/A<para>
13931N/AA message bus daemon has a configuration file that specializes it for a
13931N/Aparticular application. For example, one configuration file might set up the
13931N/Amessage bus to be a systemwide message bus, while another might set it
13931N/Aup to be a per-user-login-session bus.
13931N/A</para>
13931N/A<para>
13931N/AThe configuration file also establishes resource limits, security parameters,
13931N/Aand so forth.
13931N/A</para>
13931N/A<para>
13931N/AThe configuration file is not part of any interoperability specification and
13931N/Aits backward compatibility is not guaranteed; this document is documentation,
13931N/Anot specification.
13931N/A</para>
13931N/A<para>
13931N/AThe standard systemwide and per-session message bus setups are configured in
13931N/Athe files "<filename>/etc/dbus-1/system.conf</filename>" and
13931N/A"<filename>/etc/dbus-1/session.conf</filename>". These files normally
13931N/A&lt;include&gt; a <filename>system-local.conf</filename> or
13931N/A<filename>session-local.conf</filename>; you can put local overrides in those
13931N/Afiles to avoid modifying the primary configuration files.
13931N/A</para>
13931N/A<para>
13931N/AThe configuration file is an XML document. It must have the following doctype
13931N/Adeclaration:
13931N/A</para>
13931N/A<screen>
13931N/A &lt;!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D\-Bus Bus Configuration 1.0//EN"
13931N/A "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
13931N/A</screen>
13931N/A<para>
13931N/AThe following elements may be present in the configuration file.
13931N/ANote that some configuration file options are only meaningful with
13931N/Athe systemwide message bus, which is disabled on Solaris. Such options
13931N/Aare only documented for reference.
13931N/A</para>
13931N/A<para>
13931N/A&lt;busconfig&gt;
13931N/A</para>
13931N/A<para>
13931N/ARoot element.
13931N/A</para>
13931N/A<para>
13931N/A&lt;type&gt;
13931N/A</para>
13931N/A<para>
13931N/AThe well-known type of the message bus. Currently known values are "system"
13931N/Aand "session"; if other values are set, they should be either added to the
13931N/AD\-Bus specification, or namespaced. The last &lt;type&gt; element "wins"
13931N/A(previous values are ignored).
13931N/A</para>
13931N/A<para>
13931N/AExample: &lt;type&gt;session&lt;/type&gt;
13931N/A</para>
13931N/A<para>
13931N/A&lt;include&gt;
13931N/A</para>
13931N/A<para>
13931N/AInclude a file &lt;include&gt;filename.conf&lt;/include&gt; at this point. If
13931N/Athe filename is relative, it is located relative to the configuration file
13931N/Adoing the including.
13931N/A</para>
13931N/A<para>
13931N/A&lt;include&gt; has an optional attribute "ignore_missing=(yes|no)" which
13931N/Adefaults to "no" if not provided. This attribute controls whether it is a
13931N/Afatal error for the included file to be absent.
13931N/A</para>
13931N/A<para>
13931N/A&lt;includedir&gt;
13931N/A</para>
13931N/A<para>
13931N/AInclude all files in &lt;includedir&gt;foo.d&lt;/includedir&gt; at this point.
13931N/AFiles in the directory are included in undefined order. Only files ending in
13931N/A".conf" are included.
13931N/A</para>
13931N/A<para>
13931N/AThis is intended to allow extension of the system bus by particular packages.
13931N/AFor example, if CUPS wants to be able to send out notification of printer queue
13931N/Achanges, it could install a file to /etc/dbus-1/system.d that allowed all apps
13931N/Ato receive this message and allowed the printer daemon user to send it.
13931N/A</para>
13931N/A<para>
13931N/A&lt;user&gt;
13931N/A</para>
13931N/A<para>
13931N/AThe user account the daemon should run as, as either a username or a UID.
13931N/AIf the daemon cannot change to this UID on startup, it will exit. If this
13931N/Aelement is not present, the daemon will not change or care about its UID.
13931N/A</para>
13931N/A<para>
13931N/AThe last &lt;user&gt; entry in the file "wins", the others are ignored.
13931N/A</para>
13931N/A<para>
13931N/AThe user is changed after the bus has completed initialization. So sockets
13931N/Aetc. will be created before changing user, but no data will be read from
13931N/Aclients before changing user. This means that sockets and PID files can be
13931N/Acreated in a location that requires root privileges for writing.
13931N/A</para>
13931N/A<para>
13931N/A&lt;fork&gt;
13931N/A</para>
13931N/A<para>
13931N/AIf present, the bus daemon becomes a real daemon (forks into the background,
13931N/Aetc.). This is generally used rather than the <option>-fork</option> command
13931N/Aline option.
13931N/A</para>
13931N/A<para>
13931N/A&lt;listen&gt;
13931N/A</para>
13931N/A<para>
13931N/AAdd an address that the bus should listen on. The address is in the standard
13931N/AD\-Bus format that contains a transport name plus possible parameters/options.
13931N/A</para>
13931N/A<screen>
13931N/A Example: &lt;listen&gt;unix:path=/tmp/foo&lt;/listen&gt;
13931N/A Example: &lt;listen&gt;tcp:host=localhost,port=1234&lt;/listen&gt;
13931N/A</screen>
13931N/A<para>
13931N/AIf there are multiple &lt;listen&gt; elements, then the bus listens on multiple
13931N/Aaddresses. The bus will pass its address to started services or other
13931N/Ainterested parties with the last address given in &lt;listen&gt; first. That
13931N/Ais, apps will try to connect to the last &lt;listen&gt; address first.
13931N/A</para>
13931N/A<para>
13931N/Atcp sockets can accept IPv4 addresses, IPv6 addresses or hostnames. If a
13931N/Ahostname resolves to multiple addresses, the server will bind to all of them.
13931N/AThe family=ipv4 or family=ipv6 options can be used to force it to bind to a
13931N/Asubset of addresses.
13931N/A</para>
13931N/A<screen>
13931N/A Example:
13931N/A &lt;listen&gt;tcp:host=localhost,port=0,family=ipv4&lt;/listen&gt;
13931N/A</screen>
13931N/A<para>
13931N/AA special case is using a port number of zero (or omitting the port), which
13931N/Ameans to choose an available port selected by the operating system. The port
13931N/Anumber chosen can be obtained with the <option>-print-address</option> command
13931N/Aline parameter and will be present in other cases where the server reports its
13931N/Aown address, such as when DBUS_SESSION_BUS_ADDRESS is set.
13931N/A</para>
13931N/A<screen>
13931N/A Example: &lt;listen&gt;tcp:host=localhost,port=0&lt;/listen&gt;
13931N/A</screen>
13931N/A<para>
13931N/Atcp addresses also allow a bind=hostname option, which will override the host
13931N/Aoption specifying what address to bind to, without changing the address
13931N/Areported by the bus. The bind option can also take a special name '*' to
13931N/Acause the bus to listen on all local address (INADDR_ANY). The specified host
13931N/Ashould be a valid name of the local machine or weird stuff will happen.
13931N/A</para>
13931N/A<screen>
13931N/A Example: &lt;listen&gt;tcp:host=localhost,bind=*,port=0&lt;/listen&gt;
13931N/A</screen>
13931N/A<para>
13931N/A&lt;auth&gt;
13931N/A</para>
13931N/A<para>
13931N/ALists permitted authorization mechanisms. If this element does not exist, then
13931N/Aall known mechanisms are allowed. If there are multiple &lt;auth&gt; elements,
13931N/Aall the listed mechanisms are allowed. The order in which mechanisms are
13931N/Alisted is not meaningful.
13931N/A</para>
13931N/A<screen>
13931N/A Example: &lt;auth&gt;EXTERNAL&lt;/auth&gt;
13931N/A Example: &lt;auth&gt;DBUS_COOKIE_SHA1&lt;/auth&gt;
13931N/A</screen>
13931N/A<para>
13931N/A&lt;servicedir&gt;
13931N/A</para>
13931N/A<para>
13931N/AAdds a directory to scan for <filename>.service</filename> files. Directories
13931N/Aare scanned starting with the last to appear in the config file (the first
13931N/A<filename>.service</filename> file found that provides a particular service
13931N/Awill be used).
13931N/A</para>
13931N/A<para>
13931N/AService files tell the bus how to automatically start a program. They are
13931N/Aprimarily used with the per-user-session bus, not the systemwide bus.
13931N/A</para>
13931N/A<para>
13931N/A&lt;standard session servicedirs/&gt;
13931N/A</para>
13931N/A<para>
13931N/A&lt;standard_session_servicedirs/&gt; is equivalent to specifying a series of
13931N/A&lt;servicedir/&gt; elements for each of the data directories in the "XDG Base
13931N/ADirectory Specification" with the subdirectory "dbus-1/services", so for
13931N/Aexample "/usr/share/dbus-1/services" would be among the directories searched.
13931N/A</para>
13931N/A<para>
13931N/AThe "XDG Base Directory Specification" should be found at
13931N/A<literal>http://freedesktop.org/wiki/Standards/basedir-spec</literal>.
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;standard_session_servicedirs/&gt; option is only relevant to the
13931N/Aper-user-session bus daemon defined in
13931N/A<filename>/etc/dbus\-1/session.conf</filename>. Putting it in any other
13931N/Aconfiguration file would probably be nonsense.
13931N/A</para>
13931N/A<para>
13931N/A&lt;standard system servicedirs/&gt;
13931N/A</para>
13931N/A<para>
13931N/A&lt;standard_system_servicedirs/&gt; specifies the standard systemwide
13931N/Aactivation directories that should be searched for service files. This option
13931N/Adefaults to <filename>/usr/share/dbus-1/system-services</filename>.
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;standard_system_servicedirs/&gt; option is only relevant
13931N/Ato the per-system bus daemon defined in
13931N/A<filename>/etc/dbus\-1/system.conf</filename>. Putting it in any other
13931N/Aconfiguration file would probably be nonsense.
13931N/A</para>
13931N/A<para>
13931N/A&lt;servicehelper/&gt;
13931N/A</para>
13931N/A<para>
13931N/A&lt;servicehelper/&gt; specifies the setuid helper that is used to launch
13931N/Asystem daemons with an alternate user. Typically this would be the
13931N/A<command>dbus-daemon-launch-helper</command> executable. Because the
13931N/Asystemwide message bus is disabled on Solaris, the
13931N/A<command>dbus-daemon-launch-helper</command> executable is not distributed
13931N/Awith Solaris.
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;servicehelper/&gt; option is only relevant to the per-system bus
13931N/Adaemon defined in <filename>/etc/dbus-1/system.conf</filename>. Putting it in
13931N/Aany other configuration file would probably be nonsense.
13931N/A</para>
13931N/A<para>
13931N/A&lt;limit&gt;
13931N/A</para>
13931N/A<para>
13931N/A&lt;limit&gt; establishes a resource limit. For example:
13931N/A</para>
13931N/A<screen>
13931N/A &lt;limit name="max_message_size"&gt;64&lt;/limit&gt;
13931N/A &lt;limit name="max_completed_connections"&gt;512&lt;/limit&gt;
13931N/A</screen>
13931N/A<para>
13931N/AThe name attribute is mandatory. Available limit names are:
13931N/A</para>
13931N/A
13931N/A<screen>
13931N/A "max_incoming_bytes" : total size in bytes
13931N/A of messages incoming
13931N/A from a single
13931N/A connection
13931N/A "max_outgoing_bytes" : total size in bytes
13931N/A of messages queued up
13931N/A for a single
13931N/A connection
13931N/A "max_message_size" : max size of a single
13931N/A message in bytes
13931N/A "service_start_timeout" : milliseconds
13931N/A (thousandths) until
13931N/A a started service has
13931N/A to connect
13931N/A "auth_timeout" : milliseconds
13931N/A (thousandths) a
13931N/A connection is given
13931N/A to authenticate
13931N/A "max_completed_connections" : max number of
13931N/A authenticated
13931N/A connections
13931N/A "max_incomplete_connections" : max number of
13931N/A unauthenticated
13931N/A connections
13931N/A "max_connections_per_user" : max number of
13931N/A completed connections
13931N/A from the same user
13931N/A "max_pending_service_starts" : max number of service
13931N/A launches in progress
13931N/A at the same time
13931N/A "max_names_per_connection" : max number of names a
13931N/A single connection can
13931N/A own
13931N/A "max_match_rules_per_connection" : max number of match
13931N/A rules for a single
13931N/A connection
13931N/A "max_replies_per_connection" : max number of pending
13931N/A method replies per
13931N/A connection (number of
13931N/A calls-in-progress)
13931N/A "reply_timeout" : milliseconds
13931N/A (thousandths) until a
13931N/A method call times out
13931N/A</screen>
13931N/A<para>
13931N/AThe max incoming/outgoing queue sizes allow a new message to be queued if one
13931N/Abyte remains below the max. So you can in fact exceed the max by
13931N/Amax_message_size.
13931N/A</para>
13931N/A<para>
13931N/Amax_completed_connections divided by max_connections_per_user is the number of
13931N/Ausers that can work together to denial-of-service all other users by using up
13931N/Aall connections on the systemwide bus.
13931N/A</para>
13931N/A<para>
13931N/ALimits are normally only of interest on the systemwide bus, not the user
13931N/Asession buses.
13931N/A</para>
13931N/A<para>
13931N/A&lt;policy&gt;
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;policy&gt; element defines a security policy to be applied to a
13931N/Aparticular set of connections to the bus. A policy is made up of &lt;allow&gt;
13931N/Aand &lt;deny&gt; elements. Policies are normally used with the systemwide bus;
13931N/Athey are analogous to a firewall in that they allow expected traffic and
13931N/Aprevent unexpected traffic.
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;policy&gt; element has one of three attributes:
13931N/A</para>
13931N/A<itemizedlist>
13931N/A<listitem><para>
13931N/Acontext="(default|mandatory)"
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Auser="username or userid"
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Agroup="group name or gid"
13931N/A</para></listitem>
13931N/A</itemizedlist>
13931N/A<para>
13931N/APolicies are applied to a connection as follows:
13931N/A</para>
13931N/A<itemizedlist>
13931N/A<listitem><para>
13931N/Aall context="default" policies are applied
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Aall group="connection's user's group" policies are applied
13931N/Ain undefined order
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Aall user="connection's auth user" policies are applied
13931N/Ain undefined order
13931N/A</para></listitem>
13931N/A<listitem><para>
13931N/Aall context="mandatory" policies are applied
13931N/A</para></listitem>
13931N/A</itemizedlist>
13931N/A<para>
13931N/APolicies applied later will override those applied earlier, when the policies
13931N/Aoverlap. Multiple policies with the same user/group/context are applied in the
13931N/Aorder they appear in the config file.
13931N/A</para>
13931N/A<para>
13931N/A&lt;deny&gt; and &lt;allow&gt;
13931N/A</para>
13931N/A<para>
13931N/AA &lt;deny&gt; element appears below a &lt;policy&gt; element and prohibits
13931N/Asome action. The &lt;allow&gt; element makes an exception to previous
13931N/A&lt;deny&gt; statements, and works just like &lt;deny&gt; but with the inverse
13931N/Ameaning.
13931N/A</para>
13931N/A<para>
13931N/AThe possible attributes of these elements are:
13931N/A</para>
13931N/A<screen>
13931N/A send_interface="interface_name"
13931N/A send_member="method_or_signal_name"
13931N/A send_error="error_name"
13931N/A send_destination="name"
13931N/A send_type="method_call" | "method_return" | "signal" | "error"
13931N/A send_path="/path/name"
13931N/A</screen>
13931N/A<screen>
13931N/A receive_interface="interface_name"
13931N/A receive_member="method_or_signal_name"
13931N/A receive_error="error_name"
13931N/A receive_sender="name"
13931N/A receive_type="method_call" | "method_return" | "signal" | "error"
13931N/A receive_path="/path/name"
13931N/A</screen>
13931N/A<screen>
13931N/A send_requested_reply="true" | "false"
13931N/A receive_requested_reply="true" | "false"
13931N/A</screen>
13931N/A<screen>
13931N/A eavesdrop="true" | "false"
13931N/A</screen>
13931N/A<screen>
13931N/A own="name"
13931N/A user="username"
13931N/A group="groupname"
13931N/A</screen>
13931N/A<para>
13931N/AExamples:
13931N/A</para>
13931N/A<screen>
13931N/A &lt;deny send_interface="org.freedesktop.System" send_member="Reboot"/&gt;
13931N/A &lt;deny receive_interface="org.freedesktop.System" receive_member="Reboot"/&gt;
13931N/A &lt;deny own="org.freedesktop.System"/&gt;
13931N/A &lt;deny send_destination="org.freedesktop.System"/&gt;
13931N/A &lt;deny receive_sender="org.freedesktop.System"/&gt;
13931N/A &lt;deny user="john"/&gt;
13931N/A &lt;deny group="enemies"/&gt;
13931N/A</screen>
13931N/A<para>
13931N/AThe &lt;deny&gt; element's attributes determine whether the deny "matches" a
13931N/Aparticular action. If it matches, the action is denied (unless later rules in
13931N/Athe config file allow it).
13931N/A</para>
13931N/A<para>
13931N/Asend_destination and receive_sender rules mean that messages may not be sent to
13931N/Aor received from the *owner* of the given name, not that they may not be sent
13931N/A*to that name*. That is, if a connection owns services A, B, C, and sending to
13931N/AA is denied, sending to B or C will not work either.
13931N/A</para>
13931N/A<para>
13931N/AThe other send_* and receive_* attributes are purely textual/by-value matches
13931N/Aagainst the given field in the message header.
13931N/A</para>
13931N/A<para>
13931N/A"Eavesdropping" occurs when an application receives a message that was
13931N/Aexplicitly addressed to a name the application does not own, or is a reply to
13931N/Asuch a message. Eavesdropping thus only applies to messages that are addressed
13931N/Ato services and replies to such messages (i.e. it does not apply to signals).
13931N/A</para>
13931N/A<para>
13931N/AFor &lt;allow&gt;, eavesdrop="true" indicates that the rule matches even when
13931N/Aeavesdropping. eavesdrop="false" is the default and means that the rule only
13931N/Aallows messages to go to their specified recipient. For &lt;deny&gt;,
13931N/Aeavesdrop="true" indicates that the rule matches only when eavesdropping.
13931N/Aeavesdrop="false" is the default for &lt;deny&gt; also, but here it means that
13931N/Athe rule applies always, even when not eavesdropping. The eavesdrop attribute
13931N/Acan only be combined with send and receive rules (with send_* and receive_*
13931N/Aattributes).
13931N/A</para>
13931N/A<para>
13931N/AThe [send|receive]_requested_reply attribute works similarly to the eavesdrop
13931N/Aattribute. It controls whether the &lt;deny&gt; or &lt;allow&gt; matches a
13931N/Areply that is expected (corresponds to a previous method call message). This
13931N/Aattribute only makes sense for reply messages (errors and method returns), and
13931N/Ais ignored for other message types.
13931N/A</para>
13931N/A<para>
13931N/AFor &lt;allow&gt;, [send|receive]_requested_reply="true" is the default and
13931N/Aindicates that only requested replies are allowed by the rule.
13931N/A[send|receive]_requested_reply="false" means that the rule allows any reply
13931N/Aeven if unexpected.
13931N/A</para>
13931N/A<para>
13931N/AFor &lt;deny&gt;, [send|receive]_requested_reply="false" is the default but
13931N/Aindicates that the rule matches only when the reply was not requested.
13931N/A[send|receive]_requested_reply="true" indicates that the rule applies always,
13931N/Aregardless of pending reply state.
13931N/A</para>
13931N/A<para>
13931N/Auser and group denials mean that the given user or group may not connect to the
13931N/Amessage bus.
13931N/A</para>
13931N/A<para>
13931N/AFor "name", "username", "groupname", etc. the character "*" can be substituted,
13931N/Ameaning "any." Complex globs like "foo.bar.*" aren't allowed for now because
13931N/Athey would be work to implement and maybe encourage sloppy security anyway.
13931N/A</para>
13931N/A<para>
13931N/AIt does not make sense to deny a user or group inside a &lt;policy&gt; for
13931N/Aa user or group; user/group denials can only be inside context="default" or
13931N/Acontext="mandatory" policies.
13931N/A</para>
13931N/A<para>
13931N/AA single &lt;deny&gt; rule may specify combinations of attributes such as
13931N/Asend_destination and send_interface and send_type. In this case, the denial
13931N/Aapplies only if both attributes match the message being denied. e.g. &lt;deny
13931N/Asend_interface="foo.bar" send_destination="foo.blah"/&gt; would deny messages
13931N/Awith the given interface AND the given bus name. To get an OR effect you
13931N/Aspecify multiple &lt;deny&gt; rules.
13931N/A</para>
13931N/A<para>
13931N/AYou can't include both send_ and receive_ attributes on the same rule, since
13931N/A"whether the message can be sent" and "whether it can be received" are
13931N/Aevaluated separately.
13931N/A</para>
13931N/A<para>
13931N/ABe careful with send_interface/receive_interface, because the interface field
13931N/Ain messages is optional.
13931N/A</para>
13931N/A<para>
13931N/A&lt;selinux&gt;
13931N/A</para>
13931N/A<para>
13931N/AThe &lt;selinux&gt; element contains settings related to Security Enhanced
13931N/ALinux. More details below. Note, SELinux is not supported on Solaris.
13931N/A</para>
13931N/A<para>
13931N/A&lt;associate&gt;
13931N/A</para>
13931N/A<para>
13931N/AAn &lt;associate&gt; element appears below an &lt;selinux&gt; element and
13931N/Acreates a mapping. Right now only one kind of association is possible:
13931N/A</para>
13931N/A<screen>
13931N/A &lt;associate own="org.freedesktop.Foobar" context="foo_t"/&gt;
13931N/A</screen>
13931N/A<para>
13931N/AThis means that if a connection asks to own the name "org.freedesktop.Foobar"
13931N/Athen the source context will be the context of the connection and the target
13931N/Acontext will be "foo_t" - see the short discussion of SELinux below.
13931N/A</para>
13931N/A<para>
13931N/ANote, the context here is the target context when requesting a name, NOT the
13931N/Acontext of the connection owning the name.
13931N/A</para>
13931N/A<para>
13931N/AThere is currently no way to set a default for owning any name, if we add this
13931N/Asyntax it will look like:
13931N/A</para>
13931N/A<screen>
13931N/A &lt;associate own="*" context="foo_t"/&gt;
13931N/A</screen>
13931N/A<para>
13931N/AIf you find a reason this is useful, let the developers know. Right now the
13931N/Adefault will be the security context of the bus itself.
13931N/A</para>
13931N/A<para>
13931N/AIf two &lt;associate&gt; elements specify the same name, the element appearing
13931N/Alater in the configuration file will be used.
13931N/A</para>
13931N/A</refsect2>
13931N/A<refsect2>
13931N/A<title>SELinux</title>
13931N/A<para>
13931N/ASELinux is not supported on Solaris. It is used with the systemwide bus
13931N/Awhich is disabled on Solaris.
13931N/A</para>
13931N/A<para>
13931N/ASee <literal>http://www.nsa.gov/selinux/</literal> for full details on SELinux.
13931N/ASome useful excerpts:
13931N/A</para>
13931N/A<variablelist termlength="xtranarrow">
13931N/A<varlistentry>
13931N/A<term></term>
13931N/A<listitem>
13931N/A<para>
13931N/AEvery subject (process) and object (e.g. file, socket, IPC object, etc) in the
13931N/Asystem is assigned a collection of security attributes, known as a security
13931N/Acontext. A security context contains all of the security attributes associated
13931N/Awith a particular subject or object that are relevant to the security policy.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term></term>
13931N/A<listitem>
13931N/A<para>
13931N/AIn order to better encapsulate security contexts and to provide greater
13931N/Aefficiency, the policy enforcement code of SELinux typically handles security
13931N/Aidentifiers (SIDs) rather than security contexts. A SID is an integer that is
13931N/Amapped by the security server to a security context at runtime.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term></term>
13931N/A<listitem>
13931N/A<para>
13931N/AWhen a security decision is required, the policy enforcement code passes a pair
13931N/Aof SIDs (typically the SID of a subject and the SID of an object, but sometimes
13931N/Aa pair of subject SIDs or a pair of object SIDs), and an object security class
13931N/Ato the security server. The object security class indicates the kind of object,
13931N/Ae.g. a process, a regular file, a directory, a TCP socket, etc.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term></term>
13931N/A<listitem>
13931N/A<para>
13931N/AAccess decisions specify whether or not a permission is granted for a given
13931N/Apair of SIDs and class. Each object class has a set of associated permissions
13931N/Adefined to control operations on objects with that class.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A</variablelist>
13931N/A<para>
13931N/AD\-Bus performs SELinux security checks in two places.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<para>
13931N/AFirst, any time a message is routed from one connection to another connection,
13931N/Athe bus daemon will check permissions with the security context of the first
13931N/Aconnection as source, security context of the second connection as target,
13931N/Aobject class "dbus" and requested permission "send_msg".
13931N/A</para>
13931N/A<para>
13931N/AIf a security context is not available for a connection (impossible when using
13931N/AUNIX domain sockets), then the target context used is the context of the bus
13931N/Adaemon itself. There is currently no way to change this default, because we
13931N/Aare assuming that only UNIX domain sockets will be used to connect to the
13931N/Asystemwide bus. If this changes, we'll probably add a way to set the default
13931N/Aconnection context.
13931N/A</para>
13931N/A<para>
13931N/ASecond, any time a connection asks to own a name, the bus daemon will check
13931N/Apermissions with the security context of the connection as source, the security
13931N/Acontext specified for the name in the config file as target, object class
13931N/A"dbus" and requested permission "acquire_svc".
13931N/A</para>
13931N/A<para>
13931N/AThe security context for a bus name is specified with the &lt;associate&gt;
13931N/Aelement described earlier in this document. If a name has no security context
13931N/Aassociated in the configuration file, the security context of the bus daemon
13931N/Aitself will be used.
13931N/A</para>
13931N/A</refsect2>
13931N/A<refsect2>
13931N/A<title>DEBUGGING</title>
13931N/A<para>
13931N/AIf you are trying to figure out where your messages are going or why you are
13931N/Anot getting messages, there are several things you can try.
13931N/A</para>
13931N/A<para>
13931N/ARemember that the system bus is heavily locked down and if you have not
13931N/Ainstalled a security policy file to allow your message through, it won't work.
13931N/AFor the session bus, this is not a concern.
13931N/A</para>
13931N/A<para>
13931N/AThe simplest way to figure out what's happening on the bus is to run the
13931N/A<command>dbus-monitor</command> program, which comes with the D\-Bus package.
13931N/AYou can also send test messages with <command>dbus-send</command>. These
13931N/Aprograms have their own man pages.
13931N/A</para>
13931N/A<para>
13931N/AIf you want to know what the daemon itself is doing, you might consider running
13931N/Aa separate copy of the daemon to test against. This will allow you to put the
13931N/Adaemon under a debugger, or run it with verbose output, without messing up your
13931N/Areal session and system daemons.
13931N/A</para>
13931N/A<para>
13931N/ATo run a separate test copy of the daemon, for example you might open a
13931N/Aterminal and type:
13931N/A</para>
13931N/A<screen>
13931N/A DBUS_VERBOSE=1 &cmd; --session --print-address
13931N/A</screen>
13931N/A<para>
13931N/AThe test daemon address will be printed when the daemon starts. You will need
13931N/Ato copy-and-paste this address and use it as the value of the
13931N/ADBUS_SESSION_BUS_ADDRESS environment variable when you launch the applications
13931N/Ayou want to test. This will cause those applications to connect to your test
13931N/Abus instead of the DBUS_SESSION_BUS_ADDRESS of your real session bus.
13931N/A</para>
13931N/A<para>
13931N/ADBUS_VERBOSE=1 will have NO EFFECT unless your copy of D\-Bus was compiled with
13931N/Averbose mode enabled. This is not recommended in production builds due to
13931N/Aperformance impact. You may need to rebuild D\-Bus if your copy was not built
13931N/Awith debugging in mind. (DBUS_VERBOSE also affects the D\-Bus library and thus
13931N/Aapplications using D\-Bus; it may be useful to see verbose output on both the
13931N/Aclient side and from the daemon.)
13931N/A</para>
13931N/A<para>
13931N/AIf you want to get fancy, you can create a custom bus configuration for your
13931N/Atest bus (see the <filename>session.conf</filename> and
13931N/A<filename>system.conf</filename> files that define the two default
13931N/Aconfigurations for example). This would allow you to specify a different
13931N/Adirectory for <filename>.service</filename> files, for example.
13931N/A</para>
13931N/A</refsect2>
13931N/A</refsect1>
13931N/A<refsect1 id="dbus-daemon-1-exam"><title>&exam-tt;</title>
13931N/A<example role="example">
13931N/A<title>
13931N/AMessage bus daemon
13931N/A</title>
13931N/A<para><screen>example% <userinput>&cmd; </userinput></screen></para>
13931N/A</example>
13931N/A</refsect1>
13931N/A<refsect1 id="dbus-daemon-1-envr"><title>&envr-tt;</title>
13931N/A<para>
13931N/ASee
13931N/A<citerefentry><refentrytitle>environ</refentrytitle><manvolnum>5</manvolnum></ci
13931N/Aterefentry>
13931N/Afor descriptions of the following environment variables:
13931N/A</para>
13931N/A<variablelist termlength="wholeline">
13931N/A<varlistentry>
13931N/A<term>DBUS_SESSION_BUS_ADDRESS</term>
13931N/A<listitem><para>
13931N/AThe address of the login session message bus. If this variable is not set,
13931N/Aapplications may also try to read the address from the X Window System root
13931N/Awindow property _DBUS_SESSION_BUS_ADDRESS. The root window property
13931N/Amust have type STRING. The environment variable should have precedence over the
13931N/A root window property.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term>DBUS_VERBOSE</term>
13931N/A<listitem><para>
13931N/ASet DBUS_VERSION=1 to enable debugging, if D\-Bus was compiled with verbose
13931N/Adebug mode enabled.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A</variablelist></refsect1>
13931N/A<refsect1 id="dbus-daemon-1-exit"><title>&exit-tt;</title>
13931N/A<para>The following exit values are returned:</para>
13931N/A<variablelist termlength="xtranarrow">
13931N/A<varlistentry>
13931N/A<term><returnvalue>0</returnvalue></term>
13931N/A<listitem><para>
13931N/AApplication exited successfully
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><returnvalue>>0</returnvalue></term>
13931N/A<listitem><para>
13931N/AApplication exited with failure
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A</variablelist></refsect1>
13931N/A<refsect1 id="dbus-daemon-1-file"><title>&file-tt;</title>
13931N/A<para>The following files are used by this application:</para>
13931N/A<variablelist termlength="wholeline">
13931N/A<varlistentry>
13931N/A<term><filename>/usr/lib/&cmd;</filename></term>
13931N/A<listitem><para>
13931N/AExecutable for &cmd;
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><filename>/usr/share/dbus-1/services</filename></term>
13931N/A<listitem><para>
13931N/ADirectory containing standard D\-Bus session services.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><filename>/usr/share/dbus-1/system-services</filename></term>
13931N/A<listitem><para>
13931N/ADirectory containing standard D\-Bus systemwide services.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><filename>/etc/dbus-1/session.conf</filename></term>
13931N/A<listitem><para>
13931N/AConfiguration file for D\-Bus session services.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A<varlistentry>
13931N/A<term><filename>/etc/dbus-1/system.conf</filename></term>
13931N/A<listitem><para>
13931N/AConfiguration file for D\-Bus system services.
13931N/A</para>
13931N/A</listitem></varlistentry>
13931N/A</variablelist></refsect1>
13931N/A<refsect1 id="dbus-daemon-1-attr"><title>&attr-tt;</title>
13931N/A<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
13931N/A<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
13931N/Afor descriptions of the following attributes:</para>
13931N/A<informaltable frame="all">
13931N/A<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
13931N/A<colspec colname="COLSPEC1" colwidth="1*">
13931N/A<thead>
13931N/A<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
13931N/Avalign="middle">ATTRIBUTE VALUE</entry></row>
13931N/A</thead>
13931N/A<tbody>
13931N/A<row><entry>
13931N/A<para>Availability</para>
13931N/A</entry><entry>
13931N/A<para>SUNWdbus</para>
13931N/A</entry></row><row><entry colname="COLSPEC0">
13931N/A<para>Interface stability</para>
13931N/A</entry><entry colname="COLSPEC1">
13931N/A<para>Volatile</para>
13931N/A</entry></row>
13931N/A</tbody>
13931N/A</tgroup>
13931N/A</informaltable>
13931N/A</refsect1>
13931N/A<refsect1 id="dbus-daemon-1-also"><title>&also-tt;</title>
13931N/A<!--Reference to another man page-->
13931N/A<!--Reference to a Help manual-->
13931N/A<!--Reference to a book.-->
13931N/A<para>
13931N/A<citerefentry><refentrytitle>dbus-cleanup-sockets</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>dbus-launch</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>dbus-monitor</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>libdbus-glib-1</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
13931N/A<citerefentry><refentrytitle>environ</refentrytitle><manvolnum>5</manvolnum></citerefentry>
13931N/A</para>
13931N/A</refsect1>
13931N/A<refsect1 id="dbus-daemon-1-note"><title>&note-tt;</title>
13931N/A<para>
13931N/AFor authorship information refer to
13931N/A<literal>http://www.freedesktop.org/software/dbus/doc/AUTHORS</literal>.
13931N/AUpdated by Brian Cameron, Sun Microsystems Inc., 2007.
13931N/A</para>
13931N/A<para>
13931N/APlease send bug reports to the D\-Bus mailing list or bug
13931N/Atracker, see
13931N/A<literal>http://www.freedesktop.org/software/dbus/</literal>
13931N/A</para>
13931N/A</refsect1>
13931N/A</refentry>