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 procedure from source distribution is implemented as follows.
After installation, refer to and set up DNS server configuration, mDNkit resolver configuration, and if dnsproxy is to be used DNS Proxy Server configuration.
To install the patch included in source distribution, refer to the following instructions.
- Applying and installing a bind9 patch
- Applying and installing a bind8 patch
- Applying and installing a 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, libiconv.
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 bind9 source
The mDNkit provides a bind9 patch that can be used to generate bind9 resolvers and servers that can support multilingual domain names. The patch in this kit is for BIND 9.0.0. The source can be downloaded from the following page.
Obtaining the bind8 source
To use dnsproxy to enable client applications to support multilingual domain names, the resolver library that resolves names must be made 8-bit through. Also, 8-bit through DNS servers must be used to enable a DNS server to use encodings other than UTF-5, RACE or other ASCII compatible encoding (as multilingual domain name encoding), for example, UTF-8.
The mDNkit for that reason supplies a patch that makes BIND 8.2.2-P7 and BIND 8.2.3-T6B 8-bit through. To use bind8 with a patch installed, obtain the source of the desired version. Sources can be downloaded from the following page.
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.3.STABLE3 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.
Extracting 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)
Running Configure
First compile the following that form the major part of the mDNkit.
- MDN library (libmdn)
- DNS proxy server (dnsproxy)
- Zone master file code conversion tool (mdnconv)
- runmdn command
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 like 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 are directly related to mDNkit.
- --with-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 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, when the iconv package mentioned in Preparations is installed, it is by default installed in libiconv of /usr/local/lib, so it is a good idea to make the following entry.
When libiconv is shared library, it may also be necessary to specify the -R option:--with-iconv="-L/usr/local/lib -liconv"
--with-iconv="-L/usr/local/lib -R/usr/local/lib -liconv"
- --with-utf8=NAME
- When UTF-8 encoding is specified using iconv(), mDNkit uses UTF-8 to encoding names by default. If other names must be used when UTF-8 encoding is specified, specify the name in NAME using this option. This is not required when using iconvpackage mentioned in Preparations.
- --with-race-prefix=PREFIX
- RACE is proposed as one of the encoding system to be used for multilingual domain names in DNS protocols. RACE is an ASCII compatible encoding scheme and adds a specific prefix to the domain name to distinguish it from an ordinary ASCII domain name. This prefix is "bq--" in current Internet Drafts, but this may change in future. Use this option to enter the new prefix when a change is made.
- --with-brace-suffix=SUFFIX
- Like RACE, BRACE is being proposed as an encoding scheme for multilingual domain names to be used in DNS protocols. It is also an ASCII compatible encoding scheme, but differs from RACE in that it adds a suffix to the domain name to distinguish from normal ASCII domain names. This suffix is "-8q9" in the current Internet Draft, but this may change in future. Use this option to enter the correct suffix when a change is made.
- --with-lace-prefix=PREFIX
- Like RACE and BRACE, LACE is another ASCII compatible encoding scheme and like, RACE, it adds a special prefix to distinguish it from ordinary ASCII domain names.
In the current Internet Draft the prefix is "bq--", but this may change in the future; if it does, use this option to enter the correct prefix.
- --enable-zld
- This option adds ZLD (Zero Level Domain) function support. ZLD is a special domain name used to differentiate standard ASCII domain names from multilingual domain names in some encodings used in a DNS server. This option need not be set unless ZLD is selected as the required encoding in a DNS protocol.
The support of the ZLD function affects operation (i.e. whether or not the ZLD setting is ignored) when configuration files are read in using the dnsproxy or runmdn command. The operation of the library provided by the mDNkit does not change with this option (except some modules used for reading in configuration files), but performs ZLD processing at all times.
- --sbindir=DIR
- Specifies the directory where dnsproxy, the DNS proxy server, is installed. /usr/local/sbin is the default directory.
- --bindir=DIR
- 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. /usr/local/bin is the default directory.
- --libdir=DIR
- Specifies the directory where the basic mDNkit and other basic libraries employed by dnsproxy or mdnconv are installed.
/usr/local/lib is the default directory.
- --includedir=DIR
- Specifies the directory where the header file required for use of the basic mDNkit library is installed. /usr/local/include is the default directory.
- --sysconfdir=DIR
- Specifies the directory where dnsproxy, the DNS proxy server, configuration files and shared client configuration files for mDNkit are installed.
/usr/local/etc is the default directory.
- --mandir=DIR
- 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.
A number of other options can be specified using configure.
% ./configure --help
The above is used to display a list of specifiable options.
The related environment variables are as follows.
- CFLAGS
- Specifies options passed to the C compiler. Let's assume that when an external iconv package is installed, iconv.h, the include file is installed in a directory other than the standard directory, for example, /usr/local/include. This requires that -I/usr/local/include be configured in CFLAGS. The following configuration is required in a csh shell.
% setenv CFLAGS -I/usr/local/include
An sh shell requires the following configuration.
% CFLAGS=-I/usr/local/include; export CFLAGS
CFLAGS can be used in other situations to specify the optimum C compiler options. When -O is specified in CFLAGS compilation is optimized.
When configure is executed, Makefile and other files are generated and adapted to your system environment.
Compile
Since 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 pointing to $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
- The following executable files will be installed.
- dnsproxy
- 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. It is installed in /usr/local/bin by default.
dnsproxy is installed in /usr/local/sbin by default. If you wish to change the installation location, use the configure --sysconfdir option.
mdnconv and runmdn are installed in /usr/local/bin by default. If you wish to change the installation location, use the --bindir option.
- On-line manuals
- The following on-line manuals will be installed.
- dnsproxy.8
- The dnsproxy, a DNS proxy server, manual
- mdnconv.1
- The manual for mdnconv, a zone master file code conversion tool
- runmdn.1
- The runmdn command manual
- mdnres.conf.5
- The on-line manual for mdnres.conf, a shared client configuration file
These manuals are by default installed in /usr/local/man/man8 (dnsproxy.8), /usr/local/man/man1 (mdnconv.1, runmdn.1) and /usr/local/man/man5 (mdnres.conf.5), respectively. To change the location of installation, use the --mandir option of configure.
Configuration files
- The following configuration files and sample files will be installed.
- dnsproxy.conf
- This sample file describes setup examples for the configuration file for dnsproxy, the DNS proxy server.
If this file has already been installed, it is installed under the name dnsproxy.conf.sample so as not to overwrite the previous file.
Refer to DNS Proxy Server Configuration for information on how to set it up.
- mdnres.conf.sample
- This sample file describes setup examples for mdnres.conf, a shared client configuration file.
Refer to the mDNkit resolver configuration for information on how to set it up.
Both files are by default installed in /usr/local/etc. To change the installation location, use the --sysconfdir option.
- Libraries
- The following libraries will be installed.
- libmdn
- A basic mDNkit library that employs dnsproxy, mdnconv and other commands.
- 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.
- Header file
- Installs the libmdn header file. This file is by fault installed in the mdn directory under /usr/local/include. To change the installation location, use the --includedir option in configure.
Applying and Installing the bind9 Patch
$MDNTOP/patch/bind9/bind-9.0.0-patch in extracted source is the patch that adds multilingual domain name processing functionality to BIND 9.0.0. 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.0.0 source top directory (the directory that contains the README file).
% cd /somewhere/.../bind-9.0.0
- Use the patch command to apply the patch to the source.
% patch -p0 < $MDNTOP/patch/bind9/bind-9.0.0-patch
When the patch is applied a README.mdnkit file is created in the top directory. Read this file before compilation.
After this perform compilation and installation. Refer to README.mdnkit for instructions. As stated in this file, be sure to add the --with-mdn option when executing the configure command. Unless this option is added, capability to process multilingual domain names will not be added.
% ./configure --with-mdn
The bind9 patch assumes that the major portion of the mDNkit (especially, the library and header file) is already installed. Consequently, this operation should be performed after the mDNkit has been installed.
Adding and Installing the bind8 patch
The $MDNTOP/patch/bind8/bind-8.2.2-P7-patch in the extracted source is the 8-bit through patch for BIND 8.2.2-P7 and the $MDNTOP/patch/bind8/bind-8.2.3-T6B-patch is the 8-bit through patch for BIND 8.2.3-T6B. 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.2-P7 or BIND 8.2.3-T6B source (the directory containing the src subdirectory).
% cd /somewhere/.../bind-8.2.2-P7
- Use the patch command to apply the patch to the source.
% patch -p0 < $MDNTOP/patch/bind8/bind-8.2.2-P7-patch
When the patch has been applied, perform compilation and installation according to the standard BIND installation procedure. Refer to src/INSTALL for installation instructions.
The bind8 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 bind8 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.
