ADTRAN Operating System (AOS) includes DNS look-up and proxy services that can provide basic DNS functions for your network. This document discusses in detail what each of these functions is in a basic form, as well as continuing to discuss advanced internal operation and configuration. This includes discussion of per-VRF DNS services, IPv6 DNS, and DNS Fail-over operations and concerns.
Sections Included in this Document
Hardware and Software Requirements
Understanding DNS Operations in AOS
Deployment Concerns and Considerations
Configuration using the AOS Web Interface
Hardware and Software Requirements
DNS lookup and DNS proxy are available in all AOS units. Per-VRF functions and IPv6 operation are available in units that support those individual features as shown in the AOS Feature Matrix - Product Feature Matrix.
Understanding DNS Operations in AOS
Domain Name System (DNS) provides DNS name resolution to IP Addresses. When a hostname is provided (example: in a URL; www.adtran.com) to an application, the first step the application must take is to resolve that name into an IP Address using DNS. The application then uses that IP Address to contact the intended recipient of the information being sent.
DNS Lookup is the method of resolving a hostname to an IP Address. The DNS client sends a DNS Query to a DNS Server and it replies with a DNS Response that provides a resulting IP Address back to the AOS unit. In AOS, this feature only provides the AOS unit with the corresponding IP address to the domain name asked for, meaning this DNS lookup does not control client's DNS configuration. Units behind the AOS unit must use a DNS server themselves, or use DNS Proxy which is explained below.
When a hostname is resolved to an IP address, the AOS unit will cache the response in its DNS-cache. This way, if the unit must use this hostname again, it can quickly access the "DNS record" without having to query the server again. After a pre-set timeout in AOS, the DNS record will be "refreshed" and AOS will query the server again to make sure the information stays correct (After the timeout has expired, AOS will not query a hostname again until it is used by an AOS application).
AOS can be programmed with multiple DNS servers as well so that if a DNS server becomes unresponsive, the unit fails over to the next server and domain names can still be resolved properly. Up to 8 servers can be added to AOS. The order in which these servers is configured determines the order in which the servers will fail over if the primary sever becomes unresponsive. When the primary server configured does not reply to three successive queries by AOS, AOS will move to the next server. That server will become the primary server until it becomes non-responsive, the DNS service is restarted (Through disabling and re-enabling DNS lookup), or the AOS unit is rebooted. This continues down the sequence of configured DNS servers until a server responds to a DNS query. It is very important to properly decide the order of configured DNS servers based on this fail-over process. Remember that if an older primary DNS server becomes active again, it will not preempt the current active primary DNS server in AOS.
DNS caches are isolated and only used by the unit unless DNS proxy is configured. DNS proxy operation is discussed below.
For information about configuring DNS lookup, please see the sections Configuration using the AOS Web Interface or Configuration using the CLI.
An AOS unit has a local cache as explained above, but it can not act as a DNS server for a network. However, it can act as a proxy. This functions by configuring the local units either statically or through DHCP to use the AOS unit's IP address as a DNS server. When the unit queries the AOS unit to resolve a hostname, the AOS unit will proxy the request to its primary DNS server by changing the source IP address of the packet. Once the DNS server responds, the AOS unit proxies the response back to the original unit that sent the query.
With DNS proxy configured, static hostname-to-IP-address bindings can be configured in the AOS unit to resolve local network hostnames that are not registered in a DNS server. With this feature, more network applications can use a hostname and all of the DNS bindings can be controlled using simple AOS configurations.
Starting in R10.3.0, DNS lookup and proxy services can be enabled separately in each VRF. For example, if DNS lookup is configured in the default VRF, it will still be disabled in any non-default VRFs that are configured unless it is manually enabled.
As of 18.03.01, DNS operations now support IPv6. DNS lookup and proxy are controlled by the same services inside the router. Therefore, if either is enabled, it will be enabled for IPv4 and IPv6 simultaneously.
Per-VRF and IPv6 operation are only available to be configured in the CLI.
Deployment Concerns and Considerations
The following section should help you decide if you need either DNS lookup or DNS proxy in your AOS unit and benefits you get out of each.
As explained before, DNS lookup controls AOS' ability to resolve hostnames for any management functions. This includes using ICMP to contact a hostname entry, any ACLs that reference hostnames, and many other features that can accept a hostname as an input. ADTRAN recommends this function be turned on in any deployed units as it does not have many security concerns and can be very helpful when troubleshooting network connections. The only two downsides to running this service would be the extra load (while small) the DNS process puts on the unit's processor and having to protect the DNS process with a firewall from being improperly used.
DNS proxy provides several network advantages. As mentioned above, with DNS proxy configured and deployed any static hostnames on the network can be created and maintained in the AOS unit as well as providing normal DNS operation through the proxy. This provides the ability to simply manage changing DNS names and IP addresses on a LAN.
Along with the above, in many cases a company with a internal web server that is accessible publicly may want to access it while on the LAN. For example, consider the following example:
In the above scenario, ADTRAN has a web-server behind a NetVanta 3430 that supports all www.adtran.com operation. To allow public access to the server, the 3430 has a NAT rule to port forward any web traffic received to the web-server's private IP address. This means that www.adtran.com will resolve to IP address 1.1.1.1 when queried.
However, if an internal user tries to go to www.adtran.com, they will receive the same resolution of the the hostname to 1.1.1.1. When the local application tries to access that traffic, it will enter the 3430 on the incorrect port (internal instead of external) and the port forward will not take effect. In this situation, DNS proxy is required. If the local unit is using the NetVanta 3430 as a DNS server and it has DNS proxy configured, the local administrator could put a static DNS entry into the 3430 to resolve any requests to www.adtran.com to the private IP address of the server. Now the local unit can access the server without any issue.
Unlike DNS lookup which is local to the AOS unit, DNS proxy responds, by default, to any DNS requests it receives (it does not intercept DNS requests, only responds to queries that are destined for one of its own IP addresses). It is important to use the AOS firewall to restrict queries to only trusted internal subnets.
Configuration using the AOS Web Interface
If you need help accessing the AOS Web Interface, please see the document Accessing the Web Interface in AOS.
To configure DNS Lookup, navigate to "System" on the left hand menu in the Web Interface and select "Hostname/DNS". In the top section called "DNS Setup", add in a primary and secondary DNS server to use for DNS queries, and then select the checkbox next to "Enable DNS lookup" and hit "Apply". The below picture depicts these settings. 4.2.2.2 and 4.2.2.1 are public DNS server IP addresses. You should use your network specific DNS servers here (if you do not know these, ask an administrator):
The most efficient way to test DNS Lookup configuration is to verify the unit can look up a hostname. This can be done several ways. The easiest is to navigate to "Utilities" on the side menu and click on "Connectivity". Here you can ping a hostname like www.adtran.com to make sure it resolves properly:
You can also verify that any DNS operations in the unit are properly resolving and caching addresses by looking at the DNS cache by going back to "System" and "Hosntame/DNS" and viewing the DNS cache at the bottom of the page:
To configure DNS Proxy, navigate to "System" on the left hand menu and then select "Honstame/DNS" like before. Remember that DNS Lookup must be configured for DNS Proxy to work as shown above. Once here, click to check the box next to "Enable DNS Proxy" and then click "Apply":
To configure static hosts for the DNS Proxy to reference, use the middle section on the "Hostname/DNS" page inside the "System" menu option. Here, you can specify the host's DNS name as well as the IP address before clicking "Add":
DNS Proxy fail over can only be configured in the CLI.
To verify that DNS Proxy is configured correctly, you must run a DNS operation on a client that is pointed to the NetVanta as a DNS server like pinging www.adtran.com from the computer's command prompt. If this is successful, DNS Proxy is working properly.
If you need assistance accessing the unit's Command Line Interface, please see Accessing the Command Line Interface in AOS. It is important to remember in the following sections that DNS is an IPv4/IPv6 mutual feature as of 18.03.01 (R10.1.0 on all ADTRAN IADs/IPBGs). All DNS configuration options used will affect IPv4 and IPv6 traffic in the same manner.
By default in AOS, DNS-lookup is on in every configured VRF. The below explains how to enable it if it has been previously disabled.
As stated above, in current firmware DNS is a per-VRF operation and therefore must be explicitly configured in each VRF that is being used. To enable DNS lookup, use the domain-lookup {vrf <VRF name>} command:
(config)#domain-lookup
(config)#domain-lookup vrf VRF_One
The above commands enable DNS lookup in the default VRF as well as the VRF "VRF_One". If you are not using VRF features, only the first command is needed.
To allow DNS lookup to function properly in certain configures, you can use the source-interface option. If this option is left off, AOS uses the route table to decide what source IP address to insert into the packets when they are sent to the DNS server. For example, if AOS looks up the route for the primary DNS server and sees it is out Ethernet 0/1, the primary IP address on Ethernet 0/1 will be used as the source address for the packets to that DNS server. If there is a desire to change this behavior, you can add the option to the domain-lookup command as shown below:
(config)#domain-lookup source-interface ethernet 0/1
(config)#domain-lookup vrf VRF_One source-interface ethernet 0/1
The first command above configures the unit to use the Ethernet 0/1 interface's primary IP address for any DNS lookup communications regardless of destination address. The second command enables the same configuration for the VRF "VRF_One". If you are not using a VRF feature, only the first command would be needed. Make sure before adding the source-interface command that changing this will not disable DNS in certain situations (if the source IP address is not route-able from the destination, DNS will fail). Note that this will affect IPv4 and IPv6 operation in the same manner because DNS is an IPv4/IPv6 mutual feature.
DNS lookup configurations will be irrelevant without configuring DNS servers for the feature to contact. To add a DNS server, use the name-server {vrf <VRF name>} <ip address> command. You can append up to eight IP addresses onto the command. An IPv6 or an IPv4 address can be used, even in the same command as shown below:
(config)#name-server 4.2.2.2 8.8.8.8 2004:edb9::1
(config)#name-server vrf VRF_One 4.2.2.2 8.8.8.8 2004:edb9::1
The first command above adds the three DNS servers (the third being an IPv6 address) as DNS servers in the default VRF. The second command performs the same operation for VRF "VRF_One". If other servers are added later, they will be appended onto the end of the currently configured commands. To remove a DNS server, use the no form of the command. Individual DNS servers can be removed without removing the complete command, however, the servers can not be re-ordered without removing all of the servers whose sequence will change in the command.
There are two other options that can be added to the DNS-lookup feature. The command domain-lookup database local is disabled by default. When enabled, this command stores the DNS cache in a hidden file on the unit's non-volatile memory. In this case, if the unit reboots the DNS-cache is immediately restored to the state it was in before the reboot. The command domain-lookup snmp trap first-failure configures the unit to send an SNMP trap (if SNMP traps are configured) on the first DNS failure to alert the configured SNMP trap server.
To see the current configured DNS lookup commands in the unit, use the show running-config | include domain-lookup command:
(config)#show running-config verbose | include domain-lookup
domain-lookup
domain-lookup vrf VRF_One
domain-lookup database local ttl 3600
domain-lookup snmp trap first-failure
To see the current DNS servers in the unit, use the show running-config | include name-server command:
(config)#show running-config | include name-server
name-server 4.2.2.2 8.8.8.8 2004:edb9::1
name-server vrf VRF_One 4.2.2.2 8.8.8.8 2004:edb9::1
To verify that hosts are being properly added to the DNS-cache or "Host table", use the show host command:
(config)#show host
Name/address lookup uses domain name service
DNS Proxy is enabled
Default domain is adtran
Current DNS client server is 4.2.2.2
Current DNS proxy server is 4.2.2.2
Name servers are 4.2.2.2, 8.8.8.8, 2004:edb9::1
Records are removed from the cache based on the TTL and cache policy. After the
TTL expires, records can be kept anywhere from several seconds to indefinitely
depending on the cache policy
Host CacheP Age Type Port Prior Weigh Address/Alias
================================================================================
www.adtran.com temp 1380109 A - - - 10.10.100.5
If you initiate a ping to a host, or an application in the router utilizing a domain name, you can then use this command to verify your DNS settings are working. As well, you see what the current DNS client server is (above it is the 5th line) to verify if the unit has failed-over to another DNS server. If after verifying your configuration you are still experiencing issues with your DNS lookup configuration, please navigate to the section named Troubleshooting DNS-lookup.
The following is an example configuration to enable DNS lookup in a unit. To utilize this, put in your specific IP address information in the corresponding fields:
domain-lookup
name-server <ip address> <ip address>
To configure DNS proxy, first make sure you have properly configured DNS Lookup by following the instructions in the section Configuring DNS Lookup
Once this has been verified, you can configure DNS Proxy with the dns-proxy { vrf <vrf Name> } global configuration command:
(config)#dns-proxy
or
(config)#dns-proxy vrf My_VRF
To enable DNS Proxy Failover, use the dns-proxy failover { vrf <vrf name> } global configuration command:
(config)#dns-proxy failoveror
(config)#dns-proxy failover vrf My_VRFTo configure a static host for the DNS Proxy to reference, use the host { vrf <vrf name> } <hostname> <IPv4 or IPv6 address> command:
(config)#host MyTerminal 10.10.10.1
(config)#host vrf My_VRF Terminal 10.10.10.1
The first command above enters the host for the default VRF and the second enters the same command for the vrf "My_VRF".
To verify DNS Proxy configuration, use the show running-config | include domain-proxy command:
#show running-config | include domain-proxy
domain-proxy
domain-proxy failover
domain-proxy vrf My_VRF
domain-proxy vrf My_VRF failover
To verify operation, initiate traffic requiring DNS on a unit that is pointed to the ADTRAN as a DNS server.
Basic DNS Proxy Configuration:
dns-proxy
dns-proxy failover
Troubleshooting in AOS is performed from the Command Line Interface (CLI). For more information about accessing the CLI, consult the guide Accessing the Command Line Interface in AOS.
From Privileged Exec Mode, type debug ip dns-client to enable DNS client debugging.
Use the ping <hostname> command to test DNS lookup for a particular hostname.
#ping adtran.com
Successful DNS Lookup Debug Output:
The following is a successful DNS Lookup debug output. The DNS Client in AOS sends a DNS Query, receives a DNS Response and parses the IP Address for adtran.com. If your DNS lookup in AOS is successful, you can move onto “Troubleshooting DNS Proxy”.
DNS: CLIENT Transmitting query packet for adtran.com.Type: 1 A.
DNS: CLIENT Received query response from 172.22.48.47
DNS: Rx: adtran.com is 172.23.100.11 TTL(0) Answers: 1 Type: 1 A.
DNS answer: Rx: 1 type(000001) adtran.com
DNS answer: Rx: A 172.23.100.11 ttl(000000) adtran.com
No Record for Hostname:
If the DNS server does not have an entry for the supplied hostname, it will reply with an error indicating that hostname could not be resolved. The following is an example debug output for the unknown hostname asdfas3.com.
DNS: CLIENT Transmitting query packet for asdfas3.com.Type: 1 A.
DNS: CLIENT Received query response from 172.22.48.47.
DNS: Rx: Error: The name server does not have a record for asdfas3.com. Type: 1 A.
DNS Server Unresponsive:
If the DNS Server does not respond, you will only receive debug output stating that a DNS Query was sent, and no additional output about a DNS Response. The following shows that a DNS Query for adtran.com was sent, but no response was received. You should troubleshoot IP connectivity issues with the DNS server, or try a different DNS server.
DNS: CLIENT Transmitting query packet for adtran.com.Type: 1 A.
Domain Server Not Configured:
If you receive a message stating no DNS Server is configured, you have not configured a DNS server in AOS and you should re-read this guide.
DNS Lookup not Enabled:
If you receive a message stating DNS Lookup is not enabled, you should re-read this guide.
Before troubleshooting DNS Proxy in AOS, be sure that your DNS client is using the AOS device’s local IP address as its one and only DNS Server. If DNS Lookup is operating correctly, most likely the issue resides with the DNS client.
Most operating systems include a DNS troubleshooting tool named ‘nslookup’. If at all possible, use this tool and the included instructions to help troubleshoot DNS proxy.
Using nslookup:
1) In your operating system's command prompt, type nslookup. This should bring you to an nslookup prompt.
2) Set the AOS device as the Name Server to be used by nslookup
- Syntax: server <aos-ip-address>
- Example: server 10.10.10.1
3) Perform a DNS Query with nslookup.
- Syntax: <hostname>
- Example: www.adtran.com
- The result should be the appropriate IP Address for the supplied hostname.
In AOS type ip debug dns-proxy to enable debugging DNS Proxy events. Use the above nslookup steps to perform a DNS Query through the DNS Proxy in AOS.
Successful DNS Proxy Debug Output:
The following is debug output from a successful DNS Proxy request. The DNS Proxy receives a DNS Query (from 172.22.66.8), then forwards the query to a DNS Server (4.2.2.2) and finally forwards the reply back to the DNS Client (172.22.66.8).
2006.11.13 18:10:58 IP.DNS PROXY Received request from 172.22.66.8
2006.11.13 18:10:58 IP.DNS PROXY Forwarding query for "adtran.com" to 4.2.2.2
2006.11.13 18:10:58 IP.DNS PROXY Telling 172.22.66.8 that adtran.com is 172.23.100.11
Invalid Hostname:
If the DNS server does not have an entry for the queried hostname, there will be no value after the “hostname is” statement in the “Telling” line of the debug output. Nslookup will state that the domain-name record was not found.
2006.11.13 18:14:38 IP.DNS PROXY Received request from 172.22.66.8
2006.11.13 18:14:38 IP.DNS PROXY Forwarding query for "adtdf3.com" to 4.2.2.2
2006.11.13 18:14:38 IP.DNS PROXY Telling 172.22.66.8 that adtdf3.com is
No Response:
If nslookup states that no response was received from the DNS server, check that you have specified the correct IP address for the “server” command in nslookup. If the IP address is correct, check that the firewall in AOS is not filtering out or NATing UDP port 161 on the local LAN policy-class (security-zone). Fore more information about the firewall in AOS, consult the guide titled Configuring Access Policies in AOS.
For more information regarding IPv6 specific operation, please see Configuring IPv6 in AOS.
For more information on VRF operation, please see Configuring Multi-VRF in AOS.
