release/src/router/dnsmasq/dbus/DBus-interface

   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 SetServers
  44 ----------
  45 Returns nothing. Takes a set of arguments representing the new
  46 upstream DNS servers to be used by dnsmasq. IPv4 addresses are
  47 represented as a UINT32 (in network byte order) and IPv6 addresses
  48 are represented as sixteen BYTEs (since there is no UINT128 type).
  49 Each server address may be followed by one or more STRINGS, which are
  50 the domains for which the preceding server should be used.
  51
  52 Examples.
  53
  54 UINT32: <address1>
  55 UNIT32: <address2>
  56
  57 is equivalent to
  58
  59 --server=<address1> --server=<address2>
  60
  61
  62 UINT32 <address1>
  63 UINT32 <address2>
  64 STRING "somedomain.com"
  65
  66 is equivalent to
  67
  68 --server=<address1> --server=/somedomain.com/<address2>
  69
  70 UINT32 <address1>
  71 UINT32 <address2>
  72 STRING "somedomain.com"
  73 UINT32 <address3>
  74 STRING "anotherdomain.com"
  75 STRING "thirddomain.com"
  76
  77 is equivalent to
  78
  79 --server=<address1>
  80 --server=/somedomain.com/<address2>
  81 --server=/anotherdomain.com/thirddomain.com/<address3>
  82
  83 Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
  84 so
  85
  86 UINT32: <0.0.0.0>
  87 STRING  "local.domain"
  88
  89 is equivalent to
  90
  91 --local=/local.domain/
  92
  93
  94 Each call to SetServers completely replaces the set of servers
  95 specified by via the DBus, but it leaves any servers specified via the
  96 command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
  97
  98 SetServersEx
  99 ------------
 100
 101 This function is more flexible and the SetServers function, in that it can
 102 handle address scoping, port numbers, and is easier for clients to use.
 103
 104 Returns nothing. Takes a set of arguments representing the new
 105 upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6)
 106 are represented as STRINGS.  Each server address may be followed by one or more
 107 STRINGS, which are the domains for which the preceding server should be used.
 108
 109 This function takes an array of STRING arrays, where each inner array represents
 110 a set of DNS servers and domains for which those servers may be used.  Each
 111 string represents a list of upstream DNS servers first, and domains second.
 112 Mixing of domains and servers within a the string array is not allowed.
 113
 114 Examples.
 115
 116 [
 117   ["1.2.3.4", "foobar.com"],
 118   ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"]
 119 ]
 120
 121 is equivalent to
 122
 123 --server=/foobar.com/1.2.3.4 \
 124   --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0
 125
 126 An IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
 127 so
 128
 129 [ ["0.0.0.0", "local.domain"] ]
 130
 131 is equivalent to
 132
 133 --local=/local.domain/
 134
 135
 136 Each call to SetServersEx completely replaces the set of servers
 137 specified by via the DBus, but it leaves any servers specified via the
 138 command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
 139
 140
 141 SetDomainServers
 142 ----------------
 143
 144 Yes another variation for setting DNS servers, with the capability of
 145 SetServersEx, but without using arrays of arrays, which are not
 146 sendable with dbus-send. The arguments are an array of strings which
 147 are identical to the equivalent arguments --server, so the example
 148 for SetServersEx is represented as
 149
 150 [
 151   "/foobar.com/1.2.3.4"
 152   "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0"
 153 ]
 154
 155
 156
 157 2. SIGNALS
 158 ----------
 159
 160 If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
 161 the DHCP lease database changes. Think of these signals as transactions on
 162 a database with the IP address acting as the primary key.
 163
 164 Signals are of the form:
 165
 166 uk.org.thekelleys.<signal>
 167
 168 and their parameters are:
 169
 170 STRING "192.168.1.115"
 171 STRING "01:23:45:67:89:ab"
 172 STRING "hostname.or.fqdn"
 173
 174
 175 Available signals are:
 176
 177 DhcpLeaseAdded
 178 ---------------
 179
 180 This signal is emitted when a DHCP lease for a given IP address is created.
 181
 182 DhcpLeaseDeleted
 183 ----------------
 184
 185 This signal is emitted when a DHCP lease for a given IP address is deleted.
 186
 187 DhcpLeaseUpdated
 188 ----------------
 189
 190 This signal is emitted when a DHCP lease for a given IP address is updated.
 191