]>
Commit | Line | Data |
---|---|---|
3d8df260 SK |
1 | DBus support must be enabled at compile-time and run-time. Ensure |
2 | that src/config.h contains the line | |
3 | ||
4 | #define HAVE_DBUS. | |
5 | ||
6 | and that /etc/dnsmasq.conf contains the line | |
7 | ||
8 | enable-dbus | |
9 | ||
10 | Because dnsmasq can operate stand-alone from the DBus, and may need to provide | |
11 | service before the dbus daemon is available, it will continue to run | |
12 | if the DBus connection is not available at startup. The DBus will be polled | |
13 | every 250ms until a connection is established. Start of polling and final | |
14 | connection establishment are both logged. When dnsmasq establishes a | |
15 | connection to the dbus, it sends the signal "Up". Anything controlling | |
16 | the server settings in dnsmasq should re-invoke the SetServers method | |
17 | (q.v.) when it sees this signal. This allows dnsmasq to be restarted | |
18 | and avoids startup races with the provider of nameserver information. | |
19 | ||
20 | ||
21 | Dnsmasq provides one service on the DBus: uk.org.thekelleys.dnsmasq | |
ad094275 SK |
22 | and a single object: /uk/org/thekelleys/dnsmasq |
23 | The name of the service may be changed by giving an argument to --enable-dbus. | |
3d8df260 | 24 | |
9009d746 SK |
25 | 1. METHODS |
26 | ---------- | |
27 | ||
3d8df260 SK |
28 | Methods are of the form |
29 | ||
30 | uk.org.thekelleys.<method> | |
31 | ||
32 | Available methods are: | |
33 | ||
34 | GetVersion | |
35 | ---------- | |
36 | Returns a string containing the version of dnsmasq running. | |
37 | ||
38 | ClearCache | |
39 | ---------- | |
40 | Returns nothing. Clears the domain name cache and re-reads | |
41 | /etc/hosts. The same as sending dnsmasq a HUP signal. | |
42 | ||
c4638f9e DC |
43 | SetFilterWin2KOption |
44 | -------------------- | |
45 | Takes boolean, sets or resets the --filterwin2k option. | |
46 | ||
47 | SetBogusPrivOption | |
48 | ------------------ | |
49 | Takes boolean, sets or resets the --bogus-priv option. | |
50 | ||
3d8df260 SK |
51 | SetServers |
52 | ---------- | |
53 | Returns nothing. Takes a set of arguments representing the new | |
54 | upstream DNS servers to be used by dnsmasq. IPv4 addresses are | |
55 | represented as a UINT32 (in network byte order) and IPv6 addresses | |
56 | are represented as sixteen BYTEs (since there is no UINT128 type). | |
57 | Each server address may be followed by one or more STRINGS, which are | |
58 | the domains for which the preceding server should be used. | |
59 | ||
60 | Examples. | |
61 | ||
62 | UINT32: <address1> | |
63 | UNIT32: <address2> | |
64 | ||
65 | is equivalent to | |
66 | ||
67 | --server=<address1> --server=<address2> | |
68 | ||
69 | ||
70 | UINT32 <address1> | |
71 | UINT32 <address2> | |
72 | STRING "somedomain.com" | |
73 | ||
74 | is equivalent to | |
75 | ||
76 | --server=<address1> --server=/somedomain.com/<address2> | |
77 | ||
78 | UINT32 <address1> | |
79 | UINT32 <address2> | |
80 | STRING "somedomain.com" | |
81 | UINT32 <address3> | |
82 | STRING "anotherdomain.com" | |
83 | STRING "thirddomain.com" | |
84 | ||
85 | is equivalent to | |
86 | ||
87 | --server=<address1> | |
88 | --server=/somedomain.com/<address2> | |
89 | --server=/anotherdomain.com/thirddomain.com/<address3> | |
90 | ||
91 | Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only", | |
92 | so | |
93 | ||
94 | UINT32: <0.0.0.0> | |
95 | STRING "local.domain" | |
96 | ||
97 | is equivalent to | |
98 | ||
99 | --local=/local.domain/ | |
100 | ||
101 | ||
102 | Each call to SetServers completely replaces the set of servers | |
103 | specified by via the DBus, but it leaves any servers specified via the | |
104 | command line or /etc/dnsmasq.conf or /etc/resolv.conf alone. | |
105 | ||
faafb3f7 SK |
106 | SetServersEx |
107 | ------------ | |
108 | ||
109 | This function is more flexible and the SetServers function, in that it can | |
110 | handle address scoping, port numbers, and is easier for clients to use. | |
111 | ||
112 | Returns nothing. Takes a set of arguments representing the new | |
113 | upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6) | |
114 | are represented as STRINGS. Each server address may be followed by one or more | |
115 | STRINGS, which are the domains for which the preceding server should be used. | |
116 | ||
117 | This function takes an array of STRING arrays, where each inner array represents | |
118 | a set of DNS servers and domains for which those servers may be used. Each | |
119 | string represents a list of upstream DNS servers first, and domains second. | |
120 | Mixing of domains and servers within a the string array is not allowed. | |
121 | ||
122 | Examples. | |
123 | ||
124 | [ | |
125 | ["1.2.3.4", "foobar.com"], | |
126 | ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"] | |
127 | ] | |
128 | ||
129 | is equivalent to | |
130 | ||
131 | --server=/foobar.com/1.2.3.4 \ | |
132 | --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0 | |
133 | ||
134 | An IPv4 address of 0.0.0.0 is interpreted as "no address, local only", | |
135 | so | |
136 | ||
137 | [ ["0.0.0.0", "local.domain"] ] | |
138 | ||
139 | is equivalent to | |
140 | ||
141 | --local=/local.domain/ | |
142 | ||
143 | ||
144 | Each call to SetServersEx completely replaces the set of servers | |
145 | specified by via the DBus, but it leaves any servers specified via the | |
146 | command line or /etc/dnsmasq.conf or /etc/resolv.conf alone. | |
147 | ||
295a54ee SK |
148 | |
149 | SetDomainServers | |
150 | ---------------- | |
151 | ||
152 | Yes another variation for setting DNS servers, with the capability of | |
153 | SetServersEx, but without using arrays of arrays, which are not | |
154 | sendable with dbus-send. The arguments are an array of strings which | |
155 | are identical to the equivalent arguments --server, so the example | |
156 | for SetServersEx is represented as | |
157 | ||
158 | [ | |
159 | "/foobar.com/1.2.3.4" | |
160 | "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0" | |
161 | ] | |
162 | ||
aaeea9f6 SK |
163 | GetLoopServers |
164 | -------------- | |
165 | ||
166 | (Only available if dnsmasq compiled with HAVE_LOOP) | |
167 | ||
168 | Return an array of strings, each string is the IP address of an upstream | |
169 | server which has been found to loop queries back to this dnsmasq instance, and | |
170 | it therefore not being used. | |
171 | ||
c6d82c9b NC |
172 | AddDhcpLease |
173 | ------------ | |
174 | ||
175 | Returns nothing. Adds or updates a DHCP or DHCPv6 lease to the internal lease | |
176 | database, as if a client requested and obtained a lease. | |
177 | ||
178 | If a lease for the IPv4 or IPv6 address already exist, it is overwritten. | |
179 | ||
180 | Note that this function will trigger the DhcpLeaseAdded or DhcpLeaseUpdated | |
181 | D-Bus signal and will run the configured DHCP lease script accordingly. | |
182 | ||
183 | This function takes many arguments which are the lease parameters: | |
184 | - A string with the textual representation of the IPv4 or IPv6 address of the | |
185 | client. | |
186 | ||
187 | Examples: | |
188 | "192.168.1.115" | |
189 | "1003:1234:abcd::1%eth0" | |
190 | "2001:db8:abcd::1" | |
191 | ||
192 | - A string representing the hardware address of the client, using the same | |
193 | format as the one used in the lease database. | |
194 | ||
195 | Examples: | |
196 | ||
197 | "00:23:45:67:89:ab" | |
198 | "06-00:20:e0:3b:13:af" (token ring) | |
199 | ||
200 | - The hostname of the client, as an array of bytes (so there is no problem | |
201 | with non-ASCII character encoding). May be empty. | |
202 | ||
203 | Example (for "hostname.or.fqdn"): | |
204 | [104, 111, 115, 116, 110, 97, 109, 101, 46, 111, 114, 46, 102, 113, 100, 110] | |
205 | ||
206 | - The client identifier (IPv4) or DUID (IPv6) as an array of bytes. May be | |
207 | empty. | |
208 | ||
209 | Examples: | |
210 | ||
211 | DHCPv6 DUID: | |
212 | [0, 3, 0, 1, 0, 35, 69, 103, 137, 171] | |
213 | DHCPv4 client identifier: | |
214 | [255, 12, 34, 56, 78, 0, 1, 0, 1, 29, 9, 99, 190, 35, 69, 103, 137, 171] | |
215 | ||
216 | - The duration of the lease, in seconds. If the lease is updated, then | |
217 | the duration replaces the previous duration. | |
218 | ||
219 | Example: | |
220 | ||
221 | 7200 | |
222 | ||
223 | - The IAID (Identity association identifier) of the DHCPv6 lease, as a network | |
224 | byte-order unsigned integer. For DHCPv4 leases, this must be set to 0. | |
225 | ||
226 | Example (for IPv6): | |
227 | ||
228 | 203569230 | |
229 | ||
230 | - A boolean which, if true, indicates that the DHCPv6 lease is for a temporary | |
231 | address (IA_TA). If false, the DHCPv6 lease is for a non-temporary address | |
232 | (IA_NA). For DHCPv4 leases, this must be set to false. | |
233 | ||
234 | RemoveDhcpLease | |
235 | --------------- | |
236 | ||
237 | Returns nothing. Removes a DHCP or DHCPv6 lease to the internal lease | |
238 | database, as if a client sent a release message to abandon a lease. | |
239 | ||
240 | This function takes only one parameter: the text representation of the | |
241 | IPv4 or IPv6 address of the lease to remove. | |
242 | ||
243 | Note that this function will trigger the DhcpLeaseRemoved signal and the | |
244 | configured DHCP lease script will be run with the "del" action. | |
245 | ||
295a54ee SK |
246 | |
247 | ||
9009d746 SK |
248 | 2. SIGNALS |
249 | ---------- | |
250 | ||
251 | If dnsmasq's DHCP server is active, it will send signals over DBUS whenever | |
252 | the DHCP lease database changes. Think of these signals as transactions on | |
253 | a database with the IP address acting as the primary key. | |
254 | ||
255 | Signals are of the form: | |
256 | ||
257 | uk.org.thekelleys.<signal> | |
258 | ||
259 | and their parameters are: | |
260 | ||
261 | STRING "192.168.1.115" | |
262 | STRING "01:23:45:67:89:ab" | |
263 | STRING "hostname.or.fqdn" | |
264 | ||
265 | ||
266 | Available signals are: | |
267 | ||
268 | DhcpLeaseAdded | |
269 | --------------- | |
270 | ||
271 | This signal is emitted when a DHCP lease for a given IP address is created. | |
272 | ||
273 | DhcpLeaseDeleted | |
274 | ---------------- | |
275 | ||
276 | This signal is emitted when a DHCP lease for a given IP address is deleted. | |
277 | ||
278 | DhcpLeaseUpdated | |
279 | ---------------- | |
3d8df260 | 280 | |
9009d746 SK |
281 | This signal is emitted when a DHCP lease for a given IP address is updated. |
282 |