]>
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 | ||
295a54ee SK |
172 | |
173 | ||
9009d746 SK |
174 | 2. SIGNALS |
175 | ---------- | |
176 | ||
177 | If dnsmasq's DHCP server is active, it will send signals over DBUS whenever | |
178 | the DHCP lease database changes. Think of these signals as transactions on | |
179 | a database with the IP address acting as the primary key. | |
180 | ||
181 | Signals are of the form: | |
182 | ||
183 | uk.org.thekelleys.<signal> | |
184 | ||
185 | and their parameters are: | |
186 | ||
187 | STRING "192.168.1.115" | |
188 | STRING "01:23:45:67:89:ab" | |
189 | STRING "hostname.or.fqdn" | |
190 | ||
191 | ||
192 | Available signals are: | |
193 | ||
194 | DhcpLeaseAdded | |
195 | --------------- | |
196 | ||
197 | This signal is emitted when a DHCP lease for a given IP address is created. | |
198 | ||
199 | DhcpLeaseDeleted | |
200 | ---------------- | |
201 | ||
202 | This signal is emitted when a DHCP lease for a given IP address is deleted. | |
203 | ||
204 | DhcpLeaseUpdated | |
205 | ---------------- | |
3d8df260 | 206 | |
9009d746 SK |
207 | This signal is emitted when a DHCP lease for a given IP address is updated. |
208 |