MDNCONV(1)

NAME
mdnconv - codeset converter for named.conf and zone master files

SYNOPSIS
mdnconv [options..] [file...]

DESCRIPTION
mdnconv is a codeset converter for named configuration files and zone master files. mdnconv performs codeset conversion specified either by the command-line arguments or by the configuration file, and writes the converted text to stdout.

If file name is specified, mdnconv converts the contents of the file. Otherwise, mdnconv converts stdin.

Since mdnconv is specifically designed for converting internatinalized domain names, it may not be suitable as a general codeset converter.

OPERATION MODES
mdnconv has two operation modes.

One is a mode to convert local-encoded domain names to IDN-encoded one. Usually this mode is used for preparing domain names to be listed in named configuration files or zone master files. In this mode, the following processes are performed in addition to the codeset (encoding) conversion.

    -   local mapping

    -   standard domain name preperation (NAMEPREP)

Furthermore, delimiter mapping is also performed in case -delimitermap command line option is specified.

The other mode is a reverse conversion, from IDN-encoded domain name to local-encoded domain names. In this mode, local mapping and NAMEPREP are not performed since IDN-encoded names should already be normalized. Instead, a check is done in order to make sure the IDN-encoded domain name is properly NAMEPREP'ed. If it is not, the name will be output in IDN encoding, not in the local encoding.

OPTIONS
Normally mdnconv reads system's default configuration file (mdn.conf) and perform conversion or name preparation according to the parameters specified in the file. You can override the setting in the configuration file by various command line options below.

-in in-code, -i in-code
    Specify the codeset name of the input text. Any of the following codeset names can be specified.

    •   Any codeset names which iconv_open() library function accepts

    •   AMC-ACE-Z

    •   RACE

    •   DUDE

    •   UTF-8

    •   Any alias names for the above, defined by the codeset alias file.

    If this option is not specified, the default codeset is determined from the locale in normal conversion mode. In reverse conversion mode, the default codeset is the IDN encoding specified by the configuration file (``idn-encoding'' entry).

-out out-code, -o out-code
    Specify the codeset name of the output text. out-code can be any codeset name that can be specified for -in option.

    If this option is not specified, the default is the IDN encoding specified by the configuration file (``idn-encoding'' entry) in normal conversion mode. In reverse conversion mode, the default codeset is determined from the locale.

-conf path, -c path
    Specify the pathname of mDNkit configuration file (``mdn.conf''). If not specified, system's default file is used, unless -noconf option is specified.

-noconf, -C
    Specify that no configuration file is to be used.

-reverse, -r
    Specify reverse conversion mode.
    If this option is not specified, the normal conversion mode is used.

-nameprep version, -n version
    Specify the version of NAMEPREP. The following is a list of currently available versions.

    nameprep-03
        Perform NAMEPREP according to the Internet Draft ``draft-ietf-idn-nameprep-03.txt'' (NAMEPREP-03).

    nameprep-05
        Perform NAMEPREP according to the Internet Draft ``draft-ietf-idn-nameprep-05.txt'' (NAMEPREP-05).

    nameprep-06
        Perform NAMEPREP according to the Internet Draft ``draft-ietf-idn-nameprep-06.txt'' (NAMEPREP-06).

    This option is a shorthand for specifying the 4 options below.

    -map version
    -normalize version
    -prohibit version
    -unassigned version

-nonameprep, -N
    Specify to skip NAMEPREP process (or NAMEPREP verification process in the reverse conversion mode).

-map map
    Specify the name of the mapping rule for NAMEPREP mapping process. Currently, following maps are available.

    nameprep-03
        Use the list of mappings specified by NAMEPREP-03 draft.

    nameprep-05
        Use the list of mappings specified by NAMEPREP-05 draft.

    nameprep-06
        Use the list of mappings specified by NAMEPREP-06 draft.

    filemap:path
        Use list of mappings specified by mapfile path. See mdn.conf(5) for the format of a mapfile.

    This option can be specified more than once. In that case, each mapping will be performed in the order of the specification.
    If neither this option nor ``-nameprep'' are specified, the schemes specified in the configuration file (``nameprep-map'' entry) are used.

-normalize scheme
    Specify the normalization scheme for NAMEPREP normalization process. Currently, following schemes are available:

    unicode-form-kc
        Unicode Normlization Form KC, also described in ``Unicode Technical Report #15: Unicode Normalization Forms'', available from unicode.org.

    unicode-form-kc/3.0.1
        Unicode Normlization Form KC, version 3.0.1

    unicode-form-kc/3.1.0
        Unicode Normlization Form KC, version 3.1.0

    nameprep-03
        Synonim for ``unicode-form-kc/3.0.1''.

    nameprep-05
        Synonim for ``unicode-form-kc/3.1.0''.

    nameprep-06
        Synonim for ``unicode-form-kc/3.1.0''.

    This option can be specified more than once. In that case, each normalization will be performed in the order of the specification.
    If neither this option nor ``-nameprep'' are specified, the schemes specified in the configuration file (``nameprep-normalize'' entry) are used.

-prohibit set
    Specify the set of prohibited characters. Currently, following sets are available.

    nameprep-03
        Use list of prohibit characters specified by NAMEPREP-03 draft.

    nameprep-05
        Use list of prohibit characters specified by NAMEPREP-05 draft.

    nameprep-06
        Use list of prohibit characters specified by NAMEPREP-06 draft.

    fileset:path
        Use list of characters specified by setfile path. See mdn.conf(5) for the format of a setfile.

    This option can be specified more than once. In this case, the set of prohibited characters is the union of the specified sets.
    If neither this option nor ``-nameprep'' is specified, list of characters specified by the configuration file (``nameprep-prohibit'' entry) is used.

-unassigned set
    Specify the set of unassigned codepoints. Currently, following sets are available.

    nameprep-03
        Use the list of unassigned characters specified by NAMEPREP-03 draft.

    nameprep-05
        Use the list of unassigned characters specified by NAMEPREP-05 draft.

    nameprep-06
        Use the list of unassigned characters specified by NAMEPREP-06 draft.

    fileset:path
        Use list of characters specified by setfile path. See mdn.conf(5) for the format of a setfile.

    Note that unassigned codepoint checking is not performed unless -unassigncheck option is specified.
    This option can be specified more than once. In this case, the set of prohibited characters is the union of the specified sets.
    If neither this option nor ``-nameprep'' is specified, list of characters specified by the configuration file (``nameprep-unassigned'' entry) is used.

-unassigncheck, -u
    Specify unassigned codepoint check should be performed. Unassigned codepoint check is disabled by default.

-delimiter codepoint
    Specify the character to be mapped to domain name delimiter (period). This option can be specified more than once in order to specify multiple characters.
    If this option is not specified, characters specified by the configuration file (``delimiter-map'') is used.
    Note that delimiter mapping is not performed unless -delimitermap option is specified.
    This option is only meaningful in the normal conversion mode.

-delimitermap, -d
    Specify delimiter mapping should be performed. By default, delimiter mapping is disabled.
    This option is only meaningful in the normal conversion mode.

-whole, -w
    Perform local mapping, nameprep and conversion to output codeset for the entire input text. If this option is not specified, only non-ASCII characters and their surrounding texts will be processed. See ``CONVERSION MECHANISM'' for details.

-alias path, -a path
    Specify a codeset alias file. It is a simple text file, where each line has a pair of alias name and real name separated by one or more white spaces like below:
        alias-codeset-name    real-codeset-name
    Lines starting with ``#'' are treated as comments.

-flush
    Force line-buffering mode.

-version, -v
    Print version information and quit.

LOCAL CODESET
mdnconv guesses local codeset from locale and environment variables. See the ``LOCAL CODESET'' section in mdn.conf(5) for more details.

CONVERSION MECHANISM
Here is a brief step-by-step description of how mdnconv does its job.

1. input-side convnersion
    mdnconv reads input text line by line, and converts them from the input codeset to UTF-8 encoding. Basically this conversion is done using iconv() utility, but for some special codesets like RACE, special converter will be used.
    Normally the whole line is converted, but if the input codeset is an ACE (ASCII-compatible encoding, such as RACE), a special conversion prodedure shown below is used:

    1)  Find substrings which are valid ASCII domain names (i.e. constructed from alphanumeric characters and hyphens) in the line.

    2)  For each substring found, try converting it to UTF-8.

    3)  If the conversion succeeds, replace the substring with the conversion result. Otherwise, the original substring is retained.

2. finding where to process
    Then mdnconv looks for (part of) internationalized domain name in the converted line, and picks them up for further processing.
    mdnconv recognizes the character sequence having the following property as an internationalized domain name.

    •   containing at least one non-ASCII character, and

    •   consisting of legal domain name characters (alphabets, digits, hypens), non-ASCII characters and period.

    If you are not quite sure what this means (as I), the following regular expression may help you.
        [-A-Za-z0-9.]*<non-ASCII char>([-A-Za-z0-9.]|<non-ASCII char>)*
    For example, only ``www.###.com'' will be picked up from the following lines (`#' denotes non-ASCII character).
        www.###.com.    IN CNAME serv.xyz.com.
        serv.xyz.com.   IN A     10.0.0.1
    If -whole option is specified, this step is skipped and the entire line is subject to further processing.

3. delimiter mapping
    For each string picked up by the last step, delimiter mapping is performed. That is, substibute certain characters specified as domain name delimiter with period.

4. local mapping
    Perform local mapping. If the local mapping is specified by command line option ``-localmap'', the specified mapping rule is applied. Otherwise, find the mapping rule from the configuration file which matches to the TLD of the name, and perform mapping according to the matched rule.

5. nameprep
    Perform name preparation (NAMEPREP). This is a following 3-step process.
    1) Mapping
    2) Normalization
    3) Prohibited/unassigned character checking

    When mdnconv operates in the reverse conversion mode, this process checks that the given domain name is properly NAMEPREP'ed. If it is not properly NAMEPREP'ed and the input codeset is an ACE, the domain name is converted back to the input codeset in the following process, instead of the output codeset.

6. output-side conversion
    Finally, mdnconv converts the nameprepped strings from UTF-8 encoding to the output codeset. And it writes them to stdout together with the rest of the line.

If mdnconv operates in the reverse conversion mode, step 3 and 4 above are skipped.

FILE MANAGEMENT
Maybe the best way to manage named.conf or zone master files that contains internationalized domain name is to keep them in your local codeset so that they can be edited with your favorite editor, and generate a version in the IDN encoding using mdnconv.

`make' is a convenient tool for this purpose. Suppose the local codeset version has suffix `.lc', and its ACE version has suffix `.ace'. The following Makefile enables you to generate ACE version from local codeset version by just typing `make'.
    .SUFFIXES: .lc .ace
    .lc.ace:
            mdnconv -in $(LOCALCODE) $(MDNCONVOPT) $< > $@
    LOCALCODE = EUC-JP
    MDNCONVOPT =
    DESTFILES = db.zone1.ace db.zone2.ace
    all: $(DESTFILES)

SEE ALSO
mdn.conf(5), iconv(3)

BUGS
The automatic input-code selection depends on your system, and sometimes it cannot guess or guess wrong. It is better to explicitly specify it using -in option.