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.

3 files changed, 4 insertions, 238 deletions

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.
-
- 
-
- 
-   
-