mDNkit Configuration

mdnconv, mDN Wrapper, runmdn and, mdnsproxy commands and tools that the mDNkit provides reference a shared configuration file.

A number of data items that the client needs, in order to be able to use the mDNkit, must be entered in this file. For example, the normalization scheme and the domain name encoding scheme in the DNS protocol are specified in this file. The procedure for entering this data, and its significance, are described below.

The local encoding used by the application is acquired from the locale information of the application.

• Configuration File
  • idn-encoding
  • nameprep
  • nameprep-map
  • nameprep-normalize
  • nameprep-prohibit
  • nameprep-unassigned
  • encoding-alias-file
  • local-map
  • delimiter-map
• Local Encoding
• Map File Format
• Set File Format
• Environment Variables

---

Configuration File

The configuration file of mDNKit is a regular text file and the lines in the file (except comments line that begins with # and blank lines) are comprised of the following simple format.

Keyword value ...

idn-encoding

Specifies the multilingual domain name encoding used by the resolver or DNS server.

[Syntax]

idn-encoding <encoding>

The following names can be specified for <encoding>.

• RACE
• Punycode
• AMC-ACE-Z (it is the old name of Punycode)
• DUDE
• Encoding name recognized by iconv_open() in your system.
• Alias of the above encoding name defined in the alias definition file (refer to encoding-alias-file)

[Setting example]

idn-encoding Punycode

Since the local encoding at the application side is determined by the locale or environment variable, there is no client-recoding entry. Local encoding is explained later.

nameprep

NAMEPREP prescribes the normalization scheme of multilingual domain names. This entry specifies which version of NAMEPREP is used.

[Syntax]

nameprep <version>

The following version can be specified for <version>.

nameprep-03

The normalization scheme corresponding to Internet draft draft-ietf-idn-nameprep-03.txt

nameprep-05

The normalization scheme corresponding to Internet draft draft-ietf-idn-nameprep-05.txt

nameprep-06

The normalization scheme corresponding to Internet draft draft-ietf-idn-nameprep-06.txt

nameprep-07

The normalization scheme corresponding to Internet draft draft-ietf-idn-nameprep-07.txt

[Setting example]

nameprep nameprep-07

The NAMEPREP processing procedure consists of the following three steps.

1. Mapping
   
2. Normalization
   
3. Prohibited check, unassigned check

Besides the nameprep entry, entries used to specify the version for each process are provided.

nameprep-map <version>
nameprep-normalize <version>
nameprep-prohibit <version>
nameprep-unassigned <version>

When the above four entires are combined, the same operation takes place as if the following is specified.

nameprep <version>

When both nameprep and other detailed entry are specified, the detailed entry takes precedence.

nameprep-map

This entry is used to specify the mapping method in NAMEPREP.

[Synatx]

nameprep-map <scheme> ...

Use <scheme> to specify the mapping method name. When more than one method is specified, they apply in that order (from left to right). The following can be specified in <scheme>.

<version>

Mapping following the specific version of NAMEPREP. For available version numbers, refer to nameprep.

filemap:<pathname>

The mapping definition is loaded from <pathname> file. For information of how to describe in the file, refer to Map File Format.

[Setting example]

nameprep-map nameprep-07

nameprep-normalize

This entry is used to specify the normalization scheme in NAMEPREP.

[Syntax]

nameprep-normalize <scheme> ...

Use <scheme> to specify the normalization scheme name. When more than one scheme is specified, they apply in order (from left to right). The following can be specified in <scheme>.

<version>

Normalization following the specific version of NAMEPREP. For available version numbers, refer to nameprep.

unicode-form-kc

Unicode normalization form KC by the latest version of Unicode which mDNkit supports.

unicode-form-kc/3.0.1

Unicode normalization form KC by Unicode version 3.0.1.

unicode-form-kc/3.1.0

Unicode normalization form KC by Unicode version 3.1.0.

[Setting example]

nameprep-normalize unicode-form-kc

nameprep-prohibit

This entry is used to specify check method of prohibited characters in NAMEPREP.

[Syntax]

nameprep-prohibit <set> ...

Use <set> to specify the name of the prohibited character set. When more than one character set is specified, they apply in order (from left to right). The following can be specified in <set>.

<version>

The prohibited character set described in the specific version of NAMEPREP. For available version numbers, refer to nameprep.

fileset:<pathname>

The definition of prohibited characters is loaded from <pathname>file. For information on how to describe in the file, refer to Set File Format.

[Setting example]

nameprep-prohibit nameprep-07

nameprep-unassigned

This entry is used to specify check method of unassigned code point (code point for which characters are not assigned) in NAMEPREP. When more than one method are specified, they apply in order (from left to right).

[Syntax]

nameprep-unassigned <set> ...

Use <set> to specify the unassigned code point set name. When more than one character set is specified, they apply in order (from left to right). The following can be set in <set>.

<version>

The prohibited character set described in the specific version of NAMEPREP. For available version numbers, refer to nameprep.

fileset:<pathname>>

The definition of unassigned code point is loaded from <pathname>file. For information on how to describe in the file, refer to Set File Format.

[Setting example]

nameprep-unassigned nameprep-07

encoding-alias-file

The code set name for encoding can be added as an alias. In this example, the path name to the alias definition file to be added is specified.

[Syntax]

encoding-alias-file <path>

Specify the path name to the definition file to <path>.

[Setting example]

encoding-alias-file /some/where/mdnalias.txt

The alias definition file is a plain text file and one alias name is set in each line. The format of each line is as follows.

<Alias> <Original name>

Instead of the encoding name <Original name>, <Alias> becomes available.

local-map

This entry is used to specify local mapping applied to domain names before NAMEPREP is applied. This mapping can be specified separately for each top level domain (TLD) of domain names.

[Syntax]

local-map <TLD> <scheme> ...

Specify TLD for which mapping applies in <TLD> and mapping scheme name in <scheme>, respectively. When more than one scheme is specified, they apply in order (from left to right). The schemes that can be specified are the same as for nameprep-map.

[Setting example]

local-map .jp filemap:/some/where/jp.map
local-map -   filemap:/some/where/notld.map
local-map .   filemap:/some/where/default.map

Specifying hyphen (`-') for TLD means that mapping applies to domain names without TLD, that is, domain names without periods (`.'). In the same way, when a period is specified for TLD, mapping applies to domain names that do not match any of the TLD of the other local-map entries.

Except in cases in which the TLD is a period (`.'), the period at the beginning of a TLD can be omitted.

delimiter-map

This entry is used to specify the character used to map periods. Usually, periods (`.') are used for delimiter between labels of domain names. The character specified in this entry can be used as the delimiter in instead of a period.

[Syntax]

delimiter-map <code point> ...

Use hexadecimals to describe Unicode code point in <code point>.

[Setting example]

delimiter-map 3002

---

Local Encoding

There is no entry for setting local encoding in the configuration file because it is automatically determined by referencing the locale or environment variable.

However, the following cases cannot be automatically sensed.

• When an application that does not use the setlocate() function is executed
• When an application is executed as a C locale
• When the relationship between locale and encoding is not known

Specify the MDN_LOCAL_CODESET environment variable to set local encoding. For example, to set local encoding to EUC-JP, make the following setting beforehand.

[Setting example]

sh(Shell) Series:

$ MDN_LOCAL_CODESET=EUC-JP
$ export MDN_LOCAL_CODESET

csh(Shell) Series:

% setenv MDN_LOCAL_CODESET EUC-JP

The value to be specified is a local encoding name that must be specified using a name that is accepted by the iconv() function in the system (or more precisely iconv_open()). This name differs with the iconv implementation, refer to the iconv document for details.

If you only use a single type of local encoding, it is recommended that you save this setting in .profile or .cshrc.

---

Map File Format

The map file defines character mapping rules for nameprep-map and local-map entries. You can specify one character as the source and a string of 0 or more characters as mapped characters. Mapping that relies on the context that the mapping rule is changed according to the front and rear characters cannot be performed.

The map file is a plain text file and one mapping rule is written in each line. The mapping rule is written in the following format. Lines that begin with `#' and blank lines are ignored.

<Source code point>; <Mapped code point string>;

Use hexadecimal to describe Unicode code point of source characters in <Source code point>. Write Unicode code point value of each character of the mapped character string in <Mapped code point string> using hexadecimal. Arrange from the beginning of the characters in order using a space as the delimiter. When the mapped character is a blank character string, <Mapped code point string> is blank.

[Setting example]

# Map "A" to "a"
0041; 0061;
# Do not map "#"
0023; ;
# Map "@" to "at"
0040; 0061 0074;

---

Set File Format

The set file defines a set of Unicode code points that are not allowed to be used as domain names for nameprep-prohibit and nameprep-unassigned entries.

The set file is a simple text file. Write one code point in each one line or write the code point range. The format is as follows.

<Code point>
<Starting code point>-<Ending code point>

Use hexadecimals to describe Unicode code points for code points. Lines that begin with `#' and blank lines are ignored.

[Setting example]

# Prohibit tilde symbol
007E
# Prohibit control characters
0000-001F
007F-000F
# Prohibit characters other than Basic Multilingual Plane (BMP) of Unicode
10000-10FFFF

---

Environment Variables

Environment variables about mDNkit are the followings.

MDN_LOCAL_CODESET

This is used to set a local encoding explicitly. For details, refer to Local Encoding.

LC_ALL
LC_CTYPE
LANG

These are not the mDNkit specific environment variable, but if defined, these influence judgement of local encoding. For details, refer to Local Encoding.

MDN_DISABLE

When this variable is defined, the feature of multilingualization of domain names which MDN library provides does not work. Applications which use MDN library are affected by this environment variable.

However, some applications may be set to ignore this environment variable explicitly. The followings commands attached mDNkit, mdnsproxy, mdnconv, runmdn use MDN library, however these command perform to ignore this environment variable to support multilingualization feature always. (Because if multilingualization is of no use, these commands are nonsense.)

MDN_LOG_LEVEL

It is used to set a level to output logs. The value from 0 to 5 can be set, and if a large figure is set, the logs which output in setting figures less than the figures are output at the same time.

• 0 - Output logs when fatal errors are occured. (by default)
• 1 - Output logs when common errors are occured.
• 2 - Output warning logs.
• 3 - Output infomation logs.
• 4 - Output trace logs.
• 5 - Output dump logs.