Applies To:
Show Versions
3-DNS Controller versions 1.x - 4.x
- 2.1 PTF-01, 2.1.2, 2.1.0
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
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.
| 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.
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.
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.
| 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.
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.
Metrics collection
The metrics collection sub-statements define how the 3-DNS Controller collects path information.
Resource limits
The resource limits sub-statements define the amount of memory allocated to sending and receiving metrics information.
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.
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.
Load balancing
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.
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.
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.
iQuery port options
Probing
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.
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
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.
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.
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.
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.
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.
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.
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.
| 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 ).
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
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
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:
/* 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.
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:
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:
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:
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.
