2003-05-03 Havoc Pennington <hp@pobox.com>

	* bus/Makefile.am, bus/dbus-daemon-1.1.in: man page for the
	daemon; also documents daemon config file, so replaces
	doc/config-file.txt. Corrected some stuff from config-file.txt in
	the process of moving it.

7 files changed, 401 insertions, 240 deletions

diff --git a/ChangeLog b/ChangeLog
index 4d526ceb..d784240b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2003-05-03  Havoc Pennington  <hp@pobox.com>
 
+	* bus/Makefile.am, bus/dbus-daemon-1.1.in: man page for the
+	daemon; also documents daemon config file, so replaces
+	doc/config-file.txt. Corrected some stuff from config-file.txt in
+	the process of moving it.
+
+2003-05-03  Havoc Pennington  <hp@pobox.com>
+
 	* tools/Makefile.am, tools/dbus-send.1, tools/dbus-monitor.1: 
 	add some man pages
 
diff --git a/bus/Makefile.am b/bus/Makefile.am
index 9836ffd3..ba6524c7 100644
--- a/bus/Makefile.am
+++ b/bus/Makefile.am
@@ -100,9 +100,12 @@ initd_SCRIPTS= 	\
 endif
  ## Red Hat end
 
+MAN_IN_FILES=dbus-daemon-1.1.in
+man_MANS = dbus-daemon-1.1
+
 #### Extra dist 
 
-EXTRA_DIST=$(CONFIG_IN_FILES) $(SCRIPT_IN_FILES)
+EXTRA_DIST=$(CONFIG_IN_FILES) $(SCRIPT_IN_FILES) $(man_MANS) $(MAN_IN_FILES)
 
 if DBUS_BUILD_TESTS
 ### nothing
diff --git a/bus/dbus-daemon-1.1.in b/bus/dbus-daemon-1.1.in
new file mode 100644
index 00000000..b57d1d35
--- /dev/null
+++ b/bus/dbus-daemon-1.1.in
@@ -0,0 +1,384 @@
+.\" 
+.\" dbus-daemon-1 manual page.
+.\" Copyright (C) 2003 Red Hat, Inc.
+.\"
+.TH dbus-daemon-1 1
+.SH NAME
+dbus-daemon-1 \- Message bus daemon
+.SH SYNOPSIS
+.PP
+.B dbus-daemon-1
+dbus-daemon-1 [\-\-version] [\-\-session] [\-\-system] [\-\-config-file=FILE]
+[\-\-print-address[=DESCRIPTOR]]
+
+.SH DESCRIPTION
+
+\fIdbus-daemon-1\fP is the D-BUS message bus daemon. See
+http://www.freedesktop.org/software/dbus/ for more information about
+the big picture. D-BUS is first a library that provides one-to-one
+communication between any two applications; \fIdbus-daemon-1\fP 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.
+
+.PP
+There are two standard message bus instances: the systemwide message bus 
+(installed on many systems as the "messagebus" service) and the 
+per-user-login-session message bus (started each time a user logs in).
+\fIdbus-daemon-1\fP is used for both of these instances, but with 
+a different configuration file.
+
+.PP
+The \-\-session option is equivalent to
+"\-\-config-file=@EXPANDED_SYSCONFDIR@/dbus-1/session.conf" and the \-\-system
+option is equivalent to
+"\-\-config-file=@EXPANDED_SYSCONFDIR@/dbus-1/system.conf". By creating 
+additional configuration files and using the \-\-config-file option,
+additional special-purpose message bus daemons could be created.
+
+.PP
+The systemwide daemon is normally launched by an init script, 
+standardly called simply "messagebus". 
+
+.PP
+The systemwide daemon is largely used for broadcasting system events, 
+such as changes to the printer queue, or adding/removing devices.
+
+.PP
+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).
+
+.SH OPTIONS
+The following options are supported:
+.TP
+.I "--config-file=FILE"
+Use the given configuration file.
+.TP
+.I "--print-address[=DESCRIPTOR]"
+Print the address of the message bus to standard output, or 
+to the given file descriptor. This is used by programs that 
+launch the message bus.
+.TP
+.I "--session"
+Use the standard configuration file for the per-login-session message
+bus.
+.TP
+.I "--system"
+Use the standard configuration file for the systemwide message bus.
+.TP
+.I "--version"
+Print the version of the daemon.
+
+.SH CONFIGURATION FILE
+
+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.
+
+.PP
+The configuration file also establishes resource limits, security
+parameters, and so forth.
+
+.PP
+The configuration file is not part of any interoperability
+specification and its backward compatibility is not guaranteed; this
+document is documentation, not specification.
+
+.PP
+The standard systemwide and per-session message bus setups are
+configured in the files "@EXPANDED_SYSCONFDIR@/dbus-1/system.conf" and
+"@EXPANDED_SYSCONFDIR@/dbus-1/session.conf".  These files normally
+<include> a system-local.conf or session-local.conf; you can put local
+overrides in those files to avoid modifying the primary configuration
+files.
+
+.PP
+The configuration file is an XML document. It must have the following
+doctype declaration:
+.nf
+
+   <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+    "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+
+.fi
+
+.PP
+The following elements may be present in the configuration file.
+
+.TP
+.I "<busconfig>"
+ 
+.PP
+Root element.
+
+.TP
+.I "<type>"
+
+.PP
+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).
+
+.PP
+Example: <type>session</type>
+
+.TP
+.I "<include>"
+ 
+.PP  
+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.
+
+.PP
+<include> has an optional attribute "ignore_missing=(yes|no)"
+which defaults to "no" if not provided. This attribute 
+controls whether it's a fatal error for the included file 
+to be absent.
+
+.TP
+.I "<includedir>"
+
+.PP
+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.
+
+.PP
+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
+@EXPANDED_SYSCONFDIR@/dbus-1/system.d that allowed all apps to receive
+this message and allowed the printer daemon user to send it.
+
+.TP
+.I "<user>"
+
+.PP
+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.
+
+.PP
+The last <user> entry in the file "wins", the others are ignored.
+
+.PP
+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.
+
+.TP
+.I "<fork>"
+    
+.PP
+If present, the bus daemon becomes a real daemon (forks 
+into the background, etc.).
+
+.TP
+.I "<listen>"
+
+.PP
+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.
+
+.PP
+Example: <listen>unix:path=/tmp/foo</listen>
+
+.PP
+If there are multiple <listen> elements, then the bus listens 
+on multiple addresses. The bus will pass its address to 
+activated 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.
+
+.TP
+.I "<auth>"
+
+.PP
+Lists permitted authorization mechanisms. If this element doesn't
+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.
+    
+.PP
+Example: <auth>EXTERNAL</auth>
+
+.PP
+Example: <auth>DBUS_COOKIE_SHA1</auth>
+
+.TP
+.I "<servicedir>"
+
+.PP
+Adds a directory to scan for .service files. Directories are
+scanned starting with the last to appear in the config file 
+(the first .service file found that provides a particular 
+service will be used).
+
+.PP
+Service files tell the bus how to automatically start a particular
+service. They are primarily used with the per-user-session bus, 
+not the systemwide bus.
+
+.TP
+.I "<limit>"
+
+.PP
+<limit> establishes a resource limit. For example:
+.nf
+  <limit name="max_message_size">64</limit>
+  <limit name="max_completed_connections">512</limit>
+.fi
+
+.PP
+The name attribute is mandatory.
+Available limit names are:
+.nf
+      "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
+      "activation_timeout"         : milliseconds (thousandths) until 
+                                     an activated 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_activations"    : max number of activations in
+                                     progress at the same time
+      "max_services_per_connection": max number of services a single 
+                                     connection can own
+.fi
+
+.PP
+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.
+
+.PP
+max_completed_connections divided by max_connections_per_user is the
+number of users that can work together to DOS all other users by using
+up all connections.
+
+.TP
+.I "<policy>"
+
+.PP
+The <policy> element defines a policy to be applied to a particular
+set of connections to the bus. A policy is made up of
+<allow> and <deny> elements.
+
+.PP
+The <policy> element has one of three attributes:
+.nf
+  context="(default|mandatory)"
+  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
+   - all group="connection's user's group" policies are applied
+     in undefined order
+   - all user="connection's auth user" policies are applied
+     in undefined order
+   - all context="mandatory" policies are applied
+.fi
+
+.PP
+Policies applied later will override those applied earlier, 
+when the policies overlap. Multiple policies with the same 
+user/group/context are applied in the order they appear 
+in the config file.
+
+.TP
+.I "<deny>"
+
+.PP
+A <deny> element appears below a <policy> element and prohibits 
+some action. The possible attributes of a <deny> element are:
+.nf
+   send="messagename"
+   receive="messagename"
+   own="servicename"
+   send_to="servicename"
+   receive_from="servicename"
+   user="username"
+   group="groupname"
+.fi
+
+.PP
+Examples:
+.nf
+   <deny send="org.freedesktop.System.Reboot"/> 
+   <deny receive="org.freedesktop.System.Reboot"/>
+   <deny own="org.freedesktop.System"/>
+   <deny send_to="org.freedesktop.System"/>
+   <deny receive_from="org.freedesktop.System"/>
+   <deny user="john"/>
+   <deny group="enemies"/>
+.fi
+
+.PP
+The <deny> attributes determine whether the deny "matches" a
+particular action. If it matches, the action is denied (unless later
+rules in the config file allow it).
+
+.PP
+send_to and receive_from mean that messages may not be sent to or
+received from the *owner* of the given service, not that they may not
+be sent *to that service name*. That is, if a connection owns services
+A, B, C, and sending to A is denied, sending to B or C will not work
+either.
+
+.PP
+user and group denials mean that the given user or group may 
+not connect to the message bus.
+
+.PP
+For "servicename" or "messagename" or "username" or "groupname"
+the character "*" can be substituted, meaning "any." Complex globs
+like "foo.bar.*" aren't allowed for now because they'd be work to
+implement and maybe encourage sloppy security anyway.
+
+.PP
+It does not make sense to deny a user or group inside a <policy>
+for a user or group; user/group denials can only be inside
+context="default" or context="mandatory" policies.
+
+.PP
+A single <deny> rule may specify both send and send_to, OR both
+receive and receive_from. In this case, the denial applies only if
+both attributes match the message being denied.
+e.g. <deny send="foo.bar" send_to="foo.blah"/> would deny 
+messages of the given name AND to the given service.
+
+.TP
+.I "<allow>"
+
+.PP
+Makes an exception to previous <deny> statements. Works 
+just like <deny> but with the inverse meaning.
+
+.SH AUTHOR
+See http://www.freedesktop.org/software/dbus/doc/AUTHORS
+
+.SH BUGS
+Please send bug reports to the D-BUS mailing list or bug tracker,
+see http://www.freedesktop.org/software/dbus/
diff --git a/configure.in b/configure.in
index ffe7107f..b26a87e0 100644
--- a/configure.in
+++ b/configure.in
@@ -584,12 +584,13 @@ AC_SUBST(DBUS_SESSION_SOCKET_DIR)
 
 AC_OUTPUT([
 Doxyfile
+dbus/dbus-arch-deps.h
 bus/system.conf
 bus/session.conf
 bus/messagebus
+bus/dbus-daemon-1.1
 Makefile
 dbus/Makefile
-dbus/dbus-arch-deps.h
 glib/Makefile
 qt/Makefile
 bus/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5c2b6458..da1d011a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,5 +1,4 @@
 EXTRA_DIST= 					\
-	config-file.txt				\
 	dbus-specification.html			\
 	dbus-specification.sgml			\
 	dbus-test-plan.html			\
diff --git a/doc/TODO b/doc/TODO
index a48d6480..886d2b00 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -50,3 +50,7 @@
  - if you send a message to a service then block for reply, and the service exits/crashes
    after the message bus has processed your message but before the service has replied, 
    it would be nice if the message bus sent you an error reply.
+
+ - write a DTD for the dbus-daemon-1 configuration file
+
+ - build and install the Doxygen manual in Makefile when --enable-docs
diff --git a/doc/config-file.txt b/doc/config-file.txt
deleted file mode 100644
index e6e24e0f..00000000
--- a/doc/config-file.txt
+++ /dev/null
@@ -1,237 +0,0 @@
-
-D-BUS message bus daemon configuration
-===
-
-The 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.
-
-The configuration file also establishes resource limits, security
-parameters, and so forth.
-
-The configuration file is not part of any interoperability
-specification and its backward compatibility is not guaranteed; this
-document is documentation, not specification.
-
-A DTD should be written here eventually, but for now I suck.
-
-Doctype declaration:
-
-   <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
-    "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
-
-Elements:
-
- <busconfig>
- 
-    Root element.
-
- <type>
-
-    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"
-
-    Example: <type>session</type>
-
- <include>
-  ignore_missing="(yes|no)"   optional attribute, defaults to no
-   
-    Include a file <include>filename.conf</include> at this point.
-
- <includedir>
-
-    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.
-
-    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/system.d that allowed all apps to receive this
-    message and allowed the printer daemon user to send it.
-
- <user>
-
-    The user account the daemon should run as, as either a username or
-    a UID. If the daemon doesn't have and 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.
- 
-    The last <user> entry in the file "wins", the others are ignored.
-
-    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.
-
- <fork>
-    
-    If present, the bus daemon becomes a real daemon (forks 
-    into the background, etc.)
-
- <listen>
-
-    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.
-
-    Example: <listen>unix:path=/tmp/foo</listen>
-
-    If there are multiple <listen> elements, then the bus listens 
-    on multiple addresses. The bus will pass its address to 
-    activated 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.
-
- <auth>
-
-    Lists permitted authorization mechanisms. If this element doesn't
-    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.
-    
-    Example: <auth>EXTERNAL</auth>
-    Example: <auth>DBUS_COOKIE_SHA1</auth>
-
- <servicedir>
-
-    Adds a directory to scan for .service files. Directories are
-    scanned starting with the last to appear in the config file 
-    (the first .service file found that provides a particular 
-    service will be used).
-
- <policy>
-  context="(default|mandatory)"  one of the context/user/group
-                                 attributes is mandatory
-  user="username or userid"
-  group="group name or gid"
-
-    Encloses a policy to be applied to a particular set of 
-    connections to the bus. A policy is made up of <limit>, 
-    <allow>, <deny> elements.
-  
-    Policies are applied to a connection as follows:
-       - all context="default" policies are applied
-       - all group="connection's user's group" policies are applied
-         in undefined order
-       - all user="connection's auth user" policies are applied
-         in undefined order
-       - all context="mandatory" policies are applied
-
-    Policies applied later will override those applied earlier, 
-    when the policies overlap. Multiple policies with the same 
-    user/group/context are applied in the order they appear 
-    in the config file.
-
- <limit>
-  name="resource name"  mandatory
-  
-    Appears below a <policy> element and establishes a resource
-    limit. For example:
-      <limit name="max_message_size">64</limit>
-      <limit name="max_completed_connections">512</limit>
-
-    Available limits are:
-      "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
-      "activation_timeout"         : milliseconds (thousandths) until 
-                                     an activated 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_activations"    : max number of activations in
-                                     progress at the same time
-      "max_services_per_connection": max number of services a single 
-                                     connection can own
-
-    Some notes:
-
-       - 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
-
-       - max_completed_connections / max_connections_per_user is 
-         the number of users that can work together to DOS all 
-         other users by using up all connections
-
- <deny>
-  send="messagename"
-  receive="messagename"
-  own="servicename"
-  send_to="servicename"
-  receive_from="servicename"
-  user="username"
-  group="groupname"
-
-    Examples:
-       <deny send="org.freedesktop.System.Reboot"/> 
-       <deny receive="org.freedesktop.System.Reboot"/>
-       <deny own="org.freedesktop.System"/>
-       <deny send_to="org.freedesktop.System"/>
-       <deny receive_from="org.freedesktop.System"/>
-       <deny user="john"/>
-       <deny group="enemies"/>
-
-    send_to and receive_from mean that messages may not be sent to 
-    or received from the *owner* of the given service, not that 
-    they may not be sent *to that service name*. That is, if 
-    a connection owns services A, B, C, and sending to A is denied, 
-    sending to B or C will not work either.
-
-    user and group denials mean that the given user or group may 
-    not connect to the message bus.
-
-    For "servicename" or "messagename" or "username" or "groupname"
-    the character "*" can be substituted, meaning "any." Complex globs
-    like "foo.bar.*" aren't allowed for now because they'd be work to
-    implement and maybe encourage sloppy security anyway.
-
-    It does not make sense to deny a user or group inside a <policy>
-    for a user or group; user/group denials can only be inside
-    context="default" or context="mandatory" policies.
-
-    A single <deny> rule may specify both send and send_to, OR both
-    receive and receive_from. In this case, the denial applies only if
-    both attributes match the message being denied.
-    e.g. <deny send="foo.bar" send_to="foo.blah"/> would deny 
-    messages of the given name AND to the given service.
-
- <allow>
-  send="messagename"
-  receive="messagename"
-  own="servicename"
-  send_to="servicename"
-  receive_from="servicename"
-  user="username"
-  group="groupname"
-
-    Makes an exception to previous <deny> statements. Works 
-    just like <deny> but with the inverse meaning.
-
-    An <allow> only punches holes in the equivalent <deny>, it does
-    not unconditionally allow the message. For example:
-
-      <deny send="*"/>
-      <deny send_to="*"/>
-      <allow send="org.foo.Bar"/>
-
-    Here the policy still doesn't allow sending any messages, because 
-    no recipients have been allowed. You have to add 
-    <allow send_to="something"/> to make the policy useful.
-
- 
-
- 
-   
-