1Dynamic Management of the ISC BIND named Forwarding Table with D-BUS 2 3 Jason Vas Dias<jvdias@redhat.com>, Red Hat Inc., May 2005 4 5 6Overview: 7 8 Red Hat has developed an extension to named that is enabled during 9 rpmbuild of the bind SRPM with the option --define 'WITH_DBUS=1', 10 and at named runtime with the -D named option. 11 12 You can obtain the latest version of the source code for the BIND 13 D-BUS extensions from: 14 15 http://people.redhat.com/~jvdias/bind-dbus/ 16 17 The Red Hat BIND D-BUS extensions allow services such as Red Hat's 18 NetworkManager and dhcdbd (the DHCP Client controller D-Bus daemon) 19 to tell named which name servers to forward requests to dynamically, 20 instead of only with the "forward" and "forwarders" named.conf options. 21 22 Dynamic forwarding table management allows named to be an effective 23 and efficient caching nameserver for configurations with multiple 24 wireless or VPN IP interfaces that are not always active, and whose 25 name service parameters are typically configured with DHCP. 26 27 Problems with trying to configure such systems automatically using 28 only the libc resolver, causing conflicts over the contents of the 29 /etc/resolv.conf file, are avoided; the resolv.conf file can contain 30 only the users chosen search path and the single "nameserver 127.0.0.1" 31 entry. 32 33 named also provides a much more efficient, both in terms of caching 34 performance and resolving time, and much more feature rich DNS resolver 35 than does the libc resolver library and nscd, and has the benefit of 36 existing improved IPv6 and DNSSEC support over glibc and nscd. 37 38Operation Guide for Developers: 39 40 Programs can access named's dynamic forward table management services 41 using D-BUS, the "service messagebus" sysv-init service that is started 42 by default at boot (see the D-BUS documentation for details). 43 44 When named is started with the -D option (by adding -D to the $OPTIONS 45 variable in /etc/sysconfig/named), named provides two D-BUS methods: 46 47 These D-BUS names are common to all named D-BUS methods: 48 D-BUS Destination D-BUS Path D-BUS interface 49 ~~~~~~~~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~~~~~~ 50 com.redhat.named /com/redhat/named com.redhat.named 51 52 D-BUS Members: 53 ~~~~~~~~~~~~~~ 54 55 SetForwarders ( { [ string:<domain name>, 56 ~~~~~~~~~~~~~ [ ( uint32:<nameserver IPv4 address> 57 | array of 4 bytes : <nameserver IPv4 address> 58 | array of 16 bytes : <nameserver IPv6 address> 59 | string: <nameserver dotted-quad IPv4 or RFC2374 IPv6 address> 60 ) 61 [ uint16: <nameserver port>, ] 62 [ uint8: <forward policy> ] 63 ] 64 ] 65 } , ... 66 ) 67 68 SetForwarders will create or delete members of the forwarding table. 69 70 It accepts a list of tuples of up to 4 members: only the <domain name> 71 is required. 72 73 If ONLY the <domain name> is specified, the forwarding entry for 74 EXACTLY that domain name is deleted if it exists. 75 76 Only a specification of at least one <nameserver IP address> is required to 77 create a forwarding entry. 78 79 The IP address can be IPv4: 80 ( 32-bit integer OR array of 4 bytes OR dotted-quad string ) 81 Or IPv6: 82 ( array of 16 bytes 83 OR RFC 2373/4 ascii string of 8 ':' separate hex quads as supported by inet_pton(3) 84 ) 85 86 32 and 16-bit integer parameters MUST be given in network byte order; ie the IPv4 address 87 192.168.2.1 would be specified as uint32:16951488 on an i386 and port 53 would be uint16:13568. 88 89 There are an optional <port> 16-bit integer parameter, to specify the name server socket 90 address port associated with the preceding IP address, and a <forward policy> 91 parameter, which sets the forward policy as follows: 92 0: "none" : never forward to this nameserver for this domain. 93 1: "first": forward first to this server, and then search its authoritative data. 94 2: "only" : always forward to this nameserver for this domain. 95 96 If not specified, <port> will have the value 53, and <forward policy> will be "2": "only". 97 named's default forward policy is "first" . 98 99 Creation of forwarding domains is not "exact", as is deletion, but is "inclusive": 100 creating forwarding entry for the '.' domain sets the default set of nameservers named 101 will query for ALL domains, and creating an entry for "redhat.com" creates a set of 102 nameservers to be queried for all names suffixed by "redhat.com." . If both are specified, 103 the "redhat.com" servers will be tried first, followed by the "." servers. 104 105 Forwarding entries are ONLY created in the first DNS View that matches the "localhost" client 106 (127.0.0.1) and destination. The default view, which exists if no views have been specified 107 in named.conf, matches ALL clients and destinations. If the user has configured views, none 108 of which match the localhost client, then no forwarding will be dynamically configurable. 109 Users are also free to configure a view that matches the localhost, for which forwarding 110 will be dynamically configurable, and other views which do not match the localhost, so that 111 other, remote clients can be served that will not be subject to dynamic forwarding. So it 112 is a fully supported configuration that users can serve authoritative data to external 113 clients and still use named's forwarding features for their localhost resolver. 114 115 SetForwarders returns uint32:0 on success or a DBUS_ERROR message on failure . 116 117 118 GetForwarders ( [ string:<domain name> ] ) 119 ~~~~~~~~~~~~~ 120 Using the default "com.redhat.named" interface, returns the EXACT forwarding entry for 121 <domain name> as binary D-BUS types; there is also a com.redhat.named.text interface 122 supported by GetForwarders which returns all values as string: text . 123 124 If a <domain name> is not specified, all forwarding table entries are dumped. 125 126 127 Examples: 128 ~~~~~~~~ 129 130 Suppose we start out with the named.conf configuration: 131 132 133 options { ... 134 forwarders { 172.16.80.118; }; 135 ... 136 }; 137 138 zone "redhat.com" { 139 forward only; 140 forwarders { 172.16.76.10; 172.16.52.28; }; 141 }; 142 143 Using a "dbus-send" trivially modified to support uint16 parameters (!) : 144 145 $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \ 146 --dest=com.redhat.named /com/redhat/named com.redhat.named.GetForwarders 147 method return sender=:1.367 -> dest=:1.368 148 0 string "redhat.com" 149 1 byte 2 150 2 uint32 172757164 151 3 uint16 13568 152 4 uint32 473174188 153 5 uint16 13568 154 6 string "." 155 7 byte 1 156 8 uint32 1984958636 157 9 uint16 13568 158 159 ie. GetForwarders always returns a list of tuples of 160 ( <domain name>, <forward policy>, <ip address>, <port> ) 161 162 If the "text" interface was specified: 163 164 $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \ 165 --dest=com.redhat.named /com/redhat/named com.redhat.named.text.GetForwarders 166 method return sender=:1.367 -> dest=:1.370 167 0 string "redhat.com" 168 1 string "only" 169 2 string "172.16.76.10" 170 3 string "53" 171 4 string "172.16.52.28" 172 5 string "53" 173 6 string "." 174 7 string "first" 175 8 string "172.16.80.118" 176 9 string "53" 177 178 So we could set the default nameserver for the root zone as follows: 179 180 $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \ 181 --dest=com.redhat.named /com/redhat/named com.redhat.named.SetForwarders \ 182 string:'.' string:'192.33.14.30' string:'2001:503:231d::2:30' 183 method return sender=:1.367 -> dest=:1.371 184 0 uint32 0 185 $ dbus-send --system --type=method_call --print-reply --reply-timeout=20000 \ 186 --dest=com.redhat.named /com/redhat/named com.redhat.named.text.GetForwarders 187 method return sender=:1.367 -> dest=:1.372 188 0 string "redhat.com" 189 1 string "only" 190 2 string "172.16.76.10" 191 3 string "53" 192 4 string "172.16.52.28" 193 5 string "53" 194 6 string "." 195 7 string "only" 196 8 string "192.33.14.30" 197 9 string "53" 198 10 string "2001:503:231d::2:30" 199 11 string "53" 200 201 Using tcpdump one can verify that named will attempt to contact 192.33.14.30, then 202 2001:503:231d::2:30, for all zones not in redhat.com; for redhat.com zones, 172.16.76.10 203 and 192.33.14.30 will be tried in that order. 204 205 If the D-BUS driver dbus-daemon should shut down, named will emit the syslog message: 206 "D-BUS service disabled." 207 And will retry connecting to D-BUS every 10 seconds - once it has connected, the message: 208 "D-BUS service enabled." 209 will be logged. 210 211 NOTE: there are the "SetForwarders" and "GetForwarders" scripts in the contrib/dbus directory 212 of the BIND source code distribution which are wrappers around the dbus-send commands above. 213 Usage: SetForwarders [ -t first | only ] <zone> [ <server> [...<server>] ] 214 GetForwarders [ <zone> ] 215 216 217 DHCP Integration 218 ~~~~~~~~~~~~~~~~ 219 220 With the -D option, named will try to subscribe to dhcdbd, the DHCP Client D-BUS Daemon, to 221 be notified of DHCP "reason", "domain-name", "domain-name-server", "ip-address", and "subnet-mask" 222 DHCP options when the dhclient program has received them from a DHCP server . 223 224 If it cannot subscribe to dhcdbd, named will emit the message : 225 "D-BUS dhcdbd subscription disabled." 226 and will monitor D-BUS "NameOwnerChanged" messages for the appearance of a new owner 227 for "com.redhat.dhcp". When the name is owned, named will send a "com.redhat.dhcp.subscribe.binary" 228 message to dhcdbd to subscribe to the above options for all interfaces (provided by dhcdbd-1.5+), 229 and emit the log message: 230 "D-BUS dhcdbd subscription enabled." 231 232 named will match on signals from the com.redhat.dhcp.subscribe.binary interface for those option 233 settings, and , when the last option is received (indicated by a "reason" of 15: END_OPTIONS), it 234 will configure the forwarding table . 235 236 For each whitespace separated member of "domain-name-servers", AND for the reverse IPv4 in-addr.arpa 237 class C or less domain of the ip-address masked by the subnet-mask, it will create a forwarding entry 238 to query each "domain-server" . 239 240 To support CIDR-based reverse subnet forwarding, Views would have to be configured dynamically, a 241 possible future direction which is not yet implemented. (It would perhaps be easier to add a 242 "match-queries" ACL to the forwarders table). 243 244 When dhclient acquires a lease, named will configure forwarding, and emit the message: 245 "D-BUS: dhclient for interface eth0 acquired new lease - creating forwarders." 246 247 When a lease expires or the interface is brought down (dhclient is stopped with dhcdbd), it 248 will revert any forwarding entries from the initial, static configuration that were modified 249 by the DHCP subscription to their initial values; ie. if redhat.com had a forwarder configured 250 in named.conf, and then an DHCP session specified forwarders for redhat.com, when the DHCP 251 session ends the forwarders for redhat.com are reverted to their named.conf values; thus 252 when all DHCP interfaces have released their leases, and if no SetForwarders commands were issued, 253 the forwarding configuration will be identical to that at named startup. 254 255 256 To Do: 257 - Sending signals when any Forwarding entry is changed (easy to implement if it would be desirable). 258 - CIDR based reverse Forwarding 259 260