
				mDNkit
	    -- multilingual domain name evaluation kit --
			    version 1.2.1
	       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:

	http://clisp.cons.org/~haible/packages-libiconv.html

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
	/usr/local/sbin.

    --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
	/usr/local/etc.

    --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-T9B, BIND 9.0.1 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.1.1.1 2001/01/31 03:58:52 zarzycki Exp $
