Manual Chapter : 3-DNS Reference Guide version 4.2: 3-DNS Configuration Files

Applies To:

Show Versions Show Versions

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

  • 4.2 PTF-10, 4.2 PTF-09, 4.2 PTF-08, 4.2 PTF-07, 4.2 PTF-06, 4.2 PTF-05, 4.2 PTF-04, 4.2 PTF-03, 4.2 PTF-02, 4.2 PTF-01, 4.2.0
Manual Chapter

 

A

3-DNS Configuration File


 

Overview of the 3-DNS configuration file

The 3-DNS configuration file describes a network's data centers, servers (3-DNS systems, BIG-IP systems, EDGE-FX Caches, GLOBAL-SITE systems, and hosts), virtual servers, and the wide IPs and pools used for load balancing. The 3-DNS configuration file is called wideip.conf. Note that when you use the browser-based Configuration utility, all components of the 3-DNS configuration file are automatically generated and parsed.

Note: If you use the Configuration utility to configure the 3-DNS, and you want to see the wideip.conf configuration for a specific component, click the Configuration View button when you see it in the Configuration utility.

The wideip.conf file consists of two types of information: statements and comments. The wideip.conf file should include at least the following definitions.

  • A datacenter statement
  • At least one server statement defining a 3-DNS
  • At least one virtual server, which is defined as part of a BIG-IP, EDGE-FX Cache, or host server statement
  • A wideip statement, for load balancing

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

  • If the file cannot be parsed, 3dnsd does not start.
  • If the file can be parsed, the 3-DNS reverts to standard DNS behavior.

To open the 3-DNS configuration 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 on 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 servers in your network, and another include file that defines all the wide IPs that are used for load balancing. 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. 3-DNS automatically creates and implements include files whenever you configure your network setup using the Configuration utility.

Note: When the wideip.conf file is generated by the Configuration utility, any comments you incorporated from the command line are deleted.

Syntax for include files

Use the following syntax when incorporating include files into a wideip.conf file.

Figure A.1 Syntax for include files

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

Definitions of include statements

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

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.

"/config/3dns/include"

include root_out

Specifies the root directory in which to dump include files.

"/config/3dns/include"

include global

Specifies the name of the file that contains the globals statement.

"globals.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 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 server statements.

"3dns.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 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.

"ldns.inc"

include region

Specifies the name of the file that contains any region definitions statements.

"region.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.

"/config/3dns/
.prodruledb/manifest"

Working with statements

A top-level 3-DNS 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.
  • globals
    The globals statement defines system-level settings for any 3-DNS configuration options and sets the defaults for other statements.
  • server
    The server statement defines a 3-DNS, a BIG-IP and its virtual servers, an EDGE-FX Cache and its virtual servers, a GLOBAL-SITE, or a host machine and its virtual servers (if applicable).
  • datacenter
    The datacenter statement defines the group of 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, and host systems that reside in a single physical location.
  • sync_group
    The sync_group statement defines the group of 3-DNS systems that synchronize their configuration settings and metrics data.
  • wideip
    The wideip statement defines a wide IP and its pools. A wide IP maps a domain name to a load balancing mode and a set of virtual servers (on a BIG-IP, EDGE-FX Cache, or host, or any combination thereof).
  • topology
    The topology statement contains the topology records that facilitate the topology load balancing mode (on its own and as part of the Quality of Service mode). Note that the topology statement is the preferred location for topology configuration information.

Syntax rules

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

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

    • globals
    • most include statements (except the include ldns statement)
    • server
    • datacenter
    • sync_group
    • wideip
    • include ldns
  • Address and port specification
    For virtual servers (on a BIG-IP, an EDGE-FX Cache, or a host), the port specification must immediately follow the IP address specification. For the port specification, you can use either a port number, or a service name. For example, you can use "http" instead of 80 to represent the HTTP protocol. The address and port specification can take any of the following forms:

    address <ip_addr>:<port>

    address <ip_addr>
    port <port>

    address <ip_addr>
    service <"http">

  • Current values
    You may notice several current values (indicated by cur_"value") in the 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 current values, on page A-43 .

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
    These brackets ( [ ] ) enclose optional parameters.
  • Brackets
    These brackets ( { } ) include the options available in a statement or sub-statement.
  • 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, 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 does not find a globals statement in the configuration file, the 3-DNS uses a globals block, with each option set to its default.

If you use a globals sub-statement more than once, the 3-DNS 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 uses the value 50.

Figure A.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 A.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> ]
[ drain_requests < 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 > ]
[ 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 <number> ]
[ 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 > ]
[ rtt_allow_probe < yes | no > ]
[ rtt_allow_hops < yes | no > ]
[ rtt_allow_frag < yes | no > ]
[ rtt_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 A.4 shows an example of a valid globals statement.

Figure A.4 Example syntax for the globals statement

globals {  
prober 192.168.101.2 // Default prober is New York 3-DNS
encryption yes // Encrypt iQuery
path_ttl 2400 // Extend the life of path metrics
}

Definition of globals sub-statements

The globals sub-statements and their parameters are described in the following sections.

Synchronization

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

Synchronization sub-statement

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 and a BIG-IP is encrypted.

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 checks the availability of virtual servers or paths before the system sends a connection to a virtual server.

Dependencies sub-statement

Parameter

Description

Default

check_static_depends

Specifies whether to check the availability of virtual servers on BIG-IP, EDGE-FX Cache, and host systems. Change this option to no if you want to test your configuration. Setting this option to no forces 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 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

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

LDNS persistence sub-statement

Parameter

Description

Default

persist_ldns

Specifies whether the 3-DNS records in its cache the IP addresses of all LDNS machines that make resolution requests.

yes

Load balancing persistence

The load balancing persistence sub-statements define how the 3-DNS load balances persistent connections.

Load balancing persistence sub-statements

Parameter

Description

Default

default_persist_ttl

Specifies the length of time the 3-DNS retains persistent connections 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

drain_requests

Specifies whether load-balanced persistent connections are allowed to remain connected, until the TTL expires, when you disable a pool. When set to no, the connections are terminated immediately when the pool is disabled. This variable affects the persist setting in the load balancing sub-statement. See Table A.28, on page A-34 , for more information.

yes

Periodic task intervals

The periodic task interval sub-statements define the frequency at which the 3-DNS refreshes the metrics information it collects.

Periodic task interval sub-statements

Parameter

Description

Default

timer_get_3dns_data

Specifies how often the 3-DNS retrieves performance data for other 3-DNS systems in the sync group. You can enter a value between 1 and 4294967295 seconds.

20

timer_get_server_data

Specifies how often the 3-DNS refreshes 3-DNS, BIG-IP, EDGE-FX Cache, and GLOBAL-SITE information. You can enter a value between 1 and 4294967295 seconds.

20

timer_get_host_data

Specifies how often the 3-DNS refreshes other host machine information. You can enter a value between 1 and 4294967295 seconds.

90

timer_get_vs_data

Specifies how often the 3-DNS refreshes virtual server information. You can enter a value between 1 and 4294967295 seconds.

30

timer_get_path_data

Specifies how often the 3-DNS refreshes path information (for example, round trip time or ping packet completion rate). You can enter a value between 1 and 4294967295 seconds.

120

timer_get_ecv_data

Specifies how often the 3-DNS refreshes ECV information. You can enter a value between 5 and 4294967295 seconds.

90

timer_get_trace_data

Specifies how often the 3-DNS retrieves traceroute data (the traceroute utility collects information on router hops between each data center and each LDNS). You can enter a value between 1 and 4294967295 seconds.

60

timer_check_keep_alive

Specifies how often the 3-DNS queries remote 3-DNS, BIG-IP, EDGE-FX Cache, and GLOBAL-SITE systems. This value determines how often 3dnsd sends hello packets to each big3d agent in its configuration. You can enter a value between 1 and 4294967295 seconds.

60

timer_persist_cache

Specifies how often the 3-DNS writes the wideip.conf file from memory. You can enter a value between 1 and 4294967295 seconds.

300

Data time-outs

The data time-out sub-statements set the amount of time for which metrics information is considered valid. After a time-out is reached, the 3-DNS refreshes the information.

Data time-outs sub-statements

Parameter

Description

Default

default_ttl

Specifies the default number of seconds that the 3-DNS considers the wide IP A record to be valid. If you do not specify a wide IP TTL value when you define a wide IP pool, the wide IP definition uses the default_ttl value.

30

3dns_ttl

Specifies the number of seconds that the 3-DNS considers performance data for the other 3-DNS systems to be valid.

60

bigip_ttl

Specifies the number of seconds that the 3-DNS can use BIG-IP information for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
bigip_ttl is greater than timer_get_server_data. A 2:1 ratio is the optimal setting for this relationship.

60

edgefx_ttl

Specifies the number of seconds that the 3-DNS can use EDGE-FX Cache information for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
edge_ttl is greater than timer_get_server_data. A 2:1 ratio is the optimal setting for this relationship.

60

host_ttl

Specifies the number of seconds that the 3-DNS can use host information for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
host_ttl is greater than timer_get_host_data.

240

vs_ttl

Specifies the number of seconds that the 3-DNS can use virtual server information (data acquired from a BIG-IP, EDGE-FX Cache, or host about a virtual server) for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
vs_ttl is greater than timer_get_vs_data.

120

path_ttl

Specifies the number of seconds that the 3-DNS can use path information for name resolution and load balancing. You can enter a value between 1 and 4294967295. The following relationship should be maintained:
path_ttl is greater than timer_get_vs_data.

2400

trace_ttl

Specifies the amount of time (in seconds) that the 3-DNS 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 collects path information.

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 big3d agent to the LDNS to determine the path information between those two systems. You can type a value between 1 and 25.

3

rtt_packet_length

Specifies the length of packets, in bytes, to send from the big3d agent 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 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, and dns_rev protocols.

icmp

Resource limits

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

Resource limits sub-statements

Parameter

Description

Default

rx_buf_size

Specifies the maximum amount of socket buffer data memory the 3-DNS can use when receiving iQuery data. You can enter a value between 8192 and 65536.

49152

tx_buf_size

Specifies the maximum amount of socket buffer data memory the 3-DNS can use when transmitting iQuery 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 QOS equation shown in Figure A.5 , the Quality of Service mode compares paths between the LDNS and each virtual server included in the wideip statement. When you specify the Quality of Service load balancing mode, the 3-DNS load balances each new connection to the virtual server associated with the best (highest) path score.

Figure A.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 QOS score computation are defined in the globals statement, but you can override them within a wideip statement.

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.

50

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 packet rate when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295.

1

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.

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 respects virtual server status when load balancing switches to the specified fallback mode.

no

fb_respect_acl

Determines whether the 3-DNS imposes topology access control when load balancing switches to the specified fallback mode.

no

aol_aware

Determines whether the 3-DNS recognizes local DNS servers that belong to the Internet service provider, America Online (AOL).

yes

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 itself, but you can use other network servers.

Prober sub-statement

Parameter

Description

Default

prober

Specifies the default prober for collecting host status, and is usually the 3-DNS IP address. Using this sub-statement is not necessary if the 3-DNS does not manage host virtual servers. When this option is set to 0, the system's IP address is the implied value. This sub-statement can be overridden within the server statement.

0.0.0.0

Buffer size

The buffer size sub-statements specify the maximum amount of UDP data that the 3-DNS can receive for wide IP DNS messages.

Buffer size sub-statements

Parameter

Description

Default

resolver_rx_buf_size

Specifies the wide IP 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 wide IP send buffer size.

24576

Reaping

The 3-DNS stores local DNS server 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. 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.

Reaping sub-statements

Parameter

Description

Default

datasize_system

Specifies the amount of RAM that the 3-DNS reserves for system usage, such as non-3-DNS specific processes.

64MB

datasize_reap_pct

Specifies what percentage of memory that the 3-DNS 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 uses to send and receive iQuery traffic.

iQuery port options sub-statements

Parameter

Description

Default

use_alternate_iq_port

Determines whether the 3-DNS 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. This setting is used only by UDP-based traffic.

yes

multiplex_iq

Determines whether the 3-DNS 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 uses probing to collect path metrics. The 3-DNS then uses the metrics to make traffic distribution and load balancing decisions.

Probing sub-statements

Parameter

Description

Default

default_probe_limit

Specifies a limit on the number of times the 3-DNS 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 always uses path data even if the path's TTL expires.

no

check_dynamic_depends

Specifies that the 3-DNS 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. This parameter does not prevent the refreshing of path metrics.

yes

rtt_allow_probes

Specifies that the 3-DNS 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 should collect hops metrics when probing paths.

yes

rtt_allow_frag

Specifies that the 3-DNS should break each probe packet into smaller packets when probing paths.

no

probe_protocol

Specifies the protocol that the 3-DNS uses to probe local DNS servers. The default is icmp. The other available protocols are: dns_rev, dns_dot, udp, and tcp

icmp

The server statement

The server statement defines the characteristics associated with a particular 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, or host. A server statement contains the following information:

  • The type of server: 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, or host
  • The IP address and host name of the server
  • If the server is a BIG-IP, 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 A-25 .

Syntax for the server statement (3-DNS)

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

Figure A.6 Server statement syntax for defining a 3-DNS

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>
snmp <number>
hops <number>
ecv <number>
} ]
}

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

Figure A.7 Example syntax for defining a 3-DNS

// New York  
server {
type 3dns
address 192.168.101.2
name "3dns-newyork"
iquery_protocol udp
remote {
secure no
user "root"
}
factories {
prober 5
snmp 1
ecv 5
}
}

Syntax for the server statement (BIG-IP)

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

Figure A.8 Server statement syntax for defining a BIG-IP

server {  
type bigip
address <IP address>
[ name <"bigip_name"> ]
[ iquery_protocol [udp | tcp] ]
[ remote {
secure <yes | no>
user <"user name">
} ]
[ interface {
address <NIC IP address>
address <NIC IP address>
} ]
[ prober <ip address> ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number ]
} ]
[ factories {
prober <number>
snmp <number>
hops <number>
ecv <number>
} ]
vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ ratio <number> ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
} ]
[ depends_on {
<IP address>:<port number> //example 10.10.10.10:443
} ]
[ ratio <number> ]
[ translate {
<IP address>:<port number>
} ]
}

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

Figure A.9 Example syntax for defining a BIG-IP

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
interface {
address 192.168.101.41
address 192.168.101.42
}
# Change the number of factories doing the work at big3d
factories {
prober 6
snmp 1
hops 2
ecv 1
}
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)

This server statement syntax applies to EDGE-FX Caches only.

Figure A.10 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">
} ]
[ factories {
prober <number>
hops <number>
snmp <1> { //required
agent edgefx
version 2
community <"public">
}
} ]
vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ ratio <number> ]
[ 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 (GLOBAL-SITE)

The following server statement syntax applies to GLOBAL-SITE systems only.

Figure A.11 Example syntax for defining a GLOBAL-SITE

server {  
type gsite
address <IP address>
[ name <"gsite_name"> ]
[ iquery_protocol [ udp | tcp ] ]
[ remote {
secure <yes | no>
user <"user name">
}
[ factories {
prober <number>
hops <number>
snmp <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 12, SNMP .

Figure A.12 Server statement syntax for defining a host

server {  
type host
address <IP address>
[ name <"host_name"> ]
[ probe_protocol <tcp | icmp | 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 | dns_rev | dns_dot> ]
}
[ ratio <number> ]
[ limit {
[ kbytes_per_sec <number> ]
[ pkts_per_sec <number> ]
[ current_conns <number> ]
[ cpu_avail <number> ]
[ disk_avail <number> ]
[ mem_avail <number> ]
} ]
[ depends_on {
<IP address>:<port number> //example 10.10.10.10:443
} ]
}

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

Figure A.13 Example syntax for defining a host

server {  
type host
address 192.168.104.40
name "host-tokyo"
probe_protocol icmp
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 A.18 lists the parameters of the address information sub-statement.

Address information sub-statements

Parameter

Description

type

Indicates whether the specified server is a 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, or host.

address

Specifies the IP address of the 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, or host.

name

Specifies the name of the 3-DNS, BIG-IP, EDGE-FX Cache, GLOBAL-SITE, 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, tcp, dns_rev, or dns_dot. Applies to hosts only.

prober

Specifies the IP address of the system probing the host. This IP address points to a BIG-IP, a 3-DNS, a GLOBAL-SITE, 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 uses the prober <ip_addr> parameter defined in the globals statement. This applies to hosts only.

port

Specifies the port used to probe this host if the probe_protocol parameter is set to TCP. This applies to hosts only.

Limit settings

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

Limit sub-statement

Parameter

Description

limits

Indicates the start of the limits definition. Applies to BIG-IP systems 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

You use the remote sub-statement only if you want to specify a different login name, or specifically use SSH or RSH, on 3-DNS systems, BIG-IP systems, EDGE-FX Caches, or GLOBAL-SITE systems.

Remote connections sub-statements

Parameter

Description

remote

Indicates the start of a remote sub-statement. Applies to any of the following server types: 3-DNS, BIG-IP, GLOBAL-SITE, or EDGE-FX Cache.

secure

Specifies whether to use SSH (secure shell) or RSH (remote shell) for remote connections. The default for crypto systems is yes, which specifies that SSH is used. Non-crypto versions must use RSH instead. Applies to 3-DNS systems, BIG-IP systems, and EDGE-FX Caches. (Note that GLOBAL-SITE systems are only available as crypto systems.)

user

Specifies the "superuser" name that is used to allow a remote user to log on to the system. Enclose this name in quotation marks. If you omit this parameter, the default, "root", is used. Applies to any of the following server types: 3-DNS, BIG-IP, GLOBAL-SITE, or EDGE-FX Cache.

Hardware redundancy

If you have hardware-redundant 3-DNS or BIG-IP systems, you must configure the interface sub-statement so that the 3-DNS works properly with BIG-IP redundant systems running in Active-Active mode. This sub-statement is also required in using the standby BIG-IP or 3-DNS for probing.

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 systems and BIG-IP systems.

Factories

For any 3-DNS, BIG-IP, GLOBAL-SITE, and EDGE-FX Cache system, you can change the number and types of probing factories by using the factories sub-statement. If you omit this sub-statement, the 3-DNS uses the defaults settings specified in the globals statement. For more information on factories and probing, see Chapter 4, The big3d Agent .

Factories sub-statements

Parameter

Description

factories

Indicates the start of the factories definition. Applies to 3-DNS, BIG-IP, EDGE-FX Cache, and GLOBAL-SITE systems.

prober

Specifies the number of prober factories to use. The default setting is 5.

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. The default setting is 1.

hops

Specifies the number of hops factories to use. The default setting is 0.

ecv

Specifies the number of ECV factories to use. The default setting is 5.

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 the cache to collect additional metrics information.

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

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, EDGE-FX Cache, or host is defining the virtual servers that the server manages. You can then use the virtual servers that you define as part of the server statement in a wideip definition for load balancing.

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 uses this virtual server for load balancing.

probe_protocol

Specifies the protocol to use for probing this virtual server: ICMP or TCP.

translate

Specifies that iQuery packets sent to the BIG-IP 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 virtual servers only.

The datacenter statement

A datacenter statement defines the group of 3-DNS systems, BIG-IP systems, EDGE-FX Caches, GLOBAL-SITE systems, and hosts that reside in a single physical location.

Syntax for the datacenter statement

The datacenter statement uses the following syntax.

Figure A.14 Syntax for the datacenter statement

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

Figure A.15 shows an example of a valid datacenter statement.

Figure A.15 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
gsite 192.168.101.70
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.

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 in this data center.

bigip

Specifies the IP address of a BIG-IP in this data center.

edgefx

Specifies the IP address of an EDGE-FX Cache in this data center.

gsite

Specifies the IP address of a GLOBAL-SITE 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 systems that synchronize their configuration settings and metrics data. You configure this statement in the wideip.conf file of the principal 3-DNS.

Syntax for the sync_group statement

The sync_group statement uses the following syntax.

Figure A.16 Syntax for the sync_group statement

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

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

Figure A.17 shows an example of a valid sync_group statement.

Figure A.17 Example syntax for the sync_group statement

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

Definition of sync_group sub-statements

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

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 in the group. First list the IP address of the principal system. Then list all other 3-DNS systems, in the order that they should become a principal system, if the previously listed principal 3-DNS fails. Note that there can only be one principal system in a sync group at any time.

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.

Syntax for the wideip statement

The wideip statement uses the following syntax.

Figure A.18 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>
search_string <"string">
} ]
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 | CNAME >
[ cname <canonical name> ]
[ 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 A.19 shows an example of a valid wideip statement.

Figure A.19 Example syntax for the wideip statement

wideip {  
address 192.168.102.50
service "http"
name "http.wip.domain.com"
alias "store.wip.domain.com"
alias "*.wip.domain.com
alias "http.wip.domain.???"
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

The wideip 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.

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. Note that you can use two wildcard characters, the asterisk ( * ) and the question mark ( ? ), in wide IP names. The asterisk ( * ) can represent multiple characters, and the question mark ( ? ) can represent a single character. Any of the following examples are valid for the name or alias parameter in a wideip statement: " www.*.com", "*.domain.com", "*.domain.???", and so on.

alias

Specifies an alternate name for the wide IP. The conventions for name also apply to alias. You can specify an unlimited number of 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.

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). Note that the variables drain_requests and default_persist_ttl, in the globals statement, affect this setting. See page A-10 for more information.

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 can send connections to the specified address.

qos_coeff

Specifies the relative weighting for each load balancing method in calculating the Quality of Service mode. Before you adjust any QOS coefficients, you may want to review Chapter 9, Working with Quality of Service, in the 3-DNS Administrator Guide.

pool_lbmode

Specifies the load balancing mode to use to balance requests over all pools.

ECV sub-statements

The ECV sub-statements define the components of an extended content verification (ECV) monitor. Use the ECV sub-statement if you want the 3-DNS to verify the presence of a file, or certain content, on the servers or virtual servers that host the content mapped to the wide IP, before the wide IP is considered up for load balancing.

ECV sub-statements

Parameter

Description

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 to 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. Note that if you use wildcard characters in the wide IP name or alias parameters, those names and aliases are ignored by the ECV scans.

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 amount of time to connect to a service. Use only with the ecv sub-statement.

search_string

Specifies a regular expression that you want the ECV monitor to locate within the scanned file.

Pool sub-statements

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

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, 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 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 checks availability before returning a virtual server in the pool. (Note that this parameter does not affect the status of the virtual server on the Virtual Server Statistics screen, in the Configuration utility, while the global variable of the same name does affect the status.)

check_dynamic_depends

Specifies whether the 3-DNS checks paths before returning a virtual server in the pool.

type

Specifies the type of pool. The default is A. You can also use CNAME to redirect LDNS requests to a CDN provider in the cdn.inc file.

cname

Specifies the canonical name (cname) for the pool. Use this attribute with the pool type CNAME to redirect LDNS requests to a name server in another network, or to a CDN provider. Enclose the cname in quotation marks.

dynamic_ratio

Specifies whether the 3-DNS 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 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 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 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 (Round Robin).

alternate

Specifies the load balancing mode to use for the specified pool if the preferred mode fails. The default is rr (Round Robin). Also see the description of default_alternate in Table A.12, on page A-15 .

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 returns the request to DNS. The default is return_to_dns. Also see the description of default_fallback in Table A.12, on page A-15

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 attempts to load balance requests using the preferred mode.
  • If the preferred mode fails, the 3-DNS tries the alternate mode.
  • If the alternate mode fails, the 3-DNS 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 A.31 , 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 A-5 ).

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 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 currently handling the least amount of network traffic (determined by the fewest number of packets currently processed by the system).

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 Quality of Service 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 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 virtual 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. You must also configure a topology statement before this load balancing mode works.

static_persist

Distributes connections to a virtual server based on IP address only. The 3-DNS always returns the same virtual server to the same client, if the virtual server is available.

vs_capacity

Distributes connections based on the overall available capacity of the virtual server. Over time all virtual servers in the pool receive connections, but the virtual server with the most capacity receives the highest percentage of connections.

kbps

Distributes connections to the virtual server with the lowest kilobytes per second throughput rate.

Use the following equation to configure the Quality of Service load balancing mode:

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

Note: For more information about load balancing modes, see Chapter 8 , Load Balancing .

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 Quality of Service mode.

For more information on using the Topology load balancing mode, see Chapter 7, Configuring a Globally Distributed Network, and Chapter 8, Configuring a Content Delivery Network, in the 3-DNS Administrator Guide. For more information on topology in general, see Chapter 13, Topology , in this guide.

Syntax for the topology statement

Figure A.20 contains examples of the syntax used in the topology statement. Note that the object names are in quotation marks.

Figure A.20 Syntax for the topology statement

topology {  
longest_match <yes | no>

// server ldns score
pool.<"pool_name"> cont.<"continent_name"> <number>
datacenter.<"dc_name"> !country.<"2-letter_code"> <number>
pool.<"pool_name"> user.<"region_name"> <number>
pool.<"pool_name"> isp."AOL" <number>
}

Note: In a topology statement, use the not operator (!)to negate the meaning of an element, as shown in the example in Figure A.20 .

Definition of topology sub-statements

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

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 selects the record that is most specific, and thus has the longest match. When longest_match is set to yes, the topology records are sorted according to the longest match criteria.

server

Specifies the location of the virtual servers.

ldns

Specifies the location of the LDNS making the name resolution request.

pool.<"pool_name">

Specifies a wide-IP pool for load balancing. Note that pool names can be duplicated across wide IPs. The name must be in quotation marks. Use this for server in a topology record.

datacenter.<"datacenter_name">

Specifies a data center for load balancing. The name must be in quotation marks. Use this for server in a topology record.

continent.<"continent_name">

Specifies one of the continents for load balancing: "North America", "South America", "Europe", "Asia", "Australia", "Africa", or "Antarctica". The name must be in quotation marks. Use this for ldns in a topology record.

country.<"2-letter_code">

Specifies a country for load balancing using one of the two-letter country codes found in the file /var/3dns/include/net.ccdb. The name must be in quotation marks. Use this for ldns in a topology record.

isp."AOL"

For local DNS servers only, specifies the Internet service provider, America Online (AOL). The name must be in quotation marks.

user.<"region_name">

Specifies a user-defined region. The name must be in quotation marks.

!

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 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 will not probe. The two types of ACLs are:

  • Prober
  • Hops

Syntax for the access control lists

The access control lists use the following syntax.

Figure A.21 Syntax for the access control lists

actions {  
NO_RELAY
delete rdb ACL region "probe_acl"
delete rdb ACL region "hops_acl"
}
region_db ACL {
region {
name "probe_acl"
<ldns cidr>
<ldns cidr>
}
region {
name "hops_acl"
region "probe_acl"
<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.

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 restricts any big3d agent from probing the defined group of local DNS servers.

hops_acl

The 3-DNS restricts any big3d agent from tracerouting the defined group of local DNS servers

Note: For more information on ACLs, refer to Chapter 3 , Access Control Lists .

Working with comments

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

Syntax

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

Figure A.22 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 A.23 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 A.24 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 A.25 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 current values

You may notice several current values in the wideip.conf file. Current values are preceded by the cur_ prefix in the wideip.conf file. The purpose of current 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 without a temporary loss of intelligence.

You may notice current values associated with server, vs, path, or wideip definitions. (You can also view current values by clicking the Configuration View button in the Configuration utility.) The current values parameters show the real-time status of the servers, virtual servers, local DNS server paths, and wide IPs that make up your configuration. Examples of current values for each type of definition follow.

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

Server definition current values

Server definitions may contain several current values, as shown in
Figure A.26 .

Figure A.26 Example of current values in a server definition

// New York BIG-IP  
server {
type bigip
address 192.168.101.40
cur_ok 1 //Up
cur_packet_rate 6
cur_packet_in 1872
cur_packet_out 1812
cur_uptime 3615 //60 mins 15 Secs
[virtual server definitions]
}

The current values parameters that are shown in Figure A.26 are defined in Table A.34 . Note that you may see more current values than those listed here.

Description of current values in a server definition

Parameter

Description

cur_ok

Indicates the state of the specified server. The options are: 1 (up), 2 (down), 3 (waiting), 4 (alert), and 5 (panic).

cur_packet_rate

Indicates the number of packets per second sent during the last sample period.

cur_packet_in

Indicates the number of packets that the server has received.

cur_packet_out

Indicates the number of packets the server has sent.

cur_uptime

Indicates the length of time that the server has been running since the last reboot.

Virtual server definition current values

Virtual server definitions may contain several current values, as shown in Figure A.27 .

Figure A.27 Example of current values in a virtual server definition

vs {  
address 192.168.102.50:80 //http
[ depends_on {
address 109.168.102.50:20 //ftp-data
address 192.168.102.50:443 //https
} ]
limit { /* none */ }
probe_protocol tcp
cur_state 1 // green
cur_nodes_up 3
cur_connections 0
...
cur_picks 0
cur_refreshes 41
}

The current values parameters that are shown in Figure A.27 are defined in Table A.35 . Note that you may see more current values than those listed here.

Description of current values in a virtual server definition

Parameter

Description

cur_state

Indicates the availability of the virtual server to receive connection requests. The options are: 1 (green - available), 2 (red - down), 3 (blue - unknown), 4 (yellow - unavailable)

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.

cur_refreshes

Indicates the number of times the server and connection counts were refreshed with new data.

Local DNS server paths current values

Path definitions for local DNS servers may contain several current values, as shown in Figure A.28 .

Figure A.28 Example of current 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
}

The current values parameters that are shown in Figure A.28 are defined in Table A.36 . Note that you may see more current values than those listed here.

Description of current 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.

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 current values

Wide IP definitions may contain several current values, as shown in
Figure A.29 .

Figure A.29 Example of current 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
[pool definitions]
}

The current values parameters that are shown in Figure A.29 are defined in Table A.37 . Note that you may see more current values than those listed here.

Description of current 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 returns the wide IP key (fallback address) as specified in the zone file.

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