Installing the upgrade

The following instructions explain how to install the 3-DNS Controller, version 2.1.2 onto existing systems running version 2.0 or later.

Important:  If you are running 3-DNS Controller version 1.0.6 or earlier, you must first upgrade to version 2.0.1.  You can then upgrade to version 2.1.2.

1. Connect to the F5 Networks FTP site at ftp.f5.com. To find out how to download software from the F5 FTP site, see SOL167: Downloading software from F5 Networks and follow the instructions for using the F5 Networks FTP site.
   
   
2. Download the upgrade file to the /var/tmp/ directory on the target 3-DNS Controller.
• For controllers that use encrypted communications, download the 3dns212domkit.f5.tar file.
• For controllers that do not use encrypted communications, download the 3dns212intkit.f5.tar file.
  
3. Change to the /var/tmp/ directory:

   cd /var/tmp/

4. Verify the integrity of the file by typing the sum command:

   sum <file name>

   Note that the sum file, which is available on the FTP site, provides the checksum numbers for the upgrade files.

5. Extract the kit file in the /var/tmp/ directory:
   
   
   • For controllers that use encrypted communications, type the following command:

     tar -xvf 3dns212domkit.f5.tar

   • For controllers that do not use encrypted communications, type the following command:

     tar -xvf 3dns212intkit.f5.tar

6. Verify the integrity of each extracted file by typing the following command:

   ./checksum

7. Run the upgrade_install script in the /var/tmp/ directory:

   ./upgrade_install

   • If you are upgrading from a BETA version of 3-DNS Controller, version 2.1.2 you must add the -f switch to the ./upgrade_install command, in the following format:

     ./upgrade_install -f

   • If you are upgrading from version 2.0 or 2.0.1, after the upgrade_install script completes, the 3-DNS Controller prompts you to enter configuration information for the 3-DNS web server, for NameSurfer™ (an integrated DNS zone file management application), and for NTP (Network Time Protocol).
     
     
8. The upgrade_install script checks whether you have already configured NTP support.  If you have not, a screen appears, giving you the option to configure NTP support, disable NTP support, or leave NTP support unchanged.

   If you do not wish to synchronize your system time to a public time server, select Do Not Change NTP Settings, and exit the NTP configuration screen.

   If you wish to configure NTP support, select Configure NTP Support, and the screen presents a list of available public clock servers, based on your time zone setting.  Either use the space bar to select one or more of the servers, or type the host name or IP address of one or more servers next to the Clock Servers command, which appears after the list of time servers.

   Note:   If you already have NTP configured, you can change the configuration by running config_ntpclocks from the command line.

9. Restart the 3-DNS Controller.

   reboot

10. Once you install the 3-DNS Controller software, you need to install the new version of the big3d agent on all BIG-IP Controllers managed by the 3-DNS Controller, as follows.
    
    
    1. Log in to the 3-DNS Controller.
       
       
    2. Type 3dnsmaint to open the 3-DNS Maintenance Menu.
       
       
    3. Select Install and Start big3d, and press Enter.
       The 3-DNS Controller detects all BIG-IP^® Controllers in the network and updates their big3d agents.
       
       
    4. Press Enter to return to the 3-DNS Maintenance Menu.
       
       
    5. Press Q to quit.

Once you install the software update, refer to the Configuring and using the new software section, which contains important information about required configuration changes and new configuration options.

What's new in this version

New features and enhancements

• Geographic load balancing
  The version of the 3-DNS Controller that supports encrypted communications now contains a classifier that maps IP addresses to geographic locations.  The controller uses this mapping to resolve DNS requests to the geographically closest server.  With this classifier, the 3-DNS Controller can perform topology-based load balancing among wide IP pools or within a pool.

  For updated information on how to set up topology load balancing, please review Setting up topology-based features.

  For information on how to configure topology using the Configuration utility, view the online help for the Manage Topology Records screen.

  For information on how to configure topology in the wideip.conf file, see the Geographic load balancing section in Optional configuration changes.

• Name server load balancing
  You can now use dynamic delegation to redirect name resolution requests to third-party DNS servers.  You can also use dynamic delegation to distribute DNS resolutions between an origin site and a content delivery network (CDN).

  For information on how to configure dynamic delegation using the Configuration utility, view the online help for the Configure Load Balancing for New Pool screen.

  For information on how to configure dynamic delegation in the wideip.conf file, see the Name server load balancing section in Optional configuration changes.

• KBPS load balancing
  A new load balancing mode, KBPS, is now available for wide IPs, BIG-IP Controllers, and hosts.  This mode allows you to set up load balancing based on throughput, in kilobytes per second.  You can configure KBPS as a load balancing mode for pools, and you can also configure the KBPS factor in Quality of Service (QOS) load balancing.

  For information on how to configure this option using the Configuration utility, view the online help for the Configure Load Balancing for New Pool screen.

  For information on how to configure this option in the wideip.conf file, see the KBPS load balancing section in Optional configuration changes.

• Limit checks for availability
  When you set limit checks for availability, the 3-DNS Controller can detect when a managed server or virtual server (VS) is low on system resources, such as CPU, disk, memory, or network bandwidth, and redirect the traffic to another VS.  Setting limits helps eliminate any negative impact on a virtual server's performance of service tasks that may be time critical, require high bandwidth, or put high demand on system resources.

  For information on how to configure this option using the Configuration utility, view the online help for the Modify Limit Settings screens for BIG-IP Controllers, 3-DNS Controllers, and hosts.

  For information on how to configure this option in the wideip.conf file, see the Limit checks for availability section in Optional configuration changes.

• Last resort pool
  The wide IP pool you designate as the last resort pool, in the Configure Load Balancing for New Pool screen, is the virtual server pool that the 3-DNS Controller uses when all other pools have reached their thresholds or are unavailable for any reason.  When your network includes cache appliances hosting content from an origin site, you can designate the origin site as the last resort pool to handle requests if your cache virtual servers have reached their thresholds. You can also use the last resort pool to designate an overflow network so your origin servers remain available if network traffic spikes.

   

  Note:  The 3-DNS Controller only recognizes one last resort pool.  Therefore, if you have designated more than one wide IP pool as the last resort pool, the pool you set most recently is the last resort pool the controller recognizes.

  For information on how to configure this option using the Configuration utility, view the online help for the Configure Load Balancing for New Pool screen.

  For information on how to configure this option in the wideip.conf file, see the Last resort pool section in Optional configuration changes.

• Custom port discovery
  You can now specify a port discovery method when you use TCP probing.  The three port discovery methods are short, wks, and all.  The short discovery method scans only those ports you have included in a predefined port list.  The wks discovery method scans the ports associated with well-known network services, such as port 443 for HTTPS.  The all discovery method scans all the ports in the short and wks lists.

  For information on how to configure this option using the Configuration utility, view the online help for the System, Metric Collection screen.

  For information on how to configure this option in the wideip.conf file, see the Custom port discovery section in Optional configuration changes.

• Prober, hops, and discovery ACLs
  You can now define prober, hops, and discovery access control lists (ACLs) based on CIDR definitions.  This allows you to block probing for members of the ACL when you are using dynamic RTT probing on your 3-DNS Controller.

  For information on how to configure this option using the Configuration utility, view the online help for the ACL Configuration screen.

  For information on how to configure this option in the wideip.conf file, see the ACLs section in Optional configuration changes.

Configuring and using the new software

Required configuration changes

Note that the upgrade_install script automatically makes required syntax changes to the wideip.conf file.  The configuration changes described below are required, but you need make these changes only to each 3-DNS Controller that runs as the principal.  The 3-DNS Sync feature allows the 3-DNS Controllers that run as receivers to synchronize their configurations to the principal 3-DNS Controller in their sync group.

Geographic load balancing

If you are currently using the geographic load balancing feature, you must make the following change to the wideip.conf file so the 3-DNS Controller can instantly classify continent and country of origin for local DNS servers.

Note:  Only 3-DNS Controllers that support encrypted communications have the IP geolocation classifier.

1. Locate the following line in the wideip.conf file:

   include "net.IANA"

2. Replace the line listed in step 1 with this line:

   include geoloc "netIana.inc"

   The include statement loads the IP geolocation classifier into named.

If you are not currently using the geographic load balancing feature but plan to start using it, you must add the following line to the include statement in the wideip.conf file.

include geoloc "netIana.inc"

The include statement loads the IP geolocation classifier into named.

Optional configuration changes

A managed server or VS can have limit values associated with it.  The limit values that you can specify are listed in the following table.

Note:  For BIG-IP Controllers and virtual servers managed by BIG-IP Controllers, you can set limits only for kbytes_per_sec and pkts_per_sec.  For 3-DNS Controllers and hosts, you can set any of the limits listed in the previous table.

For example, the configuration syntax to place limits on both a BIG-IP Controller and one of its virtual servers is as follows.

server {
     type     bigip
     name     "co.dom"
     address  192.168.254.210

     limit {
       kbytes_per_sec  1024
       pkts_per_sec    4096
     }

     vs {
       address  192.168.254.210

       limit {
         kbytes_per_sec  512
         pkts_per_sec   2048
       }

     ...
     }
...
}

ACLs

We recommend that you put the access control lists (ACLs) in a separate include file.
To create an include file for the ACLs:

1. If one does not already exist, create a file called region.ACL in the /var/3dns/include directory.
   
   
2. Add the file to /etc/wideip.conf by typing, at the command line:

   include "region.ACL"

The ACLs you can create are probe_acl, to limit round trip time (RTT) probes; hops_acl, to limit traceroute probes; and discovery_acl, to limit port discovery probes.

Here is an example of a region.ACL file.

actions  {
  NO_RELAY
  delete rdb ACL region "probe_acl"
  delete rdb ACL region "hops_acl"
  delete rdb ACL region "discovery_acl"
}


region_db ACL {

  region {
    name "probe_acl"
    209.162.4.0/24
   }

  region {
    name "hops_acl"
    202.2.2.0/16
  }
  region {
    name "discovery_acl"
    192.168.11.11/32
    209.162.4.0/24
    202.2.2.0/16
  }

}

Custom port discovery

You can define custom port discovery methods in the globals.  The discovery statement can contain the following keywords:

Here is an example of a discovery statement with a custom discovery method defined.

globals {
    rtt_port_discovery  yes

    discovery {
      method     short
      port_list  7 9 1212 53
      randomize  yes
    }

Geographic load balancing

3-DNS Controllers that support encrypted communications are delivered with a classifier that maps IP addresses to their geographic locations.  To make use of these features, you need to modify the wideip.conf file as discussed in Required configuration changes.  After you enable the classifier, set pool_lbmode to topology and create a topology statement.  The 3-DNS Controller can now use the geographic attributes of local DNS servers to direct traffic.

Here is an example of a configuration using topology as the pool load balancing mode.

wideip {
    address     192.168.44.1
    name        "www.domain.com"
    port        80

    pool_lbmode topology

    pool {
       name      "cache_farm"
       preferred  qos
       address    192.168.44.1
       address    192.168.44.2
    }

    pool {
       name      "origin"
       preferred  qos
       address    172.168.11.1
       address    172.168.11.2
    }

The following directives are now allowed in the topology statement to specify pools, data centers, continents, and countries, in addition to the traditional CIDR blocks, for both servers and local DNS servers.

To add a topology statement to the include file /var/3dns/include/topology.inc, follow the format of this example.

topology {

  // server           ldns           score
  "pool.origin"        cont."North America"     100
  "pool.cache_farm"   !cont."North America"     100
}

Note:  Use the not (!) notation in a topology statement to negate the meaning of an element, as shown in the previous example.

Name server load balancing

If you want to distribute your DNS requests between an origin site and a CDN, or redirect DNS requests to a third-party content provider, you can use dynamic delegation.  Dynamic delegation is typically used in conjunction with the Topology pool load balancing mode, as shown in the following example of the wideip.conf file.

wideip {
  address     10.0.0.1
  port        80
  name        "www.domain.com"
  alias       "www.domain.com"
  pool_lbmode  topology

  pool {
     name      "Origin"
     type        A     // default
     preferred     qos
     alternate     packet_rate
     fallback     null     // instead of return_to_dns
     address   172.168.11.1
     address   172.168.11.2
  }


  pool {
     name    "CDN Pool"
     type        NS
     cname      "www.cdn.domain.com"
     zname      "cdn.domain.com"
     preferred    packet_rate
     alternate     rr
     address     cdn0
     address     cdn1
  }

}


topology {        // 2 records
  acl_threshold       0
  probe_threshold     0
  limit_probes       yes
  longest_match      yes

  // server           ldns           score
  "pool.origin"        cont."North America"     100
  "pool.cache_farm"   !cont."North America"     100

}

KBPS load balancing

The 3-DNS Controller can now use KBPS as either a load balancing mode for a pool, or as a Quality of Service (QOS) load balancing factor.  As shown in the following example, KBPS is the preferred load balancing mode for the "New York" and "Los Angeles" pools, and QOS is the preferred load balancing mode for the "Tokyo" pool.  The QOS factor is 7 for KBPS.

globals {
   qos_coeff_rtt 20
   qos_coeff_completion_rate 10
   qos_coeff_packet_rate 50
   qos_coeff_topology 10
   qos_coeff_hops 1
   qos_coeff_kbps 10
}

wideip {
   address  192.168.101.4
   name  "www.domain.com"
   port  80
   qos_coeff {
      rtt 21
      hops 0
      completion_rate 7
      packet_rate 5
      topology 1
      kbps 7

   }

   pool_lbmode  ratio
      pool {
      name  "New York"
      ratio  3
      preferred  kbps
      address 192.168.101.5
      address 192.168.101.6
      address 192.168.101.7
   }
   pool {
      name   "Los Angeles"
      ratio   2
      preferred  kbps
      address 192.168.102.5
      address 192.168.102.6
      address 192.168.102.7
   }
   pool {
      name  "Tokyo"
      ratio  1
      preferred  qos
      address  192.168.103.5
      address  192.168.103.6
      address  192.168.103.7
   }
}

Last resort pool

The last resort pool is the pool to which the 3-DNS Controller directs traffic if all other pools are unavailable.  You can only designate one last resort pool.  To designate a pool as the last resort pool, add the following to the pool definition:

  pool {
    name        "origin"
    last_resort yes
    preferred   rr
    address     192.168.103.5
    address     192.168.103.6
    address     192.168.103.7
  }

Changes to the 3-DNS Maintenance Menu

The 3-DNS Maintenance Menu contains the following changes:

• Added Backup the 3-DNS Controller.  Use this command to create a backup of your 3-DNS Controller configuration.
  
  
• Removed Checkpoint synced files.
  
  
• Removed Rollback checkpointed files.

Known issues

• 3-DNS Administrator Guide

  The 3-DNS Administrator Guide is not updated to include the new features of version 2.1.2.  Please refer to the online help or to the Release Notes if you have questions about any new features.

• Geographic load balancing

  (This applies only to controllers that support encrypted communications.)  The IP geolocation classifier included in the 3-DNS Controller, version 2.1.2 (this version) does not reliably support IP address resolution at the country level.  However, IP address resolution at the continent level is over 90% accurate.  As such, we recommend that if you are using the Topology load balancing mode, you do not use country in your topology statement because the controller probably will not load balance well enough for a production environment.  This will be addressed in a future release.

• Online help

  If you are using Microsoft Internet Explorer (IE) 5.5, you will experience some problems using online help.  Specifically, after clicking Help on the tool bar, a warning dialog box appears with the following message:  This page contains both secure and nonsecure items.  Do you want to display nonsecure items?  When you click Yes, online help displays properly.  When you click No, you see a Navigation cancelled message and online help does not appear.  This problem does not occur in versions of Internet Explorer prior to 5.5, nor in any versions of Netscape Navigator^® or Netscape^® Communicator.

• Configuration utility

  Parts of the Configuration utility for the 3-DNS Controller use Java^® applets, and require the presence of the Java Virtual Machine (JVM).  However, some default installations of Internet Explorer do not contain the JVM.  If your version of Internet Explorer does not contain a JVM, you can obtain it by going to the Tools->Windows Update menu, choosing the Product Update link, and looking in the Additional Windows Features section.  Alternately, you can go to the Internet Explorer section of Microsoft's web site.

  If the screen resolution on your monitor is set to less than 1024 x 768 pixels, you may not see the entire 3-DNS Controller toolbar in the Configuration utility.  If your monitor allows it, we recommend that you set your screen resolution to 1024 x 768 pixels to avoid this problem.

• Wide IPs

  When you create a new wide IP, you must enter a fully-qualified domain name (for example, www.f5.com) in the Wide IP Name box.  If you do not enter a fully-qualified domain name, the 3-DNS Controller does not add the new domain name to NameSurfer, and the Wide IP List screen does not display correctly in the Configuration utility.

• Pool load balancing

  The 3-DNS Controller cannot load balance hosts that are not managed by a BIG-IP Controller (or similar local traffic director) when you choose the Packet Rate or Kilobytes/Second load balancing modes.  This will be addressed in a future release.

• Metrics

  The 3-DNS Controller was interpreting the timeout value for SNMP probing in microseconds, instead of seconds.  This has been corrected and the default value is now 1.

  If you restart named or big3d, the first calculation of the packets per second or kilobytes per second metrics generates an invalid value.  The second calculation of these metrics generates an accurate value.

  The Solstice SNMP agent, which runs on some Sun^® systems, delays the updating of some metrics for longer than 30 seconds.  As a result, the packet rates and kilobytes per second rates can fluctuate from a zero value to a real value in the 3-DNS Controller SNMP Statistics screen.  If you are polling Sun Solaris^TM servers in your network, you may want to set the SNMP polling time on the 3-DNS Controller to an interval greater than 60 seconds to avoid this problem.

• Setting limit checks on servers and virtual servers

  The 3-DNS Controller currently captures SNMP metrics for several host devices, such as Windows NT^® servers, Sun Solaris servers, and the Cisco^® LocalDirectors^TM.  The 3-DNS Controller also captures iQuery metrics for BIG-IP Controllers.  The following table outlines the hosts and system resources for which you can set limits.

  Server/OS	KB/Second	PKT/Second	CPU	Memory	Disk
  BIG-IP Controller	X	X
  Windows® 2000 Server	X	X
  Windows NT 4.0	X	X	X	X
  BSD, UC Davis	X	X	X	X	X
  Linux, UC Davis	X	X		X	X
  Sun Solaris	X	X	X
  Cisco LocalDirector	X	X

  The 3-DNS Controller collects virtual server metrics only for hosts that load balance.  Currently, this list includes the BIG-IP Controller and the Cisco LocalDirector.  Metrics for hosts that do not load balance appear only at the host level.  If you are setting limits for hosts that do not load balance, you can only set limits for the host itself.

• Using encrypted communications

  (This applies only to versions of the 3-DNS Controller that use encrypted communications)  When you rebuild a 3-DNS Controller (or BIG-IP Controller) using a CD, the RSA key for sshd changes.  This breaks the trust relationship between the updated controller and any devices with which it interacts.  As a result, synchronization between the sync group controllers stops.  You also cannot update the big3d agent.  You can correct this situation by removing the newer RSA key and synchronizing the updated controller with other F5 appliances.
  To reset the RSA key for an updated 3-DNS Controller:

  1. In the /root.ssh/known_hosts directory of each sync group controller that has not been updated, remove the RSA key for the replaced controller.
     
     
  2. Type 3dnsmaint at the command line to open the 3-DNS Maintenance Menu.
     
     
  3. Choose Configure secure communication between all 3-DNS and BIG-IP systems and press Enter.
     The 3-DNS Controller updates the RSA key with the correct information.
     
     
  4. Press Enter to return to the 3-DNS Maintenance Menu.
     
     
  5. Press Q to quit.
  
  
• Other issues
  • Sometimes nan (not a number) appears in the Probers Statistics screen.  This error is benign and does not affect the operation of the 3-DNS Controller.
    
    
  • When named receives a request to dump LDNS or Paths information, it dumps only the first 7500 entries.  This limits degradation of DNS resolutions as a result of dumping these metrics.  This applies to the following items in the Configuration utility:
    
    
    • Local DNS statistics
    • Paths statistics

    It also applies to the following commands:

    • 3dns_print
    • ndc dumpdb
    
    
  • You may see the error message aic0 hung during a reboot. This error message is the result of an unterminated SCSI controller.  However, the error message is benign because the 3-DNS Controller does not use SCSI functionality.  You can either ignore the error message or remove it.
    
    

    To remove the aic0 hung error message:

    1. Reboot the controller.
       
       
    2. Press Delete to enter the BIOS configuration.
       
       
    3. Select Integrated Peripherals.
       
       
    4. Verify that Termination enabled is selected on all SCSI buses.
       
       
    5. Save your changes and exit the BIOS configuration.
    
    
  • Occasionally, when you use a static load balancing method in a pool that has a host virtual server with Unknown status (denoted by a blue ball in the Virtual Server Metrics screen in the Configuration utility), the 3-DNS Controller returns the IP address of that host as the resolution to a DNS request.  This happens intermittently and with low frequency.  Note that this does not occur with virtual servers managed by BIG-IP Controllers or Cisco LocalDirectors.
    
    
  • You can change the default prober on a 3-DNS Controller by editing the wideip.conf file from the command line.

    To change the default prober:

    1. Locate the server configuration for the 3-DNS Controller itself in the wideip.conf file.
       
       
    2. Change the IP address for prober to the IP address of the new default prober.
       
       
    3. When you are finished making the desired changes to the wideip.conf file, type ndc_restart at the command line.
       The changes are updated in the configuration.

    The following example of the server configuration in the wideip.conf file shows you where to change the IP address of the default prober.

      server {
         type   3dns
         name   "name"
         ...
         prober [ip address]
         ...
      }

  • The Configuration utility does not currently support this functionality and will be addressed in a future release.
    
    
  • Sometimes when you add a brand new 3-DNS Controller to an existing network, and the new controller is in a 3-DNS Controller sync group, a generic data center may appear in the configuration of some or all of the controllers in the sync group.  You can safely delete these new generic data centers.
    
    
  • When you disable a 3-DNS Controller that is a member of a sync group, the 3-DNS Statistics and Sync Group Statistics screens in the the disabled controller's Configuration utility display an inaccurate status (a red ball) for all other 3-DNS Controllers in the same sync group.  You can see the correct status of the controllers in the 3-DNS Statistics and Sync Group Statistics screens of any enabled 3-DNS Controller in the sync group.