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 SetLocaliseQueriesOption
  52 ------------------------
  53 Takes boolean, sets or resets the --localise-queries option.
  54
  55 SetServers
  56 ----------
  57 Returns nothing. Takes a set of arguments representing the new
  58 upstream DNS servers to be used by dnsmasq. IPv4 addresses are
  59 represented as a UINT32 (in network byte order) and IPv6 addresses
  60 are represented as sixteen BYTEs (since there is no UINT128 type).
  61 Each server address may be followed by one or more STRINGS, which are
  62 the domains for which the preceding server should be used.
  63
  64 Examples.
  65
  66 UINT32: <address1>
  67 UNIT32: <address2>
  68
  69 is equivalent to
  70
  71 --server=<address1> --server=<address2>
  72
  73
  74 UINT32 <address1>
  75 UINT32 <address2>
  76 STRING "somedomain.com"
  77
  78 is equivalent to
  79
  80 --server=<address1> --server=/somedomain.com/<address2>
  81
  82 UINT32 <address1>
  83 UINT32 <address2>
  84 STRING "somedomain.com"
  85 UINT32 <address3>
  86 STRING "anotherdomain.com"
  87 STRING "thirddomain.com"
  88
  89 is equivalent to
  90
  91 --server=<address1>
  92 --server=/somedomain.com/<address2>
  93 --server=/anotherdomain.com/thirddomain.com/<address3>
  94
  95 Am IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
  96 so
  97
  98 UINT32: <0.0.0.0>
  99 STRING  "local.domain"
 100
 101 is equivalent to
 102
 103 --local=/local.domain/
 104
 105
 106 Each call to SetServers completely replaces the set of servers
 107 specified by via the DBus, but it leaves any servers specified via the
 108 command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
 109
 110 SetServersEx
 111 ------------
 112
 113 This function is more flexible and the SetServers function, in that it can
 114 handle address scoping, port numbers, and is easier for clients to use.
 115
 116 Returns nothing. Takes a set of arguments representing the new
 117 upstream DNS servers to be used by dnsmasq. All addresses (both IPv4 and IPv6)
 118 are represented as STRINGS.  Each server address may be followed by one or more
 119 STRINGS, which are the domains for which the preceding server should be used.
 120
 121 This function takes an array of STRING arrays, where each inner array represents
 122 a set of DNS servers and domains for which those servers may be used.  Each
 123 string represents a list of upstream DNS servers first, and domains second.
 124 Mixing of domains and servers within a the string array is not allowed.
 125
 126 Examples.
 127
 128 [
 129   ["1.2.3.4", "foobar.com"],
 130   ["1003:1234:abcd::1%eth0", "eng.mycorp.com", "lab.mycorp.com"]
 131 ]
 132
 133 is equivalent to
 134
 135 --server=/foobar.com/1.2.3.4 \
 136   --server=/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0
 137
 138 An IPv4 address of 0.0.0.0 is interpreted as "no address, local only",
 139 so
 140
 141 [ ["0.0.0.0", "local.domain"] ]
 142
 143 is equivalent to
 144
 145 --local=/local.domain/
 146
 147
 148 Each call to SetServersEx completely replaces the set of servers
 149 specified by via the DBus, but it leaves any servers specified via the
 150 command line or /etc/dnsmasq.conf or /etc/resolv.conf alone.
 151
 152
 153 SetDomainServers
 154 ----------------
 155
 156 Yes another variation for setting DNS servers, with the capability of
 157 SetServersEx, but without using arrays of arrays, which are not
 158 sendable with dbus-send. The arguments are an array of strings which
 159 are identical to the equivalent arguments --server, so the example
 160 for SetServersEx is represented as
 161
 162 [
 163   "/foobar.com/1.2.3.4"
 164   "/eng.mycorp.com/lab.mycorp.com/1003:1234:abcd::1%eth0"
 165 ]
 166
 167 GetLoopServers
 168 --------------
 169
 170 (Only available if dnsmasq compiled with HAVE_LOOP)
 171
 172 Return an array of strings, each string is the IP address of an upstream
 173 server which has been found to loop queries back to this dnsmasq instance, and
 174 it therefore not being used.
 175
 176 AddDhcpLease
 177 ------------
 178
 179 Returns nothing. Adds or updates a DHCP or DHCPv6 lease to the internal lease
 180 database, as if a client requested and obtained a lease.
 181
 182 If a lease for the IPv4 or IPv6 address already exist, it is overwritten.
 183
 184 Note that this function will trigger the DhcpLeaseAdded or DhcpLeaseUpdated
 185 D-Bus signal and will run the configured DHCP lease script accordingly.
 186
 187 This function takes many arguments which are the lease parameters:
 188 - A string with the textual representation of the IPv4 or IPv6 address of the
 189   client.
 190
 191   Examples:
 192   "192.168.1.115"
 193   "1003:1234:abcd::1%eth0"
 194   "2001:db8:abcd::1"
 195
 196 - A string representing the hardware address of the client, using the same
 197   format as the one used in the lease database.
 198
 199   Examples:
 200
 201   "00:23:45:67:89:ab"
 202   "06-00:20:e0:3b:13:af" (token ring)
 203
 204 - The hostname of the client, as an array of bytes (so there is no problem
 205   with non-ASCII character encoding). May be empty.
 206
 207   Example (for "hostname.or.fqdn"):
 208   [104, 111, 115, 116, 110, 97, 109, 101, 46, 111, 114, 46, 102, 113, 100, 110]
 209
 210 - The client identifier (IPv4) or DUID (IPv6) as an array of bytes. May be
 211   empty.
 212
 213   Examples:
 214
 215   DHCPv6 DUID:
 216   [0, 3, 0, 1, 0, 35, 69, 103, 137, 171]
 217   DHCPv4 client identifier:
 218   [255, 12, 34, 56, 78, 0, 1, 0, 1, 29, 9, 99, 190, 35, 69, 103, 137, 171]
 219
 220 - The duration of the lease, in seconds. If the lease is updated, then
 221   the duration replaces the previous duration.
 222
 223   Example:
 224
 225   7200
 226
 227 - The IAID (Identity association identifier) of the DHCPv6 lease, as a network
 228   byte-order unsigned integer. For DHCPv4 leases, this must be set to 0.
 229
 230   Example (for IPv6):
 231
 232   203569230
 233
 234 - A boolean which, if true, indicates that the DHCPv6 lease is for a temporary
 235   address (IA_TA). If false, the DHCPv6 lease is for a non-temporary address
 236   (IA_NA). For DHCPv4 leases, this must be set to false.
 237
 238 RemoveDhcpLease
 239 ---------------
 240
 241 Returns nothing. Removes a DHCP or DHCPv6 lease to the internal lease
 242 database, as if a client sent a release message to abandon a lease.
 243
 244 This function takes only one parameter: the text representation of the
 245 IPv4 or IPv6 address of the lease to remove.
 246
 247 Note that this function will trigger the DhcpLeaseRemoved signal and the
 248 configured DHCP lease script will be run with the "del" action.
 249
 250 GetMetrics
 251 ----------
 252
 253 Returns an array with various metrics for DNS and DHCP.
 254
 255 GetServerMetrics
 256 ----------------
 257
 258 Returns per-DNS-server metrics.
 259
 260 ClearMetrics
 261 ------------
 262
 263 Clear call metric counters, global and per-server.
 264
 265 2. SIGNALS
 266 ----------
 267
 268 If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
 269 the DHCP lease database changes. Think of these signals as transactions on
 270 a database with the IP address acting as the primary key.
 271
 272 Signals are of the form:
 273
 274 uk.org.thekelleys.<signal>
 275
 276 and their parameters are:
 277
 278 STRING "192.168.1.115"
 279 STRING "01:23:45:67:89:ab"
 280 STRING "hostname.or.fqdn"
 281
 282
 283 Available signals are:
 284
 285 DhcpLeaseAdded
 286 ---------------
 287
 288 This signal is emitted when a DHCP lease for a given IP address is created.
 289
 290 DhcpLeaseDeleted
 291 ----------------
 292
 293 This signal is emitted when a DHCP lease for a given IP address is deleted.
 294
 295 DhcpLeaseUpdated
 296 ----------------
 297
 298 This signal is emitted when a DHCP lease for a given IP address is updated.
 299