Configuring DNS Proxy Server

A number of data items have to be set up to allow use of dnsproxy, the DNS Proxy Server. This draft describes the procedure for setup, and its significance.

• Configuration file
• Configuration data
  • listen
  • forward
  • log-file
  • log-level
  • client-translation
  • alternate-encoding
  • normalize
  • server-translation
  • user-id
  • group-id
  • root-directory

---

Configuration File

The setup data can be found in the configuration file. The configuration file can be specified on the command line when dnsproxy starts up.

% dnsproxy -config <config-file>

When not specified on the command line, the default configuration file can be used. The default configuration file

    dnsproxy.conf

is found under the following directory.

    /usr/local/etc

This directory can be specified when the mDNkit is generated.

    configure --sysconfdir=DIR

For details, refer to the installation guide: Configure and implement

---

Configuration Data

The configuration file is a text file and specifies the following configuration data.

listen

Specifies the network address and port number dnsproxy needs in order to receive client queries.

    listen <address>

<address> specifies one of the following formats.

<IP address>:<port number>

:<port number>

<IP address>

When these settings are omitted, the following settings are used.

IP address	0.0.0.0	# INADDR_ANY
port number	53

Clients that use a DNS server via dnsproxy will set up the address and port of the DNS server here. Because most clients cannot usually change the port number, it is best to use default port number 53.

forward

dnsproxy transfers DNS queries and specifies the network address and port number of the DNS server that is to receive the response.

    forward <address> [ bind4compat ]

<address>The address format is the same as that of listen above.

When the option bind4compat is specified, the address and port specified by listen is used as the source address when a request is transferred using UDP. This is a bind4 function and assumes that UDP port access is limited. A source port greater than 1024 is used when this option is not specified.

log-file

Specifies the name of the file that contains the execution log output by dnsproxy.

    log-file <path>

The log file name can also be specified using the following command line option. When both are entered, the command line option takes precedence.

    dnsproxy -logfile <address>

When not specified,

    /tmp/dnsproxy.log

is written.

Note that the execution log is added to continuously and should be deleted from time to time.

When a hangup signal (SIGHUP) is sent to dnsproxy, it temporarily closes the log file and then reopens it. This is a convenient command when the log file is to be archived.

log-level

Specifies the log level.

    log-level <level>

The following log level values can be specified.

none

No log is recorded. The absence of a log file makes it very difficult to identify the cause of a problem. If possible do not use this level.

fatal

Outputs a log only when a fatal error occurs.

warn

Records warning messages in the log. This is the default used when no log level is specified.

trace

Outputs execution trace messages in the log. This level provides a detailed record of dnsproxy operation, which is helpful in determining the cause of a problem. As it records a large amount of data, it is best not used during normal operation.

client-translation

Specifies the domain name encoding to be used on the client side.

    client-translation <ZLD> <Encoding>

For clients that do not support multilingual domain names, the local encoding of the client is normally used. In such a case, the following format is used without <ZLD>.

    client-translation . Shift_JIS

Some multilingual domain name schemes encode multilingual domain names in the client into a format that normal DNS can accept, and adds ZLD (Zero Level Domain) to distinguish it from regular domain names. Since the added ZLD and the domain name encoding scheme are interrelated, they can also be used with DNS servers using a different multilingual domain name scheme.

    client-translation .i-dns.net UTF-5

Multiple domain name encoding schemes can be used in a client if each scheme has its own unique \ZLDs.

Note that ZLD cannot be specified in the default setting of mDNkit. To use a ZLD, --enable-zld must be specifed using the configure command when mDNkit is compiled. All ZLD settings are ignored unless this specification is made when mDNkit is compiled.

The encoding of domain names in the DNS query sent by the client is converted to UTF-8 encoding that is used internally. Then normalization (described below) and conversion to server side encoding are performed after which the data is sent to the DNS server. The response from the DNS server is converted back to the original encoding and returned to the client.

The encoding names that can be used here depend on libmdn and iconv, mDNkit libraries. Since the encoding name used differs with the iconv library that is employed, check the library manual to confirm the encoding names that can be used. In addition to the enconding provided by iconv, libdmn supports the following encoding schemes recommended for multilingual DNS.

UTF-5	draft-jseng-utf5-01.txt
RACE	draft-ietf-idn-race-02.txt
BRACE	draft-ietf-idn-brace-00.txt
LACE	draft-ietf-idn-lace-00.txt

alternate-encoding

Specifies the encoding to be used in place of local encoding when the domain name returned by the DNS server contains characters that cannot be converted to the local encoding of the client.

    alternate-encoding <Encoding>

The specified encoding must be ASCII compatible encoding (ACE) so that the result of conversion is in an encoding that contains only characters that can be used in traditional domain names (alphanumerics and hyphens). For example, this is how to specify RACE, one of the ASCII compatible encoding schemes.

    alternate-encoding RACE

normalize

Specifies the normalization scheme to be used for domain names.

    normalize <scheme> ...

A number of normalization schemes can be indicated, and they will be used in order from left to right.

When the domain name in the DNS query sent by the client has been converted to UTF-8 encoding for internal use, they are normalized according to the normalization scheme specified here. The normalization schemes that can be used depends on the libmdn in the mDNkit. Available normalization schemes are described in the Normalizer Module in the libmdn manual.

server-translation

Specifies domain name encoding schemes to be used on the DNS server side.

    server-translation <ZLD> <Encoding>

Specifies '.' as the default when ZLD is not necessary.

    server-translation . UTF-8

When ZLD is required, specify both ZLD and the encoding name.

    server-translation .i-dns.net UTF-5

The encoding that can be specified is the same as for client-translation above.

user-id

Specifies user that uses dnsproxy.

    user-id <user>

Normally, dnsproxy must be started up with root permission to use a privileged port, but continued use of root permission is not recommended for security reasons. With this specification, dnsproxy runs under the user's control with a privileged port before start of service.

<user> allows you to specify user name or user ID number.

group-id

Specifies group that uses dnsproxy.

    group-id <user>

This resembles the user-id entry, but differs from it in that it specifies a group in place of the user.

<group> can be specified by a group name or group ID number.

root-directory

Specifies the root directory used with dnsproxy.

    root-directory <path>

This, also, is a security measure. By specifying the root directory used with dnsproxy access cannot be made outside of this directory. This specification causes dnsproxy to use chroot() system calls to set the specified directory as the root directory before starting service.

<path> specifies the name of the directory to be used as the root.