Chbuild utility

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

Compile the MTA character set conversion tables, and tlds.txt file.


  imsimta chbuild

imsimta chbuild Command Switches
Switch Default
-image_file=file-spec -image_file=​IMTA_CHARSET_DATA
-maximum -nomaximum
-option_file=file-spec -nooption_file
-remove None
-sizes -nosizes
-statistics -nostatistics


Must have superuser privileges, or logged in as the MTA user (see the user option in restricted.cnf) in order to use this utility.




The imsimta chbuild utility compiles the character set conversion tables and loads the resulting image file into shared memory. As of MS 7.0.5, imsimta chbuild is also the means for informing the MTA of an updated tlds.txt file---the new file used as of MS 7.0.5 to store the IANA list of Top Level Domains.

The MTA ships with very complete character set tables so prior to MS 7.0.5, it was not normally necessary to run this utility. However, as of MS 7.0.5, imsimta chbuild should be used whenever an updated tlds.txt file has been fetched from IANA. (Note that to get updates to tlds.txt to take effect, it is not necessary to also do imsimta cnbuild after the imsimta chbuild---but it is necessary that processes be new in order to see the newly compiled charset/TLD data. So if in a hurry for the changes to take effect, issue an imsimta restart command.)

Prior to MS 7.0.5, two MTA Tailor options were relevant for imsimta chbuild: imta_charset_data specified the default output image file, and imta_charset_option_file specified an option file adjusting charset internal table sizes. As of MS 7.0.5, these MTA Tailor options have been deleted, and hard-coded file paths are used instead, config-root/advanced/charset_data and server-root/lib/option_charset.dat, where server-root is the product install directory or the value of the SERVERROOT environment variable.


-image_file[=file-spec], -noimage_file

By default, imsimta chbuild creates as output the image file (formerly named by the imta_charset_data option of the MTA tailor file) CONFIGROOT/advanced/charset_data. With the -image_file switch, an alternate file name may be specified. When the -noimage_file switch is specified, imsimta chbuild does not produce an output image file; this switch is used in conjunction with the -option_file switch to produce as output an option file which specifies table sizes adequate to hold the tables required by the processed input files.

-maximum, -nomaximum (default)

When -maximum is specified, the file SERVERROOT/lib/maximum_charset.dat is read, in addition to the charset option file (prior to MS 7.0.5 located via the imta_charset_option_file MTA Tailor option) CONFIGROOT/advanced/option_charset.dat. This maximum_charset.dat file specifies near maximum table sizes but does not change any other charset option file (option_charset.dat) parameter settings. Only use the -maximum switch if the current table sizes are inadequate. The -noimage_file and -option_file switches should always be used in conjunction with this switch -- it makes no sense to actually output the enormous configuration that is produced by -maximum, but it does make sense to use -maximum to get past size restrictions in order to build an updated charset option file (option_charset.dat) containing proper size settings so that a properly sized character set image can be built with a subsequent imsimta chbuild invocation.

-option_file[=file-spec], -nooption_file (default)

imsimta chbuildcan optionally produce a charset option file that contains correct table sizes to hold the character set conversion tables which were just compiled (plus a little room for growth). The -option_file switch causes this file to be output, whereas use of the -nooption_file switch means that no option file will be output. Note that imsimta chbuild always reads any pre-existing charset option file (first looking for CONFIGROOT/advanced/option_charset.dat, then CONFIGROOT/option_charset.dat, then finally SERVERROOT/lib/option_charset.dat -- or prior to MS 7.0.5, looking for the file named by the imta_charset_option_file MTA Tailor option) -- use of the -nooption_file switch does not affect reading the old charset option file -- however, specifying -option_file causes imsimta chbuild to also output an updated charset option file. By default, the output charset option file is updated to the same location where the utility found the input charset option file. The value on the -option_file switch may be used to specify an alternate file name.

While the MTA ships with an initial SERVERROOT/lib/option_charset.dat, it is recommended that any site-generated option_charset.dat file instead be written to CONFIGROOT/advanced (or at least to CONFIGROOT) so that MTA updates will not overwrite the site-generated option_charset.dat. Thus the first time a site wishes to generate their own, modified option_charset.dat, the administrator should start by copying the distributed, initial option_charset.dat from the SERVERROOT/lib directory to the CONFIGROOT/advanced directory.

The -maximum switch may be used in conjunction with -option_file to cause imsimta chbuild to read options from maximum_charset.dat in addition to the charset option file (option_charset.dat). This maximum_charset.dat file specifies near maximum table sizes. Only use the -maximum switch if the current table sizes are quite inadequate, and only use it to create a new charset option file. The -noimage_file switch should always be specified when -maximum is specified since a maximum-size image would be truly enormous and extremely wasteful.


Remove any existant compiled character set conversion table; i.e., remove the file (prior to MS 7.0.5 located via the imta_charset_data MTA Tailor option) CONFIGROOT/advanced/charset_data.

-sizes, -nosizes (default)

The -sizes switch instructs imsimta chbuild to output information on the sizes of the uncompiled character set tables.

-statistics, -nostatistics (default)

The -statistics switch instructs imsimta chbuild to output information on the compiled conversion tables. These numbers give a rough measurement of the efficiency of the compilation, and may indicate whether or not an additional rebuild with the -option_file switch is needed.


The standard command used on UNIX to compile character set conversion tables is:

# imsimta chbuild

Or if a drastically increased set of Top Level Domains (tlds.txt file) or drastically increased set of character sets calls for a big increase in the size of the compiled charset set tables, then:

# # If a site has never before generated their own option_charset.dat,
# #    first copy the distributed option_charset.dat to the site's config area
# cp SERVERROOT/lib/option_charset.dat CONFIGROOT/advanced/option_charset.dat
# # Now have the chbuild utility figure out what it needs to resize...
# imsimta chbuild -noimage -option_file -maximum
# # Finally, build new compiled charset tables...
# imsimta chbuild

See also: