1XDG-DBUS-PROXY(1) User Commands XDG-DBUS-PROXY(1)
2
6 xdg-dbus-proxy - D-Bus proxy
7
9 xdg-dbus-proxy [OPTION...] [ADDRESS PATH [OPTION...]...]
10
12 xdg-dbus-proxy is a filtering proxy for D-Bus connections. Its
13 arguments are one or more ADDRESS-PATH pairs specifying the buses to
14 proxy, with options that specify what filtering to apply.
15 Basic Operation
17 The proxy listens to the unix domain socket at PATH, and for each
18 client that connects to the socket, it opens up a new connection to the
19 specified D-Bus ADDRESS (typically the session bus) and forwards data
20 between the two. During the authentication phase all data is forwarded
21 as received, and additionally for the first 1 byte zero we also send
22 the proxy credentials to the bus.
23 Once the connection is authenticated there are two modes, filtered and
25 unfiltered. In the unfiltered mode all messages are sent on as they are
26 received. In the filtering mode policy is applied to determine which
27 messages to allow, and which to drop.
28 Filtering is applied only to outgoing signals and method calls and
30 incoming broadcast signals. All replies (errors or method returns) are
31 allowed once for an outstanding method call, and never otherwise.
32 If a client ever receives a message from another peer on the bus, the
34 senders unique name is made visible, so the client can track caller
35 lifetimes via NameOwnerChanged signals. If a client calls a method on
36 or receives a broadcast signal from a name (even if filtered to some
37 subset of paths or interfaces), that names basic policy is considered
38 to be (at least) TALK, from then on.
39 Policy
41 The policy for the filtering consists of a mapping from well-known
42 names to a policy that is either SEE, TALK or OWN. The default initial
43 policy is that the the user is only allowed to TALK to the bus itself
44 (org.freedesktop.DBus, or no destination specified), and TALK to its
45 own unique ID. All other clients are invisible.
46 Here is a description of the policy levels (each level implies the ones
48 before it):
49 SEE
51 The name/ID is visible in the ListNames reply
52 The name/ID is visible in the ListActivatableNames reply
54 You can call GetNameOwner on the name
56 You can call NameHasOwner on the name
58 You see NameOwnerChanged signals on the name
60 You see NameOwnerChanged signals on the ID when the client
62 disconnects
63 You can call the GetXXX methods on the name/ID to get e.g. the peer
65 pid
66 You get AccessDenied rather than NameHasNoOwner when sending
68 messages to the name/ID
69 TALK
71 You can send any method calls and signals to the name/ID
72 You will receive broadcast signals from the name/ID (if you have a
74 match rule for them)
75 You can call StartServiceByName on the name
77 OWN
79 You are allowed to call RequestName/ReleaseName/ListQueuedOwners on
80 the name
81 Policy is specified with the --see, --talk and --own options. The
83 well-known names in these options can have a '.*' suffix. A name of
84 "org.foo.*" matches "org.foo", org.foo.bar", and "org.foo.bar.gazonk",
85 but not "org.foobar".
86 Polices are specified for well-known names, but they also affect the
88 owner of that name, so that the policy for a unique ID is the union of
89 the polices for all the names it owns. For technical reasons, the
90 policy for a unique name is "sticky", in that the highest policy
91 granted by a once-owned name is kept, even when the client releases
92 that name. This is impossible to avoid in a race-free way in a proxy.
93 But it is rarely a problem in practice, as few clients release names
94 and stay on the bus.
95 In addition to the basic SEE/TALK/OWN policy, it is possible to specify
97 more complicated rules about what method calls can be made on and what
98 broadcast signals can be received from well-known names. A rule can
99 restrict the allowed calls/signals to a specific object path or a
100 subtree of object paths, and it can restrict the allowed interface down
101 to an individual method or signal name.
102 Rules are specified with the --call and --broadcast options. The RULE
104 in these options determines what interfaces, methods and object paths
105 are allowed. It must be of the form [METHOD][@PATH], where METHOD can
106 be either '*' or a D-Bus interface, possible with a '.*' suffix, or a
107 fully-qualified method name, and PATH is a D-Bus object path, possible
108 with a '/*' suffix.
109
111 When options are used multiple times, the last option wins, unless
112 otherwise specified.
113 General options:
115 --help
117 Print help and exit
118 --version
120 Print version
121 --fd=FD
123 Write to FD when the proxies are ready, and stop when it is closed.
124 --args=FD
126 Parse nul-separated arguments from the given file descriptor. This
127 option can be used multiple times to parse options from multiple
128 sources.
129 Proxy Options:
131 These options can only be used after an ADDRESS and apply to the proxy
133 for that address.
134 --filter
136 Enable filtering
137 --log
139 Turn on logging
140 --sloppy-names
142 Make all unique names visible.
143 --see=NAME
145 Set the SEE policy for the given name.
146 --talk=NAME
148 Set the TALK policy for the given name.
149 --own=NAME
151 Set the OWN policy for the given name.
152 --call=NAME=RULE
154 Set a rule for calls on the given name.
155 --broadcast=NAME=RULE
157 Set a rule for broadcast signals from the given name.
158
160 $ xdg-dbus-proxy --fd=26 unix:path=/run/usr/1000/bus
161 /run/usr/1000/.dbus-proxy/session-bus-proxy --filter
162 --own=org.gnome.ghex.* --talk=ca.desrt.dconf
163 --call=org.freedesktop.portal.*=*
164 --broadcast=org.freedesktop.portal.*=@/org/freedesktop/portal/*
165flatpak XDG-DBUS-PROXY(1)