| DBus support must be enabled at compile-time and run-time. Ensure |
| that src/config.h contains the line |
| |
| #define HAVE_DBUS. |
| |
| and that /etc/dnsmasq.conf contains the line |
| |
| enable-dbus |
| |
| Because dnsmasq can operate stand-alone from the DBus, and may need to provide |
| service before the dbus daemon is available, it will continue to run |
| if the DBus connection is not available at startup. The DBus will be polled |
| every 250ms until a connection is established. Start of polling and final |
| connection establishment are both logged. When dnsmasq establishes a |
| connection to the dbus, it sends the signal "Up". Anything controlling |
| the server settings in dnsmasq should re-invoke the SetServers method |
| (q.v.) when it sees this signal. This allows dnsmasq to be restarted |
| and avoids startup races with the provider of nameserver information. |
| |
| |
| Dnsmasq provides one service on the DBus: uk.org.thekelleys.dnsmasq |
| and a single object: /uk/org/thekelleys/dnsmasq |
| The name of the service may be changed by giving an argument to --enable-dbus. |
| |
| 1. METHODS |
| ---------- |
| |
| Methods are of the form |
| |
| uk.org.thekelleys.<method> |
| |
| Available methods are: |
| |
| GetVersion |
| ---------- |
| Returns a string containing the version of dnsmasq running. |
| |
| ClearCache |
| ---------- |
| Returns nothing. Clears the domain name cache and re-reads |
| /etc/hosts. The same as sending dnsmasq a HUP signal. |
| |
| SetServers |
| ---------- |
| Returns nothing. Takes a set of arguments representing the new |
| upstream DNS servers to be used by dnsmasq. IPv4 addresses are |
| represented as a UINT32 (in network byte order) and IPv6 addresses |
| are represented as sixteen BYTEs (since there is no UINT128 type). |
| Each server address may be followed by one or more STRINGS, which are |
| the domains for which the preceding server should be used. |
| |
| Examples. |
| |
| UINT32: <address1> |
| UNIT32: <address2> |
| |
| is equivalent to |
| |
| --server=<address1> --server=<address2> |
| |
| |
| UINT32 <address1> |
| UINT32 <address2> |
| STRING "somedomain.com" |
| |
| is equivalent to |
| |
| --server=<address1> --server=/somedomain.com/<address2> |
| |
| UINT32 <address1> |
| UINT32 <address2> |
| STRING "somedomain.com" |
| UINT32 <address3> |
| STRING "anotherdomain.com" |
| STRING "thirddomain.com" |
| |
| is equivalent to |
| |
| --server=<address1> |
| --server=/somedomain.com/<address2> |
| --server=/anotherdomain.com/thirddomain.com/<address3> |
| |
| Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only", |
| so |
| |
| UINT32: <0.0.0.0> |
| STRING "local.domain" |
| |
| is equivalent to |
| |
| --local=/local.domain/ |
| |
| |
| Each call to SetServers completely replaces the set of servers |
| specified by via the DBus, but it leaves any servers specified via the |
| command line or /etc/dnsmasq.conf or /etc/resolv.conf alone. |
| |
| SetServersEx |
| ------------ |
| |
| This function is more flexible and the SetServers function, in that it can |
| handle address scoping, port numbers, and is easier for clients to use. |
| |
| Returns nothing. Takes a set of arguments representing the new |
| upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6) |
| are represented as STRINGS. Each server address may be followed by one or more |
| STRINGS, which are the domains for which the preceding server should be used. |
| |
| This function takes an array of STRING arrays, where each inner array represents |
| a set of DNS servers and domains for which those servers may be used. Each |
| string represents a list of upstream DNS servers first, and domains second. |
| Mixing of domains and servers within a the string array is not allowed. |
| |
| Examples. |
| |
| [ |
| ["1.2.3.4", "foobar.com"], |
| ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"] |
| ] |
| |
| is equivalent to |
| |
| --server=/foobar.com/1.2.3.4 \ |
| --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0 |
| |
| An IPv4 address of 0.0.0.0 is interpreted as "no address, local only", |
| so |
| |
| [ ["0.0.0.0", "local.domain"] ] |
| |
| is equivalent to |
| |
| --local=/local.domain/ |
| |
| |
| Each call to SetServersEx completely replaces the set of servers |
| specified by via the DBus, but it leaves any servers specified via the |
| command line or /etc/dnsmasq.conf or /etc/resolv.conf alone. |
| |
| |
| SetDomainServers |
| ---------------- |
| |
| Yes another variation for setting DNS servers, with the capability of |
| SetServersEx, but without using arrays of arrays, which are not |
| sendable with dbus-send. The arguments are an array of strings which |
| are identical to the equivalent arguments --server, so the example |
| for SetServersEx is represented as |
| |
| [ |
| "/foobar.com/1.2.3.4" |
| "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0" |
| ] |
| |
| |
| |
| 2. SIGNALS |
| ---------- |
| |
| If dnsmasq's DHCP server is active, it will send signals over DBUS whenever |
| the DHCP lease database changes. Think of these signals as transactions on |
| a database with the IP address acting as the primary key. |
| |
| Signals are of the form: |
| |
| uk.org.thekelleys.<signal> |
| |
| and their parameters are: |
| |
| STRING "192.168.1.115" |
| STRING "01:23:45:67:89:ab" |
| STRING "hostname.or.fqdn" |
| |
| |
| Available signals are: |
| |
| DhcpLeaseAdded |
| --------------- |
| |
| This signal is emitted when a DHCP lease for a given IP address is created. |
| |
| DhcpLeaseDeleted |
| ---------------- |
| |
| This signal is emitted when a DHCP lease for a given IP address is deleted. |
| |
| DhcpLeaseUpdated |
| ---------------- |
| |
| This signal is emitted when a DHCP lease for a given IP address is updated. |
| |