Annotation of embedaddon/dnsmasq/dbus/DBus-interface, revision 1.1.1.3

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: 
1.1.1.2   misho      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: 
1.1       misho      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: ]
1.1.1.2   misho     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.
1.1       misho     245: 
1.1.1.3 ! misho     246: GetMetrics
        !           247: ----------
        !           248: 
        !           249: Returns an array with various metrics for DNS and DHCP.
1.1       misho     250: 
                    251: 
                    252: 2. SIGNALS
                    253: ----------
                    254: 
                    255: If dnsmasq's DHCP server is active, it will send signals over DBUS whenever
                    256: the DHCP lease database changes. Think of these signals as transactions on
                    257: a database with the IP address acting as the primary key.
                    258: 
                    259: Signals are of the form:
                    260: 
                    261: uk.org.thekelleys.<signal>
                    262: 
                    263: and their parameters are:
                    264: 
                    265: STRING "192.168.1.115"
                    266: STRING "01:23:45:67:89:ab"
                    267: STRING "hostname.or.fqdn"
                    268: 
                    269: 
                    270: Available signals are:
                    271: 
                    272: DhcpLeaseAdded
                    273: ---------------
                    274: 
                    275: This signal is emitted when a DHCP lease for a given IP address is created.
                    276: 
                    277: DhcpLeaseDeleted
                    278: ----------------
                    279: 
                    280: This signal is emitted when a DHCP lease for a given IP address is deleted.
                    281: 
                    282: DhcpLeaseUpdated
                    283: ----------------
                    284: 
                    285: This signal is emitted when a DHCP lease for a given IP address is updated.
                    286:  

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>