Sync usage with man page.

[netbsd-mini2440.git] / external / bsd / bind / dist / contrib / dbus / README.DBUS

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