Manual Chapter : 3-DNS Reference Guide v3.0: Wideip.conf

Applies To:

Show Versions Show Versions

3-DNS Controller versions 1.x - 4.x

  • 3.0 PTF-02, 3.0 PTF-01, 3.0.0
Manual Chapter


13

wideip.conf Configuration



Overview of the wideip.conf file

The 3-DNS Controller configuration file is called /etc/wideip.conf. The wideip.conf file describes a network's data centers, servers (3-DNS Controllers, BIG-IP Controllers, EDGE-FX Caches, and hosts), and wide IPs. The wideip.conf file consists of two types of information: statements and comments.

Your wideip.conf file should include at least the following definitions.

  • A datacenter statement. If you do not create one, the 3-DNS Controller creates one for each configured server and names each as follows: generic-<server IP address>
  • At least one server statement defining a 3-DNS Controller
  • At least one virtual server, which is defined as part of a BIG-IP Controller, EDGE-FX Cache, or host server statement
  • A wideip statement, for load balancing

    If a wideip.conf file lacks complete definitions, one of the following happens:

  • If the file cannot be parsed, named does not start.
  • If the file can be parsed, 3-DNS Controllers revert to standard DNS behavior.

To open the /etc/wideip.conf file

  1. At the command line, type 3dnsmaint.
    The 3-DNS Maintenance menu opens.
  2. On the 3-DNS Maintenance menu, select Edit 3-DNS Configuration.

Warning: We do not recommend opening the wideip.conf file in a text editor. Instead, use the Edit 3-DNS Configuration command in the 3-DNS Maintenance menu. This command allows you to edit and save the configuration file. This command also parses the configuration file and alerts you to any syntax errors.

Using include files

Include files are files that contain configuration information about one aspect of your network, and are listed in the main configuration file (wideip.conf). For example, you can have one include file that defines the BIG-IP Controllers in your network, and another include file that defines all wide IPs. Both files are listed in the wideip.conf file in place of the actual server and wideip statements.

Using include files reduces the size of the wideip.conf file and makes it easier to manage your configuration. In addition, include files lead to better system performance because metrics for each aspect of your network are collected and dumped only to the relevant file, instead of having all metrics collected and dumped in a single, potentially unwieldy, file.

Include files are automatically created and implemented whenever one of the following occurs:

  • You configure your network setup using the Configuration utility.
  • You perform any type of dumping operation. By default, dumping operations are on. To turn dumping off, set the global sub-statement timer_persist_cache to 0.

    Note: When include files are generated, any comments you incorporated are deleted.

Syntax for include files

The following syntax is used when incorporating include files into a wideip.conf file.

Figure 1 Syntax for include files

 include root_in "/var/3dns/include"    
include root_out "/var/3dns/include"
include global <"file_name.inc">
include datacenter <"file_name.inc">
include sync_group <"file_name.inc">
include server <"file_name.inc">
include bigip <"file_name.inc">
include host <"file_name.inc">
include 3dns <"file_name.inc">
include wideip <"file_name.inc">
include 3dscript <"file_name.inc">
include topology <"file_name.inc">
include geoloc <"netIana.inc">
include cdn <"cdn.inc">
include ldns <"file_name.inc">
include region <"file_name.inc">
include manifest <"file_name.inc">

Definitions of include statements

Table 1 lists the include statements, their descriptions, and their default file names.

Table 1 Include file descriptions
Parameter Description Default
include root_in Specifies the root directory from which to get include files. Enclose all file names in quotation marks. "/var/3dns/include"
include root_out Specifies the root directory in which to dump include files. "/var/3dns/include"
include global Specifies the name of the file that contains the globals statement. "globals.inc"
include datacenter Specifies the name of the file that contains datacenter statements. "datacenters.inc"
include sync_group Specifies the name of the file that contains sync_group statements. "sync_groups.inc"
include server Specifies the name of the file that contains server statements. "servers.inc"
include bigip Specifies the name of the file that contains BIG-IP Controller server statements. "bigip.inc"
include host Specifies the name of the file that contains host server statements. "host.inc"
include 3dns Specifies the name of the file that contains 3-DNS Controller server statements. "3dns.inc"
include wideip Specifies the name of the file that contains wideip statements. "wideip.inc"
include 3dscript Specifies the name of the file that contains production rule configuration. "prodrules.inc"
include topology Specifies the name of the file that contains the topology statement. "topology.inc"
include geoloc Specifies the name of the file that contains the IP geo-classification database. It is important that you do not edit this statement. "netIana.inc"
include ldns Specifies the name of the file that contains information about local DNS servers and path information. "filename.inc"
include region Specifies the name of the file that contains any region definitions statements. "region.inc"
include cdn Specifies the name of the file that contains any content delivery network (CDN) provider statements. "cdn.inc"
include manifest Specifies the name of the file that the Configuration utility uses to manage any production rules generated by the utility. It is important that you do not edit this statement. "/var/f5/www/seeit/
.prodruledb/manifest"

Statements

A top-level 3-DNS Controller statement begins with a keyword, and may be followed either by a value or by a block of sub-statements enclosed in braces {}.

The 3-DNS platform supports the following top-level statements.

  • include
    The include statement lists any include files that are configured on the 3-DNS Controller.
  • globals
    The globals statement defines system-level settings for any 3-DNS Controller configuration options and sets defaults for other statements.
  • datacenter
    The datacenter statement defines the group of 3-DNS Controllers, BIG-IP Controllers, EDGE-FX Caches, and hosts that reside in a single physical location.
  • sync_group
    The sync_group statement defines the group of 3-DNS Controllers that synchronize their configuration settings and metrics data.
  • server
    The server statement defines a 3-DNS Controller, a BIG-IP Controller, an EDGE-FX Cache, or a host machine.
  • wideip
    The wideip statement defines a wide IP. Wide IPs map a domain name to a load balancing mode and a set of virtual servers (on BIG-IP Controllers, EDGE-FX Caches, and other host machines).
  • topology
    The topology statement contains the topology records that facilitate the topology load balancing mode (on its own and as part of the QOS mode). Note that while the topology statement is still valid, the topology.inc file is the preferred location for topology configuration information.

Syntax rules

Keep the following rules in mind when creating and editing statements in your wideip.conf file.

  • Statement order
    Statements should appear in this order in the wideip.conf file:

    • globals
    • datacenter
    • sync_group
    • server
    • wideip
  • Port specification
    When you define 3-DNS Controllers or hosts, the port specification must follow the probe_protocol sub-statement. When you define a BIG-IP Controller, EDGE-FX Cache, or virtual server (on a BIG-IP Controller, an EDGE-FX Cache, or a host), the port specification must immediately follow the address specification, and can take any of the following forms:

    address <ip_addr>:<port>

    address <ip_addr>
    port <port>

    address <ip_addr>
    service <wks>

    In the above example, <wks> stands for well-known service and is a quoted string representing the name of a WKS defined in the /etc/services file.

  • cur_ values
    You may notice several cur_ values in your wideip.conf file; do not edit them unless you are instructed to do so by your vendor's technical support. For more information, see Understanding cur_values .

Typography in syntax examples

Certain characters are used to indicate whether a parameter is mandatory or optional, or whether you can use one parameter or another.

  • Mandatory parameters
    Angle brackets (< >) enclose mandatory parameters where you must type the data associated with a command.
  • Optional parameters
    Brackets ([ ]) enclose optional parameters.
  • Choice of parameters
    A vertical bar ( | ) between two values means that either value is acceptable.

The globals statement

The globals statement sets up global options to be used by the 3-DNS Controller, and must appear before any other statements in the wideip.conf file. Each globals sub-statement has a default setting, and you do not need to edit the globals statement unless you want to change a default setting. If the 3-DNS Controller does not find a globals statement in the configuration file, the 3-DNS Controller uses a globals block, with each option set to its default.

If you use a globals sub-statement more than once, the 3-DNS Controller uses the last listed value and does not generate an error message. For example, if your globals statement contains the lines shown in the following figure, the 3-DNS Controller uses the value 50.

Figure 2 Multiple globals sub-statements

 globals {    
bigip_ttl 100
bigip_ttl 50
}

Syntax for the globals statement

The globals statement supports the following sub-statements. When you define a globals statement, you need only include those sub-statements that you want to change from the default.

Figure 3 Syntax for the globals statement

 globals {    
[ time_tolerance <number> ]
[ encryption < yes | no > ]
[ encryption_key_file <string> ]
[ check_static_depends < yes | no > ]
[ check_dynamic_depends < yes | no > ]
[ default_persist_ttl < <number> s | m | h | d | w | m | y > ]
[ default_probe_limit <number> ]
[ persist_ldns < yes | no > ]
[ persist_mask <ip address> ]
[ persist_nonwipnames < yes | no > ]
[ timer_get_3dns_data <number> ]
[ timer_get_server_data <number> ]
[ timer_get_host_data <number> ]
[ timer_get_vs_data <number> ]
[ timer_get_ecv_data <number> ]
[ timer_get_path_data <number> ]
[ timer_get_trace_data <number> ]
[ timer_check_keep_alive <number> ]
[ timer_persist_cache <number> ]
[ timer_sync_state <number> ]
[ dc_prefix <string> ]
[ dns_ttl <number> ]
[ 3dns_ttl <number> ]
[ bigip_ttl <number> ]
[ edgefx_ttl <number> ]
[ host_ttl <number> ]
[ vs_ttl <number> ]
[ path_ttl <number> ]
[ trace_ttl <number> ]
[ default_ttl <number> ]
[ rtt_timeout <number> ]
[ rtt_sample_count <number> ]
[ rtt_packet_length <number> ]
[ rx_buf_size <number> ]
[ tx_buf_size <number> ]
[ dump_region < yes | no > ]
[ dump_topology < yes | no > ]
[ filter_ip < cidr block | ip address >
[ filter_mask <ip address> ]
[ qos_coeff_rtt <number> ]
[ qos_coeff_completion_rate <number> ]
[ qos_coeff_packet_rate <number> ]
[ qos_coeff_topology <number> ]
[ qos_coeff_hops <number> ]
[ qos_coeff_vs_capacity ]
[ qos_coeff_kbps <number>]
[ qos_factor_rtt <number> ]
[ qos_factor_completion_rate <number> ]
[ qos_factor_packet_rate <number> ]
[ qos_factor_topology <number> ]
[ qos_factor_hops <number> ]
[ qos_factor_vs_capacity <number> ]
[ qos_factor_kbps <number>
[ default_alternate < ga | null | random | ratio | static_persist |
packet_rate | leastconn | return_to_dns | rr | topology | vs_capacity
| kbps > ]

[ default_fallback < completion_rate | ga | hops | leastconn |
null | packet_rate | qos | random | ratio | return_to_dns |
rr | rtt | topology | vs_capacity | static_persist | kbps > ]
[ fb_respect_depends < yes | no > ]
[ fb_respect_acl < yes | no > ]
[ aol_aware < yes | no >
[ path_duration <number> ]
[ ldns_duration <number> ]
[ prober <ip_addr> ]
[ resolver_tx_buf_size <number> ]
[ resolver_rx_buf_size <number> ]
[ use_alternate_iq_port < yes | no > ]
[ multiplex_iq < yes | no > ]
[ paths_never_die < yes | no > ]
[ paths_noclobber < yes | no > ]
[ rtt_probe_dynamic < yes | no > ]
[ rtt_port_discovery < yes | no > ]
[ rtt_autorecover_discovery < yes | no > ]
[ rtt_discovery_method < short | wks | full > ]
[ discovery_portlist {
method < short | wks | all >
[portlist { <number> <number> ... }
[randomize < yes | no >
} ]
[ rtt_allow_probe < yes | no > ]
[ rtt_allow_hops < yes | no > ]
[ rtt_allow_frag < yes | no > ]
[ probe_protocol {
[dns_rev]
[dns_dot]
[udp]
[tcp]
[icmp]
} ]
[ datasize_system <number> ]
[ datasize_reap_pct <number> ]
[ default_iquery_protocol < udp | tcp > ]
[ traceroute_port <number> ]
[ do_dynamic < yes | no > ]
}

Figure 4 shows an example of a valid globals statement.

Figure 4 Example syntax for the globals statement

 globals {     
prober 192.168.101.2 // Default prober is New York 3-DNS Controller
encryption yes // Encrypt iQuery
paths_noclobber yes // Don't overwrite metrics with zeroed results
path_ttl 2400 // Extend the life of path metrics
rtt_probe_dynamic yes // Switch probing method if current fails
}

Definition of globals sub-statements

Each globals sub-statement supports the parameters described in the following sections.

Synchronization

The synchronization sub-statement specifies how the current 3-DNS Controller handles synchronizing its database with the other 3-DNS Controllers in the network.

Table 2 Synchronization sub-statements
Parameter Description Default
time_tolerance Specifies the variation of time allowed (in seconds) when comparing time stamps on files. The syncd daemon allows for slight variation in time stamps when it compares files during the synchronization process. If the difference between the two time stamps falls within the time_tolerance setting, the daemon considers the files to be the same and does not overwrite one with the other. 10

Encryption

The encryption sub-statements specify whether the communication between the 3-DNS Controller and a BIG-IP Controller is encrypted.

Table 3 Encryption sub-statements
Parameter Description Default
encryption Specifies whether to enable encryption for iQuery events. no
encryption_key_file Specifies the location and name of the iQuery encryption key file. "/etc/F5key.dat"

Dependencies

The dependencies sub-statements specifies whether the 3-DNS Controller checks the availability of virtual servers or paths before the controller sends a connection to a virtual server.

Table 4 Dependencies sub-statement
Parameter Description Default
check_static_depends Specifies whether to check the availability of virtual servers on BIG-IP Controllers, EDGE-FX Caches, and hosts. Change this option to no if you want to test your configuration. Setting this option to no has the effect of forcing the virtual servers to have green (up) status indicators on the Virtual Server Statistics screen in the Configuration utility. yes
check_dynamic_depends Specifies that the 3-DNS Controller checks the availability of a path before it uses the path for load balancing. Changing this option to no overrides the path_ttl and whether the last probe attempt was successful. yes

LDNS persistence

The value for persist_ldns must be set to yes (the default) for the 3-DNS Controller to store and use path information. Dynamic load balancing modes depend on path information to resolve requests. If you use only static load balancing modes, you can set persist_ldns to no to conserve memory.

Table 5 LDNS persistence
Parameter Description Default
persist_ldns Specifies whether the 3-DNS Controller records in its cache the IP addresses of all LDNS machines that make resolution requests. yes
default_persist_ttl Specifies the length of time the 3-DNS Controller retains LDNS information before the information is purged 3600
persist_mask Specifies the significant bits of an LDNS IP address to use with the static_persist load balancing mode 0xFFFFFFFF

Periodic task intervals

These sub-statements define the frequency at which the 3-DNS Controller refreshes the metrics information it collects.

Table 6 Periodic task interval statements
Parameter Description Default
timer_get_3dns_data Specifies how often the 3-DNS Controller retrieves performance data for other 3-DNS Controllers in the sync group. You can enter a value between 0 and 4294967295 seconds. 20
timer_get_server_data Specifies how often the 3-DNS Controller refreshes BIG-IP Controller and EDGE-FX Cache information. You can enter a value between 0 and 4294967295 seconds. 20
timer_get_host_data Specifies how often the 3-DNS Controller refreshes other host machine information. You can enter a value between 0 and 4294967295 seconds. 90
timer_get_vs_data Specifies how often the 3-DNS Controller refreshes virtual server information. You can enter a value between 0 and 4294967295 seconds. 30
timer_get_path_data Specifies how often the 3-DNS Controller refreshes path information (for example, round trip time or ping packet completion rate). You can enter a value between 0 and 4294967295 seconds. 120
timer_get_ecv_data Specifies how often the 3-DNS Controller refreshes ECV information. You can enter a value between 0 and 4294967295 seconds. 90
timer_get_trace_data Specifies how often the 3-DNS Controller retrieves traceroute data (traceroutes between each data center and each LDNS). You can enter a value between 0 and 4294967295 seconds. 60
timer_check_keep_alive Specifies how often the 3-DNS Controller queries remote 3-DNS Controllers and BIG-IP Controllers. This value determines how often named sends hello packets to each big3d agent in its configuration. You can enter a value between 0 and 4294967295 seconds. 60
timer_persist_cache Specifies how often the 3-DNS Controller writes the wideip.conf file from memory. You can enter a value between 0 and 4294967295 seconds. 300

Data timeouts

These sub-statements set the amount of time for which metrics information is considered valid. After a timeout is reached, the 3-DNS Controller refreshes the information.

Table 7 Data timeouts sub-statements
Parameter Description Default
default_ttl Specifies the default number of seconds that the 3-DNS Controller considers the wide IP A record to be valid. If you do not specify a wide IP TTL value when defining a wide IP, the wide IP definition uses the default_ttl value. 30
3dns_ttl Specifies the number of seconds that the 3-DNS Controller considers performance data for the other 3-DNS Controllers to be valid. 60
bigip_ttl Specifies the number of seconds that BIG-IP Controller information is to be used by the 3-DNS Controller for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
bigip_ttl > timer_get_server_data. A 2:1 ratio is the optimal setting for this relationship.
60
edgefx_ttl Specifies the number of seconds that EDGE-FX Cache information is to be used by the 3-DNS Controller for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
edge_ttl> timer_get_server_data. A 2:1 ratio is the optimal setting for this relationship.
60
host_ttl Specifies the number of seconds that generic host machine information is to be used by the 3-DNS Controller for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
host_ttl > timer_get_host_data.
240
vs_ttl Specifies the number of seconds that virtual server information (data acquired from a BIG-IP Controller or other host machine about a virtual server) is to be used by the 3-DNS Controller for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
vs_ttl > timer_get_vs_data.
120
path_ttl Specifies the number of seconds that path information is to be used by the 3-DNS Controller for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
path_ttl > timer_get_vs_data.
2400
trace_ttl Specifies the amount of time (in seconds) that the 3-DNS Controller considers traceroute data to be valid. You can enter a value between 1 and 4294967295. 604800 (seven days)

Metrics collection

The metrics collection sub-statements define how the 3-DNS Controller collects path information.

Table 8 Metrics collection sub-statements
Parameter Description Default
rtt_timeout Specifies how long the big3d agent waits for a probe. You can enter a value between 1 and 4294967295 seconds. 5
rtt_sample_count Specifies the number of packets to send from the BIG-IP Controller to the LDNS to determine the path information between those two machines. You can type a value between 1 and 25. 3
rtt_packet_length Specifies the length of packets, in bytes, to send from the BIG-IP Controller to the LDNS to determine the path information between those two machines. You can type a value between 64 and 500; the default value for this setting is 64. 64
rtt_probe_protocol Determines which protocols the 3-DNS Controller uses to probe LDNS servers to calculate RTT times, and in what order the protocols are used. You can specify the icmp, udp, tcp, dns_dot, or dns_rev protocols. icmp

Resource limits

The resource limits sub-statements define the amount of memory on the 3-DNS Controller that is allocated to sending and receiving metrics information.

Table 9 Resource limits sub-statements
Parameter Description Default
rx_buf_size Specifies the maximum amount of socket buffer data memory the server can use when receiving data. You can enter a value between 8192 and 65536. 49152
tx_buf_size Specifies the maximum amount of socket buffer data memory the server can use when transmitting data. You can enter a value between 8192 and 65536. 49152

QOS values

The Quality of Service (QOS) load balancing mode distributes connections based on a path evaluation score. Using the equation below, the QOS mode compares paths between the LDNS and each virtual server included in the wideip statement. The 3-DNS Controller load balances each new connection to the virtual server associated with the best (highest) path score.

Figure 5 QOS equation

 score_path =    
[(qos_coeff_packet_rate) * (1 / score_packet_rate)] +
(qos_coeff_rtt) * (1 / score_rtt)] +
[(qos_coeff_completion_rate) * (score_completion_rate)] +
[(qos_coeff_topology) * (score_topology)] +
[(qos_coeff_hops) * (score_hops)] +
[(qos_coeff_vs_capacity) * (score_vs_capacity)] +
[(qos_coeff_kbps) * (score_kbps)]

The coefficients for the score computation are defined as globals, but you can override them within a wideip statement.

Table 10 QOS values sub-statements
Parameter Description Default
qos_coeff_rtt Specifies the relative weighting for round trip time when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 20
qos_coeff_completion_rate Specifies the relative weighting for ping packet completion rate when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 5
qos_coeff_packet_rate Specifies the relative weighting for BIG-IP Controller packet rate when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 3
qos_coeff_topology Specifies the relative weighting for topology when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 0
qos_coeff_hops Specifies the relative weighting for hops when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 0
qos_coeff_vs_capacity Specifies the relative weighting for virtual server capacity when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 0
qos_coeff_kbps Specifies the relative weighting for kilobytes per second when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 3
qos_factor_rtt Specifies the factor used to normalize raw round trip time values when computing the QOS score. 10000
qos_factor_completion_rate Specifies the factor used to normalize raw completion rate values when computing the QOS score. 10000
qos_factor_packet_rate Specifies the factor used to normalize raw packet rate values when computing the QOS score. 10000
qos_factor_topology Specifies the factor used to normalize raw topology values when computing the QOS score. 10
qos_factor_hops Specifies the factor used to normalize raw hops values when computing the QOS score. 25
qos_factor_vs_capacity Specifies the factor used to normalize raw virtual server capacity values when computing the QOS score. 1
qos_factor_kbps Specifies the factor used to normalize raw kilobytes per second values when computing the QOS score. 1

Load balancing

The load balancing sub-statement defines the alternate and fallback load balancing modes.

Table 11 Load balancing sub-statements
Parameter Description Default
default_alternate Defines the default alternate load balancing mode used when the preferred load balancing mode does not provide a resolution. You can override this setting in the wideip statement. rr
default_fallback Defines the default fallback load balancing mode used when the preferred and alternate load balancing modes do not provide a resolution. You can override this setting in the wideip statement. return_to_dns
fb_respect_depends Determines whether the 3-DNS Controller respects virtual server status when load balancing switches to the specified fallback mode. no
fb_respect_acl Determines whether the 3-DNS Controller imposes topology access control when load balancing switches to the specified fallback mode. no
aol_aware Determines whether the 3-DNS Controller recognizes local DNS servers that belong to the Internet service provider, America Online (AOL). no

Prober

The prober sub-statement defines the IP address of the machine that pings a host system to verify whether it is available. Typically, you use the IP address of the 3-DNS Controller itself, but you can use other network servers.

Table 12 Prober sub-statement
Parameter Description Default
prober Specifies the default prober for host status, usually the 3-DNS Controller IP address. Using this sub-statement is not necessary if the 3-DNS Controller only manages the BIG-IP Controller. When this option is set to 0, the 3-DNS Controller's IP address is the implied value. This sub-statement can be overridden within the server statement. 0.0.0.0

Warning: You must define a prober if the 3-DNS Controller manages virtual servers on hosts. If you do not define a default prober in the globals, or probers in the host statements for all hosts, you will encounter validation errors.

Buffer size

The buffer size sub-statements specify the maximum amount of UDP data that the 3-DNS Controller can receive, and also specify the maximum amount of TCP data that the 3-DNS Controller can send.

Table 13 Buffer size sub-statements
Parameter Description Default
resolver_rx_buf_size Specifies the UDP receive buffer size. The value is overridden only if it is larger than the one first assigned by the kernel. 98304
resolver_tx_buf_size Specifies the TCP send buffer size. 24576

Reaping

The 3-DNS Controller stores dynamic LDNS and network path data in memory. The amount of data that can be held in memory at any given time is based on the amount of memory in the 3-DNS Controller. Reaping is the process of finding the least-used data in memory and deleting it.

The default reaping values are adequate for most configurations. Contact your technical support representative if you want to make changes to them.

Table 14 Reaping sub-statements
Parameter Description Default
datasize_system Specifies the amount of RAM the 3-DNS Controller reserves for system usage, such as non-3-DNS specific processes. if 64 MB RAM, default is 32; otherwise default is 64
datasize_reap_pct Specifies what percentage of memory that the 3-DNS Controller frees up during the reap process. 15
path_duration Specifies the number of seconds that a path remains cached after its last access. You can type a value between 60 and 2147483648). 604800 (7 days)
ldns_duration Specifies the number of seconds that an inactive LDNS remains cached. Each time an LDNS makes a request, the clock starts again. You can type a value between 60 and 2147483648. 2419200
(28 days)

iQuery port options

The iQuery port options determine which port (or ports) the 3-DNS Controller uses to send and receive iQuery traffic.

Table 15 iQuery port options sub-statements
Parameter Description Default
use_alternate_iq_port Determines whether the 3-DNS Controller runs iQuery traffic on port 245 (the port used in older configurations), or on port 4353, the iQuery port registered with IANA. The default setting, yes, uses port 4353. To use port 245, change this setting to no. yes
multiplex_iq Determines whether the 3-DNS Controller uses the ephemeral ports for iQuery traffic returned from the big3d agent. The default setting forces iQuery traffic to use a single port defined by use_alternate_iq_port for all incoming iQuery traffic. yes

Probing

The 3-DNS Controller uses probing to collect path metrics. The 3-DNS Controller then uses the metrics to make traffic distribution and load balancing decisions.

Table 16 Probing sub-statements
Parameter Description Default
default_probe_limit Specifies a limit on the number of times the 3-DNS Controller probes a path. With the default setting, there is no limit on path probes. 0
paths_never_die Specifies that dynamic load balancing modes can use path data even after the TTL for the path data has expired. We recommend that you change this setting to yes, which has the effect of requiring that the 3-DNS Controller always uses path data even if the path's TTL expires. no
paths_noclobber Specifies whether the 3-DNS Controller overwrites existing path data with blank data when a path probe fails. With the default setting, the 3-DNS Controller does not overwrite existing path data with blank data when a path probe fails. Unlike paths_never_die, this parameter has no effect on path_ttl. yes
check_dynamic_depends Specifies that the 3-DNS Controller checks the availability of a path before it uses the path for load balancing. Changing this option to no overrides the path_ttl and whether the last probe attempt was successful. You can use this parameter in conjunction with paths_noclobber. This parameter does not prevent the refreshing of path metrics. yes
rtt_port_discovery Determines whether the 3-DNS Controller uses the discovery factory to find an alternate port to be used by the probing factory, if probing on port 53 fails. no
rtt_autorecover_discovery Specifies whether to move collected LDNS information from the Needs Discovery probing state to the Needs Probe state if rtt_port_discovery is set to no. Setting this to no means that if probing failed for a specific LDNS for any reason, the LDNS is ineligible for future probing attempts. yes
rtt_discovery_method Determines which ports to scan. The default, short, causes the 3-DNS Controller to scan a pre-defined list of ports, and then scans port 53. Other acceptable values are wks (well-known services), and all. short
rtt_probe_dynamic Determines whether the 3-DNS Controller scans the ports specified in rtt_discovery_method in the same order every time, or in a random order. The default setting causes the controller to scan the ports in the same order every time. no
rtt_allow_probes Specifies that the 3-DNS Controller issues probe requests for path metrics to local DNS servers. You can change this setting to no to turn off path probing. yes
rtt_allow_hops Specifies that the 3-DNS Controller should collect hops metrics when probing paths. yes
rtt_allow_frag Specifies that the 3-DNS Controller should break each probe packet into smaller packets when probing paths. no
probe_protocol Specifies the protocol that the 3-DNS Controller uses to probe local DNS servers. The default is icmp. The other available protocols are: dns_rev, dns_dot, udp, and tcp icmp

The datacenter statement

A datacenter statement defines the group of 3-DNS Controllers, BIG-IP Controllers, and hosts that reside in a single physical location.

Syntax for the datacenter statement

The datacenter statement uses the following syntax.

Figure 6 Syntax for the datacenter statement

 datacenter {    
name <"data center name">
[ location <"location info"> ]
[ contact <"contact info"> ]
[ 3dns <IP address | name> ]
[ bigip <IP address | name> ]
[ host <IP address | name> ]
[ edgefx <IP address | name>
}

Figure 7 shows an example of a valid datacenter statement.

Figure 7 Example syntax for the datacenter statement

 datacenter {    
name "New York"
location "NYC"
contact "3DNS_Admin"
3dns 192.168.101.2
bigip 192.168.101.40
edgefx 192.168.101.50
host 192.168.105.40
}

Definition of datacenter sub-statements

The datacenter sub-statements specify a name for the data center and the machines it contains.

Table 17 Data center sub-statements
Parameter Description
name Specifies the name of this data center. The name must be enclosed in quotation marks.
location Specifies the location of the data center. This name must be enclosed in quotation marks. This sub-statement is not required, but this information can be useful if problems later arise or changes are required.
contact Identifies the administrator of the data center. This name must be enclosed in quotation marks. This sub-statement is not required, but this information can be useful if problems later arise or changes are required.
3dns Specifies the IP address of a 3-DNS Controller in this data center.
bigip Specifies the IP address of a BIG-IP Controller in this data center.
edgefx Specifies the IP address of an EDGE-FX Cache in this data center.
host Specifies the IP address of a host in this data center.

The sync_group statement

The sync_group statement defines the group of 3-DNS Controllers that synchronize their configuration settings and metrics data. You configure this statement in the wideip.conf file of the principal 3-DNS Controller.

Syntax for the sync_group statement

The sync_group statement uses the following syntax.

Figure 8 Syntax for the sync_group statement

 sync_group {    
name <"name">
3dns <ip_address | "domain_name">
[ 3dns <ip_address | "domain_name"> ]
}

Note that the sync_group statement does not support location or contact sub-statements.

Figure 9 shows an example of a valid sync_group statement.

Figure 9 Example syntax for the sync_group statement

 sync_group {    
name "sync"
3dns 192.168.101.2 // New York - this is the principal controller
3dns 192.168.102.2 // Los Angeles - this is the receiver controller
3dns 192.168.103.2 // Madrid - this is also a receiver controller
}

Definition of sync_group sub-statements

The sync_group sub-statements define the members of the sync group.

Table 18 Sync_group sub-statements
Parameter Description
name Specifies the name of this sync group.
3dns Specifies the IP address or domain name (enclosed in quotation marks) of a 3-DNS Controller in the group. First list the IP address of the principal controller. Then list all other 3-DNS Controllers, in the order that they should become a principal controller, if the previously listed principal 3-DNS Controller fails. Note that there can only be one principal controller at any time.

The server statement

The server statement defines the characteristics associated with a particular 3-DNS Controller, BIG-IP Controller, EDGE-FX Cache, or host.

Note: The server statement replaces the bigip and host statements used in earlier versions of 3-DNS Controller. Although this version of 3-DNS Controller provides backward compatibility with the earlier bigip and host statements, we recommend that you use the newer syntax.

A server statement contains the following information:

  • The type of server: 3-DNS Controller, BIG-IP Controller, EDGE-FX Cache, or host
  • The IP address of the server
  • If the server is a BIG-IP Controller, EDGE-FX Cache, or host, the set of virtual servers that is available on it
  • Dynamically collected information about the server, its virtual servers and ports, and the paths between the server and LDNS

    Because available sub-statements vary by server type, the syntax and examples for each type are listed separately. All sub-statements are defined in the table starting on page 38 .

Syntax for the server statement (3-DNS Controller)

The following server statement syntax applies to 3-DNS Controllers only. Note that this server statement does not define virtual servers; the purpose of defining a 3-DNS Controller is to set up the big3d agent to obtain path probing information.

Figure 10 Server statement syntax for defining a 3-DNS Controller

 server {    
type 3dns
address <IP address>
name <"3dns_name">
iquery_protocol [ udp | tcp ]
[ remote {
secure <yes | no>
user <"user name">
} ]
[ interface {
address <NIC IP address>
address <NIC IP address>
} ]
[ factories {
prober <number>
discovery <number>
snmp <number>
hops <number>
} ]
[ prober <IP address> ]
probe_protocol < icmp | udp | tcp | dns_rev | dns_dot >
port <port to probe>
[ discovery_portlist {
method < short | wks | all >
[portlist { <number> <number> ... }
[randomize < yes | no >
} ]
}

Figure 11 shows an example of the syntax to use in defining a 3-DNS Controller.

Figure 11 Example syntax for defining a 3-DNS Controller

 // New York    
server {
type 3dns
address 192.168.101.2
name "3dns-newyork"
iquery_protocol udp
remote {
secure no
user "root"
}
probe_protocol icmp
port 53
}

Syntax for the server statement (BIG-IP Controller)

The following server statement syntax applies to BIG-IP Controllers and their virtual servers only.

Figure 12 Server statement syntax for defining a BIG-IP Controller

 server {    
type bigip
address <IP address>
name <"bigip_name">
iquery_protocol [ udp | tcp ]
[ vsmetrics < yes | no > ]
[ remote {
secure <yes | no>
user <"user name">
} ]
[ interface {
address <NIC IP address>
address <NIC IP address>
} ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number ]
} ]
[ probe_protocol < icmp | ucp | tcp | dns_dot | dns_rev > ]
[ ratio <number> ]
[ factories {
prober <number>
discovery <number>
snmp <number>
hops <number>
} ]

vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
} ]
[ depends_on {
<IP address>:<port number> //example 10.10.10.10:443
} ]
[ translate {
<IP address>:<port number>
} ]
probe_protocol <tcp | udp>
}

Figure 13 shows an example of the syntax to use in defining a BIG-IP Controller.

Figure 13 Example syntax for defining a BIG-IP Controller

 server {     
type bigip
address 192.168.101.40
name "bigip-newyork"
iquery_protocol udp

remote {
secure yes
user "administrator"
}

# Tell 3-DNS about the 2 interfaces on a BIG-IP HA Controller
interface {
address 192.168.101.41
address 192.168.101.42
}

# Change the number of factories doing the work at big3d
factories {
prober 6
discovery 1
snmp 1
hops 2
}

vs {
address 192.168.101.50
service "http"
translate {
address 10.0.0.50
port 80
}
}
vs {
address 192.168.101.50:25 // smtp
translate {
address 10.0.0.50:25
}
}
}

Syntax for the server statement (EDGE-FX Cache)

The following server statement syntax applies to EDGE-FX Caches only.

Figure 14 Example syntax for defining an EDGE-FX Cache

 server {    
type edgefx
address <IP address>
name <"edgefx_name">
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number ]
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
} ]
iquery_protocol [ udp | tcp ]
[ remote {
secure <yes | no>
user <"user name">
} ]
[ interface {
address <NIC IP address>
address <NIC IP address>
} ]

[ probe_protocol < icmp | ucp | tcp | dns_dot | dns_rev > ]
[ ratio <number> ]
[ factories {
prober <number>
discovery <number>
hops <number>
snmp <1> { //required
agent edgefx
version 2
community <"public">
}
} ]
[ vsmetrics < yes | no > ]
vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ limit {
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
} ]

Syntax for the server statement (host)

The following server statement syntax applies to hosts only. Note that the snmp sub-statement is necessary only if you want the big3d agent to use an SNMP agent on the host to collect additional metrics information. For more information on configuring these settings, see Chapter 10, SNMP, in the 3-DNS Controller Reference Guide.

Figure 15 Server statement syntax for defining a host

 server {    
type host
address <IP address>
name <"host_name">
probe_protocol <tcp | icmp | udp | dns_rev | dns_dot>
[ prober <IP address> ]
port <port number> | service <"service name">
[ snmp {
agent <generic | ucd | solstice | ntserv | win2kserv | ciscold | ciscold2 | ciscold3 | foundry | arrowpoint | alteon | cacheflow>
port <port number>
community <"community string">
timeout <seconds>
retries <number>
version <SNMP version>
} ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
} ]
vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ probe_protocol <tcp | icmp | udp| dns_rev| dns_dot> ]
}
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
} ]
}

Figure 16 shows an example of the syntax to use in defining a host.

Figure 16 Example syntax for defining a host

 server {     
type host
address 192.168.104.40
name "host-tokyo"
probe_protocol icmp
port 53
snmp {
agent ucd
community "public"
version 1
}
vs {
address 192.168.104.50:25
limit {
kbytes_per_second 15000
}
}
vs {
address 192.168.104.50:80
limit {
kbytes_per_second 15000
}
}
}

Definition of server sub-statements

The server statement supports the following sub-statements. Note that available sub-statements vary by server type.

Address information

The address information sub-statements specify the name, address, and type of each server. Depending on the type of server you are configuring, you may need to specify a probe protocol, prober IP address, and port number.

Table 19 lists the parameters of the address information sub-statement.

Table 19 Address information sub-statements
Parameter Description
type Indicates whether the specified server is a 3-DNS Controller, BIG-IP Controller, EDGE-FX Cache, or host.
address Specifies the IP address of the 3-DNS Controller, BIG-IP Controller, EDGE-FX Cache, or host.
name Specifies the name of the 3-DNS Controller, BIG-IP Controller, EDGE-FX Cache, or host. You must enclose all names in quotation marks.
iQuery_protocol Specifies the iQuery transport option, TCP or UDP.
probe_protocol Specifies the protocol method to use for probing this host: ICMP, UDP, or TCP. Applies to 3-DNS Controllers and hosts. Note that UDP is not supported on hosts.
prober Specifies the IP address of the machine probing the 3-DNS Controller or host. This IP address points to a BIG-IP Controller, a 3-DNS Controller, or an EDGE-FX Cache that runs the big3d agent. The big3d agent actually probes the host and virtual servers to verify whether the host or a particular virtual server is currently available to accept connections. If you omit this parameter, the 3-DNS Controller uses the prober <ip_addr> parameter defined in the globals statement. This applies to 3-DNS Controllers and hosts only.
port Specifies the port used to probe this host if probe_protocol is set to TCP. This applies to 3-DNS Controllers and hosts only.

Limit settings

Using the limit sub-statement, you can manage the physical and throughput resources of your BIG-IP Controllers, EDGE-FX Caches, hosts, and their respective virtual servers. If you omit this sub-statement, the 3-DNS Controller does not use resource thresholds to monitor the availability of the BIG-IP Controllers, EDGE-FX Caches, hosts, and their respective virtual servers.

Table 20 Limit sub-statement
Parameter Description
limits Indicates the start of the limits definition. Applies to BIG-IP Controllers and their virtual servers, EDGE-FX Caches and their virtual servers, and hosts and their virtual servers.
cpu_avail Specifies, in percentage, how much CPU processing must remain available on the server or virtual server. The cpu_avail parameter applies to hosts and EDGE-FX Caches only.
mem_avail Specifies, in kilobytes, how much memory must remain available on the server or virtual server. The mem_avail parameter applies to hosts and EDGE-FX Caches only.
disk_avail Specifies, in kilobytes, how much disk space must remain available on the server or virtual server. The disk_avail parameter applies to hosts and EDGE-FX Caches only.
kbytes_per_sec Specifies, in kilobytes per second, the maximum allowable throughput rate for the server or virtual server.
pkts_per_sec Specifies, in packets per second, the maximum allowable data transfer rate for the server or virtual server
current_conn Specifies the maximum number of current connections for the server or virtual server.

Remote connections

It is necessary to use the remote sub-statement only if you want to specify a different login name or specifically use SSH or RSH on 3-DNS Controllers, BIG-IP Controllers, or EDGE-FX Caches.

Table 21 Remote connections sub-statements
Parameter Description
remote Indicates the start of a remote sub-statement. Applies to 3-DNS Controllers, BIG-IP Controllers, and EDGE-FX Caches.
secure Specifies whether to use SSH (secure shell) or RSH (remote shell) for remote connections. The default for crypto controllers is yes, which specifies that SSH is used. Non-crypto controller versions must use RSH instead. Applies to 3-DNS Controllers, BIG-IP Controllers, and EDGE-FX Caches.
user Specifies the "superuser" name that is used to allow a remote user to log on to the controller. Enclose this name in quotation marks. If you omit this parameter, the default, "root", is used. Applies to 3-DNS Controllers, BIG-IP Controllers, and EDGE-FX Caches.

Hardware redundancy

If you have hardware-redundant 3-DNS Controllers and BIG-IP Controllers, you must configure the interface sub-statement for the 3-DNS Controller to work properly with BIG-IP Controllers in Active-Active mode. This sub-statement is also required in using the standby BIG-IP Controller or 3-DNS Controller for probing.

Table 22 Hardware redundancy sub-statements
Parameter Description
interface Indicates the start of the interface sub-statement.
address Specifies the IP address of both network interface cards, on separate lines. Applies to 3-DNS Controllers and BIG-IP Controllers.

Factories

With 3-DNS Controllers, BIG-IP Controllers, and EDGE-FX Caches, you can change the number and types of probing factories by using the factories sub-statement. If you omit this sub-statement, the defaults are used. For more information on probing, see Chapter 3, big3d Agent, in the 3-DNS Controller Reference Guide.

Table 23 Factories sub-statements
Parameter Description
factories Indicates the start of the factories definition. Applies to 3-DNS Controllers and BIG-IP Controllers.
prober Specifies the number of prober factories to use.
discovery Specifies the number of discovery factories to use.
snmp Specifies the number of SNMP factories to use. Note that you must use an SNMP factory to collect metrics from an EDGE-FX Cache.
hops Specifies the number of hops factories to use.

SNMP settings

The snmp sub-statement is valid for hosts and EDGE-FX Caches only. This sub-statement instructs the big3d agent to use an SNMP agent on the host or cache to collect additional metrics information.

If you need help configuring the SNMP agent on the EDGE-FX Cache, refer to the EDGE-FX Cache Administrator Guide. If you need help configuring the SNMP agent on the host, refer to the documentation provided with the host.

Table 24 SNMP sub-statements
Parameter Description
snmp Specifies the start of an SNMP definition. Applies to hosts and EDGE-FX Caches only.
agent Specifies the SNMP agent type. If you omit this parameter, the big3d agent uses the generic SNMP agent. Applies to hosts and EDGE-FX Caches only.
port Specifies the port the SNMP agent runs on. Applies to hosts and EDGE-FX Caches only.
community Specifies the password for basic SNMP security and for grouping SNMP hosts. Enclose this string in quotation marks. Applies to hosts and EDGE-FX Caches only.
timeout Specifies the amount of time (in seconds) for the timeout. The default is appropriate in most cases. If you are contacting a host through a very slow network, you can try increasing the timeout and retries values to improve performance. However, the problem with increasing these values is that a host that is down may hold up other SNMP responses for an excessive amount of time. Applies to hosts only.
retries Specifies the number of times requests should be retried. The default is appropriate in most cases. If you are contacting a host through a very slow network, you can try increasing the timeout and retries values to improve performance. However, the problem with increasing these values is that a host that is down may hold up other SNMP responses for an excessive amount of time. Applies to hosts only.
version Specifies the SNMP agent version number. Applies to hosts only.

Virtual server definitions

Part of defining a BIG-IP Controller, EDGE-FX Cache, or host is defining the virtual servers that the server manages. After you define a virtual server here (including specifying the address and port), you can use this virtual server in a wideip definition.

Table 25 Virtual server definitions
Parameter Description
vs Indicates the start of a virtual server definition.
address Specifies the IP address of the virtual server. Note that the virtual server's address must be listed first, before port or service values.
port or service Specifies the virtual server's port number or service name. You can add the port number, preceded by a colon, on the same line as the virtual server's address, or you can enter it on the next line. You can use the service name if it is a WKS (well known service) and you enclose it in quotation marks.
limit Specifies resource thresholds for the virtual server. Note that if a virtual server reaches a limit, the virtual server is marked as unavailable for load balancing.
depends_on Specifies the IP address and port of other virtual servers that must also be available for load balancing (up status) before the 3-DNS Controller uses this virtual server for load balancing.
probe_protocol Specifies the protocol to use for probing this virtual server: ICMP, UDP, or TCP. Note that for host virtual servers you cannot use UDP.
translate Specifies that iQuery packets sent to the BIG-IP Controller include translated IP addresses (required if the packets must pass through a firewall). When you use this keyword, you must then include address and port/service information for the translated IP addresses. Applies to BIG-IP Controllers only.

The wide IP statement

The wideip statement defines a wide IP. A wide IP maps a domain name to a load balancing mode and a set of virtual servers (on BIG-IP Controllers, EDGE-FX Caches, and/or other host machines).

Syntax for the wideip statement

The wideip statement uses the following syntax.

Figure 17 Syntax for the wideip statement

 wideip {    
address <ip_address>
port <port_number> | <"service name">
[ ttl <number> ]
[ persist < yes | no > ]
[ persist_ttl <number> ]
name <"domain_name">
[ alias <"alias_name"> ]
[ port_list <port_number> <port_number> ... ]
[ qos_coeff {
rtt <number>
hops <number>
completion_rate <number>
packet_rate <number>
vs_capacity <number>
topology <number>
kbps <number>
} ]
[ pool_lbmode <rr | ratio | ga | random | topology>
[ ecv {
protocol <none | ftp | http | https>
file_name <string>
user <string>
password <string>
hashed_password <string>
scan_level <none | all | first>
transfer_amount <number>
connection_timeout <number>
transfer_timeout <number>
} ]
pool {
name <"pool_name">
[ ttl <number> ]
[ ratio <number> ]
[ last_resort <yes | no>
[ check_static_depends < yes | no > ]
[ check_dynamic_depends < yes | no > ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
} ]
[ type <A | NS | CDN>
[ CDN <string> ]
[ CNAME <canonical name> ]
[ ZNAME <zone name> ]
[ ratio <pool_ratio> ]
[ dynamic_ratio < yes | no > ]
[ rr_ldns < yes | no > ]
[ rr_ldns_limit <number> ]
[ preferred < completion_rate | ga | hops | leastconn |
packet_rate | qos | random | ratio | return_to_dns | rr |
rtt | topology | vs_capacity | null | static_persist | kbps> ]
[ alternate < ga | null | random | ratio | return_to_dns | rr |
topology | packet_rate| leastconn | vs_capacity |
static_persist> ]
[ fallback < completion_rate | ga | hops | leastconn |
packet_rate | qos | random | ratio | return_to_dns | rr |
rtt | topology | vs_capacity | null | static_persist | kbps> ]
address <vs IP address:port> [ratio <weight>]
}
}

Figure 18 shows an example of a valid wideip statement.

Figure 18 Example syntax for the wideip statement

 wideip {    
address 192.168.102.50
service "smtp"
name "mx.wip.domain.com"
alias "mail.wip.domain.com"
pool_lbmode ratio
pool {
name "pool_1"
ratio 3
limit {
kbytes_per_second 10000
}
preferred rtt
alternate random
address 192.168.101.50
address 192.168.102.50
address 192.168.103.50
}
pool {
name "pool_2"
ratio 1
limit {
kbytes_per_second 10000
}
preferred ratio
address 192.168.104.50 ratio 2
address 192.168.105.50 ratio 1
}
}

Definition of wideip sub-statements

Wide IP sub-statements define groups of virtual servers to be load balanced, and they assign load balancing characteristics, such as the load balancing mode, to each group.

Address information

The address information sub-statements specify the IP address, name, and alias of the wide IP. They also specify the pool of virtual servers that the wide IP load balances.

Table 26 Address information sub-statements
Parameter Description
address Specifies the IP address registered with InterNIC that corresponds to the wide IP name. This IP address is also listed as the A record in the zone file for the domain.
port or service Specifies the default port number or service name for the wide IP. You can use the service name if it is a well known service (WKS) and you enclose it in quotation marks.
name Specifies the fully qualified domain name for the wide IP (for example, "www.wip.domain.com"). You must enclose all names in quotation marks.
alias Specifies an alternate name for the wide IP. You must enclose all names in quotation marks. Alias names are treated the same as the domain name. You can specify up to 200 alias names for each wide IP.

Load balancing sub-statements

The load balancing sub-statements denote the general load balancing attributes for all pools in the wideip.conf file.

Table 27 Load balancing sub-statements
Parameter Description
ttl Specifies the amount of time (in seconds) that the A record is used by the LDNS after resolving the wide IP. This is the TTL associated with the A record as specified by RFC 1035.
persist Specifies whether to maintain a persistent connection between an LDNS and a particular virtual server in the wide IP (rather than load-balancing the connection to any available virtual server).
persist_ttl Specifies the number of seconds to maintain a persistent connection between an LDNS and a particular virtual server in this wide IP; this setting is valid only if you have configured the persist parameter.
port_list Specifies a list of ports that must be available before the 3-DNS Controller can send connections to the specified address.
qos_coeff Specifies the relative weighting for each load balancing method in calculating the Quality of Service (QOS) mode. Before you adjust any QOS coefficients, you may want to review Chapter 7, Additional Load Balancing Options, in the 3-DNS Controller Administrator Guide.
pool_lbmode Specifies the load balancing mode to use to balance requests over all pools.
ecv Specifies an extended content verification (ECV) monitor for a virtual server in a pool.
protocol Specifies the protocol to use for the ECV. You can use only http, https, or ftp. Use only with the ecv sub-statement.
file_name Specifies the name of the object to retrieve. Use only with the ecv sub-statement.
user Specifies the user name that you use to log in to the service. Use only with the ecv sub-statement.
password Specifies the password that corresponds the user account. Use only with the ecv sub-statement.
hashed_password Specifies the password in encrypted characters. Use only with the ecv sub-statement.
scan_level Specifies whether you want to scan just through the configured wide IP names, or through the wide IP names and aliases. Use only with the ecv sub-statement.
transfer_amount Specifies the number of bytes to transfer. Use only with the ecv sub-statement.
transfer_timeout Specifies the maximum amount of time the file information transfer should take. Use only with the ecv sub-statement.
connection_timeout Specifies the maximum abount of time to connect to a service. Use only with the ecv sub-statement.

Pool sub-statements

The pool sub-statements define the virtual servers, and the load balancing modes within the pool, that the 3-DNS Controller uses to respond to DNS requests. Note that you can have one or more pools in a wide IP definition.

Table 28 Pool sub-statements
Parameter Description
pool Indicates the start of the pool definition for this wide IP. A pool is a set of virtual servers defined and owned by a BIG-IP Controller, EDGE-FX Cache, or host machine.
name As part of a pool definition, defines the name of the pool. All names must be enclosed in quotation marks.
ttl Specifies the amount of time (in seconds) that the A record is used by the LDNS after resolving the wide IP. This is the TTL associated with the A record as specified by RFC 1035.
ratio As part of a pool definition, ratio specifies the default weighting to use, with respect to other pool types, when the pool_lbmode is ratio.
last_resort Specifies whether the 3-DNS Controller directs LDNS requests to this pool when no other pools in the wide IP successfully respond to the request. The default setting is no.
check_static_depends Specifies whether the 3-DNS Controller checks availability before returning a virtual server.
check_dynamic_depends Specifies whether the 3-DNS Controller checks paths before returning a virtual server.
type Specifies the type of pool. The default is A. However, you can specify NS if you want to redirect LDNS requests to other name servers. You can also use CDN to redirect LDNS requests to a CDN provider in the cdn.inc file.
cdn Specifies the name of the CDN provider to redirect LDNS requests to, as listed in the cdn.inc file. Use this attribute only if you specify the pool type as CDN.
cname Specifies the canonical name (cname) for the pool. Use this attribute with the pool type NS or CDN to redirect LDNS requests to a CDN provider. Enclose the cname in quotation marks.
zname Specifies the zone name (zname), or domain name, for the CDN pool. Use this attribute with the pool type CDN. Enclose the zname in quotation marks.
dynamic_ratio Specifies whether the 3-DNS Controller treats QOS scores as ratios, and uses each server in proportion to the ratio determined by the QOS calculation. The default is no.
rr_ldns Specifies whether the 3-DNS Controller returns a list of available virtual servers available for load balancing to a client and stores the list in the browser cache. The default is no, which specifies that the 3-DNS Controller returns only one A record per query.
rr_ldns_limit The maximum number of A records to return when rr_ldns is set to yes. You can enter a value between 0 and 16. The default is 0, which specifies that the 3-DNS Controller returns the IP addresses of all (up to 16) available virtual servers.
preferred Specifies the load balancing mode to use for the specified pool. Each acceptable value is described in the next table. The default is rr.
alternate Specifies the load balancing mode to use for the specified pool if the preferred mode fails. The default is rr. Also see the description of default_alternate, a globals sub-statement, on page 11 .
fallback Specifies the load balancing mode to use for the specified pool if the alternate mode fails. If the fallback mode fails, the 3-DNS Controller returns the request to DNS. The default is return_to_dns. Also see the description of default_fallback, a globals sub-statement, on page 11 .
address As part of a pool definition, address specifies the IP address of each virtual server in the pool. You can use the same virtual server in multiple pools, but not within the same pool.
port Specifies a specific port to use for the specified virtual server. This sub-statement is optional. A port specified here overrides the wide IP's port setting. If a port is not specified here, the wide IP's port value is assumed.
ratio As part of a virtual server's address specification, ratio defines the default weighting to use with respect to all virtual servers in this pool when the ratio load balancing mode is employed. The default is 1.

Load balancing modes

The load balancing sub-statements specify the load balancing modes to use for the wide IP in this order:

  • The 3-DNS Controller attempts to load balance requests using the preferred mode.
  • If the preferred mode fails, the 3-DNS Controller tries the alternate mode.
  • If the alternate mode fails, the 3-DNS Controller tries the fallback mode.
  • If the fallback mode fails, the request is returned to DNS.
    DNS attempts to resolve the request based on the contents of the zone files.

As noted in Table 29 , not all modes are valid for the alternate sub-statement. Also note that the alternate and fallback sub-statements accept two additional values, return_to_dns and null.

If you do not specify a load balancing mode within a pool, the wide IP uses the default load balancing mode defined in the globals statement (see page 7 ).

Table 29 Load balancing mode sub-statements
Parameter Description
completion_rate Sends each new connection to the server that has the fewest number of dropped packets. Valid in a preferred or fallback sub-statement.
global_availability (ga) Distributes connections to a list of servers, always sending a connection to the first available server in the list.
hops Sends each new connection to the server that has the fewest number of network hops between the server and the client LDNS. Valid in a preferred or fallback sub-statement.
leastconn Sends each new connection to the server that currently hosts the fewest current connections.
null Bypasses the current load balancing method and forces the 3-DNS Controller to use the next load balancing method or, if it has cycled through all load balancing sub-statements for the pool, to the next pool. Valid in an alternate or fallback sub-statement.
packet_rate Sends each new connection to the server that is managed by a BIG-IP Controller currently handling the least amount of network traffic (determined by the fewest number of packets currently processed by the controller).
qos Takes these performance factors into account when determining how to distribute connections: hops, packet rate, completion rate, round trip time, kbps, virtual server capacity, and topology. You can configure how much emphasis to place on each performance factor, or you can configure the QOS mode to treat all factors as being equally important. Valid in a preferred or fallback sub-statement.
random Distributes each new connection to a server chosen at random from the wide IP set of virtual servers.
ratio Distributes new connections across servers in proportion to a user-defined ratio.
return_to_dns Returns the resolution request to DNS, preventing the 3-DNS Controller from using the next load balancing method or using the next available pool.
rr Distributes connections evenly across all servers, passing each new connection to the next server in line.
rtt Sends each new connection to the server that demonstrates the fastest round trip time between the server and the client LDNS. Valid in a preferred or fallback sub-statement.
topology Distributes connections based on the proximity of an LDNS to a particular data center.
static_persist Distributes connections to a virtual server based on IP address only. The 3-DNS Controller always returns the same virtual server, if the virtual server is available.
kbps Distributes connections to the virtual server with the lowest kilobytes per second throughput rate.

Use the following equation to configure the QOS load balancing mode:

A (1/packet rate) + B (1/rtt) + C (completion rate) + D (topology) + E (1/hops) + F (1/kbps) + G (vs_capacity)

The topology statement

The topology statement implements a form of wide-area IP filtering, based on the geographic attributes of the DNS message. For example, you can specify that requesting LDNS clients in North America are allowed access to data centers in North America, but not allowed access to data centers in South America.

By including a topology statement in your wideip.conf file, you can use the topology load balancing mode, both on its own and as part of the QOS mode.

For more information on using the Topology load balancing mode, see Chapter 3, Configuring a Globally Distributed Network, and Chapter 4, Configuring a Content Delivery Network, in the 3-DNS Controller Administrator Guide. For more information on topology in general, see Chapter 10, Topology, in the 3-DNS Controller Reference Guide.

Syntax for the topology statement

The topology statement uses the following syntax.

Figure 19 Syntax for the topology statement

 topology {     
longest_match <yes | no>

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

Definition of topology sub-statements

The topology sub-statements define the topology records that the 3-DNS Controller uses for Topology load balancing.

Table 30 Topology sub-statements
Parameter Description
longest_match In cases where there are topology records that match a particular IP address, longest_match specifies whether the 3-DNS Controller selects the record that is most specific, and thus has the longest mask. The default is yes.
server Specifies the location of the virtual servers.
ldns Specifies the location of the LDNS making the name resolution request.
pool Specifies a wide-IP pool for load balancing. Note that pool names can be duplicated across wide IPs. Use this for server in a topology record.
datacenter Specify a data center for load balancing. Use this for server in a topology record.
continent Specify one of these continents for load balancing: "North America", "South America", "Europe", "Asia", "Australia", "Africa", or "Antarctica". Use this for ldns in a topology record.
country Specify a country for load balancing using one of the two-letter country codes found in the file /var/3dns/include/net.ccdb. Use this for ldns in a topology record.
isp.AOL For local DNS servers only, specify the Internet service provider, America Online (AOL).
! The not ( ! ) operator negates the meaning of an element in a topology record.
score Specifies the relative weight, or score, for the topology record, which allows the 3-DNS Controller to evaluate the best resolution option for a DNS request.

Access control lists

You can now create access control lists (ACLs) that contain a group of LDNS IP addresses whose paths the 3-DNS Controller will not probe. The three different types of ACLs are:

  • Prober
  • Hops
  • Discovery

Syntax for the access control lists

The access control lists use the following syntax.

Figure 20 Syntax for the access control lists

 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"
region "probe_acl"
<ldns cidr>
<ldns cidr>
}
region {
name "hops_acl"
<ldns cidr>
<ldns cidr>
}
region {
name "discovery_acl"
<ldns cidr>
<ldns cidr>
<ldns cidr>
}
}

Definition of the access control list sub-statements

The access control list sub-statements define local DNS servers that should not be probed.

Table 31 Access control list sub-statements
Parameter Description
actions Include, but do not modify this sub-statement.
region_db ACL Specifies that ACLs are being created.
region Specifies groups of CIDRs by probe type.
name Specifies the name of the ACL.
probe_acl The 3-DNS Controller restricts any big3d agent from probing the defined group of LDNS servers.
hops_acl The 3-DNS Controller restricts any big3d agent from tracerouting the defined group of LDNS servers
discovery_acl The 3-DNS Controller restricts any big3d agents from performing port discovery on the defined group of LDNS servers

Comments

You can insert comments anywhere you would otherwise see white space in the 3-DNS Controller configuration file.

Syntax

Note that the comment syntax depends on the environment in which you use the configuration file.

Figure 21 Syntax for comments

 /* This is a 3-DNS comment as in C */    
// This is a 3-DNS comment as in C++
# This is a 3-DNS comment as in common UNIX shells and Perl

Definition and usage

The format for comments varies by programming language; each format is described below. To avoid comment nesting problems, we recommend that you use only one comment style in your wideip.conf file. However, all styles may be used in a single wideip.conf file.

C style comments

C style comments start with the slash character, followed by the asterisk character (/*), and end with the asterisk character, followed with the slash character (*/). Because the comment is completely delimited with these characters, a comment can span multiple lines.

Note that C style comments cannot be nested. For example, the following syntax is not valid because the entire comment ends with the first */.

Figure 22 Syntax for C style comments

 /* This is the start of a comment.    
This is still part of the comment.
/* This is an incorrect attempt to nest a comment. */
This is no longer in any comment. */

C++ style comments

C++ style comments start with two slash characters (//) and are no longer than one line in length. To have one logical comment span multiple lines, each line must start with the // pair.

Figure 23 Syntax for C++ style comments

 // This is the start of a comment. The next line    
// is a new comment line, even though it is
// logically part of the previous comment.

Shell style comments

Shell style (also known as Perl style) comments start with the number character ( # ) and are no longer than one line in length.

Figure 24 Syntax for shell style comments

 # This is the start of a comment. The next line    
# is a new comment line, even though it is logically
# part of the previous comment.

Understanding cur_values

You may notice several cur_values in your wideip.conf file. The purpose of cur_values is to pre-load the database with previously collected statistics and metrics. The collected statistics and metrics are useful if you want to quickly restart a 3-DNS Controller without a temporary loss of intelligence.

You may notice cur_ values in server, vs, path, or wideip definitions. The cur_values parameters show the status of the servers, virtual servers, local DNS server paths, and wide IPs. Examples of cur_values for each type of definition follow.

Warning: Do not edit the cur_values statements unless you are a very experienced 3-DNS Controller user, or you are instructed to do so by your vendor.

Server definition cur_values

Figure 25 Example of cur_ values in a server definition

 // New York BIG-IP Controller    
server {
type bigip
address 192.168.101.40
cur_packet_rate 139
cur_ok 1
[virtual server definitions]
}

In the example shown in Figure 25 , the cur_ values parameters are defined as indicated in the following table.

Table 32 Description of cur_values in a server definition
Parameter Description
cur_packet_rate Indicates the number of packets per second sent during the last sample period.
cur_ok Indicates the state of the specified server. The options are: 1 (Up), 2 (Down), 3 (Waiting), 4 (Alert), and 5 (Panic).

Virtual server definition cur_values

Figure 26 Example of cur_ values in a virtual server definition

 vs {    
address 192.168.102.50:80
cur_serv_cnt 1
cur_connections 0
cur_picks 39
cur_refreshes 783
}

In the example shown in Figure 26 , the cur_ values parameters are defined as indicated in the following table.

Table 33 Description of cur_ values in a virtual server definition
Parameter Description
cur_nodes_up Indicates the number of active servers serving the specified virtual server.
cur_connections Indicates the number of connections to the specified virtual server.
cur_picks Indicates the number of times the specified virtual server was returned by the 3-DNS Controller.
cur_refreshes Indicates the number of times the server and connection counts were refreshed with new data.

Local DNS server paths cur_values

Figure 27 Example of cur_ values in a path definition

 path {    
address 10.25.50.100 // LDNS
cur_rtt 102382
cur_completion_rate 10000
cur_picks 239
cur_accesses 302
}

In the example shown in Figure 27 , the cur_ values parameters are defined as indicated in the following table.

Table 34 Description of cur_ values in a path definition
Parameter Description
cur_rtt Indicates the round trip time (RTT), which is a calculation of the time (in microseconds) that the specified machine takes to respond to a probe issued by the 3-DNS Controller.
cur_completion_rate Indicates the percentage of completed packets versus lost packets, using this equation:
[1 - (packets received / sent)] X 10000.
cur_picks Indicates the number of times this path's data resulted in the virtual server being chosen for a connection. This only applies if a wide IP is doing dynamic load balancing (using path data).
cur_accesses Indicates the number of times this path was considered when performing dynamic load balancing.

Wide IP definition cur_values

Figure 28 Example of cur_ values in a wide IP definition

 wideip {    
address 192.168.102.70
name "www.domain.com"
port 80
cur_preferred 143982
cur_alternate 108090
cur_fallback 130094
cur_returned_to_dns 23872
[virtual server definitions]
}

In the example shown in Figure 28 , the cur_ values parameters are defined as indicated in the following table.

Table 35 Description of cur_ values in a wide IP definition
Parameter Description
cur_preferred Indicates the number of times the specified wide IP was resolved by the preferred load balancing mode.
cur_alternate Indicates the number of times the specified wide IP was resolved by the alternate load balancing mode.
cur_fallback Indicates the number of times the specified wide IP was resolved by the fallback load balancing mode.
cur_returned_to_dns Indicates the number of times the specified wide IP did not find a suitable virtual server to return using the preferred, alternate, or fallback load balancing modes. In this situation, the 3-DNS Controller returns the wide IP key (fallback address) as specified in the zone file.

To find out how many times the 3-DNS Controller received resolution requests for this wide IP, add the values for cur_preferred, cur_alternate, and cur_fallback.