.\"
.\" dbus-daemon manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
+.\" Copyright (C) 2003,2008 Red Hat, Inc.
.\"
.TH dbus-daemon 1
.SH NAME
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).
+<type> element "wins" (previous values are ignored). This element
+only controls which message bus specific environment variables are
+set in activated clients. Most of the policy that distinguishes a
+session bus from the system bus is controlled from the other elements
+in the configuration file.
+
+.PP
+If the well-known type of the message bus is "session", then the
+DBUS_STARTER_BUS_TYPE environment variable will be set to "session"
+and the DBUS_SESSION_BUS_ADDRESS environment variable will be set
+to the address of the session bus. Likewise, if the type of the
+message bus is "system", then the DBUS_STARTER_BUS_TYPE environment
+variable will be set to "system" and the DBUS_SESSION_BUS_ADDRESS
+environment variable will be set to the address of the system bus
+(which is normally well known anyway).
.PP
Example: <type>session</type>
rather than the \-\-fork command line option.
.TP
+.I "<keep_umask>"
+
+.PP
+If present, the bus daemon keeps its original umask when forking.
+This may be useful to avoid affecting the behavior of child processes.
+
+.TP
.I "<listen>"
.PP
Example: <listen>unix:path=/tmp/foo</listen>
.PP
+Example: <listen>tcp:host=localhost,port=1234</listen>
+
+.PP
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.
+.PP
+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
+
+.PP
+Example: <listen>tcp:host=localhost,port=0,family=ipv4</listen>
+
+.PP
+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
+--print-address 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.
+
+.PP
+Example: <listen>tcp:host=localhost,port=0</listen>
+
+.PP
+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.
+
+.PP
+Example: <listen>tcp:host=localhost,bind=*,port=0</listen>
+
.TP
.I "<auth>"
configuration file would probably be nonsense.
.TP
+.I "<standard_system_servicedirs/>"
+
+.PP
+<standard_system_servicedirs/> specifies the standard system-wide
+activation directories that should be searched for service files.
+This option defaults to @EXPANDED_DATADIR@/dbus-1/system-services.
+
+.PP
+The <standard_system_servicedirs/> option is only relevant to the
+per-system bus daemon defined in
+@EXPANDED_SYSCONFDIR@/dbus-1/system.conf. Putting it in any other
+configuration file would probably be nonsense.
+
+.TP
+.I "<servicehelper/>"
+
+.PP
+<servicehelper/> specifies the setuid helper that is used to launch
+system daemons with an alternate user. Typically this should be
+the dbus-daemon-launch-helper executable in located in libexec.
+
+.PP
+The <servicehelper/> option is only relevant to the per-system bus daemon
+defined in @EXPANDED_SYSCONFDIR@/dbus-1/system.conf. Putting it in any other
+configuration file would probably be nonsense.
+
+.TP
.I "<limit>"
.PP
and prevent unexpected traffic.
.PP
-The <policy> element has one of three attributes:
+Currently, the system bus has a default-deny policy for sending method calls
+and owning bus names. Everything else, in particular reply messages, receive
+checks, and signals has a default allow policy.
+
+.PP
+In general, it is best to keep system services as small, targeted programs which
+run in their own process and provide a single bus name. Then, all that is needed
+is an <allow> rule for the "own" permission to let the process claim the bus
+name, and a "send_destination" rule to allow traffic from some or all uids to
+your service.
+
+.PP
+The <policy> element has one of four attributes:
+daemon.1.in
.nf
context="(default|mandatory)"
+ at_console="(true|false)"
user="username or userid"
group="group name or gid"
.fi
.PP
-
Policies are applied to a connection as follows:
.nf
- all context="default" policies are applied
in undefined order
- all user="connection's auth user" policies are applied
in undefined order
+ - all at_console="true" policies are applied
+ - all at_console="false" policies are applied
- all context="mandatory" policies are applied
.fi
.PP
"Eavesdropping" occurs when an application receives a message that
-was explicitly addressed to a name the application does not own.
-Eavesdropping thus only applies to messages that are addressed to
-services (i.e. it does not apply to signals).
+was explicitly addressed to a name the application does not own, or
+is a reply to such a message. Eavesdropping thus only applies to
+messages that are addressed to services and replies to such messages
+(i.e. it does not apply to signals).
.PP
For <allow>, eavesdrop="true" indicates that the rule matches even
only when eavesdropping. eavesdrop="false" is the default for <deny>
also, but here it means that the rule applies always, even when
not eavesdropping. The eavesdrop attribute can only be combined with
-receive rules (with receive_* attributes).
+send and receive rules (with send_* and receive_* attributes).
.PP
.PP
Be careful with send_interface/receive_interface, because the
-interface field in messages is optional.
+interface field in messages is optional. In particular, do NOT
+specify <deny send_interface="org.foo.Bar"/>! This will cause
+no-interface messages to be blocked for all services, which is
+almost certainly not what you intended. Always use rules of
+the form: <deny send_interface="org.foo.Bar" send_destination="org.foo.Service"/>
.TP
.I "<selinux>"
projects / platform / upstream / dbus.git / blobdiff