dns-proxy

dns-proxy
Prev	Kernun UTM Reference (5)	Next

Name

dns-proxy — format of dns-proxy component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the dns-proxy component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in dns-proxy configuration directives:

enabling (see common(5))

yes-no (see common(5))

direction (see common(5))

ip-version (see common(5))

osi4-proto (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

obligation (see common(5))

dbglev (see log(5))

logfail-mode (see log(5))

week-day (see time(5))

month (see time(5))

auth-method (see auth(5))

source-address-mode (see source-address(5))

transparency (see acl(5))

user-auth-spec (see acl(5))

doctype-ident-method (see acl(5))

dns-type (see resolver(5))

dns-opcode (see resolver(5))

dns-response (see resolver(5))

dns-qaction (see resolver(5))

dns-raction (see resolver(5))

dns-fake (see resolver(5))

xfr-mode (see resolver(5))

listen-on-sock (see listen-on(5))

dns-name-type (name-usage obligatory)

forward, reverse

ITEMS AND SECTIONS

Configuration of dns-proxy library component consists of following prototypes:

* dns-proxy name { ... }

Description:

dns-proxy name {

  phase ... ;
* tag ... ;
  log-debug { ... }
  log-stats { ... }
  use-resolver ... ;
  cfg-resolution ... ;
  monitoring { ... }
  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
  nodaemon ... ;
  singleproc ... ;
  app-user ... ;
  idle-timeout ... ;
  run-block-sigalrm ... ;
  listen-on { ... }
  doctype-identification { ... }
  queue-size ... ;
  edns ... ;
  dnssec ... ;
  cache { ... }
  request-timeout ... ;
  response-timeout ... ;
  query-timeout ... ;
  server-dead ... ;
  server-retry ... ;
  server-proto ... ;
  requests-table-size ... ;
  sockets-table-size ... ;
  internal-request-depth ... ;
  adr-reply-limit ... ;
  ptr-reply-limit ... ;
  client-conn { ... }
  server-conn { ... }
* session-acl name { ... }
* request-acl name { ... }
}

This section defines DNS-proxy attributes.

The dns-proxy section is derived from proxy section prototype. For detail description of it, see application(5).

Changes to the dns-proxy section:

Section tcpserver is not valid.

Section udpserver is not valid.

Item source-address is not valid.

At least one SESSION-ACL must be specified (proxy must be named in some SYSTEM.ACL.SERVICES).

At least one REQUEST-ACL must be specified.

EDNS must be enabled for DNSSEC.

Item phase (see common(5))

Element number is optional, default: 20.

Section monitoring (see monitoring(5))

Item user is not valid.

Item aproxy-user is not valid.

Item data used as query.

Item idle-timeout (see application(5))

Element seconds is optional, default: 120.

Item listen-on.non-transparent (see listen-on(5))

Element port is optional, default: 53.

DNS proxy cannot bind address [0.0.0.0] : 53.

Item listen-on.transparent (see listen-on(5))

Element port is optional, default: 53.

Added items & subsections:

queue-size [value];

Queue length for listen(2) syscall.

value (type: uint8, optional, default: 10)

edns [support];

EDNS support.

support (type: enabling, optional, default: enable)

dnssec [support];

DNSSEC support.

support (type: enabling, optional, default: disable)

cache {

  cleanup-period ... ;
  max-domains ... ;
  max-hosts ... ;
}

Internal nameserver cache attributes.

This cache is used by the proxy for internal purposes only.

Items & subsections:

cleanup-period [seconds];

Cache cleanup period.

Cache is periodically cleaned, items not used within last cleanup period are removed.

seconds (type: uint16, optional, default: 900)

max-domains [items];

Maximum of domains stored in the cache.

If reached, non-periodical cleanup is done.

items (type: uint16, optional, default: 1000)

max-hosts [items];

Maximum of nameservers stored in the cache.

If reached, non-periodical cleanup is done.

items (type: uint16, optional, default: 2000)

[End of section dns-proxy.cache description.]

request-timeout [seconds];

Timeout to close uncompleted requests and reply by ServFail.

seconds (type: uint16, optional, default: 120)

response-timeout tmout;

Timeout to send responses (after expiring no response is sent).

tmout (type: fract)

query-timeout [seconds];

Initial timeout for querying another server.

seconds (type: uint16, optional, default: 2)

server-dead [seconds];

Timeout to assume server is dead.

seconds (type: uint16, optional, default: 15)

server-retry [seconds];

Timeout to wait before retry dead server.

seconds (type: uint16, optional, default: 15)

server-proto ver;

Allowed protocol for resolving from the root.

If not used, no restriction is applied.

ver (type: ip-version)

requests-table-size [number];

Number of simultaneous requests.

Requests table contains both client requests (UDP and TCP) and internal requests (nameserver resolving and CNAME querying).

number (type: uint16, optional, default: 256)
Constraints:: Number of requests must not be zero.

sockets-table-size [number];

Number of simultaneously opened sockets.

Sockets table contains each socket used for solving of any request in parallel.

number (type: uint16, optional, default: 0): Number of sockets, default is REQUESTS-TABLE-SIZE * 2

internal-request-depth [number];

Number of internal requests generated recursively.

number (type: uint16, optional, default: 50)

adr-reply-limit [bytes];

Size limit for A and AAAA RRs in answer.

Older clients' resolver routines crashes on too long replies. Reasonable value is default one, use zero to switch test off.

bytes (type: uint16, optional, default: 8192)

ptr-reply-limit [bytes];

Size limit for PTR RRs in answer.

Older clients' resolver routines crashes on too long replies. Reasonable value is default one, use zero to switch test off.

bytes (type: uint16, optional, default: 512)

client-conn {

  conn-timeout ... ;
  recv-timeout ... ;
  recv-bufsize ... ;
  send-timeout ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Client connection options.

The client-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Item recv-bufsize (see netio(5))

Element bytes is optional, default: 4100.

Input buffer size must be at least 512B.

Item send-timeout (see netio(5))

Element seconds is optional, default: 60.

Item send-bufsize (see netio(5))

Output buffer size must be at least 512B.

server-conn {

  conn-timeout ... ;
  recv-timeout ... ;
  recv-bufsize ... ;
  send-timeout ... ;
  close-timeout ... ;
  send-bufsize ... ;
  log-limit ... ;
}

Server connection options.

The server-conn section is derived from sock-opt section prototype. For detail description of it, see netio(5).

Item recv-bufsize (see netio(5))

Input buffer size must be at least 512B.

Item send-timeout (see netio(5))

Element seconds is optional, default: 60.

Item send-bufsize (see netio(5))

Element bytes is optional, default: 4100.

Output buffer size must be at least 512B.

session-acl name {

* from ... ;
* to ... ;
* time ... ;
  time-period-set { ... }
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
  source-address ... ;
}

The first level ACL decides only between acceptation and denial of the incoming datagram/connection.

The session-acl section is derived from acl-1 section prototype. For detail description of it, see acl(5).

Changes to the session-acl section:

Item user is not valid.

Item auth is not valid.

Item idle-timeout is not valid.

Item idle-timeout-peer is not valid.

Item plug-to is not valid.

request-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* session-acl ... ;
  deny ... ;
  accept ... ;
* doctype-ident-order ... ;
  rule ... ;
* query-name ... ;
* request-type ... ;
* query ... ;
  notify ... ;
* reply ... ;
* fake ... ;
  edns ... ;
  ignore-void-rr ... ;
  ignore-missing-aa ... ;
  ignore-trailer ... ;
  rr-limit ... ;
  xfr-format ... ;
  neg-resp-ttl ... ;
  client-altq ... ;
  server-altq ... ;
}

The second level ACL decides how to handle particular DNS query/notify request.

The request-acl section is derived from acl-2 section prototype. For detail description of it, see acl(5).

Changes to the request-acl section:

Item server is not valid.

Item user is not valid.

Item parent-acl used as session-acl.

At least one QUERY/NOTIFY must be specified.

DENY and QUERY/NOTIFY are mutually exclusive.

QUERY/NOTIFY and REPLY set must be consistent.

Cannot mix CNAME and other RR types.

Added items & subsections:

query-name [forward] names;

query-name reverse nets;

Entry condition - request domain name.

If no QUERY-NAME item is used, ACL matches for all requests independently of domain name.

<branching element> (type: dns-name-type, optional, default: forward)

names (type: str-set)

Set of domain names and/or regexps.

Query name matches the set if

matches any regexp-member of the set (regexp must respect a dot appended to every tested name), or
any name-member of the set is equal to the last part of the query name.

nets (type: net-set)

Set of networks.

Query name matches the set if it is a reverse query (*.in-addr.arpa or ip6.arpa) and the corresponding host matches the set.

request-type op-types [rr-types];

Entry condition - request type.

If no REQUEST-TYPE item is used, ACL matches for all requests independently of request type.

op-types (type: dns-opcode-set): Set of DNS operation types (QUERY and NOTIFY supported).
rr-types (type: dns-type-set, optional, default: *): Set of RR types requested.

query types abort;

query types deny [error-code];

query types resolve ns-list;

query types forward ns-list [clear-aa];

query types fake;

Allow/deny particular query types for matching domain names. Each query received is checked against QUERY items in order of their occurence in cfg file, and the first matching one is used. If no one matches, request fails.

types (type: dns-type-set): Set of query types matching this QUERY section.
<branching element> (type: dns-qaction): DNS operation requested for matching queries.
ns-list (type: name of ns-list, see resolver(5)): Nameserver address list used resolving or forwarding.
clear-aa (type: key, optional): Clear AA flag in responses being forwarded.
error-code (type: dns-response, optional, default: Refused=5): Response code for denied queries.

notify abort;

notify deny [error-code];

notify resolve ns-list;

notify forward ns-list;

notify fake;

Allow/deny NOTIFY requests for matching domain names. If NOTIFY item is not used, request fails.

<branching element> (type: dns-qaction): DNS operation requested by this item.
ns-list (type: name of ns-list, see resolver(5)): Nameserver addresses.
error-code (type: dns-response, optional, default: Refused=5): Response code used.
Constraints:: NOTIFY requests cannot be handled by RESOLVE or FAKE.

reply types abort;

reply types deny [error-code];

reply types permit;

reply types remove;

Allow/deny particular reply RR types for particular domain names. Each record received is checked against REPLY items in order of their appearance in cfg file, and the first matching one is used. If no one matches, query is denied (FormErr).

types (type: dns-type-set): Set of RR types.
<branching element> (type: dns-raction): DNS operation requested by this item.
error-code (type: dns-response, optional, default: Refused=5): Response code used.

fake ttl 0;

fake ttl a addr;

fake ttl ns name;

fake ttl 3;

fake ttl 4;

fake ttl cname name;

fake ttl 6;

fake ttl 7;

fake ttl 8;

fake ttl 9;

fake ttl 10;

fake ttl 11;

fake ttl ptr name;

fake ttl 13;

fake ttl 14;

fake ttl mx prty name;

fake ttl 16;

fake ttl 17;

fake ttl 18;

fake ttl 19;

fake ttl 20;

fake ttl 21;

fake ttl 22;

fake ttl 23;

fake ttl 24;

fake ttl 25;

fake ttl 26;

fake ttl 27;

fake ttl aaaa addr;

Fake particular RRs in answer.

ttl (type: uint32): Time-to-live value of DNS RR.
<branching element> (type: dns-fake)
prty (type: uint16): Priority value of MX DNS RR.
name (type: str): Hostname value of various DNS RRs.
addr (type: host): IPv4 address of address type DNS RR.

edns [udp-payload udp-payload];

EDNS support parameters.

udp-payload udp-payload (type: uint16, optional, default: 4096): Maximum UDP payload.

ignore-void-rr [status];

Ignore RRs with name having no relationship to the question.

Without this item, the dns-proxy rejects replies having RRs with name that does not appear in other RR, e.g. due to incorrect using of CNAMEs. The server is marked as untrusted.

Some nameservers send more A RRs in the ADDITIONAL section than NS RRs in the AUTHORITY section. This item can prevent to mark them as unusable.

status (type: enabling, optional, default: enable)

ignore-missing-aa [status];

Ignore missing AUTHORITATIVE flag in the response.

The algorithm used by the proxy is based on a strategy to find recursively a server for particular domain that admits the fact that it is an authoritative server for this domain. However, some authoritative servers does not set this flags so this algorithm fails.

This flag allows to ignore missing AA flag (for domains where this behavior is known) and trust the answer even without the flag.

status (type: enabling, optional, default: enable)

ignore-trailer [status];

Ignore meaningless appendices.

Some servers write errorneous responses containing meaningless byte stream at the end. Proxy ignores this appendix by default. This item can disable this feature and errorneous responses will be treated as errors.

status (type: enabling, optional, default: enable)

rr-limit [records];

Maximal allowed number of RRs in response to request.

This limitation is used for DoS prevention, you can set it accordingly to the request type. For zone transfer, this limitation respects total number of RRs in all separated DNS messages belonging to the request.

records (type: uint32, optional, default: 1000)

xfr-format [mode];

Zone transfer format.

mode (type: xfr-mode, optional, default: keep)

neg-resp-ttl [seconds];

TTL for negative responses.

If the proxy sends negative QUERY responses (NoError response code with no answer records or NXDomain response code), e.g. by faking replies, by filtering out of incoming response records, or by denying of particular query/response, it can send a SOA record in AUTHORITY section. This record causes caching of this negative answer in clients (nameservers) for the time used as the TTL of the SOA RR. This value can be defined by this item.

Setting the TTL to zero means switching this feature off. Use this with care because it can cause ineffectivity of DNS service.

seconds (type: uint32, optional, default: 3600)

client-altq altq [paltq paltq];

ALTQ queues for data sent to client.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

server-altq altq [paltq paltq];

ALTQ queues for data sent to server.

altq (type: name of pf-queue, see pf-queue(5)): queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL): priority queue name (if set, used for TCP ACK without data)

[End of section dns-proxy.request-acl description.]

[End of section dns-proxy description.]

Prev	Up	Next
dhcp-server	Home	dns-proxy.cfg

Name

DESCRIPTION

TYPES

ITEMS AND SECTIONS

SEE ALSO