doc/config-file.txt

   1
   2 D-BUS message bus daemon configuration
   3 ===
   4
   5 The message bus daemon has a configuration file that specializes it
   6 for a particular application. For example, one configuration
   7 file might set up the message bus to be a systemwide message bus,
   8 while another might set it up to be a per-user login session bus.
   9
  10 The configuration file also establishes resource limits, security
  11 parameters, and so forth.
  12
  13 The configuration file is not part of any interoperability
  14 specification and its backward compatibility is not guaranteed; this
  15 document is documentation, not specification.
  16
  17 A DTD should be written here eventually, but for now I suck.
  18
  19 Doctype declaration:
  20
  21    <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
  22     "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
  23
  24 Elements:
  25
  26  <busconfig>
  27
  28     Root element.
  29
  30  <type>
  31
  32     The well-known type of the message bus. Currently known values
  33     are "system" and "session"; if other values are set, they should
  34     be either added to the D-BUS specification, or namespaced.
  35     The last <type> element "wins"
  36
  37     Example: <type>session</type>
  38
  39  <include>
  40   ignore_missing="(yes|no)"   optional attribute, defaults to no
  41
  42     Include a file <include>filename.conf</include> at this point.
  43
  44  <includedir>
  45
  46     Include all files in <includedir>foo.d</includedir> at this
  47     point. Files in the directory are included in undefined order.
  48     Only files ending in ".conf" are included.
  49
  50     This is intended to allow extension of the system bus by
  51     particular packages. For example, if CUPS wants to be able to send
  52     out notification of printer queue changes, it could install a file
  53     to /etc/dbus/system.d that allowed all apps to receive this
  54     message and allowed the printer daemon user to send it.
  55
  56  <user>
  57
  58     The user account the daemon should run as, as either a username or
  59     a UID. If the daemon doesn't have and cannot change to this UID on
  60     startup, it will exit.  If this element is not present, the daemon
  61     will not change or care about its UID.
  62
  63     The last <user> entry in the file "wins", the others are ignored.
  64
  65     The user is changed after the bus has completed initialization.
  66     So sockets etc. will be created before changing user, but no
  67     data will be read from clients before changing user.
  68
  69  <fork>
  70
  71     If present, the bus daemon becomes a real daemon (forks
  72     into the background, etc.)
  73
  74  <listen>
  75
  76     Add an address that the bus should listen on. The
  77     address is in the standard D-BUS format that contains
  78     a transport name plus possible parameters/options.
  79
  80     Example: <listen>unix:path=/tmp/foo</listen>
  81
  82     If there are multiple <listen> elements, then the bus listens
  83     on multiple addresses. The bus will pass its address to
  84     activated services or other interested parties with
  85     the last address given in <listen> first. That is,
  86     apps will try to connect to the last <listen> address first.
  87
  88  <auth>
  89
  90     Lists permitted authorization mechanisms. If this element doesn't
  91     exist, then all known mechanisms are allowed.  If there are
  92     multiple <auth> elements, all the listed mechanisms are allowed.
  93     The order in which mechanisms are listed is not meaningful.
  94
  95     Example: <auth>EXTERNAL</auth>
  96     Example: <auth>DBUS_COOKIE_SHA1</auth>
  97
  98  <servicedir>
  99
 100     Adds a directory to scan for .service files. Directories are
 101     scanned starting with the last to appear in the config file
 102     (the first .service file found that provides a particular
 103     service will be used).
 104
 105  <policy>
 106   context="(default|mandatory)"  one of the context/user/group
 107                                  attributes is mandatory
 108   user="username or userid"
 109   group="group name or gid"
 110
 111     Encloses a policy to be applied to a particular set of
 112     connections to the bus. A policy is made up of <limit>,
 113     <allow>, <deny> elements.
 114
 115     Policies are applied to a connection as follows:
 116        - all context="default" policies are applied
 117        - all group="connection's user's group" policies are applied
 118          in undefined order
 119        - all user="connection's auth user" policies are applied
 120          in undefined order
 121        - all context="mandatory" policies are applied
 122
 123     Policies applied later will override those applied earlier,
 124     when the policies overlap. Multiple policies with the same
 125     user/group/context are applied in the order they appear
 126     in the config file.
 127
 128  <limit>
 129   name="resource name"  mandatory
 130
 131     Appears below a <policy> element and establishes a resource
 132     limit. For example:
 133       <limit name="max_message_size">64</limit>
 134       <limit name="max_completed_connections">512</limit>
 135
 136     Available limits are:
 137       "max_incoming_bytes"         : total size in bytes of messages
 138                                      incoming from a single connection
 139       "max_outgoing_bytes"         : total size in bytes of messages
 140                                      queued up for a single connection
 141       "max_message_size"           : max size of a single message in
 142                                      bytes
 143       "activation_timeout"         : milliseconds (thousandths) until
 144                                      an activated service has to connect
 145       "auth_timeout"               : milliseconds (thousandths) a
 146                                      connection is given to
 147                                      authenticate
 148       "max_completed_connections"  : max number of authenticated connections
 149       "max_incomplete_connections" : max number of unauthenticated
 150                                      connections
 151       "max_connections_per_user"   : max number of completed connections from
 152                                      the same user
 153       "max_pending_activations"    : max number of activations in
 154                                      progress at the same time
 155       "max_services_per_connection": max number of services a single
 156                                      connection can own
 157
 158     Some notes:
 159
 160        - the max incoming/outgoing queue sizes allow a new message
 161          to be queued if one byte remains below the max. So you can
 162          in fact exceed the max by max_message_size
 163
 164        - max_completed_connections / max_connections_per_user is
 165          the number of users that can work together to DOS all
 166          other users by using up all connections
 167
 168  <deny>
 169   send="messagename"
 170   receive="messagename"
 171   own="servicename"
 172   send_to="servicename"
 173   receive_from="servicename"
 174   user="username"
 175   group="groupname"
 176
 177     Examples:
 178        <deny send="org.freedesktop.System.Reboot"/>
 179        <deny receive="org.freedesktop.System.Reboot"/>
 180        <deny own="org.freedesktop.System"/>
 181        <deny send_to="org.freedesktop.System"/>
 182        <deny receive_from="org.freedesktop.System"/>
 183        <deny user="john"/>
 184        <deny group="enemies"/>
 185
 186     send_to and receive_from mean that messages may not be sent to
 187     or received from the *owner* of the given service, not that
 188     they may not be sent *to that service name*. That is, if
 189     a connection owns services A, B, C, and sending to A is denied,
 190     sending to B or C will not work either.
 191
 192     user and group denials mean that the given user or group may
 193     not connect to the message bus.
 194
 195     For "servicename" or "messagename" or "username" or "groupname"
 196     the character "*" can be substituted, meaning "any." Complex globs
 197     like "foo.bar.*" aren't allowed for now because they'd be work to
 198     implement and maybe encourage sloppy security anyway.
 199
 200     It does not make sense to deny a user or group inside a <policy>
 201     for a user or group; user/group denials can only be inside
 202     context="default" or context="mandatory" policies.
 203
 204     A single <deny> rule may specify both send and send_to, OR both
 205     receive and receive_from. In this case, the denial applies only if
 206     both attributes match the message being denied.
 207     e.g. <deny send="foo.bar" send_to="foo.blah"/> would deny
 208     messages of the given name AND to the given service.
 209
 210  <allow>
 211   send="messagename"
 212   receive="messagename"
 213   own="servicename"
 214   send_to="servicename"
 215   receive_from="servicename"
 216   user="username"
 217   group="groupname"
 218
 219     Makes an exception to previous <deny> statements. Works
 220     just like <deny> but with the inverse meaning.
 221
 222     An <allow> only punches holes in the equivalent <deny>, it does
 223     not unconditionally allow the message. For example:
 224
 225       <deny send="*"/>
 226       <deny send_to="*"/>
 227       <allow send="org.foo.Bar"/>
 228
 229     Here the policy still doesn't allow sending any messages, because
 230     no recipients have been allowed. You have to add
 231     <allow send_to="something"/> to make the policy useful.
 232
 233
 234
 235
 236
 237