Showing results for 
Show  only  | Search instead for 
Did you mean: 

Advanced Configuration and Troubleshooting DNS Lookup and DNS Proxy in AOS

Advanced Configuration and Troubleshooting DNS Lookup and DNS Proxy in AOS

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

Configuration using the CLI


Useful Links

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; 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 and Fail-over

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.

  • DNS-proxy

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.

  • Per-VRF and IPv6 Operation

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.

  • Why Use DNS Lookup?

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.

  • Why Use DNS Proxy?

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 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 will resolve to IP address when queried.

However, if an internal user tries to go to, they will receive the same resolution of the the hostname to 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 to the private IP address of the server. Now the local unit can access the server without any issue.

    • Important Security Concerns

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.

  • Configuring DNS Lookup

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. and are public DNS server IP addresses. You should use your network specific DNS servers here (if you do not know these, ask an administrator):


    • DNS-lookup Configuration Verification

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


  • Configuring DNS Proxy

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.

    • DNS Proxy Configuration Verification

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 from the computer's command prompt. If this is successful, DNS Proxy is working properly.

Configuration using the CLI

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 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 2004:edb9::1

(config)#name-server vrf VRF_One 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.

    • DNS-lookup Configuration Verification

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 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 2004:edb9::1

name-server vrf VRF_One 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

Current DNS proxy server is

Name servers are,, 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

================================================================================          temp  1380109  A    -    -    -

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.

    • Example Configuration

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:


name-server <ip address> <ip address>

  • Configuring DNS Proxy

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 vrf My_VRF

To enable DNS Proxy Failover, use the dns-proxy failover { vrf <vrf name> } global configuration command:

(config)#dns-proxy failover


(config)#dns-proxy failover vrf My_VRF

To 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
(config)#host vrf My_VRF Terminal

The first command above enters the host for the default VRF and the second enters the same command for the vrf "My_VRF".

    • DNS-proxy Configuration Verification

To verify DNS Proxy configuration, use the show running-config | include domain-proxy command:

#show running-config | include 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.

    • Example Configuration

Basic DNS Proxy Configuration:

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.

  • Troubleshooting DNS-lookup

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.


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 If your DNS lookup in AOS is successful, you can move onto “Troubleshooting DNS Proxy”.

DNS: CLIENT Transmitting query packet for 1 A.

DNS: CLIENT Received query response from

DNS: Rx: is TTL(0) Answers: 1 Type: 1 A.

DNS answer: Rx: 1 type(000001)

DNS answer: Rx: A ttl(000000)

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

DNS: CLIENT Transmitting query packet for 1 A.

DNS: CLIENT Received query response from

DNS: Rx: Error: The name server does not have a record for 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 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 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.

  • Troubleshooting DNS Proxy

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

  1. Syntax: server <aos-ip-address>
  2. Example: server

3)      Perform a DNS Query with nslookup.

  1. Syntax: <hostname>
  2. Example:
  3. 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, then forwards the query to a DNS Server ( and finally forwards the reply back to the DNS Client (

2006.11.13 18:10:58 IP.DNS PROXY Received request from

2006.11.13 18:10:58 IP.DNS PROXY Forwarding query for "" to

2006.11.13 18:10:58 IP.DNS PROXY Telling that is

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

2006.11.13 18:14:38 IP.DNS PROXY Forwarding query for "" to

2006.11.13 18:14:38 IP.DNS PROXY Telling that 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.

Useful Links

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.

Labels (1)
Version history
Last update:
‎02-01-2012 12:51 PM
Updated by: