Return to DBus-interface CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq / dbus

dnsmasq

    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: