mDNS Proxy Server Configuration
A number of data items have to be set up to allow use of mdnsproxy, the mDNS Proxy Server. This draft describes the procedure for setup, and its significance.
Configuration File
The configuration file is loaded when mdnsproxy starts up. The configuration file can be specified in the command line when mdnsproxy starts up.
% mdnsproxy -config<config-file>
When not specified in the command line, the default configuration file is used. When mdnsproxy is installed under /usr/local, the default configuration file is /usr/local/etc/mdnsproxy.conf.
This file is a plain text file and the lines of the file (except comments line that begins with # and blank lines) consist of the following simple format.
<group> can be specified by a group name or group ID number.
Keyword value...
listen
Specifies the network address and port number mdnsproxy 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 <IP address> is omitted, 0.0.0.0 (INADDR_ANY) is used and when <port number> is omitted, port number 53 is used. If listen itself is omitted, 0.0.0.0:53 is used as <address>.
Clients that use a DNS server via mdnsproxy 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
mdnsproxy 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.
client-encoding
The client side specifies the domain name encoding.
client-encoding<Encoding>
The DNS requested domain name sent from the client is converted from the encoding specified here to UTF-8 encoding that is used internally. Then, normalization explained later and server side encoding conversion are performed on the domain name and it is sent out to the DNS server. In reverse, the response from the DNS server is converted back to the original encoding and is returned to the client.
Encoding name that can be specified here depends on limbdn attached to mDNkit and the iconv library that is used. The encoding names may differ depending on the iconv library, thus see the library manual to confirm the available encoding name. In addition to the encoding provided by iconv, libmdn supports the following encoding methods that have been proposed for multilingual DNS.
Punycode draft-ietf-idn-punycode-00.txt RACE draft-ietf-idn-race-03.txt DUDE draft-ietf-idn-dude-02.txt
mdn-conf-file
Specifies the configuration file name of libmdn attached to mDNkit.
mdn-conf-file<path>
mdnsproxy performs multilingual domain-related processing using libmdn attached to mDNkit.
mdn-conf-file is used to specify the file name of the configuration file of libmdn.
The file name can be specified using command option -conf. When both are specified, the command line option takes precedence. If neither is specified, the configuration file is loaded from /usr/local/etc/mdn.conf.
For details of how to describe the configuration file of libmdn, refer to mDNkit Configuration.
log-file
Specifies the name of the file that contains the execution log output by mdnsproxy.
log-file<path>
The log file name can also be specified using the -logfile command line option. When both are entered, the command line option takes precedence.
When both are specified, the command line option takes precedence. If neither is specified, the execution log is output to /usr/local/var/mdnsproxy/mdnsproxy.log.
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 mdnsproxy, it temporarily closes the log file and then reopens it. Utilizing this operation, when modifying the log file name and sending a hangup signal, new log file is created. This is a convenient command when the log file is to be archived.
When syslog is specified as <path>, log is output for syslog. When stderr is specified, log is output for standard error output.
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.
When syslog is used to output logs, a fatal error message is output in priority ERR of syslog. In the same way, the warning level error message is output in priority WARNING and trace nessage is output in priority DEBUG.
mdn-log-level
Sets the log level of libmdn.
mdn-log-level<level>
mdnsproxy performs multilingual domain-related processing using libmdn attached to mDNkit.
mdn-log-level is used to set the level of the log with respect to processing inside libmdn.
The following five levels of log are defined.
fatal(= 0)error(= 1)warning(= 2)info(= 3)trace(= 4)dump(= 5)
syslog-facility
Sets the syslog facility.
syslog-facility<facility>
The facility used when log is output using syslog.
When log is not output using syslog, it is ignored.
(To output log using syslog, it must be specified using log-file or -logfile command line.
When it is omitted, daemon is used.
user-id
Specifies the user that uses mdnsproxy.
user-id<user>
Normally, mdnsproxy 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, mdnsproxy runs under the specified user's control with a created privileged port before start of service.
<user> allows you to specify a user name or ID number.
group-id
Specifies group that uses mdnsproxy.
group-id<group>
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 mdnsproxy.
root-directory<path>
This, also, is a security measure. By specifying the root directory used with mdnsproxy access cannot be made outside of this directory. This specification causes mdnsproxy 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.
allow-access
Sets the access restriction based on the IP address of clients to limit clients who can access mdnsproxy.
allow-acccess<where> ...
<where> is specified using one of the following formats.
<IP address> <IP address>/<prefix-length>
The first one permits access from hosts that have the specific IP address. The latter one permits access from the host that have the address prefix specified by <IP address> and <prefix-length>. For example, when the following is specified,
allow-access 192.168.0.0/16
Access from hosts whose upper 16 bits of address (prefix) is 192.168 can be permitted.
More than one entry can be specified. When more than one entry is specified, access is permitted if one of them matches.
When this entry is not specified, access from all hosts is permitted.
log-on-denied
When a connection is rejected by the access restriction set in allow-access, whether it is recorded in the log is specified.
log-on-denied<yes-or-no>
yes or no can be specified.
When yes is specified, the rejected connection is recorded in the log. If not, it is not recorded in the log.
