Manual Chapter : 3-DNS Administrator Guide v2.1: Wideip.conf Syntax

Applies To:

Show Versions Show Versions

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

  • 2.1 PTF-01, 2.1.2, 2.1.0
Manual Chapter


A

Wideip.conf Syntax



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, 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 virtual server, which is defined as part of a BIG-IP or host server statement
  • At least one server statement defining a 3-DNS Controller
  • A wideip statement

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

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

To open the /etc/wideip.conf file

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 Maintenance menu's Edit 3-DNS Configuration command. 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.

To see an example of a wideip.conf file that incorporates include files, see Sample 3-DNS Controller configuration file using include files, on page A-65 .

Syntax for include files

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

Figure A.1 Special syntax for include files

 include root_in "/var/3dns/include"    
include root_out "/var/3dns/include"
include global <"file_name.conf">
include datacenter <"file_name.conf">
include sync_group <"file_name.conf">
include server <"file_name.conf">
include wideip <"file_name.conf">
include 3dscript <"file_name.conf">
include topology <"file_name.conf">

Definition of include statements

Include file descriptions
Parameter Description Default
include root_in Specifies the name of the default directory. Enclose all file names in quotation marks. "/var/3dns/include"
include root_out Specifies the name of the default directory. "/var/3dns/include"
include global Specifies the name of the file that contains the globals statement. "globals.conf"
include datacenter Specifies the name of the file that contains datacenter statements. "datacenters.conf"
include sync_group Specifies the name of the file that contains sync_group statements. "sync_groups.conf"
include server Specifies the name of the file that contains server statements. "servers.conf"
include wideip Specifies the name of the file that contains wideip statements. "wideips.conf"
include 3dscript Specifies the name of the file that contains production rule configuration. "prodrules.conf"
include topology Specifies the name of the file that contains the topology statement. "topology.conf"
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 by either a value, or by a block of sub-statements enclosed in braces {}.

You can find an example of a complete configuration file in Sample 3-DNS Controller configuration file, on page A-48 .

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

  • globals
    Controls global 3-DNS Controller configuration options and sets defaults for other statements.
  • datacenter
    Defines the group of 3-DNS Controllers, BIG-IP Controllers, and hosts that reside in a single physical location.
  • sync_group
    Defines the group of 3-DNS Controllers that synchronize their configuration settings and metrics data.
  • server
    Defines a 3-DNS Controller, a BIG-IP Controller, or a generic host machine.
  • wideip
    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 and other host machines).
  • topology
    Implements and defines topology-based access control, and makes it possible for you to use the topology load balancing mode (on its own and as part of the QOS mode).

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:
    • globals
    • datacenter
    • sync_group
    • server
    • wideip
    • topology
  • 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 or virtual server (on a BIG-IP Controller or on 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, on page A-79 .

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 following lines, the 3-DNS Controller uses the value 50:

Figure A.2 Multiple globals sub-statements

 globals {    
bigip_ttl 100
host_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 (continued on next page)

 globals {    
[ time_tolerance <number> ]
[ encryption < yes | no > ]
[ encryption_key_file <string> ]
[ check_static_depends < yes | no > ]
[ check_dynamic_depends < yes | no > ]
[ persist_ldns < yes | no > ]
[ timer_get_3dns_data <number> ]
[ timer_get_bigip_data <number> ]
[ timer_get_host_data <number> ]
[ timer_get_vs_data <number> ]
[ timer_get_path_data <number> ]
[ timer_get_trace_data <number> ]
[ timer_check_keep_alive <number> ]
[ timer_persist_cache <number> ]
[ 3dns_ttl <number> ]
[ bigip_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> ]
[ qos_coeff_rtt <number> ]
[ qos_coeff_completion_rate <number> ]
[ qos_coeff_packet_rate <number> ]

Figure A.3 Syntax for the globals statement (continued from previous page)

   [ qos_coeff_topology <number> ]    
[ qos_coeff_hops <number> ]
[ qos_coeff_vs_capacity ]
[ 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> ]
[ default_alternate < ga | null | random | ratio |
return_to_dns | rr | topology | vs_capacity > ]
[ default_fallback < completion_rate | ga | hops | leastconn |
null | packet_rate | qos | random | ratio | return_to_dns |
rr | rtt | topology | vs_capacity> ]
[ fb_respect_depends < yes | no > ]
[ fb_respect_acl < 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 | all > ]
[ rtt_allow_probe < yes | no > ]
[ rtt_allow_hops < yes | no > ]
[ rtt_allow_frag < yes | no > ]

Figure A.3 Syntax for the globals statement (continued from previous page)

   [ probe_protocol {    
[dns_ver]
[dns_dot]
[icmp]
[udp]
[tcp]
}]
[ datasize_system ]
[ datasize_reap_pct ]
[ default_iquery_protocol ]

}

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 3DNS
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 below.

Synchronization

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

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. See Setting the time tolerance value, on page 4-32 . 10

Encryption

The encryption sub-statements specify whether the communication between the 3-DNS Controller and a BIG-IP Controller 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-statement specifies whether the 3-DNS Controller checks the availability of virtual servers on BIG-IP Controllers or hosts before the 3-DNS Controller sends a connection to the virtual server.

Dependencies sub-statement
Parameter Description Default
check_static_depends Specifies whether to check the availability of virtual servers on BIG-IP Controllers and hosts. Change this option to no if you want to test your configuration. Settings this option to no has the effect of forcing the virtual servers to have green (up) status indicators on the virtual servers statistics page in the Configuration utility. 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.

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

Periodic task intervals

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

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_bigip_data Specifies how often the 3-DNS Controller refreshes BIG-IP Controller 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_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.

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_bigip_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.

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_VER protocol. icmp

Resource limits

The resource limits sub-statements define the amount of memory 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 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 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)]

The coefficients for the score computation are defined as globals, 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. 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 vs capacity when the load balancing mode is set to Quality of Service. You can enter a value between 0 and 4294967295. 0
qos_factor_rtt Specifies the factor used to normalize raw RTT 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 vs capacity values when computing the QOS score. 1

Load balancing

Load balancing sub-statements
Parameter Description Default
default_alternate Defines the default load balancing mode used for the alternate method (formerly default_static). You can override this setting in the wideip statement. rr
default_fallback Defines the default load balancing mode used for the fall-back method. 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

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.

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.

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 F5 technical support if you want to make changes to them.

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 in the cache 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 will remain in the cache. 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

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 the IANA registered iQuery port, 4353. 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

Probing sub-statements
Parameter Description Default
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), full (all ports between 1 and 1024), and all. short

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 A.6 Syntax for the datacenter statement

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

Figure A.7 shows an example of a valid datacenter statement:

Figure A.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
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 Controller in this data center.
bigip Specifies the IP address of a BIG-IP Controller 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 A.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 A.9 shows an example of a valid sync_group statement:

Figure A.9 Example syntax for the sync_group statement

 sync_group {    
name "sync"
3dns 192.168.101.2 // New York
3dns 192.168.102.2 // Los Angeles
}

Definition of sync_group sub-statements

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 itself. Then list all other 3-DNS Controllers, in the order that they should become principals should previously listed 3-DNS Controllers fail.

The server statement

The server statement defines the characteristics associated with a particular 3-DNS Controller, BIG-IP Controller, 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, or host
  • The IP address of the server
  • If the server is a BIG-IP Controller or host, the set of virtual servers that are available on it
  • If the server is a BIG-IP Controller, dynamically collected information about the BIG-IP Controller, its virtual servers and ports, and the paths between the BIG-IP Controller 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-32 .

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 A.10 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 >
port <port to probe>
}

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

Figure A.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 only.

Figure A.12 Syntax for defining a BIG-IP Controller

 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>
} ]
[ factories {
prober <number>
discovery <number>
snmp <number>
hops <number>
} ]

vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ translate {
address <IP address>
port <port number>|service <"service name">
} ]
}
}

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

Figure A.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
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 (host)

The following server statement syntax applies to hosts only. Note that the snmp sub-statement is only necessary if you want the big3d agent to use an SNMP agent on the host to collect additional metrics information. For more information, see Configuring host SNMP settings , on page 4-17.

Figure A.14 Syntax for defining a host

 server {    
type host
address <IP address>
name <"host_name">
probe_protocol <tcp | icmp | udp | dns_ver| dns_dot>
[ prober <IP address> ]
port <port number> | service <"service name">
[ snmp {
agent <generic | ucd | solstice | ntserv | ciscold | ciscold2 | ciscold3>
port <port number>
community <"community string">
timeout <seconds>
retries <number>
version <SNMP version>
} ]
vs {
address <virtual server IP address>
port <port number> | service <"service name">
[ probe_protocol <tcp | icmp | udp| dns_ver| dns_dot> ]
}
}

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

Figure A.15 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
}
vs {
address 192.168.104.50:80
}
}

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.

Address information sub-statements
Parameter Description
type Indicates whether the specified server is a 3-DNS Controller, BIG-IP Controller, or host.
address Specifies the IP address of the 3-DNS Controller, BIG-IP Controller, or host.
name Specifies the name of the 3-DNS Controller, BIG-IP Controller, 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 either a BIG-IP Controller or a 3-DNS Controller 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. Applies to 3-DNS Controller and hosts.
port Specifies the port used to probe this host if probe_protocol is set to TCP. Applies to 3-DNS Controllers and hosts.

Remote connections

Using the remote sub-statement is only necessary if you want to specify a different log-on name or specifically use SSH or RSH on 3-DNS Controllers and BIG-IP Controllers.

Remote connections sub-statements
Parameter Description
remote Indicates the start of a remote sub-statement. Applies to 3-DNS Controllers and BIG-IP Controllers.
secure Specifies whether to use ssh (secure shell) or rsh (remote shell) for remote connections. The default for US controllers is yes, which specifies that ssh is used. International versions must use rsh instead. Applies to 3-DNS Controllers and BIG-IP Controllers.
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 and BIG-IP Controllers.

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.

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 and BIG-IP Controllers, 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 Setting up data collection with the big3d agent , on page 2-9.

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.
hops Specifies the number of hops factories to use.

SNMP settings

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

If you need help configuring the SNMP agent on the host itself, see Configuring SNMP agents on hosts , on page 4-20.

SNMP sub-statements
Parameter Description
snmp Specifies the start of an SNMP definition. Applies to hosts only.
agent Specifies the SNMP agent type. If you omit this parameter, the big3d agent uses the generic SNMP agent. Applies to hosts only.
port Specifies the port the SNMP agent runs on. Applies to hosts only.
community Specifies the password for basic SNMP security and for grouping SNMP hosts. Enclose this string in quotation marks. Applies to hosts 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 can hang up the SNMP 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 can hang up the SNMP 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 server or host server 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.

Virtual server definitions
Parameter Description
vs Indicates the start of a virtual server definition. Applies to BIG-IP Controllers and hosts.
address Specifies the IP address of a virtual server owned by a BIG-IP Controller or host. Note that the virtual server's address must be listed first, before port or service values. Applies to BIG-IP Controllers and hosts.
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. Applies to BIG-IP Controllers and hosts.
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 and/or other host machines).

Syntax for the wideip statement

The wideip statement uses the following syntax.

Figure A.16 Syntax for the wideip statement

 wideip {    
address <ip_addr>
port <port_number> | <"service name">
name <"domain_name">
[ alias <"alias_name"> ]
[ ttl <number> ]
[ persist < yes | no > ]
[ persist_ttl <number>]
[ port_list <port_number> <port_number> ... ]
[ qos_coeff {
rtt <n>
completion_rate <n>
packet_rate <n>
topology <n>
hops <n>
vs_capacity <n>
} ]
[ pool_lbmode <rr | ratio | ga | random> ]
pool {
name <"pool_name">
[ ttl <number> ]
[ 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 > ]
[ alternate < ga | null | random | ratio | return_to_dns |
rr | topology | packet_rate| leastconn | vs_capacity > ]
[ fallback < completion_rate | ga | hops | leastconn | null |
packet_rate | qos | random | ratio | return_to_dns | rr |
rtt | topology | vs_capacity > ]
address <vs_addr>[:<port>] [ratio <weight>]
}
}

Figure A.17 shows an example of a valid wideip statement:

Figure A.17 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
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
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 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 wide IP key. They also specify the pool of virtual servers that the wide IP load balances.

Address information sub-statements
Parameter Description
address Specifies a key that represents one valid virtual server IP address from the set that services this wide IP. This key is also listed as the A record in the zone file for the domain.
port or service Specifies the virtual server's default port number or service name. You can use the service name if it is a WKS (well known service) and you enclose it in quotation marks.
name Specifies the domain name for this wide IP (for example, "www.wip.domain.com"). You must enclose all names in quotation marks.
alias Specifies an alternate name for this 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.
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, on pages 29 and 30.
port_list Specifies a list of ports that must be available before the 3-DNS Controller can send connections to the specified address.
persist Specifies whether to maintain a persistent connection between an LDNS and a particular virtual server in this 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.
qos_coeff Specifies the relative weighting for each load balancing method in calculating the Quality of Service (QOS) mode. Before adjusting QOS coefficients, see Understanding QOS coefficients, on page 6-2 .
pool_lbmode Specifies the load balancing mode to use to balance requests over all pools.
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 or other host machine.
name As part of a pool definition, defines the name of this pool. All names must be enclosed in quotation marks.
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.
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 A-10 .
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 A-10 .
address As part of a pool definition, address specifies the IP address of each virtual server in this 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 the table below, 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, the wide IP uses the default load balancing mode defined in the globals statement (see page A-7 ).

    Load balancing 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, 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 a LDNS to a particular data center.

    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)

The topology statement

The topology statement implements a form of wide-area IP filtering. Topology-based access control allows you to specify which data centers are acceptable for a given resolution request, based on the proximity of the data center's IP address to the requesting IP address of the LDNS server. 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 also use the topology load balancing mode, both on its own and as part of the QOS mode.

For more information and an example of a topology statement, see Setting up topology-based access control, on page 6-15 .

Syntax for the topology statement

The topology statement uses the following syntax.

Figure A.18 Syntax for the topology statement

 topology {     
acl_threshold <0..4294967295>
probe_threshold <0..4294967295>
limit_probes <yes |no>
longest_match <yes | no>
<server cidr> <LDNS cidr> <score>
}

Definition of topology sub-statements

Topology sub-statements
Parameter Description
acl_threshold Specifies a score threshold. Any list record (prober IP address/LDNS IP address) score that is less than the threshold value will not have access to the listed virtual servers. You can enter a value between 0 and 4294967295.
probe_threshold Specifies a threshold for probing. Any list record (prober IP address/LDNS IP address) score that is less the than the probe threshold value prevents the LDNS from being probed by the specific prober. You can enter a value between 1 and 4294967295.
limit_probes Specifies whether to apply access control to the probing of paths. If this parameter is set to yes, the 3-DNS Controller requests a given BIG-IP Controller to probe only those LDNS servers that can connect to it according to the probe_threshold value and the topology map scores. The default is yes.
longest_match In cases where there are several IP/mask items 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 CIDR Specifies the server mask for a given data center. This is one of two values used to determine the longest match.
LDNS CIDR Specifies the LDNS mask. This is one of two values used to determine the longest match.
score Specifies the list record score, which is used for the comparison of virtual servers when the topology load balancing mode is employed.

Probing exclusion lists

You can now create probing exclusion lists that contain a group of LDNS IP addresses whose paths the 3-DNS Controller will not probe. There are three different types of probing exclusion lists:

Syntax for the probing exclusion lists

The probing exclusion lists use the following syntax.

Figure A.19 Syntax for the probing exclusion lists

 probe_acl {     
<LDNS cidr>
<LDNS cidr>
<LDNS cidr>
}

hops_acl {
<LDNS cidr>
<LDNS cidr>
<LDNS cidr>
}

discovery_acl {
<LDNS cidr>
<LDNS cidr>
<LDNS cidr>
}

Definition of the probing exclusion list sub-statements

Probing exclusion list sub-statements
Parameter Description
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.

For example:

Figure A.20 Comment syntax

 /* 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 is not valid because the entire comment ends with the first */:

Figure A.21 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.

For example:

Figure A.22 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 # character and are no longer than one line in length.

For example:

Figure A.23 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.

Sample 3-DNS Controller configuration file

The following is an example of a 3-DNS Controller configuration file. Note that very few global parameters are listed. This is because you do not need to include each global parameter; you need only include those parameters for which you want to specify a value other than the default.

The following sample file contains examples of common configurations and each load balancing mode. (This sample file is several pages long.)

The following examples show the same sample configuration as shown in the previous section, but with the incorporation of include files.

Sample wideip.conf using include files

#
# Sample /etc/wideip.conf using include files
#
include root_in "/var/3dns/etc"
include root_out "/var/3dns/etc"
include global "globals.conf"
include datacenter "datacenters.conf"
include sync_group "sync_groups.conf"
include server "3dns.conf"
include server "bigips.conf"
include server "hosts.conf"
include wideip "wideips.conf"
include 3dscript "prodrules.conf"
include topology "topology.conf"

Sample globals.conf

// globals.conf
globals {
prober 192.168.101.2 // Default prober is New York 3DNS
encryption yes // Encrypt iQuery
paths_noclobber yes // Don't overwrite metrics with
// zeroed results

path_ttl 400 // Extend the life of path metrics
rtt_probe_dynamic yes // Switch to tcp probing if icmp
// fails

multiplex_iq yes // Source port is same as dest.
// port for iQuery
use_alternate_iq_port yes // Use IANA registered port for
// iQuery
}

Sample datacenters.conf

// datacenters.conf
/*** Define 3 Datacenters: New York, Los Angeles, and Tokyo ***/
datacenter {
name "New York"
3dns 192.168.101.2
bigip 192.168.101.40
host 192.168.105.40
}
datacenter {
name "Los Angeles"
3dns 192.168.102.2
bigip 192.168.102.40
}
datacenter {
name "Tokyo"
bigip 192.168.103.40
host 192.168.104.40
}

Sample sync_groups.conf

// sync_groups.conf
sync_group {
name "sync"
3dns 192.168.101.2 // New York
3dns 192.168.102.2 // Los Angeles
}

Sample 3dns.conf

// 3dns.conf
// New York
server {
type 3dns
address 192.168.101.2
name "3dns-newyork"
remote {
secure no
user "root"
}
probe_protocol icmp
port 53
}
// Los Angeles
server {
type 3dns
address 192.168.102.2
name "3dns-la"
remote {
secure no
user "root"
}
probe_protocol tcp
port 53
}

Sample bigips.conf

bigips.conf
// The New York BIG-IP is behind a firewall and the virtual servers
// need to be translated
server {
type bigip
address 192.168.101.40
name "bigip-newyork"
remote {
secure yes
user "administrator"
}
# Tell 3-DNS about the 2 interfaces on a BIG-IP HA
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
}
include vs "bigip_ny/vs.conf"
include path "bigip_ny/path.conf"
}
// Los Angeles
server {
type bigip
address 192.168.102.40
name "bigip-la"
remote {
secure no
}
include vs "bigip_la/vs.conf"
include path "bigip_la/path.conf"
}
// Tokyo
server {
type bigip
address 192.168.103.40
name "bigip-tokyo"
vs {
address 192.168.103.50:80
}
include vs "bigip_tokyo/vs.conf"
include path "bigip_tokyo/path.conf"
}

Sample bigip_ny/vs.conf

// bigip_ny/vs.conf
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
}
}
vs {
address 192.168.101.60:21 // ftp
translate {
address 10.0.0.60:21
}
}
vs {
address 192.168.101.60
port 80
translate {
address 10.0.0.60
port 80
}
}
vs {
address 192.168.101.70
port 443
translate {
address 10.0.0.70
port 443
}
}
vs {
address 192.168.101.70:80 // http
translate {
address 10.0.0.70:80
}
}

Sample bigip_la/vs.conf

// bigip_la/vs.conf
vs {
address 192.168.102.50:80
}
vs {
address 192.168.102.50:25
}
vs {
address 192.168.102.60:21
}
vs {
address 192.168.102.60:443
}
vs {
address 192.168.102.60:80
}
vs {
address 192.168.102.70:80
}

Sample bigip_tokyo/vs.conf

// bigip_tokyo/vs.conf
vs {
address 192.168.103.50:25
}
vs {
address 192.168.103.60:21
}
vs {
address 192.168.103.60:80
}
vs {
address 192.168.103.70:80
}

Sample hosts.conf

// hosts.conf
server {
type host
address 192.168.104.40
name "host-tokyo"
probe_protocol icmp
port 53
snmp {
agent ucd
community "public"
version 1
}
include vs "host_tokyo/vs.conf"
include path "host_tokyo/path.conf"
}
server {
type host
address 192.168.105.40
name "host-la"
probe_protocol tcp
prober 192.168.103.40 // Use the prober in Tokyo
port 80
snmp {
agent solstice
community "3dns"
version 2
}
include vs "host_la/vs.conf"
include path "host_la/path.conf"
}

Sample host_tokyo/vs.conf

// host_tokyo/vs.conf
vs {
address 192.168.104.50:25
}
vs {
address 192.168.104.50:80
}
vs {
address 192.168.104.50:443
}

Sample host_la/vs.conf

// host_la/vs.conf
vs {
address 192.168.105.50
port 80
probe_protocol tcp
}
vs {
address 192.168.105.50:25
probe_protocol tcp
}
vs {
address 192.168.105.60:443
probe_protocol icmp
}
vs {
address 192.168.105.60:80
probe_protocol icmp
}

Sample wideips.conf

// wideips.conf
// Two pools with a production rule
wideip {
address 192.168.101.50
service "http"
name "www.wip.domain.com"
ttl 60 // increase the domain default ttl
qos_coeff {
rtt 21
hops 0
completion_rate 7
packet_rate 5
topology 1
}
pool {
name "Pool_1"
ratio 2 // applies to pool_lbmode == ratio
preferred leastconn
alternate ratio
address 192.168.101.50 ratio 2
address 192.168.102.50 ratio 1
address 192.168.103.50 ratio 1
}
pool {
name "Pool_2"
ratio 1
preferred rr
address 192.168.102.60 ratio 2
address 192.168.103.60 ratio 1
}
}

// Global availability
wideip {
address 192.168.101.60
port 80 // http
name "cgi.wip.domain.com"
pool {
name "mypool"
preferred ga
address 192.168.101.60
address 192.168.102.60
address 192.168.103.60
}
}

// Round robin pool load balancing between bigip and hosts
// This site runs a catalog and shopping cart and only wishes
// to send client to a datacenter if services are up on both
// ports 80 and 443.
wideip {
address 192.168.101.70
port 80 // http
port_list 80 443 // e-commerce
name "ssl.wip.domain.com"
pool_lbmode rr
pool {
name "bigip_pool"
ratio 2
preferred qos
alternate ratio
address 192.168.101.70 ratio 7
address 192.168.102.60 ratio 2
}
pool {
name "host_pool"
ratio 1
preferred ratio
address 192.168.104.50 ratio 2
address 192.168.105.60 ratio 1
}
}

// Mixing hosts and BIG-IP virtual servers
// Ratio pool load balancing between bigip and hosts
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
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
preferred ratio
address 192.168.104.50 ratio 2
address 192.168.105.50 ratio 1
}
}

// Least connections with ratio as an alternate
wideip {
address 192.168.102.60
service "ftp"
name "ftp.wip.domain.com"
pool {
name "main_pool"
preferred leastconn
alternate ratio
address 192.168.101.60 ratio 2
address 192.168.102.60 ratio 4
address 192.168.103.60
}
}

// Preferred set to QOS with attributes dynamic ratio and ldns_rr
// Alternate set to leastconn
wideip {
address 192.168.103.70:80
name "www2.wip.domain.com"
pool {
name "pool_1"
dynamic_ratio yes
rr_ldns yes
rr_ldns_limit 10 // Return up to 10 available virtual servers
preferred qos
alternate leastconn
address 192.168.101.60
address 192.168.102.60
address 192.168.103.70
}
}

// Global availability pool load balancing between bigip
// datacenters with specialized use of preferred, alternate, and
// fallback load balancing methods null and return_to_dns.
wideip {
address 192.168.102.70
port 80
name "www.domain.com"
alias "home.domain.com"
ttl 120
pool_lbmode ga
pool {
name "New York"
ratio 2
preferred leastconn
alternate null
fallback null // null here allows fail over to next pool
address 192.168.101.50
address 192.168.101.60
address 192.168.101.70
}
pool {
name "Los Angeles"
ratio 1
preferred leastconn
alternate null
fallback null // null here allows fail over to next pool
address 192.168.102.50
address 192.168.102.60
address 192.168.102.70
}
pool {
name "Tokyo"
ratio 1
preferred leastconn
alternate null
# fallback return_to_dns // (this is the fallback default)
address 192.168.103.50
address 192.168.103.60
address 192.168.103.70
}
}

// Round trip time load balancing with topology as alternate load
// balancing (see topology below)
wideip {
address 192.168.103.60
port 80
name "ntp.wip.domain.com"
pool {
name "poolA"
preferred rtt
alternate topology
address 192.168.101.60 // New York
address 192.168.102.60 // Los Angeles
address 192.168.103.60 // Tokyo
}
}

Sample prodrules.conf

// prodrules.conf
// Pool rules can start anywhere after the pool name
// and before the virtual servers.

// Add some special rules to switch lbmodes:
// Weekday 6am-5pm: qos
// Weekday 5pm-6am: leastconn
// Weekend : packet_rate

/*** If a weekday ***/
rule "myRule1"
if(day != "sat" && day != "sun") {

/*** If during business hours 6am-5pm, do QOS ***/
rule "myRule2"
if(preferred != "qos" && (time >= "6:00" && time <= "17:00")) {
// switch the lbmode and log a message that it happened
preferred qos
log("Switching preferred to $preferred")
}

/*** Otherwise, do least connections ***/
else {
rule "myRule3"
if(preferred != "leastconn") {
preferred leastconn
log("Switching preferred to $preferred")
}
}
}

/*** If weekend, switch to packet rate ***/
else {
rule "weekendPolicy"
if(preferred != "packet_rate") {
preferred packet_rate
log("Switching preferred to $preferred")
}
}

Sample topology.conf

// topology.conf
topology {
acl_threshold 5
probe_threshold 5
limit_probes yes
longest_match yes

// server/mask ldns/mask score


///////////////////////////
// North American LDNS's:
// 198.0.0.0/8
// 199.0.0.0/8

// North America Priority List
//
// 1. New York
// 2. L.A.
// 3. Tokyo

// New York
192.168.101.0/24 198.0.0.0/8 30
192.168.101.0/24 199.0.0.0/8 30

// Los Angeles
192.168.102.0/24 198.0.0.0/8 20
192.168.102.0/24 199.0.0.0/8 20

// Tokyo
192.168.103.0/24 198.0.0.0/8 10
192.168.103.0/24 199.0.0.0/8 10


///////////////////////////
// South American LDNS's:
// 200.0.0.0/8
// 201.0.0.0/8

// South America Priority List
//
// 1. Tokyo
// 2. L.A.
// (New York excluded by acl_threshold)

// Tokyo
192.168.103.0/24 200.0.0.0/8 30
192.168.103.0/24 201.0.0.0/8 30

// Los Angeles
192.168.102.0/24 200.0.0.0/8 20
192.168.102.0/24 201.0.0.0/8 20

// New York
192.168.101.0/24 200.0.0.0/8 0
192.168.101.0/24 201.0.0.0/8 0

///////////////////////////
// Wildcard List Record
//
// By default, if a list record is not found in the
// topology map for an LDNS, the score is assumed to
// be 0. By including the following "wildcard" list
// record, all other LDNS's (not North or South America
// as specified above) are assigned a score of 1 so
// the acl_threshold does not indicate that the
// virtual servers are down.

0.0.0.0/0 0.0.0.0/0 1


}


/*
* Some global production rules
*/

rule "everyExample"
every(60) {
log("We should do something nifty every minute")
}


rule "whenExample"
when(SIGHUP) {
log("System was just restarted (i.e. ndc reload)")
}

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.

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

How cur_ values are used

You may notice cur_ values in server, vs, path, or wideip definitions. Examples for each type of definition follow.

Example: server definition

Figure A.24 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 above example, the cur_ values indicate the following.

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).

Example: vs definition

Figure A.25 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 above example, the cur_ values indicate the following:

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.

Example: path definition

Figure A.26 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 above example, the cur_ values indicate the following:

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.

Example: wide IP definition

Figure A.27 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 above example, the cur_ values indicate the following:

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.

Tip: 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.