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: 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:
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:
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:
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:
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:
246: GetMetrics
247: ----------
248:
249: Returns an array with various metrics for DNS and DHCP.
250:
251:
252: 2. SIGNALS
253: ----------
254:
255: If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
256: the DHCP lease database changes. Think of these signals as transactions on
257: a database with the IP address acting as the primary key.
258:
259: Signals are of the form:
260:
261: uk.org.thekelleys.<signal>
262:
263: and their parameters are:
264:
265: STRING "192.168.1.115"
266: STRING "01:23:45:67:89:ab"
267: STRING "hostname.or.fqdn"
268:
269:
270: Available signals are:
271:
272: DhcpLeaseAdded
273: ---------------
274:
275: This signal is emitted when a DHCP lease for a given IP address is created.
276:
277: DhcpLeaseDeleted
278: ----------------
279:
280: This signal is emitted when a DHCP lease for a given IP address is deleted.
281:
282: DhcpLeaseUpdated
283: ----------------
284:
285: This signal is emitted when a DHCP lease for a given IP address is updated.
286:
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