Install

This document describes mDNkit compiling and installation procedures. Procedures for how to install from the source is described here. Distribution of binary packages is planned; refer to the instructions that accompany each package.

This document describes the compiling and installing procedures for Unix. Refer to the section Setup in mDN Wrapper for information on procedures to install in Windows mDN Wrapper.

Installation procedures from source distribution are implemented as follows.

Preparations
Extracting distribution source
Executing configure
Compile
Installing files

After installation, refer to and set up DNS Server Configuration, mDNkit Configuration, and if mdnsproxy is to be used mDNS Proxy Server Configuration.

To install the patch included in source distribution, refer to the following instructions.

Applying and Installing the BIND 9 Patch
Applying and Installing the BIND 8 Patch
Applying and Installing the Squid Patch

Preparations

iconv installation

mDNkit uses iconv() , a general-purpose utility, to convert domain name encoding of EUC, SJIS or other local encoding. iconv() must be installed prior to mDNkit installation in those systems that do not have iconv() as a standard package, such as FreeBSD. Also, the mDNkit requires that iconv() should support UTF-8 encoding. An external package must be installed if the provided iconv() in the system does not support UTF-8.

There are free versions of iconv(), for example, GNU libiconv.

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

This source can be downloaded from the above page. This is an LGPL-based free software package that runs on a variety of Unix operating systems. Refer to the above page or the INSTALL.generic file that accompanies the source distribution for information on installation procedures.

Obtaining the BIND 9 source

mDNkit includes the patch for BIND 9. By using this, it is possible to directly specify multilingual domain names for tools such as dig or nslookup included in BIND 9.

To use these tools, prepare the source of BIND 9 beforehand. The patch in this kit is for BIND 9.1.3. The source can be downloaded from the following page.

http://www.isc.org/products/BIND/bind9.html

Obtaining the BIND 8 source

To use mdnsproxy to enable client applications to support multilingual domain names, the resolver library that resolves names must be made 8-bit through.

The mDNkit for that reason supplies a patch that makes BIND 8.2. 8-bit through. To use BIND 8 with an installed patch, obtain the source of this version. Sources can be downloaded from the following page.

http://www.isc.org/products/BIND/bind8.html

Obtaining Squid

Squid, a Web cache server, cannot be used as is, because it will generate an error when entering multilingual domain names. mDNkit comes with a patch that makes Squid-2.4.STABLE1 8-bit through. Obtain this source if you wish to make Squid support multilingual domain names.

Extracting distribution source

The latest information regarding the mDNkit is available on the following site. The most recent distribution source can also be downloaded from the following page.

http://www.nic.ad.jp/en/research/idn/

Extract the obtained mDNkit distribution source. Distribution sources with file names such as mdnkit-X.Y.tar.gz are extracted as shown below

% gunzip mdnkit-X.Y.tar.gz
% tar -xf mdnkit-X.Y.tar

When extracted, a mdnkit-X.Y directory is generated, move to this directory.

% cd mdnkit-X.Y

In the following descriptions, this directory is referred to as $MDNTOP . Setting the environment variable $MDNTOP makes it easier to use.

% setenv MDNTOP `pwd` (for a csh system shell)
% MDNTOP=`pwd`; export MDNTOP (for a sh system shell)

Executing `configure`

First compile the following from the major part of the mDNkit.

MDN library (libmdn, libmdnlite)
DNS proxy server (mdnsproxy)
Zone master file code conversion tool (mdnconv)
runmdn command (runmdn)

First move to the mDNkit top directory (the directory that $MDNTOP points to) and execute the configure script. configure is a tool that checks the header file and libraries to learn the features of the system to configure the optimum compiler environment.

% cd $MDNTOP
% ./configure

When iconv() is included with the system and no special options are used during compilation, it can be executed as above without the need to specify any arguments. In other cases, operation of configure can be changed using options and environment variables.

The following options that can be set by configure seem to be important.

--prefix=PREFIX: Specifies the path of the directory that mDNkit will be installed in. The default value is /usr/local.
--with-libiconv=LIBICONV_PREFIX: When GNU libiconv that was already installed will be linked to mDNkit, specify this option. To the argument LIBICONV_PREFIX, the path that GNU libiconv is installed in is specified. When the argument is omitted, it is regarded as specifying PREFIX (the value of PREFIX is derive from --prefix=PREFIX). --with-libiconv is contractional option for GNU libiconv.

--with-libiconv=/usr/local

This is equivalent to the following.

--with-iconv-include='-I/usr/local/include'
--with-iconv='-L/usr/local/lib -R/usr/local/lib -liconv'

Both the contractional option (--with-libiconv) and the normal option (--with-iconv-include, --with-iconv) are specified, the normal option is prior.
--with-iconv-include=ICONV_INCDIR: When iconv.h is put in the directory which is not usually searched by C compiler, specify the directory as the following.

--with-iconv-include=/usr/local/include
--with-iconv=ICONV_LIB: When the iconv() package is installed either because it is not included with the system or because you do not wish to use the existing iconv() in the system, use this option to configure the iconv() library. Use ICONV_LIB to specify the library. Use the full path to specify the library or specify it using an option format assigned to the C compiler.
For example, specify the following entry.

--with-iconv="-L/usr/local/lib -liconv"

When iconv is a shared library, it may be also necessary to specify the -R option:

--with-iconv="-L/usr/local/lib -R/usr/local/lib -liconv"
--with-iconv-sofile=SOFILE_PATH: runmdn command which is contained in mDNkit need to know the path name for the shared libraries which contain iconv(). mDNkit searchs the path names by the definition of --with-iconv option. However, when it failed, you can specify the shared libraries as the following.

--with-iconv-sofile=/usr/local/lib/libiconvv.so.2.0
--with-utf8=UTF8_NAME: When UTF-8 encoding is specified using iconv(), mDNkit uses UTF-8 to encoding names by default. If encoding names other than UTF-8 need to be used when UTF-8 encoding is specified, specify the name in UTF8_NAME by this option. When the package of iconv mentioned in mentioned in Preparations is used, this option is unnecessary.

Another `configure` options

Though these are not often used, configure has various options except for the above-mentioned. Specify accoding to need.

--with-preference=PREFERENCE: Makes the default configuration of the sample configuration file (mdn.conf.sample) to be installed for PREFERENCE. When this operation is specified, the default configuration file (mdn.conf) will be installed (if it does not already exist in the installed directory.) The contents of the installed file are the same as for the sample configuration file.
Currently, only jp can be specified as PREFERENCE.
--with-punycode-prefix=PUNYCODE_PREFIX: Punycode (it was AMC-ACE-Z before) is an encoding scheme proposed about a multilingual domain name used with the DNS protocol. To distinguish multilingual domain names from usual ASCII domain names needs to prepare fixed prefix. However actual Internet-Draft of Punycode draft-ietf-idn-punycode-00.txt is not defined a prefix. To use this option makes specify a prefix. If not specified, the prefix "zq--" is defined.
--with-race-prefix=RACE_PREFIX
--with-dude-prefix=DUDE_PREFIX: RACE and DUDE are also encoding schemes proposed about a multilingual domain name used with the DNS protocol. However these are already out of date. The Internet-Drafts draft-ietf-idn-race-03.txt and draft-ietf-idn-dude-02.txt are defined prefixes. However it is possible to change the prefixes by this option.
--exec-prefix=EXEC_PREFIX: Specifies the directory path which the machine specific files are installed. The default value is PREFIX (possible to specify by --prefix=PREFIX, the default of PREFIX is /usr/local)
--sbindir=SBINDIR: Specifies the directory where the mdnconv of DNS proxy server is installed. EXEC_PREFIX/sbin is the default directory.
--bindir=BINDIR: Specifies the directory where the mdnconv command, a tool for converting zone master file code, and the runmdn command that adds multilingual domain name processing capability to a client, are installed. EXEC_PREFIX/bin is the default directory.
--libdir=LIBDIR: Specifies the directory where the basic mDNkit and other basic libraries employed by mdnsproxy or mdnconv are installed. EXEC_PREFIX/lib is the default directory.
--includedir=INCDIR: Specifies the directory where the header file required for use of the basic mDNkit library is installed. PREFIX/include is the default directory.
--sysconfdir=SYSCONFDIR: Specifies the directory where mdnsproxy, the DNS proxy server, configuration files and shared client configuration files for mDNkit are installed. PREFIX/etc is the default directory.
--mandir=MANDIR: Specifies the base directory where the online manuals are installed. /usr/local/man is the default directory. In fact, they are installed in its man1 or man8 subdirectory.
--datadir=DATADIR: Specifies the directory which the file that is enable to share between deferent machines is installed in. The default value is PREFIX/share. Actually some data files are installed in the sub-directory DATADIR/mdnkit.
--localstatedir=LOCALSTATEDIR
--logdir=LOGDIR: specifies the standard directory where the log file is output by mdnsproxy to LOGDIR. The default value of LOGDIR is LOLOCALSTATEDIR/mdnsproxy. The default value of LOLOCALSTATEDIR is PREFIX/var.
--enable-debug: Enable debug code. Usually this is not used. no is the default value.
--enable-shared: Create as a shared library. yesis the default value.
--enable-static: Create as a static library. yesis the default value.

A number of other options is in configure. However, because other options are hardly not used, the expositions are omitted.

% ./configure --help

The above is used to display a list of specifiable options.

Environment variables about `configure`

Environment variables about configure are as follows. If necessary, also specify these.

CC: Specifies C compiler command name.
CFLAGS: Specifies options passed to the C compiler. For example, if using GCC, it is performed to compile optimization level 3 to specify -O3. The following configuration is required in a csh shell.

% setenv CFLAGS -O3

An sh shell requires the following configuration.

% CFLAGS=-O3; export CFLAGS

When configure is executed, Makefile and other files are generated and adapted to your system environment.

Compile

Since executing configure generates a Makefile tailored to the system environment, all that compile needs to do is to execute the make command in the top directory (the directory pointed to by $MDNTOP).

% make

Installing Files

When compiling is finished, install the executable files and other files. Become a superuser prior to installation.

% su

Then execute make install to install all the required files in the system.

# make install

The following files will be installed.

Executable files to be installed

The following executable files will be installed.

mdnsproxy: The DNS proxy server.
mdnconv: The code conversion tool for zone master files.
runmdn: This command adds, without the need for recompiling, the capability to resolve multilingual domain names to clients.

mdnsproxy is installed in /usr/local/sbin by default. If you wish to change the installation location, use the --sbindir option in configure.

mdnconv and runmdn are installed in /usr/local/bin by default. If you wish to change the installation location, use the --bindir option in configure.

On-line manuals to be installed

The following on-line manuals will be installed.

mdnconv.1: The manual for mdnconv, a zone master file code conversion tool
runmdn.1: The runmdn command manual
libmdn.3, libmdnlite.3: The on-line manual for multilingual domain name conversion API
mdn.conf.5: The on-line manual for mdn.conf.5, a shared client configuration file
mdnsproxy.8: The mdnsproxy, a DNS proxy server, manual

These manuals are by default installed in /usr/local/man/man1 (mdnconv.1, runmdn.1), /usr/local/man/man3 (libmdn.3, libmdnlite.3), /usr/local/man/man5 (mdn.conf.5), and /usr/local/man/man8 (mdnsproxy.8) by default. To change the location of installation, use the --mandir option in configure.

Configuration files to be installed

The following configuration files and sample files will be installed.

mdnsproxy.conf.sample: This sample file describes setup examples for the configuration file for mdnsproxy, the DNS proxy server. Refer to mDNS Proxy Server Configuration for information on how to set it up.
mdn.conf.sample: This sample file describes setup examples for mdn.conf, a shared client configuration file of mDNkit. Refer to mDNkit Configuration for information on how to set it up.
mdn.conf: This is a shared configuration file of mDNkit. This file is installed only when --with-preference option is specified to configure and also the same directory name does not exist in the installed directory.

All files are by default installed in /usr/local/etc. To change the installation location, use the --sysconfdir option in configure.

Libraries to be installed

The following libraries will be installed.

libmdn: A basic mDNkit library that employs mdnsproxy, mdnconv and other commands.
libmdnlite: A light weight version of libmdn. The part of feature of the code conversion between a local encoding and UTF-8 is excepted from libmdn, however all of the other features are as same as libmdn.
libmdnres: A library dynamically linked to a client using the runmdn command.

Both libraries are by default installed in /usr/local/lib. To change the installation location, use configure with the --libdir option in configure.

Header files to be installed

Installs the libmdn header file. This file is by default installed in the mdn directory under /usr/local/include. To change the installation location, use the --includedir option in configure.

Applying and Installing the BIND 9 Patch

Information on how to apply the patch is appended to the beginning of the file, but the following is a brief description.

Move to the BIND 9.1.3 source top directory (the directory that contains the README file).

% cd /somewhere/.../bind-9.1.3
Use the patch command to apply the patch to the source.

% patch -p0 < $MDNTOP/patch/bind9/bind-9.1.3-patch

After the patch is applied, refer to the README.mdnkit file in the BIND 9 source. This file describes the compiling and installation methods.

To compile BIND 9 to which the patch was applied, compile and install mDNkit beforehand.

Applying and Installing the BIND 8 Patch

The $MDNTOP/patch/bind8/bind-8.2.3-patch in the extracted source is the 8-bit through patch for BIND 8.2.3. Information on how to apply the patch is appended to the beginning of the file, but the following is a brief description.

Move to the top directory of the BIND 8.2.3 source (the directory containing the src subdirectory).

% cd /somewhere/.../bind-8.2.3
Use the patch command to apply the patch to the source.

% patch -p0 < $MDNTOP/patch/bind8/bind-8.2.3-patch

When the patch has been applied, perform compilation and installation according to the standard BIND installation procedure. Refer to src/INSTALL in the BIND source for installation instructions.

The BIND 8 patch only makes BIND 8-bit through and does not use the mDNkit library. Thus it can be compiled and installed separately from the mDNkit

Applying and Installing the Squid Patch

The $MDNTOP/patch/squid/squid-2.3.STABLE3-patch in the extracted source is the 8-bit through patch for Squid 2.3.STABLE3. Information on how to apply the patch is appended to the beginning of the file, but the following is a brief description.

Move to the top directory of Squid 2.3.STABLE3 source (the directory containing the README file).

% cd /somewhere/.../squid-2.3.STABLE3
Use the patch command to apply the patch to the source.

% patch -p1 < $MDNTOP/patch/squid/squid-2.3.STABLE3-patch

When the patch has been applied, perform compilation and installation according to the standard Squid install procedure. Refer to INSTALL in the Squid source for installation instructions.

Both the Squid and the BIND 8 patches only add 8-bit through capability and does not use any mDNkit library or other function. Thus they can be compiled and installed independently from the mDNkit.