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
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.
24:
25: 1. METHODS
26: ----------
27:
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:
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:
51: SetLocaliseQueriesOption
52: ------------------------
53: Takes boolean, sets or resets the --localise-queries option.
54:
55: SetServers
56: ----------
57: Returns nothing. Takes a set of arguments representing the new
58: upstream DNS servers to be used by dnsmasq. IPv4 addresses are
59: represented as a UINT32 (in network byte order) and IPv6 addresses
60: are represented as sixteen BYTEs (since there is no UINT128 type).
61: Each server address may be followed by one or more STRINGS, which are
62: the domains for which the preceding server should be used.
63:
64: Examples.
65:
66: UINT32: <address1>
67: UNIT32: <address2>
68:
69: is equivalent to
70:
71: --server=<address1> --server=<address2>
72:
73:
74: UINT32 <address1>
75: UINT32 <address2>
76: STRING "somedomain.com"
77:
78: is equivalent to
79:
80: --server=<address1> --server=/somedomain.com/<address2>
81:
82: UINT32 <address1>
83: UINT32 <address2>
84: STRING "somedomain.com"
85: UINT32 <address3>
86: STRING "anotherdomain.com"
87: STRING "thirddomain.com"
88:
89: is equivalent to
90:
91: --server=<address1>
92: --server=/somedomain.com/<address2>
93: --server=/anotherdomain.com/thirddomain.com/<address3>
94:
95: Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
96: so
97:
98: UINT32: <0.0.0.0>
99: STRING "local.domain"
100:
101: is equivalent to
102:
103: --local=/local.domain/
104:
105:
106: Each call to SetServers completely replaces the set of servers
107: specified by via the DBus, but it leaves any servers specified via the
108: command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
109:
110: SetServersEx
111: ------------
112:
113: This function is more flexible and the SetServers function, in that it can
114: handle address scoping, port numbers, and is easier for clients to use.
115:
116: Returns nothing. Takes a set of arguments representing the new
117: upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6)
118: are represented as STRINGS. Each server address may be followed by one or more
119: STRINGS, which are the domains for which the preceding server should be used.
120:
121: This function takes an array of STRING arrays, where each inner array represents
122: a set of DNS servers and domains for which those servers may be used. Each
123: string represents a list of upstream DNS servers first, and domains second.
124: Mixing of domains and servers within a the string array is not allowed.
125:
126: Examples.
127:
128: [
129: ["1.2.3.4", "foobar.com"],
130: ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"]
131: ]
132:
133: is equivalent to
134:
135: --server=/foobar.com/1.2.3.4 \
136: --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0
137:
138: An IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
139: so
140:
141: [ ["0.0.0.0", "local.domain"] ]
142:
143: is equivalent to
144:
145: --local=/local.domain/
146:
147:
148: Each call to SetServersEx completely replaces the set of servers
149: specified by via the DBus, but it leaves any servers specified via the
150: command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
151:
152:
153: SetDomainServers
154: ----------------
155:
156: Yes another variation for setting DNS servers, with the capability of
157: SetServersEx, but without using arrays of arrays, which are not
158: sendable with dbus-send. The arguments are an array of strings which
159: are identical to the equivalent arguments --server, so the example
160: for SetServersEx is represented as
161:
162: [
163: "/foobar.com/1.2.3.4"
164: "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0"
165: ]
166:
167: GetLoopServers
168: --------------
169:
170: (Only available if dnsmasq compiled with HAVE_LOOP)
171:
172: Return an array of strings, each string is the IP address of an upstream
173: server which has been found to loop queries back to this dnsmasq instance, and
174: it therefore not being used.
175:
176: AddDhcpLease
177: ------------
178:
179: Returns nothing. Adds or updates a DHCP or DHCPv6 lease to the internal lease
180: database, as if a client requested and obtained a lease.
181:
182: If a lease for the IPv4 or IPv6 address already exist, it is overwritten.
183:
184: Note that this function will trigger the DhcpLeaseAdded or DhcpLeaseUpdated
185: D-Bus signal and will run the configured DHCP lease script accordingly.
186:
187: This function takes many arguments which are the lease parameters:
188: - A string with the textual representation of the IPv4 or IPv6 address of the
189: client.
190:
191: Examples:
192: "192.168.1.115"
193: "1003:1234:abcd::1%eth0"
194: "2001:db8:abcd::1"
195:
196: - A string representing the hardware address of the client, using the same
197: format as the one used in the lease database.
198:
199: Examples:
200:
201: "00:23:45:67:89:ab"
202: "06-00:20:e0:3b:13:af" (token ring)
203:
204: - The hostname of the client, as an array of bytes (so there is no problem
205: with non-ASCII character encoding). May be empty.
206:
207: Example (for "hostname.or.fqdn"):
208: [104, 111, 115, 116, 110, 97, 109, 101, 46, 111, 114, 46, 102, 113, 100, 110]
209:
210: - The client identifier (IPv4) or DUID (IPv6) as an array of bytes. May be
211: empty.
212:
213: Examples:
214:
215: DHCPv6 DUID:
216: [0, 3, 0, 1, 0, 35, 69, 103, 137, 171]
217: DHCPv4 client identifier:
218: [255, 12, 34, 56, 78, 0, 1, 0, 1, 29, 9, 99, 190, 35, 69, 103, 137, 171]
219:
220: - The duration of the lease, in seconds. If the lease is updated, then
221: the duration replaces the previous duration.
222:
223: Example:
224:
225: 7200
226:
227: - The IAID (Identity association identifier) of the DHCPv6 lease, as a network
228: byte-order unsigned integer. For DHCPv4 leases, this must be set to 0.
229:
230: Example (for IPv6):
231:
232: 203569230
233:
234: - A boolean which, if true, indicates that the DHCPv6 lease is for a temporary
235: address (IA_TA). If false, the DHCPv6 lease is for a non-temporary address
236: (IA_NA). For DHCPv4 leases, this must be set to false.
237:
238: RemoveDhcpLease
239: ---------------
240:
241: Returns nothing. Removes a DHCP or DHCPv6 lease to the internal lease
242: database, as if a client sent a release message to abandon a lease.
243:
244: This function takes only one parameter: the text representation of the
245: IPv4 or IPv6 address of the lease to remove.
246:
247: Note that this function will trigger the DhcpLeaseRemoved signal and the
248: configured DHCP lease script will be run with the "del" action.
249:
250: GetMetrics
251: ----------
252:
253: Returns an array with various metrics for DNS and DHCP.
254:
255: GetServerMetrics
256: ----------------
257:
258: Returns per-DNS-server metrics.
259:
260: ClearMetrics
261: ------------
262:
263: Clear call metric counters, global and per-server.
264:
265: 2. SIGNALS
266: ----------
267:
268: If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
269: the DHCP lease database changes. Think of these signals as transactions on
270: a database with the IP address acting as the primary key.
271:
272: Signals are of the form:
273:
274: uk.org.thekelleys.<signal>
275:
276: and their parameters are:
277:
278: STRING "192.168.1.115"
279: STRING "01:23:45:67:89:ab"
280: STRING "hostname.or.fqdn"
281:
282:
283: Available signals are:
284:
285: DhcpLeaseAdded
286: ---------------
287:
288: This signal is emitted when a DHCP lease for a given IP address is created.
289:
290: DhcpLeaseDeleted
291: ----------------
292:
293: This signal is emitted when a DHCP lease for a given IP address is deleted.
294:
295: DhcpLeaseUpdated
296: ----------------
297:
298: This signal is emitted when a DHCP lease for a given IP address is updated.
299:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to DBus-interface CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq / dbus