Fix inotify shutdown

[platform/upstream/dbus.git] / bus / dbus-daemon.1.in

diff --git a/bus/dbus-daemon.1.in b/bus/dbus-daemon.1.in
index 63d9718..8342600 100644 (file)
--- a/bus/dbus-daemon.1.in
+++ b/bus/dbus-daemon.1.in
@@ -1,6 +1,6 @@
 .\" 
 .\" dbus-daemon manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
+.\" Copyright (C) 2003,2008 Red Hat, Inc.
 .\"
 .TH dbus-daemon 1
 .SH NAME
@@ -138,7 +138,21 @@ Root element.
 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>
@@ -200,6 +214,13 @@ into the background, etc.). This is generally used
 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
@@ -232,9 +253,10 @@ 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 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.
+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>
@@ -395,15 +417,28 @@ they are analogous to a firewall in that they allow expected traffic
 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
@@ -411,6 +446,8 @@ Policies are applied to a connection as follows:
      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
 
@@ -551,7 +588,11 @@ received" are evaluated separately.
 
 .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>"