Annotation of embedaddon/dnsmasq/dbus/DBus-interface, revision 1.1
1.1 ! misho 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to DBus-interface CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dnsmasq / dbus