blob: 8d578caf75c1d8700262ed37abf625b5e518e2ed [file] [log] [blame]
San Mehatffd68722010-01-20 09:56:15 -08001DBus support must be enabled at compile-time and run-time. Ensure
2that src/config.h contains the line
3
4#define HAVE_DBUS.
5
6and that /etc/dnsmasq.conf contains the line
7
8enable-dbus
9
10Because dnsmasq can operate stand-alone from the DBus, and may need to provide
11service before the dbus daemon is available, it will continue to run
12if the DBus connection is not available at startup. The DBus will be polled
13every 250ms until a connection is established. Start of polling and final
14connection establishment are both logged. When dnsmasq establishes a
15connection to the dbus, it sends the signal "Up". Anything controlling
16the server settings in dnsmasq should re-invoke the SetServers method
17(q.v.) when it sees this signal. This allows dnsmasq to be restarted
18and avoids startup races with the provider of nameserver information.
19
20
21Dnsmasq provides one service on the DBus: uk.org.thekelleys.dnsmasq
22and a single object: /uk/org/thekelleys/dnsmasq
23
241. METHODS
25----------
26
27Methods are of the form
28
29uk.org.thekelleys.<method>
30
31Available methods are:
32
33GetVersion
34----------
35Returns a string containing the version of dnsmasq running.
36
37ClearCache
38----------
39Returns nothing. Clears the domain name cache and re-reads
40/etc/hosts. The same as sending dnsmasq a HUP signal.
41
42SetServers
43----------
44Returns nothing. Takes a set of arguments representing the new
45upstream DNS servers to be used by dnsmasq. IPv4 addresses are
46represented as a UINT32 (in network byte order) and IPv6 addresses
47are represented as sixteen BYTEs (since there is no UINT128 type).
48Each server address may be followed by one or more STRINGS, which are
49the domains for which the preceding server should be used.
50
51Examples.
52
53UINT32: <address1>
54UNIT32: <address2>
55
56is equivalent to
57
58--server=<address1> --server=<address2>
59
60
61UINT32 <address1>
62UINT32 <address2>
63STRING "somedomain.com"
64
65is equivalent to
66
67--server=<address1> --server=/somedomain.com/<address2>
68
69UINT32 <address1>
70UINT32 <address2>
71STRING "somedomain.com"
72UINT32 <address3>
73STRING "anotherdomain.com"
74STRING "thirddomain.com"
75
76is equivalent to
77
78--server=<address1>
79--server=/somedomain.com/<address2>
80--server=/anotherdomain.com/thirddomain.com/<address3>
81
82Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
83so
84
85UINT32: <0.0.0.0>
86STRING "local.domain"
87
88is equivalent to
89
90--local=/local.domain/
91
92
93Each call to SetServers completely replaces the set of servers
94specified by via the DBus, but it leaves any servers specified via the
95command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
96
972. SIGNALS
98----------
99
100If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
101the DHCP lease database changes. Think of these signals as transactions on
102a database with the IP address acting as the primary key.
103
104Signals are of the form:
105
106uk.org.thekelleys.<signal>
107
108and their parameters are:
109
110STRING "192.168.1.115"
111STRING "01:23:45:67:89:ab"
112STRING "hostname.or.fqdn"
113
114
115Available signals are:
116
117DhcpLeaseAdded
118---------------
119
120This signal is emitted when a DHCP lease for a given IP address is created.
121
122DhcpLeaseDeleted
123----------------
124
125This signal is emitted when a DHCP lease for a given IP address is deleted.
126
127DhcpLeaseUpdated
128----------------
129
130This signal is emitted when a DHCP lease for a given IP address is updated.
131