README revision 401538f8dd8a608a8c1fea5876c80536fe8986d0
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:
*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
--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
--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 $