NAME
idnconv - codeset converter for named.conf and zone master files
SYNOPSIS
idnconv [options..] [file...]
DESCRIPTION
idnconv is a codeset converter for named configuration files and zone master files. idnconv 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, idnconv converts the contents of the file. Otherwise, idnconv converts stdin.
Since idnconv is specifically designed for converting internatinalized domain names, it may not be suitable as a general codeset converter.
OPERATION MODES
idnconv 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) |
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 NAMEPREPed. If it is not, the name will be output in IDN encoding, not in the local encoding.
OPTIONS
Normally idnconv reads systems default configuration file (idn.conf) and performs 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.
| |||||||||
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 idnkit configuration file (idn.conf). If not specified, systems 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.
| |||||||||
-nonameprep, -N | |||||||||
Specify to skip NAMEPREP process (or NAMEPREP verification process in the reverse conversion mode). This option implies -nounassigncheck and -nobidicheck. | |||||||||
-localmap map | |||||||||
Specify the name of local mapping rule.
Currently, following maps are available.
| |||||||||
This option can be specified more than once. In that case, each mapping will be performed in the order of the specification. | |||||||||
-nounassigncheck, -U | |||||||||
Skip unassigned codepoint check. | |||||||||
-nobidicheck, -B | |||||||||
Skip bidi character check. | |||||||||
-nolengthcheck | |||||||||
Do not check label length of normal conversion result. This option is only meaningful in the normal conversion mode. | |||||||||
-noasciicheck, -A | |||||||||
Do not check ASCII range characters. This option is only meaningful in the normal conversion mode. | |||||||||
-noroundtripcheck | |||||||||
Do not perform round trip check. This option is only meaningful in the reverse conversion mode. | |||||||||
-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. 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 NORAML CONVERSION MECHANISM and REVERSE 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
idnconv guesses local codeset from locale and environment variables. See the LOCAL CODESET section in idn.conf(5) for more details.
NORMAL CONVERSION MECHANISM
idnconv performs conversion line by line. Here describes how idnconv does its job for each line.
1. read a line from input text | |||||||||||||
2. convert the line to UTF-8 | idnconv converts the line from local encoding to UTF-8. | ||||||||||||
3. find internationalized domain names |
If the -whole (or -w) option is specified, the entire line is
assumed as an internationalized domain name.
Otherwise, idnconv recognizes any character sequences having
the following properties in the line as internationalized domain names.
| ||||||||||||
4. convert internationalized domain names to ACE |
For each internationalized domain name found in the line,
idnconv converts the name to ACE.
The details about the conversion procedure is:
| ||||||||||||
5. output the result | |||||||||||||
REVERSE CONVERSION MECHANISM
This is like the normal conversion mechanism, but they are not symmetric. idnconv does its job for each line.
1. read a line from input text | |||||||||||
2. convert the line to UTF-8 | idnconv converts the line from local encoding to UTF-8. | ||||||||||
3. find internationalized domain names | If the -whole (or -w) option is specified, the entire line is assumed as an internationalized domain name. Otherwise, idnconv decodes any valid ASCII domain names including ACE names in the line. | ||||||||||
4. convert domain names to local encoding |
Then, idnconv decodes the domain names.
The decode procedure consists of the following steps.
| ||||||||||
5. output the result | |||||||||||
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 idnconv.
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:
idnconv -in $(LOCALCODE) -out $(IDNCODE) \
$(IDNCONVOPT) $< > $@
LOCALCODE = EUC-JP
IDNCODE = Punycode
IDNCONVOPT =
DESTFILES = db.zone1.ace db.zone2.ace
all: $(DESTFILES)
SEE ALSO
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.