Startup and Configuration

The proxy reads its configuration file and starts listening on specified IP sockets (address/port couples), as specified in the listen-on configuration section (see listen-on(5)). Proxy listens for both UDP and TCP protocols.

If support of transparent connections (see transparency(7)) is requested by item transparent in section listen-on, the corresponding NAT redirections are established during proxy startup and removed upon exit. However, transparent connections are in fact not supported by this proxy, decisions about servers are made according to the proxy configuration, not by original destination.

In the resolve mode, the proxy checks each address being stored into cache whether it matches to one of addresses, the proxy listens on. If it does, the record is not stored, so that this does not lead to infinite loop. For this reason, listening addresses (for port 53) must be specified explicitly, expression [0.0.0.0]:53 is not allowed.

DNS Subset

Current version of the dns-proxy implements following subset of protocol:

OPCODEs

Requests with unimplemented OPCODEs are replied with the NotImp response code. Requests with unknown OPCODEs are replied with the FormErr response code.

CLASSes

Requests with query resource record (RR) of unimplemented CLASS are replied with the NotImp response code, unknown classes cause the FormErr response code. The '*' requests are converted to IN, resolved and then sent to the client with authority flag set to 0.

TYPEs

Requests with query RR of unimplemented TYPE are by default replied with the NotImp response code. This behavior can be changed in the configuration (ACL settings). Requests to unknown TYPE are replied with the FormErr response code.

Requests

Every request is stored into a table item containing all necessary information. Size of this table must be specified in configuration (requests-table-size item) and it is recommended to reserve a little more items then estimated number of parallel requests. Some requests processed in resolve mode can generate so called internal requests (see below) that occupy table items, too.

Besides number of requests, number of simultaneously opened sockets is monitored. The maximum of sockets must be specified in the configuration (sockets-table-size item).

There are two kinds of internal requests:

Both types of internal requests suspend processing of the original request (originator) until the internal request is completed. If another request is to generate a new internal request of the same subject as another running one, no new internal request is created and the originator is suspended waiting for the first internal request, too. After (successful or unsuccessful) completion of internal request, all originators are waked up.

Similar principle is used also for client requests. If a request with the same parameters (query name, query type, EDNS UDP payload etc.) is already being processed, new request is also suspended, waiting for the result of the previous request.

Both types of internal requests can also generate new internal requests. For instance, in following definition:

    domain1 IN NS ns.domain2
    domain2 IN NS ns.domain3

a request to the domain1 will generate request to the ns.domain2 name and solution of this will result to a new CACHE request to ns.domain3. Proxy detects an infinite loop, if occurs. Proxy also limits number of internal requests generated by one internal request in the row (item internal-request-depth) to prevent DoS attack by means of non-infinite but very long loop of references.

Both types of internal requests respect the resolving policy according to the query name and type given by the configuration. For every new request, the request-acl list (see below) is searched through and the new ACL defines operation to be used.

If no free request table item is available,

Access Control Lists

The proxy uses two layers of ACL (see access-control(7)) named session-acl and request-acl.

When a request arrives, configuration is consulted, proper session-acl is selected and according to it, request is served or not.

Subsequently, protocol-specific parameters of query is checked against set of request-acl entry conditions and proper mode of operation is selected.

Additionally to the general Kernun ACL concept, request-acl brings new entry condition items:

By these two items, a detail selection of request-acl can be done to set special handling for different tasks like regular queries, zone transfers, server notifications etc.

If no matching ACL is found, request is replied by the Refused response code. If ACL is found, query type and class are checked. Requests with classes other than IN and * (ANY class) are rejected with response code NotImp.

As we stated above, there are several possible proxy operations. The proxy decides among them by matching query RR type against a set of special request-acl items query/notify. The first matching item is used and the operation is executed. If no proper item is found, request is rejected with the Refused response code.

In case of resolve and forward operations, request is resent (with a new, random ID) to a new server. The set of possible responders is defined in a global section of ns-list type. Each received reply RR is then checked against a set of special ACL items called reply in the same manner as queried RR is checked. The reply items can tune handling of particular RR (permit, remove), so as even predefine reaction to the whole request (abort, deny). If no proper reply item is found, request is rejected with the Refused response code. If permit action is required for non-implemented RR, record is removed.

After filtering the response from server, other proper RRs (given by special fake items) can be added to the answer. The same set of items is used for reply construction in case of fake operation. Fake RRs are placed into the answer in the order of appearance in the configuration.

After completing all answer RRs, reply is completely reconstructed and sent to the client. The resolved requests will have the authority (AA) flag cleared while for the forwarded requests, the admin can choose whether to preserve or clear the flag (see the request-acl.query.clear-aa definition in dns-proxy(5)).

If the response has the NXDomain response code, or the NoError response code with no answer (AN) records, and if this status was caused by the proxy (e.g. due to denying query or filtering response), the proxy will add, by default, a SOA record with proper TTL for successful negative caching in clients. This behavior can be configured by the neg-resp-ttl item of the particular request-acl.

Syntax and Semantics Verification

Besides Security Policy application, the proxy checks both queries and replies to correctness in sense of relevant RFCs.

Cache

Name server cache is used for increased efficiency, namely for repeated queries to the same domain (TLDs, resending query via TCP, resolution of CNAMEs etc.). “Root servers” for different network zones are defined in ns-list configuration sections, each zone has a separated cache “zone” named by the name of ns-list section. All other name servers and their addresses are introduced to the cache as a result of authoritative answers. “Authoritative” server (in sense of dns-proxy) is either a root server or a server delegated by some “authoritative” server for a parent domain (already being in the cache). All new RRs are used with respect of their time to live (TTL) value. When the minimal of TTLs of name servers (both their NS and address records) for a domain expires, the domain item is unusable and it is removed from the cache at nearest cleanup. Similarly, when the minimal of TTLs of addresses for a host expires, the host item is unusable and it is removed from the cache at nearest cleanup.

Some properties of the cache are configurable in a special cache section:

If any maximum is reached, a non-periodical cleanup is started. This cleanup removes all items currently not used.

Server Selection Algorithm

When a domain name is to be resolved, the longest match search in the cache is done. After it, the new best server for the domain found is chosen. Server comparison criteria:

This algorithm guarantees a primitive "load balancing" and error recovery of multiple servers.

When querying for an EDNS request, the EDNS servers have priority. If a server responds FormErr to an EDNS query, the non-EDNS query is repeated immediately.

First of all, the selected server is queried with a very short (1 sec.) timeout. When this timeout fires, the query is simply repeated to avoid errors caused by loosing UDP packets.

Then the queried server has a longer timeout for the response. Each server has its own timeout stored in the cache. Starting value of this timeout is set by query-timeout configuration directive. Each time the server does not respond within the timeout, the timeout doubles, up to server-dead value. When the timeout reaches this value, server is marked as “dead” and a new attempt to contact it cannot be done until server-retry seconds period. If the server responds within the timeout, his timeout for the next attempt is set to his response time plus query-timeout.

The number of attempts per one query is hardcoded to eight (regardless of which servers were queried). However, typically this number is not reached before firing the request-timeout (see below).

The same mechanism is used for selection among forwarders. That's why forwarders lists are also stored in the cache (every list in its separated zone).

The timeout for the whole request processing (including resolving of generated internal requests etc.) is also set in the configuration (request-timeout) and if reached, request is replied with the ServFail response code.

Zone Transfers

Zone transfers need some more special handling. First of all, the requests are typically addressed by originators directly to a conrete server. That's why either the transparent mode (if public addresses are used), or non-transparent mode to a dedicated address/port on firewall (in the case of server on a private address) should be used. Also, besides QUERY operation, the NOTIFY operation should be permitted.

Moreover, the own transfers (responses to the AXFR/IXFR queries) should be sent by servers either separated (i.e. more DNS messages with one RR in each one) or aggregated (i.e. all RRs in one DNS message). The proxy can force one of these methods, or keep the incoming format according to the xfr-format configuration directive.

Configuration example:

  ns-list MASTER {
    server ns.x.y.z [10.1.1.1];
  }
  ns-list SLAVE {
    server sns.x.y.z [20.2.2.2];
  }
  ...
  dns-proxy ZONE-TRANSFERS {
    ...
    request-acl TO-MASTER {
      to non-transparent [20.2.2.1]; # special external fw adr
      query { axfr, ixfr } forward MASTER;
      ...
    }
    request-acl TO-SLAVE {
      to transparent [20.2.2.2];
      notify forward SLAVE;
      ...
    }

Common Kernun Features

The proxy uses common Kernun mechanism for listening on its sockets, optionally changing root directory and running with alternative user privileges. For more detailed information, see application(5) and listen-on(5).

The proxy uses common Kernun mechanism for network input/output operations. Configuration allows for specifying several parameters like buffer sizes and timeouts, both for client and server connections. They can be included in client-conn and server-conn configuration sections, respectively. For more detailed information, see netio(7).

The proxy uses common Kernun mechanism for logging. For more detailed information, see logging(7). For every request, one REQUEST (DNSP-860-I) message is logged (besides one or two ACL messages - DNSP-810-I and DNSP-820-I). Every log message has process ID suffix equal to the index of request being currently processed.

The proxy, in fact, does not use common Kernun mechanism for name resolving (see resolving(7) manual page), because it does not use DNS names at all. In spite of that, the item use-resolver remains in the dns-proxy configuration for compatibility with other proxies (and thus e.g. ability to use common cml(8) variables).

Signals

The dns-proxy handles following signals:

Program options

The program options are as follows: