dbus/DBus-interface

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

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.

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.