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 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
  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 ]
 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.
 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