README revision 04bdb234571448ed6194e1d4048e6512f2446f1c
mDNkit
-- multilingual domain name evaluation kit --
version 1.2
Japan Network Information Center (JPNIC)
* Overview
mDNkit is a kit for evaluating various proposed methods regarding
multilingualized/internationalized DNS. To handle multilingualized
domain name, the following features are required:
+ encoding conversion of domain names between
the encoding application uses (local encoding) and
the encoding on DNS protocol.
+ normalization of domain names.
mDNkit provides several ways for adding these features.
This kit consists of following components.
+ DNS proxy server (dnsproxy)
This works as a fake DNS server for the clients. It receives
DNS request containing domain names in the client's local
encoding (e.g. Shift_JIS), translates them into the encoding
on DNS protocol (e.g. UTF-8 or RACE), and forwards to the real
DNS server. Also the response from the server is converted
back to the client's local encoding and returned. See
``1. using dnsproxy'' below.
+ a command dynamically adds MDN feature to unix applications (runmdn)
This command enables normal applications to handle
multilingual domain names by dynamically attaching special
library to them. See ``2. using runmdn'' below.
+ a patch for BIND-9 that adds MDN capability
This patch adds MDN capability to BIND9. BIND 9 employs a
completely new name resolving scheme called ``light weight
resolver'', consisting of client-side library (liblwres) and a
name resolving daemon (lwresd). This patch adds MDN features
to them. See ``3. using patched version of bind-9'' below.
+ mDN wrapper for Windows applications
On windows, name resolving request is passed to WINSOCK DLL. So,
replacing WINSOCK DLL with multi-lingual domain name version
makes legacy windows applications compatible with mDN. This is
wrapper DLL for WINSOCK's name resolving functions. See
``4. using mDN wrapper'' below.
+ a codeset converter for named.conf/zone master files (mdnconv)
This is a codeset (encoding) converter specially designed for
converting named.conf and zone master files from your local
encoding (e.g. EUC-JP) to the encoding which internationalized
DNS servers employ (e.g. UTF-8).
+ libraries for handling multilingual domain names (libmdn, libmdnres)
These are the basic libraries implementing encoding conversion
and normalization. All the commands in this kit (such as
dnsproxy and mdnconv) are built using these libraries.
+ a patch that makes BIND-8 8-bit through
This is needed in order for named and resolver to handle
non-ascii domain names encoded in local encoding or UTF-8.
The patch is rudimentary; it makes almost any byte sequence
legal as a domain name (which is what 8-bit through is for).
+ a patch for making Squid cache server 8-bit through
This is a simple patch that disables Squid's validity check
for host name part in URLs. Without this patch, Squid rejects
URLs containing multilingual domain name (correctly).
This kit provides several ways to handle multilingual domain names
using above components.
** 1. using dnsproxy
domain name encoding domain name
in local conversion and in encoding
+------------+ encoding normalization on DNS
| client | +----------------+ protocol +----------+
|application |------------>| dnsproxy |------------>|DNS server|
| with |<------------| |<------------| |
|8bit through| +----------------+ +----------+
| resolver |
+------------+
** 2. using runmdn
encoding domain name
conversion and in encoding
normalization on DNS
+-----------+-------------+ protocol
| client | dynamically | +----------+
|application| attached |---------------->|DNS server|
|with normal| library |<----------------| |
| resolver | (libmdnres) | +----------+
+-----------+-------------+
** 3. using patched version of bind-9
domain name normalization domain name
in UTF-8 and encoding in encoding
+------------+ encoding conversion on DNS
| client | +----------------+ protocol +----------+
|application |------------>| light weight |------------>|DNS server|
|with bind9's|<------------| resolver |<------------| |
|light weight| | daemon | +----------+
| resolver | +----------------+
+------------+
** 4. using mDN wrapper
domain name normalization domain name
in local and encoding in ecnoding
+-----------+ encoding conversion on DNS
| legacy | +---------+---------+ protocol +----------+
| windows |------------>| mDN | orignal |---------->|DNS server|
| network |<------------| wrapper | winsock |<----------| |
|application| +---------+---------+ +----------+
+-----------+
* Directory structure of this distribution
Below is a directory structure of this distribution with some
important files and their brief description.
+README this file
+README.ja .. in Japanese
+DISTFILES list of files in this distribution
+NEWS what's new in this version
+ChangeLog list of changes
+configure a `configure' script
+Makefile.in toplevel makefile template
+include/
| +config.h.in template header file for configuration
| +mdn/ header files for mdn library
+dnsproxy/ source directory for DNS proxy server
+lib/ source directory for mdn library
+wsock/ source directory for mDN wrapper
+tools/ source directory for tools
| +mdnconv/ source directory for codeset converter
| +runmdn/ source directory for runmdn command
+patch/ various patch files
| +bind8/ bind-8 patch directory
| +bind9/ bind-9 patch directory
| +squid/ squid patch directory
+util/ utilities
* Compilation and installation
0. Prerequisite
If your system's library does not have iconv() function, which is a
general codeset conversion utility, install it as an external library.
You also need external library if the system's implementation cannot
handle UTF-8 encoding, or it doesn't support some encodings which your
client applications uses.
You can get a free version of iconv() implementation (under LGPL
license), from:
1. Running configure script
Run `configure' script in the top directory. This checks various
characteristics of your system and it will create Makefiles and
config.h appropriate for your system.
% ./configure
`configure' accepts many options. Here is a list of some important
options.
--with-iconv=LIB
If your libc doesn't contain iconv(), specify the library
that contains iconv(). For example, if iconv() is libiconv
in /usr/local/lib, you should specify:
--with-iconv="-L/usr/local/lib -liconv"
Note that if the library is a shared one, you might also want to
specify -R option, like:
--with-iconv="-L/usr/local/lib -R/usr/local/lib -liconv"
If the header file "iconv.h" has installed in a non-standard
directory like /usr/local/include, you should specify CFLAGS
environment variable. See below.
--with-iconv-sofile=PATH
``runmdn'' command in this kit needs to know the pathname of
shared library file that contains iconv(), if iconv() is not
part of libc. mDNkit tries to find out the pathname from the
informaiton provided by ``--with-iconv'' option described
above. But when it fails, you have to specify it with this
option, like:
--with-iconv-sofile=/usr/local/lib/libiconv.so.2.0
--with-utf8=NAME
If your iconv() (precisely, iconv_open()) does not accept
"UTF-8" as the name of UTF-8 encoding, specify the name for
it. For example if your iconv() uses "utf8" instead, you
should specify:
--with-utf8=utf8
--with-race-prefix=PREFIX
--with-brace-suffix=SUFFIX
--with-lace-prefix=PREFIX
RACE (Row-based ASCII-Compatible Encoding), BRACE (Bi-mode
Row-based ASCII-Compatible Encoding) and LACE (Length-based
ASCII Compatible Encoding) are proposed encodings for
multilingual domain name in DNS protocol data. They uses a
fixed prefix (or suffix) string to distinguish names encoded
by them from normal ASCII domain names. These prefix/suffix
are defined by the current Internet Drafts and mDNkit uses
them by default, but later version of the drafts may change
them. In that case you can specify the prefix/suffix with
these options.
--enable-zld
The ZLD (zero level domain) support is disabled by default.
If you want to try this feature, this option must be
specified.
--sbindir=DIR
Specifies the install directory for dnsproxy. Default is
--bindir=DIR
Specifies the install directory for mdnconv and runmdn.
Default is /usr/local/bin.
--sysconfdir=DIR
Specifies the install directory for sample files of dnsproxy
configuration and mDNkit's resolver configuration. Default is
--mandir=DIR
Specifies the base install directory for online manuals.
Default is /usr/local/man.
`configure' has many more options. To see the list of available
options, you should run it with --help option.
% ./configure --help
If you want to specify extra compiler options, like adding non-standard
directory to include file search path, use environment variable CFLAGS.
% CFLAGS="-I/usr/local/include -O2" ./configure ... (for sh)
% setenv CFLAGS "-I/usr/local/include -g"; ./configure ... (for csh)
2. Compiling
Run `make' for compilation.
% make
3. Installation
Run `make install' to install binaries and manuals. Don't forget to
become a super-user before the installation.
% su
# make install
4. Configuration and usage
Please consult online manuals for configuration and usage of `dnsproxy'
`mdnconv', and `runmdn'. Also for `mdnconv' and `runmdn', please refer
the manual of mDNkit's resolver configuration file `mdnres.conf'.
% man dnsproxy
% man mdnconv
% man runmdn
% man mdnres.conf
* Applying patches
This distribution also contains patches for BIND 8.2.2-P7,
BIND 8.2.3-T6B, BIND 9.0.0 and Squid 2.3.STABLE3. The top of these
patch files describe how to apply the patch and (re)install.
Note that on Solaris, "patch" command that comes with the system
sometimes doesn't work correctly. You may want to install the GNU
version of the command (http://www.gnu.org/software/patch/) and use
it.
* Contact information
Please see http//www.nic.ad.jp/jp/research/idn/ for the latest news
about this kit.
Bug reports and comments on this kit should be sent to
mdnkit-bugs@nic.ad.jp and idn-cmt@nic.ad.jp, respectively.
; $Id: README,v 1.15 2000/11/21 07:54:13 ishisone Exp $