summaryrefslogtreecommitdiff
path: root/dbus/DBus-interface
blob: 59b41b1b33150f2f16db03bb540b8be1807258c3 (plain)
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
DBus support must be enabled at compile-time and run-time. Ensure 
that src/config.h contains the line

#define HAVE_DBUS.

and that /etc/dnsmasq.conf contains the line

enable-dbus

Because dnsmasq can operate stand-alone from the DBus, and may need to provide
service before the dbus daemon is available, it will continue to run
if the DBus connection is not available at startup. The DBus will be polled 
every 250ms until a connection is established. Start of polling and final
connection establishment are both logged. When dnsmasq establishes a
connection to the dbus, it sends the signal "Up". Anything controlling
the server settings in dnsmasq should re-invoke the SetServers method
(q.v.) when it sees this signal. This allows dnsmasq to be restarted
and avoids startup races with the provider of nameserver information.


Dnsmasq provides one service on the DBus: uk.org.thekelleys.dnsmasq
and a single object: /uk/org/thekelleys/dnsmasq 
The name of the service may be changed by giving an argument to --enable-dbus.

1. METHODS
----------

Methods are of the form

uk.org.thekelleys.<method>

Available methods are:

GetVersion
----------
Returns a string containing the version of dnsmasq running.

ClearCache
----------
Returns nothing. Clears the domain name cache and re-reads
/etc/hosts. The same as sending dnsmasq a HUP signal.

SetFilterWin2KOption
--------------------
Takes boolean, sets or resets the --filterwin2k option.

SetBogusPrivOption
------------------
Takes boolean, sets or resets the --bogus-priv option.

SetLocaliseQueriesOption
------------------------
Takes boolean, sets or resets the --localise-queries option.

SetServers
----------
Returns nothing. Takes a set of arguments representing the new
upstream DNS servers to be used by dnsmasq. IPv4 addresses are
represented as a UINT32 (in network byte order) and IPv6 addresses
are represented as sixteen BYTEs (since there is no UINT128 type).
Each server address may be followed by one or more STRINGS, which are
the domains for which the preceding server should be used.

Examples.

UINT32: <address1>
UNIT32: <address2>

is equivalent to

--server=<address1> --server=<address2>


UINT32 <address1>
UINT32 <address2>
STRING "somedomain.com"

is equivalent to

--server=<address1> --server=/somedomain.com/<address2> 

UINT32 <address1>
UINT32 <address2>
STRING "somedomain.com"
UINT32 <address3>
STRING "anotherdomain.com"
STRING "thirddomain.com"

is equivalent to

--server=<address1> 
--server=/somedomain.com/<address2> 
--server=/anotherdomain.com/thirddomain.com/<address3>

Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
so

UINT32: <0.0.0.0>
STRING  "local.domain"

is equivalent to

--local=/local.domain/


Each call to SetServers completely replaces the set of servers
specified by via the DBus, but it leaves any servers specified via the
command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.

SetServersEx
------------

This function is more flexible and the SetServers function, in that it can
handle address scoping, port numbers, and is easier for clients to use.

Returns nothing. Takes a set of arguments representing the new
upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6)
are represented as STRINGS.  Each server address may be followed by one or more
STRINGS, which are the domains for which the preceding server should be used.

This function takes an array of STRING arrays, where each inner array represents
a set of DNS servers and domains for which those servers may be used.  Each
string represents a list of upstream DNS servers first, and domains second.
Mixing of domains and servers within a the string array is not allowed.

Examples.

[
  ["1.2.3.4", "foobar.com"],
  ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"]
]

is equivalent to

--server=/foobar.com/1.2.3.4 \
  --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0

An IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
so

[ ["0.0.0.0", "local.domain"] ]

is equivalent to

--local=/local.domain/


Each call to SetServersEx completely replaces the set of servers
specified by via the DBus, but it leaves any servers specified via the
command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.


SetDomainServers
----------------

Yes another variation for setting DNS servers, with the capability of
SetServersEx, but without using arrays of arrays, which are not
sendable with dbus-send. The arguments are an array of strings which
are identical to the equivalent arguments --server, so the example
for SetServersEx is represented as

[
  "/foobar.com/1.2.3.4"
  "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0"
]

GetLoopServers
--------------

(Only available if dnsmasq compiled with HAVE_LOOP)

Return an array of strings, each string is the IP address of an upstream
server which has been found to loop queries back to this dnsmasq instance, and 
it therefore not being used.

AddDhcpLease
------------

Returns nothing. Adds or updates a DHCP or DHCPv6 lease to the internal lease
database, as if a client requested and obtained a lease.

If a lease for the IPv4 or IPv6 address already exist, it is overwritten.

Note that this function will trigger the DhcpLeaseAdded or DhcpLeaseUpdated
D-Bus signal and will run the configured DHCP lease script accordingly.

This function takes many arguments which are the lease parameters:
- A string with the textual representation of the IPv4 or IPv6 address of the
  client.

  Examples:
  "192.168.1.115"
  "1003:1234:abcd::1%eth0"
  "2001:db8:abcd::1"

- A string representing the hardware address of the client, using the same
  format as the one used in the lease database.

  Examples:

  "00:23:45:67:89:ab"
  "06-00:20:e0:3b:13:af" (token ring)

- The hostname of the client, as an array of bytes (so there is no problem
  with non-ASCII character encoding). May be empty.

  Example (for "hostname.or.fqdn"):
  [104, 111, 115, 116, 110, 97, 109, 101, 46, 111, 114, 46, 102, 113, 100, 110]

- The client identifier (IPv4) or DUID (IPv6) as an array of bytes. May be
  empty.

  Examples:

  DHCPv6 DUID:
  [0, 3, 0, 1, 0, 35, 69, 103, 137, 171]
  DHCPv4 client identifier:
  [255, 12, 34, 56, 78, 0, 1, 0, 1, 29, 9, 99, 190, 35, 69, 103, 137, 171]

- The duration of the lease, in seconds. If the lease is updated, then
  the duration replaces the previous duration.

  Example:

  7200

- The IAID (Identity association identifier) of the DHCPv6 lease, as a network
  byte-order unsigned integer. For DHCPv4 leases, this must be set to 0.

  Example (for IPv6):

  203569230

- A boolean which, if true, indicates that the DHCPv6 lease is for a temporary
  address (IA_TA). If false, the DHCPv6 lease is for a non-temporary address
  (IA_NA). For DHCPv4 leases, this must be set to false.

RemoveDhcpLease
---------------

Returns nothing. Removes a DHCP or DHCPv6 lease to the internal lease
database, as if a client sent a release message to abandon a lease.

This function takes only one parameter: the text representation of the
IPv4 or IPv6 address of the lease to remove.

Note that this function will trigger the DhcpLeaseRemoved signal and the
configured DHCP lease script will be run with the "del" action.

GetMetrics
----------

Returns an array with various metrics for DNS and DHCP.

GetServerMetrics
----------------

Returns per-DNS-server metrics.

ClearMetrics
------------

Clear call metric counters, global and per-server.

2. SIGNALS
----------

If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
the DHCP lease database changes. Think of these signals as transactions on
a database with the IP address acting as the primary key.

Signals are of the form:

uk.org.thekelleys.<signal>

and their parameters are:

STRING "192.168.1.115"
STRING "01:23:45:67:89:ab"
STRING "hostname.or.fqdn"


Available signals are:

DhcpLeaseAdded
---------------

This signal is emitted when a DHCP lease for a given IP address is created.

DhcpLeaseDeleted
----------------

This signal is emitted when a DHCP lease for a given IP address is deleted.

DhcpLeaseUpdated
----------------

This signal is emitted when a DHCP lease for a given IP address is updated.