set dnsproxy

Purpose

Enables the DNS Proxy feature on the Digi device. The DNS Proxy feature permits DNS client hosts to communicate with this Digi device as if it were a DNS Server. The DNS Proxy will forward the DNS client's request to one of the DNS servers configured in its network settings. The device relays the response from the actual DNS serverto the requesting client when it is received by the DNS Proxy. Note that the DNS Proxy does not cache the actual detailed client requests nor the responses received from the DNS servers. Rather, it simply acts as a request/response relay agent between the DNS clients and servers.

The DNS Proxy cycles through the DNS servers configured in the Digi device. DNS client requests are identified by the client's IP address and the unique Query ID in the DNS request message. For each new DNS client request (new Query ID), the DNS Proxy uses the first DNS server in its list of DNS servers. If the client retries the same request (same Query ID), the DNS Proxy recognizes that retry message and either sends the retry request to the same DNS server as the previous request for this client, or it moves to the next DNS server in its list of DNS servers. The DNS Proxy feature determines when to retry the same DNS server, or move to the next DNS server, according to the “retries” (request retries per DNS server) option. The DNS Proxy itself does not perform unsolicited retries of DNS client requests.

Note The DHCP Server feature on the Digi device can be configured to use the DNS Proxy feature. For more information, see the set dhcpserver command and the dnsproxy={on|off} option.

The content of the DNS server list can be dynamic. For example, when DNS server IP addresses are received from a mobile service provider's network, they are added to the DNS server list of this Digi device server. Those DNS server IP addresses may or may not be configured when the DHCP Server offers a lease to a DHCP client. As a result, the DHCP client might have no DNS servers provided to it in the lease; as a result, domain name resolution might fail for that client. A significant benefit of the DNS Proxy feature is that the DHCP Server can offer its own IP address as a DNS server in the client lease, and the DNS Proxy forwards DNS requests and responses as stated above. Since the DHCP protocol does not allow a DHCP Server to force an unsolicited DNS server list update to its clients, the DNS Proxy feature provides an indirect method that makes such updates effective for the client.

Note The DHCP server will not offer its own IP address to its DHCP clients in the lease if the DNS Proxy is disabled.

Required permissions

For Digi products with two or more users, permissions must be set to set permissions s-dnsproxy=read to display settings, and to set permissions s-dnsproxy=rw to display and configure them. See set permissions for details on setting user permissions for commands.

Syntax

set dnsproxy [state={enabled|disabled}]
  [maxentries=16-1024]
  [idlettl=10-120]
  [retries=0-4]
  {default: 1}
  [onmaxentries={replacelru|discardnew}]

Options

state={enabled|disabled}

Enables or disables the DNS Proxy service.

maxentries=16-1024

Request cache size maximum. Specifies the maximum number of DNS client request records the DNS Proxy maintains concurrently in its cache. A large cache consumes more system resources than a small cache. However, if the maximum cache size is too small, new DNS client requests may be quietly discarded until the cache has room to add new client request records, or existing cache entries may be replaced by the new requests. If a large number of concurrent DNS client lookups is anticipated, configuring a larger maximum cache size is recommended. See also the onmaxentries option. The default is 256 entries.

idlettl=10 - 120

The period of time, in seconds, that a DNS client request remains in the DNS Proxy cache before it is deleted. This is a period of idle time, during which neither a DNS client request retry is received by the DNS Proxy, nor a DNS server response is received by the DNS Proxy, for a specific DNS client request. A shorter idlettl value results in resources being used more efficiently by the DNS Proxy, since the client request cache is reduced in size and the request buffers are released more quickly for future use for other DNS client requests. The default is 20 seconds.

retries=0-4

Request retries per DNS server; the number of retries using the same DNS server, for a specific DNS client request that is being retried (retransmitted) by the DNS client. There is always one “try” but the number of retries is configurable. The default is 1.

onmaxentries={replacelru|discardnew}

Handling new client requests when the maximum number of client request entries is already being serviced; that is, the request cache is full.

replacelru

Remove the least recently used (LRU) client request entry from the cache, and add an entry for the new client request.

discardnew

Discard (ignore) new client requests until existing client requests have expired, allowing new requests. Silently discard the new client request, and do this for all future new requests until one or more entries have expired and been removed from the request cache.

The default is replacelru.

Examples

#> set dnsproxy state=enabled retries=2

#> set dnsproxy

 DNS Proxy Configuration :

    state         : enabled
    maxentries    : 256
    idlettl       : 20
    retries       : 2
    onmaxentries  : replacelru