config-file.txt 5.24 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96

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.

 <include>
  ignore_missing="(yes|no)"   optional attribute, defaults to no
   
    Include a file <include>filename.conf</include> at this point.

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

 <listen>
  address="name"    mandatory attribute

    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 address="unix:path=/tmp/foo"/>

    If there are multiple <listen> elements, then the bus listens 
    on multiple addresses.

 <auth>

    Lists permitted authorization mechanisms. If this element doesn't
    exist, then all known mechanisms are allowed.  If there are
    multiple <auth> elements, the last one wins (they are not merged).

 <policy>
  context="(default|required)"   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
       - all user="connection's auth user" policies are applied
       - all context="required" 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_connections">512</limit>

 <deny>
  send="messagename"
  receive="messagename"
  own="servicename"
  send_to="servicename"
  receive_from="servicename"
97 98
  user="username"
  group="groupname"
99 100 101 102 103 104 105

    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"/>
106 107
       <deny user="john"/>
       <deny group="enemies"/>
108 109 110 111 112 113 114

    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.

115 116
    user and group denials mean that the given user or group may 
    not connect to the message bus.
117

118 119 120 121 122 123 124 125 126 127 128 129
    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="required" 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.
130 131 132 133 134 135 136 137 138
    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"
139 140
  user="username"
  group="groupname"
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160

    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.