summaryrefslogtreecommitdiffstats
path: root/contrib/dbus/README.DBUS
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/dbus/README.DBUS')
-rw-r--r--contrib/dbus/README.DBUS259
1 files changed, 259 insertions, 0 deletions
diff --git a/contrib/dbus/README.DBUS b/contrib/dbus/README.DBUS
new file mode 100644
index 0000000..8c5c73f
--- /dev/null
+++ b/contrib/dbus/README.DBUS
@@ -0,0 +1,259 @@
+Dynamic Management of the ISC BIND named Forwarding Table with D-BUS
+
+ Jason Vas Dias<jvdias@redhat.com>, Red Hat Inc., May 2005
+
+
+Overview:
+
+ Red Hat has developed an extension to named that is enabled during
+ rpmbuild of the bind SRPM with the option --define 'WITH_DBUS=1',
+ and at named runtime with the -D named option.
+
+ You can obtain the latest version of the source code for the BIND
+ D-BUS extensions from:
+
+ http://people.redhat.com/~jvdias/bind-dbus/
+
+ The Red Hat BIND D-BUS extensions allow services such as Red Hat's
+ NetworkManager and dhcdbd (the DHCP Client controller D-Bus daemon)
+ to tell named which name servers to forward requests to dynamically,
+ instead of only with the "forward" and "forwarders" named.conf options.
+
+ Dynamic forwarding table management allows named to be an effective
+ and efficient caching nameserver for configurations with multiple
+ wireless or VPN IP interfaces that are not always active, and whose
+ name service parameters are typically configured with DHCP.
+
+ Problems with trying to configure such systems automatically using
+ only the libc resolver, causing conflicts over the contents of the
+ /etc/resolv.conf file, are avoided; the resolv.conf file can contain
+ only the users chosen search path and the single "nameserver 127.0.0.1"
+ entry.
+
+ named also provides a much more efficient, both in terms of caching
+ performance and resolving time, and much more feature rich DNS resolver
+ than does the libc resolver library and nscd, and has the benefit of
+ existing improved IPv6 and DNSSEC support over glibc and nscd.
+
+Operation Guide for Developers:
+
+ Programs can access named's dynamic forward table management services
+ using D-BUS, the "service messagebus" sysv-init service that is started
+ by default at boot (see the D-BUS documentation for details).
+
+ When named is started with the -D option (by adding -D to the $OPTIONS
+ variable in /etc/sysconfig/named), named provides two D-BUS methods:
+
+ These D-BUS names are common to all named D-BUS methods:
+ D-BUS Destination D-BUS Path D-BUS interface
+ ~~~~~~~~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~~~~~~
+ com.redhat.named /com/redhat/named com.redhat.named
+
+ D-BUS Members:
+ ~~~~~~~~~~~~~~
+
+ SetForwarders ( { [ string:<domain name>,
+ ~~~~~~~~~~~~~ [ ( uint32:<nameserver IPv4 address>
+ | array of 4 bytes : <nameserver IPv4 address>
+ | array of 16 bytes : <nameserver IPv6 address>
+ | string: <nameserver dotted-quad IPv4 or RFC2374 IPv6 address>
+ )
+ [ uint16: <nameserver port>, ]
+ [ uint8: <forward policy> ]
+ ]
+ ]
+ } , ...
+ )
+
+ SetForwarders will create or delete members of the forwarding table.
+
+ It accepts a list of tuples of up to 4 members: only the <domain name>
+ is required.
+
+ If ONLY the <domain name> is specified, the forwarding entry for
+ EXACTLY that domain name is deleted if it exists.
+
+ Only a specification of at least one <nameserver IP address> is required to
+ create a forwarding entry.
+
+ The IP address can be IPv4:
+ ( 32-bit integer OR array of 4 bytes OR dotted-quad string )
+ Or IPv6:
+ ( array of 16 bytes
+ OR RFC 2373/4 ascii string of 8 ':' separate hex quads as supported by inet_pton(3)
+ )
+
+ 32 and 16-bit integer parameters MUST be given in network byte order; ie the IPv4 address
+ 192.168.2.1 would be specified as uint32:16951488 on an i386 and port 53 would be uint16:13568.
+
+ There are an optional <port> 16-bit integer parameter, to specify the name server socket
+ address port associated with the preceding IP address, and a <forward policy>
+ parameter, which sets the forward policy as follows:
+ 0: "none" : never forward to this nameserver for this domain.
+ 1: "first": forward first to this server, and then search its authoritative data.
+ 2: "only" : always forward to this nameserver for this domain.
+
+ If not specified, <port> will have the value 53, and <forward policy> will be "2": "only".
+ named's default forward policy is "first" .
+
+ Creation of forwarding domains is not "exact", as is deletion, but is "inclusive":
+ creating forwarding entry for the '.' domain sets the default set of nameservers named
+ will query for ALL domains, and creating an entry for "redhat.com" creates a set of
+ nameservers to be queried for all names suffixed by "redhat.com." . If both are specified,
+ the "redhat.com" servers will be tried first, followed by the "." servers.
+
+ Forwarding entries are ONLY created in the first DNS View that matches the "localhost" client
+ (127.0.0.1) and destination. The default view, which exists if no views have been specified
+ in named.conf, matches ALL clients and destinations. If the user has configured views, none
+ of which match the localhost client, then no forwarding will be dynamically configurable.
+ Users are also free to configure a view that matches the localhost, for which forwarding
+ will be dynamically configurable, and other views which do not match the localhost, so that
+ other, remote clients can be served that will not be subject to dynamic forwarding. So it
+ is a fully supported configuration that users can serve authoritative data to external
+ clients and still use named's forwarding features for their localhost resolver.
+
+ SetForwarders returns uint32:0 on success or a DBUS_ERROR message on failure .
+
+
+ GetForwarders ( [ string:<domain name> ] )
+ ~~~~~~~~~~~~~
+ Using the default "com.redhat.named" interface, returns the EXACT forwarding entry for
+ <domain name> as binary D-BUS types; there is also a com.redhat.named.text interface
+ supported by GetForwarders which returns all values as string: text .
+
+ If a <domain name> is not specified, all forwarding table entries are dumped.
+
+
+ Examples:
+ ~~~~~~~~
+
+ Suppose we start out with the named.conf configuration:
+
+
+ options { ...
+ forwarders { 172.16.80.118; };
+ ...
+ };
+
+ zone "redhat.com" {
+ forward only;
+ forwarders { 172.16.76.10; 172.16.52.28; };
+ };
+
+ Using a "dbus-send" trivially modified to support uint16 parameters (!) :
+
+ $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \
+ --dest=com.redhat.named /com/redhat/named com.redhat.named.GetForwarders
+ method return sender=:1.367 -> dest=:1.368
+ 0 string "redhat.com"
+ 1 byte 2
+ 2 uint32 172757164
+ 3 uint16 13568
+ 4 uint32 473174188
+ 5 uint16 13568
+ 6 string "."
+ 7 byte 1
+ 8 uint32 1984958636
+ 9 uint16 13568
+
+ ie. GetForwarders always returns a list of tuples of
+ ( <domain name>, <forward policy>, <ip address>, <port> )
+
+ If the "text" interface was specified:
+
+ $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \
+ --dest=com.redhat.named /com/redhat/named com.redhat.named.text.GetForwarders
+ method return sender=:1.367 -> dest=:1.370
+ 0 string "redhat.com"
+ 1 string "only"
+ 2 string "172.16.76.10"
+ 3 string "53"
+ 4 string "172.16.52.28"
+ 5 string "53"
+ 6 string "."
+ 7 string "first"
+ 8 string "172.16.80.118"
+ 9 string "53"
+
+ So we could set the default nameserver for the root zone as follows:
+
+ $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \
+ --dest=com.redhat.named /com/redhat/named com.redhat.named.SetForwarders \
+ string:'.' string:'192.33.14.30' string:'2001:503:231d::2:30'
+ method return sender=:1.367 -> dest=:1.371
+ 0 uint32 0
+ $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \
+ --dest=com.redhat.named /com/redhat/named com.redhat.named.text.GetForwarders
+ method return sender=:1.367 -> dest=:1.372
+ 0 string "redhat.com"
+ 1 string "only"
+ 2 string "172.16.76.10"
+ 3 string "53"
+ 4 string "172.16.52.28"
+ 5 string "53"
+ 6 string "."
+ 7 string "only"
+ 8 string "192.33.14.30"
+ 9 string "53"
+ 10 string "2001:503:231d::2:30"
+ 11 string "53"
+
+ Using tcpdump one can verify that named will attempt to contact 192.33.14.30, then
+ 2001:503:231d::2:30, for all zones not in redhat.com; for redhat.com zones, 172.16.76.10
+ and 192.33.14.30 will be tried in that order.
+
+ If the D-BUS driver dbus-daemon should shut down, named will emit the syslog message:
+ "D-BUS service disabled."
+ And will retry connecting to D-BUS every 10 seconds - once it has connected, the message:
+ "D-BUS service enabled."
+ will be logged.
+
+ NOTE: there are the "SetForwarders" and "GetForwarders" scripts in the contrib/dbus directory
+ of the BIND source code distribution which are wrappers around the dbus-send commands above.
+ Usage: SetForwarders [ -t first | only ] <zone> [ <server> [...<server>] ]
+ GetForwarders [ <zone> ]
+
+
+ DHCP Integration
+ ~~~~~~~~~~~~~~~~
+
+ With the -D option, named will try to subscribe to dhcdbd, the DHCP Client D-BUS Daemon, to
+ be notified of DHCP "reason", "domain-name", "domain-name-server", "ip-address", and "subnet-mask"
+ DHCP options when the dhclient program has received them from a DHCP server .
+
+ If it cannot subscribe to dhcdbd, named will emit the message :
+ "D-BUS dhcdbd subscription disabled."
+ and will monitor D-BUS "NameOwnerChanged" messages for the appearance of a new owner
+ for "com.redhat.dhcp". When the name is owned, named will send a "com.redhat.dhcp.subscribe.binary"
+ message to dhcdbd to subscribe to the above options for all interfaces (provided by dhcdbd-1.5+),
+ and emit the log message:
+ "D-BUS dhcdbd subscription enabled."
+
+ named will match on signals from the com.redhat.dhcp.subscribe.binary interface for those option
+ settings, and , when the last option is received (indicated by a "reason" of 15: END_OPTIONS), it
+ will configure the forwarding table .
+
+ For each whitespace separated member of "domain-name-servers", AND for the reverse IPv4 in-addr.arpa
+ class C or less domain of the ip-address masked by the subnet-mask, it will create a forwarding entry
+ to query each "domain-server" .
+
+ To support CIDR-based reverse subnet forwarding, Views would have to be configured dynamically, a
+ possible future direction which is not yet implemented. (It would perhaps be easier to add a
+ "match-queries" ACL to the forwarders table).
+
+ When dhclient acquires a lease, named will configure forwarding, and emit the message:
+ "D-BUS: dhclient for interface eth0 acquired new lease - creating forwarders."
+
+ When a lease expires or the interface is brought down (dhclient is stopped with dhcdbd), it
+ will revert any forwarding entries from the initial, static configuration that were modified
+ by the DHCP subscription to their initial values; ie. if redhat.com had a forwarder configured
+ in named.conf, and then an DHCP session specified forwarders for redhat.com, when the DHCP
+ session ends the forwarders for redhat.com are reverted to their named.conf values; thus
+ when all DHCP interfaces have released their leases, and if no SetForwarders commands were issued,
+ the forwarding configuration will be identical to that at named startup.
+
+
+ To Do:
+ - Sending signals when any Forwarding entry is changed (easy to implement if it would be desirable).
+ - CIDR based reverse Forwarding
+
generated by cgit (git 2.34.1) at 2024-04-19 09:16:06 +0000