Cnbuild utility

Legacy configuration: Compile the MTA configuration, alias, mapping, conversion, system wide filter, circuit check, and option files, and  various   parameters, as well as (optionally) the  reverse "database", general "database", and forward  "database", and also (as of MS 7.0) the Job Controller  configuration file, the Dispatcher configuration file, and TCP/IP  channel option files; generate an image file (suitable for memory  mapping by MTA processes).

Unified Configuration: Compile  as well as  (optionally) the reverse "database", general  "database", and forward "database"; generate an  image file (suitable for memory mapping by MTA processes).

Syntax
imsimta cnbuild

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

Description
With a legacy configuration, the  utility compiles  the textual configuration, option, mapping, conversion, system wide  filter, circuit check, and alias files, and various    parameters (see  Basic configuration settings relevant to alias LDAP lookups and Basic configuration settings relevant to domain LDAP lookups), and (depending  upon the setting of the    MTA option)  also optionally  the reverse "database",  general "database", and  forward "database", and  (as of MS 7.0) also the  Job Controller configuration file,  Dispatcher configuration file, and  TCP/IP channel option files (for SMTP channels or LMTP client  channels), and generates an image file (suitable for memory mapping by  MTA processes). With a Unified Configuration, most of these files have been consolidated: when using a Unified Configuration, the    utility compiles the    file, and (depending upon the setting of the    MTA  option) also optionally the  reverse "database",  general "database", and  forward "database", and generates  an image file (suitable for memory mapping by MTA processes). The resulting image is the file formerly named by the    option of the MTA tailor file; as of MS 7.0.5, such MTA tailor file  options have been replaced by consistent locations, and the image file  is simply.

Whenever a component of the MTA (e.g., a channel program) must read any possibly compiled configuration component, it first checks to  see whether a compiled configuration image file exists, and if so, the  running program uses that image. There are five exceptions to this rule. The first is  itself, which for  obvious reasons always reads the text files and never tries to use an  image form of the configuration data. The remaining four exceptions are ,  ,   , and    which can all be instructed with the    switch to use a different compiled  configuration file. This facility in   is useful for testing changes prior to compiling them.

One reason for compiling configuration information is simple: performance. Precompiling the MTA configuration allows MTA processes to quickly load that precompiled configuration and then get immediately to  work, rather than each new MTA process needing to read the MTA  configuration and build the in-memory representation of the  configuration itself, before starting its own work. Note that MTA design includes short-lived, transient processes (e.g., most  channel delivery job processes), as well as long-lived processes  (e.g., Dispatcher and  Job Controller), so avoiding the  overhead of each MTA process, short-lived or not, repeating the same  configuration-processing work reduces overhead.

A second, and nowadays often more important, reason for compiling configuration information is for convenience in configuration  management and updating: due to the fact that when a compiled  configuration exists the MTA processes will normally refer to it  preferentially, the MTA administrator can make changes to the  underlying configuration files at leisure, and optionally perform some  testing of such changes (e.g., using a    switch with test utilities) prior to  compiling the updated configuration and having the changes become  "live"; meantime, the MTA continues running with the older,  compiled configuration.

Once you begin to use a compiled configuration, it will be necessary to recompile the configuration every time changes are made to the settings  and files comprising the source of the compiled configuration. For a Unified Configuration, this is primarily    (normally modified using the   utility); if the    MTA option  has been set, then also potentially the  reverse "database"  replacement text file, the  general "database"  replacement text file, and the  forward "database"  replacement text file. Specifically, these are the files

 CONFIGROOT , 

 CONFIGROOT , 

 CONFIGROOT, and 

 CONFIGROOT. 



For a legacy configuration, this includes various relevant   parameters (see  Basic configuration settings relevant to alias LDAP lookups and Basic configuration settings relevant to domain LDAP lookups) and the following files: the MTA configuration file (or any files  referenced by it, such as  ), the MTA system  alias file, the MTA mapping file, the MTA option file, the MTA  conversion file, system wide filter file, or the circuit check  configuration file; if the     MTA option has been set,  then also the reverse "database" replacement text file, the  general "database" replacement text file, the forward  "database" replacement text file; as of MS 7.0, also the Job  Controller configuration file, the Dispatcher configuration file, and  TCP/IP channel option files (affecting SMTP channels and LMTP client  channels). Specifically, these are the files  which, prior to MS 7.0.5, were pointed at by the MTA Tailor file options ,  ,  ,   ,   ,   ,   ,   ,   , respectively,  or nowadays are simply:

 CONFIGROOT , 

 CONFIGROOT , 

 CONFIGROOT , 

 CONFIGROOT , </li>

 CONFIGROOT , </li>

 CONFIGROOT , </li>

 CONFIGROOT , </li>

 CONFIGROOT, and </li>

 CONFIGROOT , </li>

</ul>

as well as the file CONFIGROOT.

Until such time as the configuration is recompiled, changes to any of these files will not be visible to the MTA. Furthermore, even after recompiling the configuration, note that changes to the MTA compiled  configuration will not be seen by running MTA processes unless  and until the MTA configuration is reloaded via the    utility,  or until the process expires and is replaced by  a new process. In the case of transient, short-lived processes, (e.g., most channel delivery jobs) their own natural quick  expiration may lead to them being replaced by new processes soon enough  that any lag in making use of the new MTA configuration is relatively  unimportant; however, for significant changes impacting the  Job Controller,  or the Dispatcher or its server processes (SMTP server  processes, SMTP SUBMIT server processes, LMTP server processes), after  performing   also consider performing  ,  when the change needs to take effect  "immediately" and   will suffice. (Note that   only updates certain parts of the  precompiled MTA configuration; in particular, it does not reload the  channel definitions and rewrite rules portions of the MTA configuration  as they are complex and intertwined and require a full re-read of the  configuration. Some additional cases of configuration changes relevant  to the Job Controller can instead be modified "live", without requiring  a restart of the Job Controller, via the    utility.)  A full restart of the MTA (especially  restarting the Job Controller) should be avoided on production systems  unless truly necessary as a restart interrupts and disrupts message  delivery; however, a    to restart the  various servers underneath the Dispatcher causes only brief disruption  in acceptance of incoming messages, so is acceptable when enqueue  processing changes beyond those covered by    need to take effect "immediately" upon incoming messages.

Note that updates to the  file (introduced in MS  7.0.5) do not require use of   to  take effect; instead, updates to   are incorporated  by use of the   utility.

See Compiling the MTA configuration for further details on the use of compiled  configurations.

If  spots a syntactic error in one of the  files that it is attempting to use to build the compiled configuration,  it will be reported, typically as an error of the form time-stamp: Error in mm_init -- detail where the  provides additional, specific  detail about the particular error. For instance (with output wrapped here for display convenience; in reality it would appear all on one  line): 09:28:26.15: Error in mm_init -- duplicate host in channel table -- host.domain. com -- line #45 in file IMTA_CONFIG_FILE Note that   does not know specifics of the syntax and  semantics of the Dispatcher configuration file or Job Controller  configuration file, or channel option files, so generally errors in the  option settings in those files---other than egregiously, obviously  broken syntax problems---will not be reported by the utility and  instead will get reported by the component in question when it attempts  to begin running.

As of MS 6.3p1, errors compiling the configuration (in particular, mm_init errors) will cause   to exit with a  non-zero status. Prior to that version, while such errors would certainly cause   to exit with error text  and without making a new compiled configuration, the exit status was  nevertheless zero in many cases.

There is also a secondary, "tuning" use of. When the MTA is building an in-memory representation of its configuration (whether that is to generate a compiled  configuration, or whether in the absence of any compiled configuration  MTA processes are each reading the MTA configuration and building their  own private representations of the MTA configuration), it starts by  assuming certain table sizes, and if those table sizes are not  adequate, iteratively increases those sizes until reaching "big enough"  tables in memory to hold the current configuration. The starting points for such table sizes are controlled by  internal size MTA options. Using   with its   switch  provides information on how "close" the current internal size MTA  options are to the sizes needed for the current MTA configuration, and  using   with the set of switches    will generate a new  MTA option file with internal size MTA options set appropriately for  the current MTA configuration. This sort of tuning permits more efficient compilation of the MTA configuration---though it is not  strictly necessary (since the MTA will interatively resize, if  necessary, on-the-fly while reading its configuration).

Since the MTA will resize its internal table sizes as needed, errors about exceeding table sizes are normally seen only if the MTA&#x27;s  more-or-less "hard" limits on resizing are reached. (The limits are established by the   file and/or  "hard" limits in the code.) And since the MTA&#x27;s  "hard" limits are very generous, exceeding the  limits is usually an indication of either a configuration error of a  type that has confused the MTA about the intended meaning of certain  configuration inputs (for instance, an extraneous blank line in the  rewrite rules, causing the MTA to attempt to interpret all remaining  material as channel definitions), or configuration choices involving  poor use of MTA facilities that would be better handled in an alternate  manner (such as attempting to  hard code  many thousands of mapping table entries,  rather than using a few general entries that do  general database callouts&#x3e;  for the specific fields). In particular, reaching the limits specified in the normal   file is usually  an indication of poor configuration choices; you should contact Oracle  if you believe you wish to exceed those limits, as you may be better  served by alternate configuration tactics.

Finally, a command such as may be used to list current option values (as specified in the current MTA option file, plus default values) in the file specified as   . To list (most) default option values, irrespective of override values specified in the current MTA option  file, the current MTA option file must be "moved aside"  before the above command is issued. (For instance, temporarily rename the MTA option file, then issue the above command, then rename the MTA  option file back to its normal location.)
 * 1) imsimta cnbuild -noimage_file -option_file=file-spec

,  (default)
means to check the structure of the   file.

&#x5b; &#x5d;,
By default,  creates as output the image  file named  CONFIGROOT ; (prior to MS 7.0.5, the file located via the    MTA Tailor option). With the   switch, an alternate file name may be  specified. When the  switch is specified,    does not produce an output image file. This switch is used in conjunction with the   switch to produce as output an option file  which specifies table sizes adequate to hold the configuration required  by the processed input files.

,  (default)
When  is specified, the file  SERVERROOT   is read in addition to the  internal size MTA options (which in legacy configuration would be stored in the  MTA   file, located prior to MS 7.0.5 via the   MTA Tailor file option). The  file specifies  near maximum table sizes but does not change any other MTA option  settings. Only use the  switch if the current table sizes  are inadequate. The  and    switches should always be used in  conjunction with this switch---it makes no sense to output the  enormous configuration that is produced by , but  it does make sense to use   to get past size  restrictions in order to set properly adjusted MTA option values (in legacy configuration, build an MTA option file with properly adjusted option values) so that a  properly sized configuration can be built with a subsequent    invocation.

&#x5b; &#x5d;,   (default)
can optionally set various internal size MTA options (in legacy configuration, produce an option file that contains correct table sizes) to hold the configuration that was just  compiled (plus a little room for growth). The   switch causes this file to be output. By default, this file is named CONFIGROOT  (or prior to MS 7.0.5, was located via the   MTA Tailor file option). The value on the   switch may be used to specify an alternate file name. If the   switch is given, then no option file  will be output. always reads any MTA options previously set, whether set as Unified Configuration MTA options or set in the MTA option file, CONFIGROOT ;   use of the   switch will not  alter this behavior. However, use of the   switch causes   to also read MTA options from the file  CONFIGROOT  This   file specifies near maximum table sizes. Only use the  switch if the current table sizes are inadequate, and only use it to generate new MTA option settings (set either as new values for MTA options in Unified Configuration, or by building a new   file in legacy configuration). The  switch should always  be specified when   is specified since a  maximum-size image would be truly enormous and extremely wasteful.

,  (default)
The  switch causes removal of any existant compiled configuration; i.e., removes the  file  CONFIGROOT  (located prior to MS 7.0.5 via the   MTA Tailor file option).

,  (default)
The  switch instructs   to output information on the sizes of uncompiled MTA  tables.

,  (default)
The  switch instructs   to output information on how much of the various tables  in the compiled configuration were actually used to store data. These numbers give a rough measurement of the efficiency of the compilation,  and may indicate whether or not an additional rebuild with the    switch is needed. Specifying   effectively forces.

,  (default)
means to output a list of MTA option and channel option synonyms; that is, output a list of the MTA options and channel  option marked as aliases in  : spamfilter_config_file -&#x3e; spamfilter1_config_file brightmail1_config_file -&#x3e; spamfilter1_config_file brightmail_config_file -&#x3e; spamfilter1_config_file ...additional aliased MTA options... 733 -&#x3e; percents 822 -&#x3e; sourceroute brightmail -&#x3e; sourcespamfilter1 channelfilter -&#x3e; destinationfilter ...additional aliased channel keywords...

,   (default)
directs  to compile a  Unified Configuration;   directs    to compile a legay configuration.

Examples
This is the standard command used on UNIX to regenerate a compiled configuration. After compiling the configuration, restart any programs which may need to reload the new configuration; e.g., the SMTP  server should be restarted. (Note that the  character  may need shell-quoting so that it will be passed through the shell properly to the MTA utility.) Use these two UNIX commands when you encounter the infamous " " MTA error message.
 * 1) imsimta cnbuild
 * 2) #     Depending upon what has changed, consider issuing:
 * 3) # imsimta reload
 * 4) # imsimta restart &#x2a;
 * 1) imsimta cnbuild -noimage_file -option_file -maximum
 * 2) imsimta cnbuild

See also:
 * use_text_databases MTA Option
 * Reverse database
 * General database
 * Forward database
 * Job Controller options
 * Dispatcher options
 * TCPIP-channel-specific options
 * imta_config_data MTA Option
 * reload utility
 * Internal size MTA options
 * restart utility
 * MTA command line utilities