resolving — DNS resolving in Kernun applications


All Kernun components use Kernun own name resolver, which differs from the standard FreeBSD name resolver in some key features. Moreover, the components having only one regular child (e.g. UDP based proxies) use non-blocking model of name/addresses resolving.

Blocking resolver

The Kernun library name resolver differs from the standard FreeBSD name resolver in following points:

  • It is possible to set the total timeout for a query regardless of the number of domain in the search list and the number of servers.

  • It is possible to set different timeouts for different situations.

  • It is possible to set the timeout for the connect() call in the case of a TCP query.

  • It is possible to set different port numbers for different servers.

Non-blocking resolver

In UDP-based proxies there is a problem with online resolving. Since all requests are processed in a single process, the calling of regular blocking resolver routines would increase proxy latency. Thus, UDP-based proxies running in parent/child mode (i.e. not in the singleproc mode) start an extra child process (Asynchro Parallel Resolver, or APR) that provides the resolution. This process is, in fact, an instance of the core of the dns-proxy(8) working in the forwarding mode.

The resolver section used by the APR is converted to the dns-proxy structures using this schema:

  • There is a special zone named resolver-section-name.APR. Name of this pseudozone can be found in log messages like DNSE-590-C.

  • There is a special server named #server-number within the APR pseudozone for every server in resolver section. These server names can be found in log messages like DNSE-740-W.

Resolver configuration

The key part of resolver configuration is a section named resolver (see resolver(5) manual page) that contains following directives:


The timeout for resolution of each domain name used in configuration. The value is given in seconds with decimal values allowed.

For configuration resolution, see the section called “Configuration Resolution” below.


Timeout to resolve connection critical addresses. The value is given in seconds with decimal values allowed.

This timeout will be used for any resolution necessary for successful progress of the proxy work, e.g. of a server address.


The deresolution of (client and server) IP addresses can be suppressed entirely using this item.


The timeout used for deresolving a client address immediately before logging the SESSION-END message. The value is given in seconds with decimal values allowed.

When a session closes, the SESSION-END message is to be logged. For this message, another attempt to deresolve the client's address is made (of course, only if the first attempt on client deresolution failed because of reaching the initial-timeout).


The timeout for the initial attempt to deresolve a client address. The value is given in seconds with decimal values allowed.

When a client contacts the proxy/server, an attempt to deresolve its address is made. If it fails, the client's address will be logged without a name until the SESSION-END message. In the case of APR (see above) usage, this timeout is ignored.


The order of IPv4 and IPv6 addresses in responses can be selected using this item.


The order of domains added to non qualified domain names for resolving can be selected using this item.


The list of nameservers being queried can be defined using this item.

There can be more resolver sections in the kernun.cml and every component can use its own one (being configured by the use-resolver item). The same item is used also on the system-level configuration and this resolver section defines the system-wide parameters, i.e. content of the file /etc/resolv.conf and parameters for components not using their own resolver section. The behavior of the system name-service switch dispatcher (nsdispatch() function) is not changed - Kernun creates the file /etc/nsswitch.conf with the content hosts: files dns during the installation and does not alter it further.

Configuration Resolution

All names in the configuration are resolved during the proxy startup. Within this process, each name resolution is tried for conf-timeout seconds; if it fails, the name remains unresolved.

If the proxy runs in the parent/child mode (i.e. not the singleproc mode), it starts an extra child process (Asynchro Configuration Resolver, or ACR) as soon as new resolution is needed (i.e. some names have expired). This child tries to resolve the expired names again and stores the result in a memory mapped file shared by all regular children. There are some exceptions to this rule. For instance, the listen-on addresses must be resolved immediately at the beginning of the proxy run and they are not refreshed until the end of the execution of the proxy.

Some parameters of the configuration resolution refreshment can be specified by means of the cfg-resolution configuration item (see application(5)).


Every configuration name has a limited number of addresses, to which it can be resolved. Default: 10.


If the name remains unresolved (either for the negative answer or because of query expiration), this value is used as expiration (and thus also next refresh period) time. Default: 1 min.


If the name TTL is too high, or the name is resolved using the /etc/hosts file (not by DNS), this value is used as expiration (and thus also next refresh period) time. Default: 1 day.


Parent process, resolving child and regular children use a shared file for exchanging resolution results. The file is named RESCFG.proxy-name.parent-PID and resides in the pool-dir directory. Default: /tmp.

See Also

Kernun: application(5), resolver(5), system(5), dns-proxy(8)

FreeBSD: resolv.conf(5), nsswitch.conf(5)


This man page is a part of Kernun Firewall.
Copyright © 2000–2023 Trusted Network Solutions, a. s.
All rights reserved.