dnsproxy specification

# dnsproxy

## 概要

## Overview

dnsproxyは、クライアントからのローカルコードベースの多言語ドメイン名を 含むDNS要求を受け取り、多言語化対応したDNSが受付けられるドメイン名に 変換し、また逆に、DNSからの応答の多言語ドメイン名を、 クライアント側で認識できる形式に戻します。

dnsproxy receives DNS requests including local code-based multilingual domain names from the client and converts them to domain names that can be accepted by the multilingual DNS. In reverse, it returns multilingual domain names included in responses from the DNS to a format that can be recognized by the client side.

これによって、クライアントは何も改造することなく 各種の多言語ドメイン名を使うことができるようになります。 また、DNSサーバから見た場合には、クライアント+dnsproxyによって 多言語ドメイン名に対応したクライアントとして動作しているように 見えることになります。

Because of this, the client can use various multilingual domain names without modification. From the DNS server's point of view, because of client + dnsproxy, the client operates as if it supports multilingual domain names.

ただし、dnsproxy が正しく動作するには、クライアントのリゾルバライブラリが ローカルエンコーディングのドメイン名をそのまま透過させ、エラーにならない ようになっている必要があります。残念ながら現在 UNIX のリゾルバライブラリの 多くは 8ビットスルーではないので、そのままでは dnsproxy を用いても 多言語ドメイン名を扱えるようにはなりません。この場合には

However, in order for dnsproxy to operate correctly, it is necessary for the resolver library of the client to transmit domain names in local encoding as is and does not cause an error. Regretably, many current UNIX resolver libraries are not 8-bit through and they cannot support multilingual domain names even when dnsproxy is used. In such cases, it is necessary to use the following methods.

- BIND-8 の8ビットスルーパッチ を当てたリゾルバライブラリを使用する
- Use resolver library for which 8-bit through patch of BIND-8 is applied
- dnsproxy の代わりに runmdn や BIND-9 パッチ を使用する
- Instead of dnsproxy, use runmdn or BIND-9 patch.

というような方法をとる必要があります。

## 起動

## Usage

>     $ dnsproxy [オプション...]

>     $ dnsproxy [Option...]

## オプション

## Option

-daemon

  dnsproxyをデーモンとして起動します。

  dnsproxy is activated as a daemon.

-config config-file

  コンフィギュレーションファイルを指示します。 コマンドラインで指示しなかった場合には デフォルトのコンフィギュレーションファイルが使用されます。 詳しくはコンフィギュレーションの 項で説明します。

  Indicates the configuration file. When the command line does is not used to indicate a configuration file, the default configuration file is used. The details of this are explained in the Configuration section.

-logfile log-file

  dnsproxyが実行ログを出力するファイル名を指定します。 特に指定されなかった場合には、コンフィギュレーションファイルで 指示されたログファイル、あるいはデフォルトのログファイルに 出力されます。

  Specifies the file name for dnsproxy to output the execution log. Unless otherwise specified, the execution log is output to the log file specified by the configuration file or the default log file.

## コンフィギュレーション

## Configuration

設定情報はコンフィギュレーションファイルに記載されます。 コンフィギュレーションファイルは、 dnsproxyの起動時にコマンドラインで指示することができます。

The configuration information is written in the configuration file. The configuration file can be specified by the command line upon activation of dnsproxy.

>     % dnsproxy -config <config-file>

コマンドラインで指示しなかった場合には デフォルトのコンフィギュレーションファイルが使用されます。 デフォルトのコンフィギュレーションファイルは、ディレクトリ

        /usr/local/etc

の下の

        dnsproxy.conf

です。ディレクトリは、mDNkit作成時に

        configure --sysconfdir=DIR

で指示することもできます。

When the configuration file is not specified by the command line, the default configuration file is used. The default configuration file is located in

        dnsproxy.conf

under

        /usr/local/etc

The directory can be specified by

        configure --sysconfdir=DIR

when mDNkit is created.

コンフィギュレーションファイルはテキストファイルで、 以下のコンフィギュレーションデータを指定します。

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

listen

  dnsproxyがクライアントからの要求を受付ける ネットワークアドレス、ポート番号を指定します。

  Specifies the network address and port number used by dnsproxy to accept requests from the client.

          listen <address>

  <address>は以下のいずれかの形式で指示します。

  <address> is specified using one of the following formats.

  > <IP address>:<port number>
  > :<port number>
  > <IP address>

  省略された場合には
  When omitted

  > IP address | 0.0.0.0 # INADDR_ANY
  > port number | 53

  が使用されます。
  is used.

forward

  dnsproxyが、DNS要求を転送し、応答を受け取る本来のDNSサーバの ネットワークアドレス、ポート番号を指定します。

  dnsproxy specifies the original network address and port number of the DNS server that transfers DNS requests and accepts responses.

          forward <address> [ bind4compat ]

  <address>の形式は上のlistenのものと同じです。
  <address> format is the same as the above listen.

  オプションの bind4compatが指示された場合には、 UDPでリクエストを転送する時に、ソースアドレスとして、 listenで指示されたアドレス/ポートを使用します。

  When an option bind4compat is specified, the address/port specified by listen is used as the source address when a request is transferred via UDP.

log-file

  dnsproxyが実行ログを出力するファイル名を指定します。

  Specifies the file name for dnsproxy to output the execution log.

          log-file <path>

  ログファイル名は、 以下のコマンドラインオプションで指定することもできます。 両方指定した場合にはコマンドラインオプションの指定のほうが優先されます。

  The log file name can be specified by the following command line option. When both are specified, priority is given to the command line option specification.

          dnsproxy -logfile <address>

  指定されなかった場合には、

          /tmp/dnsproxy.log

  に書き込まれます。

  When the log file name is not specified, the execution log is output to

          /tmp/dnsproxy.log

log-level

  ログのレベルを設定します。

  Sets the log level.

          log-level <level>

  レベルとして指定できる値は次の通りです。

  The level values that can be specified are as follows.

  > none
  >   一切ログを記録しません。
  > none
  >   Logs are not recorded at all.
  > fatal
  >   致命的なエラーのみ記録します。
  > fatal
  >   Records only fatal errors.
  > warn
  >   警告メッセージも記録します
  > warn
  >   Records warning messages as well.
  > trace
  >   実行トレースメッセージも記録します。
  > trace
  >   Records execution trace messages as well.

  指定しなかった場合のデフォルトは warn です。

  When the value is not specified, the default is warn.

  none を指定した場合、ログファイルは作成されません。

  When none is specified, no log file is created.

  trace レベルを指定すると大量のログが出力されるので、短時間で ログファイルが巨大になる可能性があります。注意してください。

  Use care that when the trace level is specified, large log files are output and it is possible that the log file can become very large in a short period of time.

client-translation

  クライアント側でのドメイン名のエンコーディングを指示します。

  Indicates the encoding of the domain name at the client side.

          client-translation <ZLD> <Encoding>

  多言語ドメイン名に対応していないクライアントの場合には、 通常、クライアントのローカルエンコーディングになっています。 そのような場合には

  When the client does not support multilingual domain names, usually the local encoding used by the client is used. In such a case, use the following form

          client-translation . Shift_JIS

  という形で、<ZLD>無しで指示します。

  and with no <ZLD>.

  多言語ドメイン名の手法によっては、 クライアント側で多言語ドメイン名を通常のDNSでも 受付けられる形式にエンコードして、それを通常のドメイン名と 区別するために ZLD (Zero Level Domain) を付加するものがあります。 そのような場合には、付加されるZLDとその時のドメイン名の エンコーディング方法とを対応付けることにより、 他の多言語ドメイン名の手法のDNSサーバを利用することが できるようになります。

  Depending on the multilingual domain name method used, the client side encodes multilingual domain names so that the usual DNS can accept them and adds ZLD (Zero Level Domain) in order to distinguish them from the usual domain names. In such cases, by associating the added ZLD and encoding method of the domain name at that time, it becomes possible to use DNS servers that use another multilingual domain name method.

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

  クライアント側のドメイン名のエンコーディングは、 ZLD が異なっていれば、複数指定することができます。

  More than one encoding method can be specified for domain names at the client side when the ZLD is different.

  ただし、mDNkit のデフォルトの設定では ZLD の指定はできないように なっています。ZLD を使用するためには、mDNkit のコンパイルの際、 `configure` コマンドに `--enable-zld` を指定する必要があります。 この指定をせずに mDNkit をコンパイルした場合には、ZLD の指定は すべて無視されます。

  However, ZLD cannot be specified with the default setting of mDNkit. In order to use ZLD, it is necessary to specify `--enable-zld` in the `configure` command when compiling mDNkit. If mDNkit is compiled without this specification, ZLDs are all ignored even though they may be specified.

  クライアントから送られてきたDNS要求のドメイン名は、 ここで指示したエンコーディングから、内部的に使用される UTF-8エンコーディングに変換されます。 そして、後述の正規化、サーバ側エンコーディングへの変換が 行なわれてDNSサーバに送出されます。また、DNSサーバからの 応答は、逆に元のエンコデーィングに戻されてクライアントに 返されます。

  The domain name of the DNS request sent from the client is converted from the specified encoding to the internally used UTF-8 encoding. Then, normalization (explained below) and conversion to the server side encoding are performed and it is output to the DNS server. Also, the response from the DNS server is converted back to the orginal encoding and is returned to the client.

  ここで指定可能なエンコーディング名は、mDNkit付属のlibmdnおよび 使用するiconv ライブラリに依存します。 iconv ライブラリによって、エンコーディング名が異なっている ことがありますので、ライブラリのマニュアルをご覧になって 使用可能なエンコーディング名を確認してください。 付属のlibmdnでは、iconvが提供するエンコーディングの他に、 多言語化DNS用に提案されている

  Encoding names that can be specified here depend on libmdn attached to mDNkit and iconv library used. Encoding names may differ depending on the iconv library. Refer to the manual of the library and check the encoding names that can be used. With the attached libmdn, in addition to the coding provided by iconv, the following proposed multilingual DNS coding methods are supported.

  > 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

  DNS サーバから返されたドメイン名がクライアントのローカルエンコーディングに 変換できない文字を含んでいた場合に、ローカルエンコーディングの代わりに使用する エンコーディングを指定します。

  When a domain name returned from the DNS server includes characters that cannot be converted to the local encoding used by the client, this specifies the encoding to be used instead of local encoding.

          alternate-encoding <Encoding>

  指定するエンコーディングは必ず「ASCII互換エンコーディング (ACE)」と呼ばれる、 変換結果が従来のドメイン名として使用可能な文字 (英数字およびハイフン) だけ からなるエンコーディングでなければなりません。たとえば ASCII 互換 エンコーディングの一つである RACE を指定する場合には次のように指定します。

  The specified encoding must be "ASCII-conpatible encoding (ACE)" so that the conversion result consists of only characters (alphanumeric characters and hyphens) that are used in conventional domain names. For example, to specify RACE (one type of ASCII-compatible encoding), specify as follows.

          alternate-encoding RACE

normalize

  ドメイン名の正規化手法を指定します。

  Specifies the normalization method used for domain names.

          normalize <scheme> ...

  正規化手法は複数指定可能で、左側から順に適用されていきます。

  More than one normalization method can be specified and they are applied in order starting from the left side.

  クライアントから送られてきたDNS要求のドメイン名は、 内部的に使用されるUTF-8エンコーディングに変換された上で、 ここで指示した正規化が適用されます。

  Domain names in the DNS request sent from the client are converted to internally used UTF-8 encoding and then the normalization specified here is applied.

  次に示す正規化手法を指定することができます。

  The following normalization methods can be specified.

  - ascii-uppercase
  - ascii-lowercase
  - unicode-uppercase
  - unicode-lowercase
  - unicode-form-c
  - unicode-form-kc
  - ja-kana-fullwidth
  - ja-alnum-halfwidth
  - ja-compose-voiced-sound
  - ja-minus-hack
  - ja-delimiter-hack

  それぞれの内容については libmdnのマニュアルの normalizer モジュール を参照してください。

  For details of each method, refer to normalizer module of the libmdn manual

server-translation

  DNSサーバ側のドメイン名エンコーディング方法を指示します。

  Indicates the encoding method used for domain names at the DNS server side.

          server-translation <ZLD> <Encoding>

  ZLDが不要なエンコーディングであれば、`<ZLD>` の部分には `'.'` を指示します。

  When the encoding method does not need a ZLD, specify `'.'` in `<ZLD>`.

          server-translation . UTF-8

  ZLDを必要するエンコーディングでは、ZLDとエンコーディング名の 両方を指定します。

  When the encoding method requires a ZLD, specify both the ZLD and encoding name.

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

  ZLD の指定を有効にするには、mDNkit のコンパイル時の設定が必要です。 `client-translation`の項を ご覧ください。

  To make the ZLD specification active, you must set a setting when compiling mDNkit. Refer to the `client-translation` section for details.

  指定可能なエンコーディングは、前出の `client-translation` でのものと同じです。

  The encoding methods that can be specified are the same as those previously explained in `client-translation`.

user-id

  dnsproxy が動作するユーザを指定します。

  Specifies users for whom dnsproxy is operational.

          user-id <user>

  通常、dnsproxy は特権ポートを使用するためルート権限で起動させる必要が ありますが、ルート権限のままで動作させるのはセキュリティ上好ましくありません。 この指定により、dnsproxy は特権ポートを作成したあとサービスを開始する前に 指定したユーザの権限で動くようになります。

  Usually, since dnsproxy uses a special port, it can only be activated if the user has root authorization; however, operating under root authorization is not recommended for security reasons. With this specification, after the special port is created, dnsproxy operates uner the specified user authorization before starting the service.

  <user> にはユーザ名あるいはユーザ ID 番号を指定することができます。
  User name or user ID number can be specified in <user>.

group-id

  dnsproxy が動作するグループを指定します。

  Specifies the group wherein dnsproxy operates.

          group-id <user>

  これは `user-id` エントリと似ていますが、ユーザの代わりにグループを 指定する点が異なります。

  This looks like the `user-id` entry but differs in that a group is specified instead of a user.

  <group> にはグループ名あるいはグループ ID 番号を指定することが できます。

  The group name or group ID number can be specied in <group>.

root-directory

  dnsproxy が動作する際のルートディレクトリを指定します。

  Specifies the root directry when dnsproxy operates.

          root-directory <path>

  これもセキュリティ対策の一つです。dnsproxy が動作する際のルートディレクトリ を指定することで、そのディレクトリの外にはアクセスできないようにします。 この指定により、dnsproxy はサービスを開始する前に、chroot() システムコールを用いて指定したディレクトリをルートディレクトリとして 設定します。

  This is also a security measure. By specifying the root directory when dnsproxy operates, access other than by the specified directory is prevented. Because of this specification, dnsproxy sets the specified directry using the chroot() system call as the root directory before dnsproxy starts the service.

  <path> にはルートとして設定したいディレクトリ名を指定します。

  Directry name to be set as the root is specified in <path>.

## シグナル

## Signal

dnsproxy に SIGHUP シグナルを送ると、ログファイルをいったん閉じ、 再度オープンするという動作を行います。これは次のような手順で ログをアーカイブできるようにするためです。

When a SIGHUP signal is sent to dnsproxy, the log file is closed and opened again. This is performed so that the log can be archived as described in the following procedure.

1. `mv` コマンド等を用いてログファイルを別の名前にする。
   Use `mv` command to create a different name for the log file.
2. dnsproxy に SIGHUP を送り、新たなログファイルをオープンさせる。
   Send a SIGHUP signal to dnsproxy to open a new log file.