Annotation of embedaddon/dnsmasq/dbus/DBus-interface, revision 1.1.1.2
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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: ]
1.1.1.2 ! misho 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.
1.1 misho 245:
246:
247:
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: ----------------
280:
281: This signal is emitted when a DHCP lease for a given IP address is updated.
282:
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