
				mDNkit
		-- multilingual domain name toolkit --
			     version 2.1
	       Japan Network Information Center (JPNIC)


* Overview

mDNkit is a toolkit for handling multilingualized/internationalized 
domain names.  To handle such names, the following features are required:

    + Encoding conversion
	Multilingualized domain names have to be converted from
	the encoding application uses (local encoding) to
	the encoding used for name resolution (IDN encoding), and
	vice versa.  Since domain names in IDN encoding just look
	like good old ASCII domain names, the encoding is also known
	as ASCII-compatible encoding (ACE).

    + NAMEPREP
	Name preparation of domain names before converting to
	IDN encoding.  Basically this is a normalization process
	of the domain names.

These conversion/nameprep processes to domain names have to be
performed before they are sent to DNS servers.  And since the
processed domain names (in IDN encoding) consist of only legal ASCII
characters, no changes are required to DNS servers.
	
mDNkit provides several ways for adding these features.

This kit consists of following components.

    + library for handling multilingual domain names (libmdn)
	This is a library implementing encoding conversion and
	nameprep.  The library provides easy-to-use API for these
	features, so it should be easy to add capability of handling
	multilingual domain name to your applications using this
	library.
	This library is also used for implementing various commands in
	this toolkit (such as mdnsproxy and mdnconv).

    + DNS proxy server (mdnsproxy)
	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
	``2. using mdnsproxy'' 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 ``3. using runmdn'' below.

    + a patch for BIND-9 that adds MDN capability
	This patch adds MDN capability to BIND9.  It adds encoding
	conversion and nameprep features to `dig', `host' and
	`nslookup'.  With the patch, those commands become capable of
	multilingual domain names.

    + 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. RACE).

    + 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 API
    This is the preferred way to handle multilingual domain names,
    applications are required to explicitly call the name conversion
    API mDNkit provides.

				  domain name
   +-----------+-------+--------+   in ACE
   |           |       |        |  encoding  +------------+
   |  client   |  mdn  |system's|----------->| DNS server |
   |application|library|resolver|<-----------|            |
   |           |       |        |            +------------+
   +-----------+-------+--------+ 

 ** 2. using mdnsproxy
    In case the application cannot be modified to use the above API,
    you can still be able to use multilingual domain names using
    mdnsproxy, provided that the application uses 8bit-through
    resolver.

		  domain name      encoding      domain name
		   in local     conversion and     in ACE
   +------------+  encoding        nameprep       endoding
   |   client   |             +----------------+             +----------+
   |application |------------>|   mdnsproxy    |------------>|DNS server|
   |    with    |<------------|                |<------------|          |
   |8bit through|             +----------------+             +----------+
   |  resolver  |
   +------------+

 ** 3. using runmdn
    Or if the client application dynamically links resolver API (such as
    gethostbyname) and the OS supports certain features, you can use
    runmdn.  By replacing the resolver API with a version which performs
    encoding conversion and nameprep, runmdn enables normal applications
    to resolve multilingual domain names.

		   encoding      domain name
		conversion and     in ACE
		   nameprep       encoding
   +-----------+-------------+                 +----------+
   |   client  | dynamically |---------------->|DNS server|
   |application|  attached   |<----------------|          |
   |           |   library   |                 +----------+
   +-----------+-------------+

 ** 4. using mDN wrapper
    By wrapping WINSOCK DLL, mDN Wrapper enables Windows applications
    to resolve multilingual domain names.

                domain name    nameprep           domain name
                 in local     and encoding          in ACE
   +-----------+ encoding      conversion          encoding
   |  legacy   |             +---------+---------+           +----------+
   |  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
    +Makefile.in	toplevel makefile template
    +configure		a `configure' script
    +include/
    |	+config.h.in	template header file for configuration
    |	+mdn/		header files for mdn library
    +lib/		source directory for mdn library
    +mdnsproxy/		source directory for DNS proxy server
    +patch/		various patch files
    |	+bind8/		bind-8 patch directory
    |	+bind9/		bind-9 patch directory
    |   +libiconv/	libiconv patch directory
    |	+squid/		squid patch directory
    +tools/		source directory for tools
    |	+mdnconv/	source directory for codeset converter
    |   +runmdn/	source directory for runmdn command
    +util/		utilities
    +wsock/		source directory for mDN wrapper


* 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

*Note*
  The current version of the above implementation (libiconv-1.6.1) is
  known to have a compilation problem on NetBSD 1.5.  There is a patch
  file for the bug under patch/libiconv directory.  If you are a
  NetBSD 1.5 user and found a problem in compiling libiconv, apply the
  patch and try again.  The patch file contains brief instructions on
  how to apply it at the beginning.

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-preference=PREFERENCE
	This option sets the preference for the sample mDNkit
	configuration file (mdn.conf.sample).  Also this option
	enables to install default configuration file (mdn.conf)
	if the file didn't exist.
	The only preference supported by this version is "jp".

    --with-race-prefix=PREFIX
    --with-brace-suffix=SUFFIX
    --with-lace-prefix=PREFIX
    --with-dude-prefix=PREFIX
	RACE (Row-based ASCII-Compatible Encoding), BRACE (Bi-mode
	Row-based ASCII-Compatible Encoding), LACE (Length-based ASCII
	Compatible Encoding) and DUDE (Differential Unicode Domain
	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.

    --with-altdude-prefix=PREFIX
    --with-altdude-suffix=SUFFIX
    --with-amc-ace-m-prefix=PREFIX
    --with-amc-ace-m-suffix=SUFFIX
    --with-amc-ace-o-prefix=PREFIX
    --with-amc-ace-o-suffix=SUFFIX
    --with-amc-ace-r-prefix=PREFIX
	AltDUDE, AMC-ACE-M, AMC-ACE-O and AMC-ACE-R are also proposed
	encodings for multilingual domain names.  Unlike encodings
	mentioned above, the Internet Drafts for these do not define
	specific prefixes nor suffixes.  mDNkit provides default for
	them, but you can override them with these options.
	You can specify either prefix or suffix for AltDUDE, AMC-ACE-M
	and AMC-ACE-O.  In case both are specified, prefix is
	preferred.

    --sbindir=DIR
	Specifies the install directory for mdnsproxy.  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 mdnsproxy
	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 `mdnsproxy'
`mdnconv', and `runmdn'.  Also for `mdnconv' and `runmdn', please refer
the manual of mDNkit's resolver configuration file `mdn.conf'.

	% man mdnsproxy
	% man mdnconv
	% man mdn.conf


* Applying patches

This distribution also contains patches for BIND 9.1.1, BIND 8.2.3 and
Squid 2.4.STABLE1.  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.29 2001/06/01 01:13:46 ishisone Exp $
