The command-line utilities described in this chapter are used to perform various maintenance, testing, and management tasks for the Message Transfer Agent (MTA).
The MTA commands are also referred to as the imsimta commands. The imsimta script is located in the msg_svr_base/ directory.
msg_svr_base represents the directory path in which you install the server.
The commands are listed in Table 2–1.
Command |
Description |
---|---|
Performs operations on the queue cache. |
|
Compiles the MTA character set conversion tables. |
|
Compiles the MTA configuration files. |
|
Performs operations on the channel counters. |
|
Creates an MTA database. |
|
Locates the precise filename of the specified version of an MTA log file |
|
Terminates the specified process. |
|
Lists currently running MTA jobs. |
|
Manipulates the MTA program delivery options. |
|
Purges MTA log files. |
|
Holds or deletes message files containing specific substrings in their envelope From:address, Subject: line, or content. |
|
Manages MTA message queues. |
|
Displays the most frequently occurring envelope From: Subject:, or message content fields found in message files in the channel queues. |
|
Combines the functionality of the imsimta cnbuild and imsimta restart utilities. |
|
Allows changes to certain configuration files to take effect without restarting the server. |
|
Renames a MTA database. |
|
Restarts detached MTA processes. |
|
Returns (bounces) a mail message to its originator. |
|
Processes messages in a specified channel. |
|
Shuts down the MTA Job Controller and the MTA Dispatcher as well as individual processes running under the Dispatcher. |
|
Starts the MTA Job Controller and Dispatcher. |
|
Shuts down the MTA Job Controller and the MTA Dispatcher as well as individual processes running under the Dispatcher. |
|
Processes messages in a specified channel. |
|
Performs tests on mapping tables, wildcard patterns, address rewriting, and URLs. |
|
Prints the MTA version number. |
|
Displays log files. |
You need to be logged in as root (UNIX) or administrator (Windows NT) to run the MTA commands. Unless mentioned otherwise, all MTA commands should be run as mailsrv (the mail server user that is created at installation).
The MTA maintains an in-memory cache of all the messages currently stored in its queues. This cache is called the queue cache. The purpose of the queue cache is to make dequeue operations perform more efficiently by relieving master programs from having to open every message file to find out which message to dequeue and in which order.
imsimta cache -sync | -view [channel] |
The options for this command are:
Option |
Description |
---|---|
-sync |
Updates the active queue cache by updating it to reflect all non-held message files currently present in the /msg_svr_base/imta/queue/ subdirectories. Note that the -sync option does not remove entries from the queue cache. The queue cache entries not corresponding to an actual queued message are silently discarded by channel master programs. |
-view [channel] |
Shows the current non-held entries in the MTA queue cache for a channel. channel is the name of the channel for which to show entries. This is a potentially expensive command if you have a large backlog of messages. Instead of running this command frequently, consider using the imsimta qm messages command. |
-walk [-debug=xxx] |
Used to diagnose potential problems with the job controller. Each time this command is run, the internal state of the message queues and job scheduling information is written to the job_controller.log file. In addition, the job controller debug mask is set to the value given. You should not run this command unless you are instructed to do so by support. |
To synchronize the queue cache:
imsimta cache -sync |
To view entries in the queue cache for the tcp_local channel, execute the command:
imsimta cache -view tcp_local |
The imsimta chbuild command compiles the character set conversion tables and loads the resulting image file into shared memory. The MTA ships with complete character set tables so you would not normally need to run this command. You would use imsimta chbuild only if you added or modified any character sets.
imsimta chbuild [-image_file=file_spec | -noimage_file] [-maximum | -nomaximum][-option_file=[option_file] | -nooption_file] [-remove] [-sizes |-nosizes] [-statistics | -nostatistics] |
The options for this command are:
Option |
Description |
---|---|
-image_file=file_spec | -noimage_file |
By default, imsimta chbuild creates as output the image file named by the IMTA_CHARSET_DATA option of the MTA tailor file, msg_svr_base/config/imta_tailor. With the -image_file option, an alternate file name may be specified. When the -noimage_file option is specified, imsimta chbuild does not produce an output image file. The -noimage_file option is used in conjunction with the -option_file option to produce as output an option file that specifies table sizes adequate to hold the tables required by the processed input files. |
-maximum | -nomaximum |
The file msg_svr_base/config/maximum_charset.dat is read in addition to the file named by the IMTA_CHARSET_OPTION_FILE option of the MTA tailor file, msg_svr_base/config/imta_tailor, when -maximum is specified. This file specifies near -maximum table sizes but does not change any other settings. Use this option only if the current table sizes are inadequate. The -noimage and -option_file options should always be used in conjunction with this option—it makes no sense to 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 a properly sized option file for use in building a manageable configuration with a subsequent imsimta chbuild invocation. |
-option_file=[option_file] | -nooption_file |
imsimta chbuild can produce an option file that contains the correct table sizes to hold the conversion tables that were just processed (plus a little room for growth). The -option_file option causes this file to be output. By default, this file is the file named by the IMTA_CHARSET_OPTION_FILE option of the MTA tailor file, msg_svr_base/config/imta_tailor. The value of the -option_file option may be used to specify an alternate file name. If the -nooption_file option is given, then no option file is output. imsimta chbuild always reads any option file (for example, the file named by the IMTA_OPTION_FILE option of the MTA tailor file) that is already present; use of this option does not alter this behavior. However, use of the -maximum option causes imsimta chbuild to read options from maximum_charset.dat in addition to IMTA_CHARSET_OPTION_FILE. This file specifies near-maximum table sizes. Use this option only if the current table sizes are inadequate, and only use it to create a new option file. The -noimage_file option should always be specified with -maximum, since a maximum-size image would be enormous and inefficient. |
-remove |
Removes any existing compiled character set conversion table. This is the file named by the IMTA_CHARSET_DATA option of the MTA tailor file, msg_svr_base/config/imta_tailor. |
-sizes | -nosizes |
The -sizes option instructs imsimta chbuild to output or suppress information on the sizes of the uncompiled conversion tables. The -nosizes option is the default. |
-statistics | -nostatistics |
The -statistics option instructs imsimta chbuild to output or suppress information on the compiled conversion tables. This information gives a rough measurement of the efficiency of the compilation, and may indicate whether or not an additional rebuild with the -option_file option is needed. The -nostatistics option is the default. |
The standard command you use to compile character set conversion tables is:
imsimta chbuild |
The imsimta cnbuild command compiles the textual configuration, option, mapping, conversion, circuit check and alias files, and loads the resulting image file into shared memory. The resulting image is saved to a file usually named imta/lib/config_data by the IMTA_CONFIG_DATA option of the MTA tailor file, msg_svr_base/config/imta_tailor.
Whenever a component of the MTA (for example, a channel program) must read a compiled configuration component, it first checks to see whether the file named by the MTA tailor file option IMTA_CONFIG_DATA is loaded into shared memory; if this compiled image exists but is not loaded, the MTA loads it into shared memory. If the MTA finds (or not finding, is able to load) a compiled image in shared memory, the running program uses that image.
The reason for compiling configuration information is simple: performance. The only penalty paid for compilation is the need to recompile and reload the image any time the underlying configuration files are edited. Also, be sure to restart any programs or channels that load the configuration data only once when they start up-for example, the MTA multithreaded SMTP server.
It is necessary to recompile the configuration every time changes are made to any of the following files:
MTA configuration file (or any files referenced by it)
MTA system alias file
MTA mapping file
MTA option file
MTA conversion file
MTA security configuration file
MTA circuit check configuration file
MTA system wide filter file
Specifically, these are the files pointed at by the MTA tailor file options IMTA_CONFIG_FILE, IMTA_ALIAS_FILE, IMTA_MAPPING_FILE, IMTA_OPTION_FILE, and IMTA_CONVERSION_FILE respectively, which usually point to the following files:
msg_svr_base/config/imta.cnf
msg_svr_base/config/aliases
msg_svr_base/config/mappings
msg_svr_base/config/option.dat
msg_svr_base/config/conversions
Until the configuration is rebuilt, changes to any of these files are not visible to the running MTA system.
imsimta cnbuild [-image_file=file_spec | -noimage_file] [-maximum | -nomaximum] [-option_file=[option_file] | -nooption_file] [-remove] [-sizes | -nosizes] [-statistics | -nostatistics] |
The options for this command are:
Option |
Description |
---|---|
-image_file=file_spec | -noimage_file |
By default, imsimta cnbuild creates as output the image file named by the IMTA_CONFIG_DATA option of the MTA tailor file, msg_svr_base/config/imta_tailor. With the -image_file option, an alternate filename can be specified. When the -noimage_file option is specified, imsimta cnbuild does not produce an output image file. This option is used in conjunction with the -option_file option to produce as output an option file which specifies table sizes adequate to hold the configuration required by the processed input files. The default value is -image_file=IMTA_CONFIG_DATA. |
-maximum | -nomaximum |
msg_svr_base/config/maximum.dat is read in addition to the file named by the IMTA_OPTION_FILE option in the MTA tailor file, msg_svr_base/config/imta_tailor. This file specifies near maximum table sizes but does not change any other option file parameter settings. Only use this option if the current table sizes are inadequate. The -noimage and -option_file options should always be used in conjunction with this qualifier; it makes no sense to 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 a properly-sized option file so that a proportionately-sized configuration can be built with a subsequent imsimta cnbuild invocation. The default is -nomaximum. |
-option_file=[option_file] | -nooption_file |
imsimta cnbuild can optionally produce an option file that contains correct table sizes to hold the configuration that was just compiled (plus a little room for growth). The -option_file option causes this file to be output. By default, this file is the file named by the IMTA_OPTION_FILE option in the MTA tailor file, msg_svr_base/config/imta_tailor. The value on the -option_file option may be used to specify an alternate file name. If the -nooption_file option is given, then no option file will be output. imsimta cnbuild always reads any option file that is already present via the IMTA_OPTION_FILE option of the MTA tailor file, msg_svr_base/config/imta_tailor; use of this option will not alter this behavior. However, use of the -maximum option causes imsimta cnbuild to read MTA options from the msg_svr_base/config/maximum.dat file in addition to reading the file named by IMTA_OPTION_FILE. This file specifies near maximum table sizes. Use this option only if the current table sizes are inadequate, and only to create a new option file. The -noimage_file option should always be specified when -maximum is specified since a maximum-size image would be enormous and wasteful. The default value is -option_file=IMTA_OPTION_FILE. |
-remove |
Remove any existing compiled configuration; for example, remove the file named by the IMTA_CONFIG_DATA option of the MTA tailor file, msg_svr_base/config/imta_tailor. |
-sizes | -nosizes |
The -sizes option instructs imsimta cnbuild to output information on the sizes of uncompiled MTA tables. The -nosizes option is the default. |
-statistics | -nostatistics |
The -statistics option instructs imsimta cnbuild to output information table usage. This information gives a rough measurement of the efficiency of the compilation, and may indicate whether or not an additional rebuild with the -resize_tables option is needed. The -nostatistics option is the default. |
To regenerate a compiled configuration enter the following command:
imsimta cnbuild |
After compiling the configuration, restart any programs that may need to reload the new configuration. For example, the SMTP server should be restarted:
imsimta restart dispatcher |
imsimta cnbuild is executed whenever the imsimta refresh command is invoked.
The MTA accumulates message traffic counters for each of its active channels. These statistics, referred to as channel counters, are kept in shared memory. The imsimta counters command manipulates these counters.
imsimta counters -clear imsimta counters -create [-max_channels=value] imsimta counters -delete imsimta counters -show [-associations | -noassociations] [-channels | -nochannels] [-headers | -noheaders] [-output=file_spec] |
The options for this command are:
Option |
Description |
---|---|
-associations |-noassociations |
Specifies whether or not to show the in-memory cache of association counters. The -associations option is the default. This option is only used with the -show option. |
-channels |-nochannels |
Specifies whether or not to show the in-memory cache or channel counters. The -channels option is the default. This option is only used with the -show option. |
-clear |
The -clear command clears the in-memory channel counters. |
-create |
Creates the in-memory channel counters. Counters are not created by default. You must create the counters if you wish to use them. You must create them after restarting the MTA as well. |
-headers |-noheaders |
Controls whether or not a header line describing each column in the table of counters is output. The -headers option is the default. This option is only used with the -show option. |
-max_channels=value |
By default, the in-memory channel counters can hold information for CHANNEL_TABLE_SIZE channels. CHANNEL_TABLE_SIZE is the value specified by the MTA option file option of the same name. Use the -max_channels=value option to select a different size. This option is used only with the -create option. |
-delete |
Deletes the in-memory channel counters. |
-show |
Displays the in-memory channel counters. |
-headers | -noheaders |
Controls whether or not a header line describing each column in the table of counters is output. The -headers option is the default. This option is only used with the -show option. |
-output=file_spec |
Directs the output to the specified file. By default, the output appears on your display. This option is only used with the -show option. |
To display the counters for all channels:
imsimta counters -show |
The imsimta crdb command creates and updates MTA database files. imsimta crdb converts a plain text file into MTA database records; from them, it either creates a new database or adds the records to an existing database.
In general, each line of the input file must consist of a left side and a right side. The two sides are separated by one or more spaces or tabs. The left side is limited to 32 characters in a short database (the default variety) and 80 characters in a long database. The right side is limited to 80 characters in a short database and 256 in a long database. Spaces and tabs may not appear in the left side unless the -quoted option is specified. Comment lines may be included in input files. A comment line is a line that begins with an exclamation mark (!) in column 1.
imsimta crdb input-file-spec output-database-spec [-append | -noappend] [-count | -nocount] [-duplicates | -noduplicates] [-long_records | -nolong_records] [-quoted | -noquoted] [-remove | -noremove] [-statistics | -nostatistics] [-strip_colons | -nostrip_colons] |
The options for this command are:
Option |
Description |
---|---|
input-file-spec |
A text file containing the entries to be placed into the database. Each line of the text file must correspond to a single entry. This attribute is mandatory. |
output-database-spec |
The initial name string of the files to which to write the database (unless -dump is specified). The .db extension is appended to the file name. This attribute is mandatory. |
-append | -noappend |
When the default, -noappend, option is in effect, a new database is created, overwriting any old database of that name. Use the -append option to instruct the MTA to instead add the new records to an existing database. The -noappend option is the default. In the event of a duplicate record, the newly appended record overwrites the old record when -noduplicates is specified. |
-count | -nocount |
Controls whether or not a count is output after each group of 100 input lines are processed. The -count option is the default. |
-duplicates | -noduplicates |
Controls whether or not duplicate records are allowed in the output files. Currently, duplicate records are of use only in the domain database (rewrite rules database) and databases associated with the directory channel. The -noduplicates option is the default. |
-long_records | -nolong_records |
Controls the size of the output records. By default, left sides are limited to 32 characters and right sides are limited to 80 characters. If -long_records is specified, the limits are changed to 80 and 256, respectively. The -nolong_records option is the default. |
-quoted | -noquoted |
Controls the handling of quotes. Normally imsimta crdb pays no attention to double quotes. If -quoted is specified, imsimta crdb matches up double quotes in the process of determining the break between the left and right hand sides of each input line. Spaces and tabs are then allowed in the left side if they are within a matching pair of quotes. This is useful for certain kinds of databases, where spaces may form a part of database keys. The quotes are not removed unless the -remove option is also specified. The -noquoted option is the default. |
-remove | -noremove |
Controls the removal of quotes. If imsimta crdb is instructed to pay attention to quotes, the quotes are normally retained. If -remove is specified, imsimta crdb removes the outermost set of quotes from the left hand side of each input line. Spaces and tabs are then allowed in the left side if they are within a matching pair of quotes. This is useful for certain kinds of databases, where spaces may form a part of database keys. -remove is ignored if -quoted is not in effect. The -noremove option is the default. |
-statistics | -nostatistics |
Controls whether or not some simple statistics are output by imsimta crdb, including the number of entries (lines) converted, the number of exceptions (usually duplicate records) detected, and the number of entries that could not be converted because they were too long to fit in the output database. -nostatistics suppresses output of this information. The -statistics option is the default. |
-strip_colons | -nostrip_colons |
Instructs imsimta crdb to strip a trailing colon from the right end of the left hand side of each line it reads from the input file. This is useful for turning alias file entries into an alias database. The -nostrip_colons is the default. |
The following commands create an alias database with “long” record entries. The creation is performed in a two-step process using a temporary database to minimize any window of time, such as during database generation, when the database would be locked and inaccessible to the MTA.
imsimta crdb -long_records aliases-tmp imsimta renamedb aliases-tmp IMTA_ALIAS_DATABASE |
The imsimta crdb -dump command writes the entries in MTA databases to a flat ASCII file. In particular, this command may be used to write the contents of an old style database to a file from which a new style database may be built using the imsimta crdb command. The output begins with a comment line that displays a proper imsimta crdb command to use in order to return the ASCII output to a database.
Make sure you are logged in as mailsrv (the mail server user) before performing this command.
imsimta crdb -dump input-database-spec [output-file-spec] |
The parameters for this command are:
Parameter |
Description |
---|---|
input-database-spec |
Database from which to read entries. By default, the MTA looks for a current format database of the given name; if this does not exist, the MTA will look for an old format database of the given name. The special keywords IMTA_ALIAS_DATABASE, IMTA_REVERSE_DATABASE, and IMTA_GENERAL_DATABASE are supported; the use of such a special keyword tells the MTA to dump the database specified by the corresponding MTA tailor file option. |
output-file-spec |
ASCII file to which the entries stored in the database are written. This file should be in a directory where you have write permissions. If an output file is not specified, the output is written to stdout. |
The following command can be used to dump the contents of an alias database to a file, and then to recreate the alias database from that file
imsimta crdb -dump IMTA_ALIAS_DATABASE alias.txt imsimta crdb alias.txt alias-tmp imsimta renamedb alias-tmp IMTA_ALIAS_DATABASE |
The imsimta find utility locates the precise filename of the specified version of an MTA log file. MTA log files have a -uniqueid appended to the filename to allow for the creation of multiple versions of the log file. On UNIX, the -uniqueid is appended to the very end of the filename (the end of the file extension), while on Windows NT, the -uniqueid is appended to the end of the name part of the filename, before the file extension. The imsimta find utility understands these unique ids and can find the particular filename corresponding to the requested version of the file.
imsimta find file-pattern [-f=offset-from-first] [-l=offset-from-last] |
The options for this command are:
Option |
Description |
---|---|
-f=offset-from-first |
Finds the specified version of the file (starting from 0). For example, to find the earliest (oldest) version of the file, specify -f=0. By default, imsimta find finds the most recent version of the file. |
-l=offset-from-last |
Finds the last version of the specified file. For example, to find the most recent (newest) version of the file, specify -l=0. By default, imsimta find finds the most recent version of the file. |
file-pattern |
Specifies a filename pattern for which the log file to find. |
The following command prints out the filename of the tcp_local_slave.log-uniqueid file most recently created:
imsimta find msg_svr_base/imsimta/log/tcp_local_slave.log |
The following command displays the filename of the oldest tcp_bitnet_master.log-uniqueid file:
imsimta find \ msg_svr_base/imsimta/log/tcp_bitnet_master.log -f=0 |
The imsimta kill utility immediately and indiscriminately terminates the specified process. This command is equivalent to the UNIX kill -9 command. The process is terminated even if it is in the middle of transferring email. So use of the imsimta shutdown utility, which performs an orderly shutdown, is generally preferable.
imsimta kill component |
You must have the same process id as the process to be killed, or be root. This utility is not available on Windows NT.
component is the MTA component to be killed. Valid values are job_controller and dispatcher.
This command displays the current MTA processes. Additional processes may be present if messages are currently being processed, or if certain additional MTA components are in use.
imsimta process |
The following command shows current MTA processes:
# imsimta process imsimta process USER PID S VSZ RSS STIME TIME COMMAND mailsrv 15334 S 21368 9048 17:32:44 0:01 imta/bin/dispatcher mailsrv 15337 S 21088 10968 17:32:45 0:01 imta/bin/tcp_smtp_server mailsrv 15338 S 21080 11064 17:32:45 0:01 imta/bin/tcp_smtp_server mailsrv 15349 S 21176 10224 17:33:02 0:02 imta/bin/job_controller |
The imsimta program command is used to manipulate the program delivery options.
This command can be executed as root or mailsrv. mailsrv is the default user for Messaging Server, but could be whatever the specified user name for the Messaging Server is when Messaging Server is installed.
The program is passed the entire message, unparsed from stdin. This includes the From line (without the colon) as the first line, followed by the headers and the message body. This may include any MIME attachments that are part of the message.
imsimta program -a -m method -p program [-g argument_list] [-eexec_permission] imsimta program -d -m method imsimta program -c -m method -p program | -g argument_list | -e exec_permission |
The options for this command are:
Option |
Description |
---|---|
-a |
Add a method to the set of program delivery methods. This option cannot be used with the -d, -c, -l, or -u options. |
-c |
Change the arguments to a program that has already been entered. |
-m method |
Name given by the administrator to a particular method. This will be the name by which the method will be advertised to users. Method names must not contain spaces, tabs, or equal signs (=). The method name cannot be none or local. The method name is restricted to U.S. ASCII. This option is required with the -a, -d, -c, and -u options. |
-p program |
Actual name of the executable for a particular method. The executable should exist in the programs directory (msg_svr_base/data/site-programs) for the add to be successful. It can be a symbolic link to an executable in some other directory. This option is required with the -a option. |
-g argument_list |
Argument list to be used while executing the program. If this option is not specified during an add, no arguments will be used. Each argument must be separated by a space and the entire argument list must be given within double quotes. If the %s tag is used in the argument list, it will be substituted with the user's username for programs executed by the users and with username+programlabel for programs executed by inetmail. programlabel is a unique string to identify that program. This option can be used with the -a and -c options. |
-e exec_permission |
exec_permission can be user or postmaster. If it is specified as user, the program is executed as the user. By default, execute permission for all programs are set to postmaster. Programs with exec_permission set to user can be accessed by users with UNIX accounts only. This option can be used with the -a and -c options. The directory from where this program is run as postmaster is the postmaster’s home directory. If specified as user, then the user’s home directory is the environment where the program is run as the user. |
-d |
Delete a method from the list of supported program delivery methods. This option cannot be used with the -a, -c, -l, or -u options. |
-h |
Help for this command. |
-l |
List all methods. |
-u |
List all users using the method specified with the -m option. |
To add a method procmail1 that executes the program procmail with the arguments -d username and executes as the user, enter the following:
imsimta program -a -m procmail1 -p procmail -g "-d %s" -e user |
The imsimta purge command deletes older versions of MTA log files. imsimta purge can determine the age of log files from the uniqueid strings terminating MTA log file names.
imsimta purge [file-pattern] -day=dvalue -hour=hvalue -num=nvalue |
The options for this command are:
Option |
Description |
---|---|
file-pattern |
If specified, the file-pattern parameter is a file name pattern that establishes which MTA log files to purge. The default pattern, if none is specified, is log/imta/log. |
-day=dvalue |
Purges all but the last dvalue days worth of log files. |
-hour=hvalue |
Purges all but the last hvalue hours worth of log files. |
-num=nvalue |
Purges all but the last nvalue log files. The default is 5. |
To purge all but the last five versions of each type of log file in the log/imta directory:
imsimta purge |
The imsimta qclean utility holds or deletes message files containing specific substrings in their envelope From:address, Subject: line, or content.
imsimta qclean [-content=substring] [-from=substring][-subject=substring] [-to=substring] [-domain_to=substring] [-database] [-delete | -hold] [-directory_tree] [-ignore_zz] [-match=keyword] [-min_length=n] [-threads | -nothreads] [-verbose | -noverbose] [channel] |
The options for this command are:
Option |
Description |
---|---|
-content=substring -from=substring
-subject=substring -to=substring -domain_to=substring |
Specifies the substrings for which to search. Any combination of -content, -from, -subject, -to, and -domain_to may be specified. However, only one of each may be used. When a combination of such options is used, the -match option controls whether the options are interpreted as further restrictions (-match=AND) or as alternatives (-match=OR). The -domain_to option scans for frequently occurring envelope To: addresses. Identical to the -to option, except -domain_to looks at only the host.domain portion of the envelope To: address. |
-database |
Specifies that only message files identified by the queue cache is searched. |
-delete |
Deletes matching message files. |
-hold |
Holds matching message files. |
-directory_tree |
Searches all message files that are actually present in the channel queue directory tree. |
-ignore_zz |
Ignores queued message files with file names beginning with “ZZ”. This option may be used to scan only those message files which represent queued messages which have failed at least one delivery attempt. |
-match=keyword |
Controls whether a message file must contain all (-match=AND) or only one of (-match=OR) the specified substrings in order to be held or deleted. The default is -match=AND. |
-min_length=n |
Specifies the minimum length of the substring for which to search. By default, each substring must be at least 24 bytes long. Use the -min_length option to override this limit. |
-threads=n | -nothreads |
Accelerates the searching on multiprocessor systems by dividing the work amongst multiple, simultaneous running threads. To run n simultaneous searching threads, specify -threads=n. The value n must be an integer between 1 and 8. The default is -nothreads. |
-verbose | -noverbose |
Requests that the utility displays operation information (-verbose). The default is -noverbose. |
channel |
Specifies an MTA channel area to be searched for matching messages. The * or ? wildcard characters may be used in the channel specification. |
The imsimta qm utility inspects and manipulates the channel queue directories and the messages contained in the queues. imsimta qm contains some functionality overlap with the imsimta cache and imsimta counters commands.
For example, some of the information returned by imsimta cache -view is also available through the imsimta qm directory command. However, imsimta qm, does not completely replace imsimta cache or imsimta queue.
You must be root or mailsrv to run imsimta qm.
imsimta qm can be run in an interactive or non-interactive mode. To run imsimta qm in the interactive mode, enter:
imsimta qm |
You can then enter the sub-commands that are available for use in the interactive mode. To exit out of the interactive mode, enter exit or quit.
To run imsimta qm in the non-interactive mode, enter:
imsimta qm sub-commands [options] |
Note that some of the sub-commands available in the interactive mode are not available in the non-interactive mode, and vice versa. See Sub-Commands indicates the mode for which mode it is available.
The clean sub-command holds or deletes message files containing specific substrings in their envelope From: address, Subject: line, or content.
Available in both interactive and non-interactive modes.
clean [-content=substring] [-from=substring] [-subject=substring] [-to=substring] [-domain_to=substring] [-database | -directory_tree] [-delete | -hold] [-ignore_zz] [-match=keyword] [-min_length=n] [-threads=n | -nothreads] [-verbose | -noverbose] [channel] |
The options for this sub-command are:
Option |
Description |
---|---|
-content=substring -from=substring -subject=substring -to=substring -domain_to=substring |
Specifies the substrings for which to search. Any combination of each option may be used. However, only one of each may only be used. When a combination of such options is used, the -match option controls whether the options are interpreted as further restrictions (-match=AND), or as alternatives (-match=OR). The -domain_to option scans for frequently occurring envelope To: addresses. Identical to the -to option, except -domain_to looks at only the host.domain portion of the envelope To: address. The -from option can take an empty address using, for example, imsimta qm clean -from=\<\>. |
-database | -directory_tree |
Controls whether the message files searched are only those with entries in the queue cache (-database) or all message files actually present in the channel queue directory tree (-directory_tree). When neither -database nor -directory_tree is specified, then the view selected with the view sub-command will be used. If no view sub-command has been issued, then -directory_tree is assumed. |
-delete | -hold |
Specifies whether matching message files are held (-hold) or deleted (-delete). The -hold option is the default. |
-ignore_zz |
Ignores queued message files with file names beginning with “ZZ”. This option may be used to scan only those message files which represent queued messages which have failed at least one delivery attempt. |
-match=keyword |
Controls whether a message file must contain all (-match=AND) or only one of (-match=OR) the specified substrings in order to be held or deleted. The substrings are specified by the -content, -env_from, and -subject options. The default is -match=AND. |
-min_length=n |
Overrides the length limit for each substring to be searched. By default, the limit is 24 bytes (-min_length=24). |
-threads=n | -nothreads |
Accelerates the searching on multiprocessor systems by dividing the work amongst multiple, simultaneous running threads. To run n simultaneous searching threads, specify -threads=n. The value n must be an integer between 1 and 8. The default is -nothreads. |
-verbose | -noverbose |
Requests that the utility displays operation information (-verbose). The default is -noverbose. |
channel |
Specifies a specific MTA channel area to be searched for matching messages. The * or ? wildcard characters may be used in the channel specification. |
The counters clear sub-command performs the following operations:
Creates the shared memory segment for the channel message and association counters if the segment does not already exist.
Sets all counter values to zero.
When -channels is specified, sets the counts of stored messages, recipients, and volume from the queue cache database.
Available for both interactive and non-interactive modes.
counters clear [-channels] [-associations] |
The options for this sub-command are:
Option |
Description |
---|---|
-channels |
Clears the message counters |
-associations |
Clears the association counters |
When neither option is specified, both are assumed. When -associations is specified and -channels is not specified, step (3) above is not performed.
The counters create sub-command performs the following operations:
Creates the shared memory segment for the channel message and association counters if the segment does not already exist.
Sets the counts of stored messages, recipients, and volume from the queue cache database.
Available for both interactive and non-interactive modes.
counters create [-max_channels=n] |
The option for this sub-command is:
Option |
Description |
---|---|
-max_channels=n |
Tells the MTA how many channels to allow for in the memory segment. If this option is omitted, then the MTA looks at the imta.cnf file and determines a value on its own. |
The counters delete sub-command deletes the shared memory segment used for channel message and association counters. Note that active MTA server processes and channels will likely recreate the memory segment.
Available for both interactive and non-interactive modes.
counters delete |
Use the counters show sub-command to display channel message counters. When the optional channel-name parameter is omitted, * (wildcard) is assumed and the message counters for all channels are displayed. The channel-name parameter may contain the * and? wildcard characters.
The counters show sub-command performs the following operations:
Creates the shared memory segment for the channel message and associated counters if the segment does not already exist.
Sets the counts of stored messages, recipients, and volume from the queue cache database.
Displays the message counters for the specified channels.
Available for both interactive and non-interactive modes.
counters show [-headers] [-noheaders] [-output=file-spec] \ [channel-name] |
The options for this sub-command are:
Option |
Description |
---|---|
-headers or -noheaders |
Controls whether or not a heading is displayed. The -headers option is the default. |
-output=file_spec |
Causes the output to be written to a file. Any existing file with the same name as the output file is overwritten. |
Displays the current time and date in RFC 822, 1123 format.
Available for both interactive and non-interactive modes.
date |
Deletes the specified messages displayed in the most recently generated message queue listing.
delete [-channel=name [-all]] [-confirm | -noconfirm] [-log | -nolog] [id...] |
The id parameter specifies the messages to be deleted.
See imsimta qm Options for information on using the -channel, -all, -confirm, and -log options.
Available only in interactive mode.
Generates a listing of queued message files. By default, the imta/queue directory tree is used as the source of queued message information; this default may be changed with the view sub-command. The -database and -directory_tree options may be used to override the default.
Available for both interactive and non-interactive modes.
directory [-held | -noheld] [-database] [-directory_tree] [-envelope] [-owner=username] [-from=address] [-to=address] [-match=bool] [-file_info | -nofile_info] [-total | -nototal] [channel-name] |
The options for this sub-command are:
Option |
Description |
---|---|
-database |
Obtains message information from the Job Controller. |
-directory_tree |
Selects the on-disk directory tree as the source of message information. |
-envelope |
Generates a listing which also contains envelope address information. |
-total | -nototal |
Generates size and count totals across all selected channels. |
-owner=username |
Lists only those messages owned by a particular user. Messages enqueued by a local user will be owned by that user; most other messages will be owned by mailsrv. Use of the -owner option implies -database. |
-from=address and -to=address and -match=bool |
Lists only those messages with envelope From: or To: addresses matching the specified address. When both -from and -to are specified, a message is listed if either its envelope From: or To: addresses match the specified addresses. This corresponds to the -match=or option. Specify -match=and to list only messages matching both the specified From: and To: addresses. Use of -from or -to implies -envelope. address can include a wild card (*) that matches a sequence of characters or a % character that matches a single character. |
-held | -noheld |
By default, active messages are listed. Specify -held to instead list messages which have been marked as held. Note that -held implies -directory_tree. |
-file_info | -nofile_info |
When the directory tree is scanned, each message file is accessed to determine its size as measured in units of blocks (normally 1024 bytes). To suppress this behavior and speed up generation of the listing, specify -nofile_info. When the queue cache database is used, the -nofile_info option is ignored as the size information is stored in the database. |
channel-name |
Restricts the listing to one or more channels. If the channel-name parameter is omitted, a listing is made for all channels. The channel name parameter may contain the * and ? wildcard characters. |
Exits the imsimta qm utility. Synonymous with the quit sub-command.
Available for both interactive and non-interactive modes.
exit |
Generates a listing of message files which have been marked as held. This listing is always generated from the imta/queue/ directory tree.
Available for both interactive and non-interactive modes.
held [-envelope] [-file_info | -nofile_info] [-total | -nototal] [-from=address] [-to=address] [-match=bool] [channel-name] |
The options for this sub-command are:
Option |
Description |
---|---|
-envelope |
Generates a listing which also contains envelope address information. |
-total | -nototal |
Generate size and count totals across all selected channels. |
-from=address and -to=address and -match=bool |
Lists only those messages with envelope From: or To: addresses matching the specified address. When both -from and -to are specified, a message is listed if either its envelope From: or To: addresses match the specified addresses. This corresponds to the -match=or option. Specify -match=and to list only messages matching both the specified From: and To: addresses. Use of -from or -to implies -envelope. |
-file_info | -nofile_info |
When the directory tree is scanned, each message file is opened to determine its size as measured in units of blocks (normally 1024 bytes). To suppress this behavior and speed up generation of the listing, specify -nofile_info. |
channel-name |
Restricts the listing to one or more channels. If the channel-name parameter is omitted, a listing is made for all channels. The channel-name parameter may contain the * and ? wildcard characters. |
Displays any delivery history information for the specified messages from the most recently generated message queue listing.
Available only in interactive mode.
history [-channel=name [-all] ] [-confirm | -noconfirm] [id...] |
Use the id parameter to specify the messages whose history is displayed.
See imsimta qm Options for information on using the -channel, -all, and -confirm options.
Marks as held the specified messages from the most recently generated message queue listing
Available only in interactive mode.
hold [-channel=name [-all]] [-confirm | -noconfirm] [-log | -nolog] [id...] |
Use the id parameter to specify the messages to mark as held.
See imsimta qm Options for information on the -channel, -all, -confirm, and -log options.
The imsimta qm messages utility displays the number of messages queued for the channel given. Separate counts are given for messages that are ready to be processes (or are being processed) and those messages that have been tried and are awaiting their retry backoff. For channels where the destination host is significant, in particular the tcp_* channels, the messages are displayed by destination host.
messageschannel |
Example:
imsimta qm messages tcp_local
host active messages delayed messages
siroe.com 32 47
west.siroe.com 0 3
Exits the imsimta qm utility. Synonymous with the exit sub-command.
Available in both interactive and non-interactive modes.
quit |
Displays the specified messages from the most recently generated message queue listing.
Available only in interactive mode.
read [-content | -nocontent ] [-channel=name [-all]] [-confirm | -noconfirm] [id...] |
The options for this sub-command are:
Option |
Description |
---|---|
-content | -nocontent |
Displays (-content) or suppresses display (-nocontent) of message content along with the envelope and header information. -nocontent is the default. |
id |
Specifies the messages to display. |
See imsimta qm Options for information on using the -channel, -all, and -confirm options.
If the specified message file is marked as held, it is renamed to remove the hold mark. The Job Controller, if running, is informed that the message is to be processed immediately, ahead of all other messages.
Available only in interactive mode.
release [-channel=name [-all]] [-confirm | -noconfirm] [-log | -nolog] [id...] |
Use the id parameter to specify the messages to release from .HELD status.
See imsimta qm Options for information on using the -channel, -all, -confirm, and -log options.
Returns as undelivered the specified messages shown in the most recently generated message queue listing.
Available only in interactive mode.
return [-channel=name [-all]] [-confirm | -noconfirm] [-log | -nolog] [id...] |
Use the id parameter to specify the messages to return.
See imsimta qm Options for information on using the -channel, -all, -confirm, and -log options.
Processes, line-by-line, the commands specified in a file.
Available in both interactive and non-interactive modes.
run [-ignore | -noignore] [-log | -nolog]file-spec |
Specifically, file-spec is opened and each line from it is read and executed.
The options for this sub-command are:
Option |
Description |
---|---|
-ignore | -noignore |
Unless -ignore is specified, command execution will be aborted should one of the sub-commands generate an error. |
-log | -nolog |
By default, each command is echoed to the terminal before being executed (the -log option). Specify -nolog to suppress this echo. |
Restart processing of messages enqueued for the specified channel. The Job Controller not only marks the channel as “okay” to process, but it additionally starts processing jobs for the channel. This command takes effect whether the Job Controller is running or not.
startchannel |
The channel parameter specifies the channel to restart.
Stops processing of messages enqueued for the specified channel. This command prevents you from having to stop the Job Controller and recompiling the configuration. The channel does not process messages until a start command is issued for that channel. This state persists across restarts of the Job Controller, the Messaging Server, and the host computer itself. This command takes effect whether the Job Controller is running or not.
stop channel |
The channel parameter specifies the channel to stop.
The summarize sub-command displays a summary listing of message files.
summarize [-database | -directory_tree] [-heading | -noheading] [-held | -noheld] [-trailing | -notrailing] |
This is a potentially expensive command if you have a large backlog of messages. Instead of running this command frequently, consider using the imsimta qm messages command.
The options for this sub-command are:
Option |
Description |
---|---|
-database | -directory_tree |
Controls whether the information presented is obtained from the Job Controller (-database) or by looking at the actual directory tree containing the channel queues (-directory_tree). When neither -database nor -directory_tree is specified, then the “view” selected with the view sub-command will be used. If no view sub-command has been issued, then -directory_tree is assumed. |
-heading | -noheading |
Controls whether or not a heading line describing each column of output is displayed at the start of the summary listing. The -heading option is the default. |
-held | -noheld |
Controls whether or not to include counts of .HELD messages in the output. The -noheld option is the default. |
-trailing | -notrailing |
Controls whether or not a trailing line with totals is displayed at the end of the summary. The -trailing option is the default. |
The top sub-command displays the most frequently occurring envelope From:, Subject:, or message content fields found in message files in the channel queues. When used in conjunction with the clean sub-command, top may be used to locate unsolicited bulk email in the query and hold or delete it.
top [-content[=range]] [-from[=range]] [-subject[=range]] [-to[=range]] [-database | -directory_tree] [-domain_to[=range]] [-held] [-ignore_zz] [-min_count=n] [-threads=n | -nothreads] [-top=n] [-verbose | -noverbose] [channel] |
The options for this sub-command are:
Option |
Description |
---|---|
-content[=range] -from[=range] -subject[=range] -to[=range] -domain_to[=range] |
The -content, -from, -subject, and -to options are used to specify which frequently occurring fields should be displayed. By default, only Subject: fields are shown (-subject). Use -from to display frequent envelope From: fields, -to to display frequent envelope To: fields, or -content to display frequent message contents. Use -domain_to to display frequently occurring envelope To: addresses. Identical to -to option, except -domain_to looks at only the host.domain portion of the envelope To: address. Any combination of -content, -from, -to, -domain_to, and -subject may be specified. However, only one of each may be used. The -content, -from, -to, -domain_to, and -subject options accept the optional parameters START=n and LENGTH=n. These parameters indicate the starting position and number of bytes in the field to consider. The defaults are -content=(START=1,LENGTH=256), -from=(START=1,LENGTH=2147483647), -to=(START=1,LENGTH=2147483647), -subject=(START=1,LENGTH=2147483647), and -domain_to=(START=1,LENGTH=214783647). Use of these parameters is useful when, for example, trying to identify occurrences of a spam message which uses random text at the start of the Subject: line. |
-database | -directory_tree |
Controls whether the message files scanned are only those with entries in the queue cache database (-database) or all message files actually present in the channel queue directory tree (-directory_tree). When neither -database nor -directory_tree is specified, then the “view” selected with the view sub-command will be used. If no view sub-command has been issued, then -directory_tree is assumed. |
-held |
Lists only the files which have a .HELD extension. |
-ignore_zz |
Ignores queued message files with file names beginning with “ZZ”. This option may be used to scan only those message files which represent queued messages which have failed at least one delivery attempt. |
-min_count=n |
Changes the minimum number of times that a string must occur in order to be displayed. The default is -min_count=2. |
-threads=n | -nothreads |
Accelerates searching on multiprocessor systems by dividing the work amongst multiple, simultaneously running threads. To run n simultaneous searching threads, specify -threads=n. The value n must be an integer between 1 and 8. The default is -nothreads. |
-top=n |
Changes the amount of most frequently occurring fields that are displayed. The default is -top=20. |
-verbose | -noverbose |
Requests that the utility displays operation information (-verbose). The default is -noverbose. |
channel |
Specifies an MTA channel area to be scanned for string frequencies. The * or? wildcard characters may be used in the channel specification. |
Specifies the source of queued message information for subsequent directory commands.
Available only in interactive mode.
view -database | -directory_tree |
By default, queued message listings are generated by scanning the imta/queue/ directory tree. This corresponds to the -directory_tree option. You can, alternatively, generate the listings from the MTA queue cache database by issuing the -database option.
Settings made with the view sub-command remain the default until either another view command is issued or the utility exits. The default may be overridden with the -database or -directory_tree options of the directory command.
Note that the directory tree is always used when listing held message files.
The delete, history, hold, read, release, and return sub-commands all support the following options and parameter:
Option |
Description |
---|---|
-channel=name |
Operates on the specified channel. |
-all |
The -all option may be used to operate on all of the previously listed messages. When used in conjunction with the -channel option, only those previously listed messages for the specified channel are operated on. The -all option may not be used in conjunction with an id parameter. However, -all or at least one id parameter must be specified. |
-confirm and -noconfirm |
When the id parameter is not used to explicitly select messages, you will be prompted to confirm the operation. This prevents accidental delete -all sub-commands from being executed. You can use the -noconfirm option to suppress this prompt. Similarly, -confirm causes a confirmation prompt to be required. |
-log and -nolog |
Controls whether or not the operation on each selected message is reported. |
id |
The identification number of a message shown in the most recent listing generated by either the directory or the held sub-command. The identification number for a message is the integer value displayed in the left-most column of the listing. The id can also be a range or comma-separated list. |
These options identify the messages to which the command is applied. When none of the options are specified, at least one id parameter must be supplied.
For example, in the following listing the first message displayed has an identification number of 1 and the second 2:
qm.maint> directory tcp_local Channel: tcp_local Size Queued since -------------------------------------------------------------- 1 XS01IVX1T0QZ18984YIW.00 24 16-APR-1998 00:30:30.07 2 YH01IW2MZLN0RE984VUK.00 24 20-APR-1998 00:30:40.31 |
These two messages can therefore be selected by either “1,2” or “1-2”.
The following example generates a list of queued messages:
imsimta qm directory Wed, 24 Feb 1999 14:20:29 -0800 (PST) Data gathered from the queue directory tree Channel: sims-ms Size Queued since -------------------------------------------------------------- 1 ZZ0F7O00I03CJHZD.00 1 24-Feb-1999 11:52:29 2 ZZ0F7O00I03CILY6.00 1 24-Feb-1999 11:51:57 -------------------------------------------------------------- Total size: 2 Grand total size: 2 |
In the following interactive session, the directory sub-command is used to obtain a list of queued messages. The delete sub-command is then used to delete the first of the displayed messages. Finally, another directory sub-command is issued that displays that the deleted message is indeed gone.
imsimta qm qm.maint> directory Thu, 25 Feb 1999 11:37:00 -0800 (PST) Data gathered from the queue directory tree Channel: sims-ms Size Queued since -------------------------------------------------------------- 1 ZZ0F7O00I03CJHZD.00 1 24-Feb-1999 11:52:29 2 ZZ0F7O00I03CILY6.00 1 24-Feb-1999 11:51:57 -------------------------------------------------------------- Total size: 2 Grand total size: 2 qm.maint> delete 1 %QM-I-DELETED, deleted the message file msg-tango/imta/queue/sims-ms/013/ZZ0F7O00I03CJHZD.00 qm.maint> directory Thu, 25 Feb 1999 11:37:09 -0800 (PST) Data gathered from the queue directory tree Channel: sims-ms Size Queued since -------------------------------------------------------------- 1 ZZ0F7O00I03CILY6.00 1 24-Feb-1999 11:51:57 -------------------------------------------------------------- Total size: 1 Grand total size: |
The imsimta qtop utility displays the most frequently occurring envelope From:, To:, Subject:, or message content fields found in message files in the channel queues.
imsimta qtop [-content[=range]] [-from[=range]] [-subject[=range]] [-to[=range]] [-domain_to[=range]] [-database | -directory_tree] [-ignore_zz] [-min_count=n] [-threads=n | -nothreads] [-top=n] [-verbose | -noverbose] [channel] |
The options for this command are:
Option |
Description |
---|---|
-content[=range] -from[=range] -subject[=range] -to[=range] -domain_to[=range] |
Specifies which frequently occurring fields should be displayed. By default, only Subject: fields are shown (-subject). Specify -from to display frequent envelope From: fields, -to to display frequent envelope To: fields, or -content to display frequent message contents. Specify -domain_to to display frequently occurring envelope To: fields. Identical to -to option, except -domain_to looks at only the host.domain portion of the envelope To: address. Any combination may be specified. However, only one of each my be used. These options accept the START=n and LENGTH=n arguments. These arguments indicate the starting offset and number of bytes in the field to consider. The defaults are -content=(START=1,LENGTH=256), -from=(START=1,LENGTH=2147483647), -subject=(START=1,LENGTH=2147483647), and -domain_to=(START=1,LENGTH=2147483647). |
-database |
Specifies that only message files identified by the queue cache database is searched. |
-directory_tree |
Searches all message files actually present in the channel queue directory tree. |
-ignore_zz |
Ignores queued message files with file name beginning with “ZZ”. This option may be used to scan only those message files which represent queued messages which have failed at least one delivery attempt. For example, the following command indicates to which domains the MTA has problems delivering messages: imsimta qtop -ignore_zz -domain_to |
-min_count=n |
Changes the minimum number of times that a string must occur in order to be displayed. The default is -min_count=2. |
-threads=n | -nothreads |
Accelerates searching on multiprocessor systems by dividing the work amongst multiple, simultaneously running threads. To run n simultaneous searching threads, specify -threads=n. The value n must be an integer between 1 and 8. The default is -nothreads. |
-top=n |
Changes the amount of most frequently occurring fields that are displayed. The default is -top=20. |
-verbose | -noverbose |
Requests that the utility displays operation information (-verbose). The default is -noverbose |
channel |
Specifies a channel area to be scanned for string frequencies. The * and ? wildcard characters may be used in the channel specification. |
The imsimta refresh utility performs the following functions:
Recompiles the MTA configuration files.
Stops any MTA Job Controller or MTA Service Dispatcher jobs that are currently running.
Restarts the Job Controller and MTA Service Dispatcher.
Essentially, imsimta refresh combines the function of imsimta cnbuild and imsimta restart.
You must be logged in as root to run imsimta refresh.
imsimta refresh [job_controller | dispatcher] |
The options for this command are:
Option |
Description |
---|---|
job_controller |
Restarts the Job Controller. |
dispatcher |
Restarts the MTA Service Dispatcher. |
If no component name is specified, all active components are restarted.
Some parts of the MTA configuration can be changed and have these changes activated without having to stop and start the system. The reloadable parts of the configuration are:
mappings
aliases
general, forward and reverse lookup tables
These can be changed, compiled, and the changes activated by issuing the commands:
imsimta cnbuild
imsimta reload
The imsimta reload command informs the dispatcher and job controller of the change, and they in turn inform the processes they started.
imsimta reload |
The imsimta renamedb command renames an MTA database. Since the MTA may optionally reference several “live” databases, that is, databases whose presence triggers their use by the MTA, it is important, first, to ensure that the MTA does not see such a database while it is in a mixed state, and second, to minimize any period of time during which the database is inaccessible. The imsimta crdb command locks the database it is creating to avoid having it accessed in a mixed state.
It is therefore recommended that the MTA databases be created or updated in a two-step process:
Create or update a temporary database.
Rename the temporary database to the “live” name using the imsimta renamedb command.
The imsimta renamedb command, which must delete any old database files and rename the new database files, locks the database during the renaming process to avoid presenting the database in a mixed state. In this way the database is never accessible while it is in a mixed state, yet any window of time during which the database is inaccessible is minimized. Renaming is generally quicker than database generation.
imsimta renamedb old-database-spec new-database-spec |
The parameters for this command are:
Parameter |
Description |
---|---|
old-database-spec |
The name of the database that is being renamed. |
new-database-spec |
The new name of the database. This may either be an actual pathname, or one of the special names such as IMTA_ALIAS_DATABASE, IMTA_REVERSE_DATABASE, IMTA_GENERAL_DATABASE, or IMTA_DOMAIN_DATABASE, listed in the MTA tailor file and pointing to actual pathnames. |
The following command renames the database tmpdb to be the actual MTA alias database (usually msg_svr_base/data/db/aliasesdb).
imsimta renamedb tmpdb IMTA_ALIAS_DATABASE |
The imsimta restart command stops and restarts the Job Controller and Service Dispatcher. This causes all MTA master and slave programs to be restarted. It can also restart SMTP, LMTP, and SMTP_SUBMIT.
Detached MTA processes should be restarted whenever the MTA configuration is altered—these processes load information from the configuration only once and need to be restarted in order for configuration changes to become visible to them. In addition to general MTA configuration files, such as the imta.cnf file, some components, such as the MTA Service Dispatcher, have their own specific configuration files, for example, dispatcher.cnf, and should be restarted after changes to any of these files.
You must be logged in as root to use this utility.
imsimta restart [job_controller |dispatcher|smtp|lmtp|smtp_submit] |
Restarting the MTA Service Dispatcher effectively restarts all the service components it handles. If no component name is given, all active components are restarted.
To restart the MTA Job Controller and channel master programs:
imsimta restart job_controller |
The imsimta return command returns a message to the message's originator. The returned message a single multipart message with two parts. The first part explains the reason why the message is being returned. The text of the reason is contained in the file return_bounce.txt located in the msg_svr_base/config/locale/C/LC_MESSAGES directory. The second part of the returned message contains the original message.
imsimta return message-file |
message-file is the name of the message file to return. The name may include wildcards, but if so, the specification must be quoted.
The following command causes the specified the message to be returned to its originators.
imsimta return /imta/queue/l/ZZ0FRW00A03G2EUS.00 |
The imsimta run command processes the messages in the channel specified by the channel parameter. Output during processing is displayed at your terminal, which makes your terminal unavailable for the duration of the operation of the utility. Refer also to the imsimta submit command which, unlike imsimta run, does not monopolize your terminal.
Note that a channel delivery program that is run using this command, unlike the imsimta submit command, attempts to deliver messages before any pending backoff delay has expired.
imsimta run channel |
The parameter for this command is:
Parameter |
Description |
---|---|
channel |
Specifies the channel to be processed. This parameter is mandatory. |
Type the following command to process any messages in the tcp_local channel:
imsimta run tcp_local |
The imsimta shutdown command shuts down the MTA Job Controller and the MTA Dispatcher. Shutting down the MTA Dispatcher shuts down all services (for example, SMTP) being handled by the Dispatcher. It can also be used to stop the SMTP, LMTP, SMTP_SUBMIT servers. Note that you can only restart a Dispatcher service that is currently running. If you do imsimta shutdown smtp, you must restart the Dispatcher to start the SMTP service again.
You must be logged in as root to use this utility.
imsimta shutdown [dispatcher|job_controller|smtp|smtp_submit|lmtp] |
Use the following command to shut down the MTA jobs:
imsimta shutdown |
The imsimta start command starts up detached MTA processes. If no component parameter is specified, then the MTA Job Controller and MTA Service Dispatcher are started. Starting the Service Dispatcher starts all services the Service Dispatcher is configured to handle, which usually includes the SMTP server.
The services handled by the MTA Service Dispatcher must be started by starting the MTA Service Dispatcher. Only services not being handled by the MTA Service Dispatcher can be individually started via the imsimta start command. The Service Dispatcher may be configured to handle various services, for example, the multithreaded SMTP server.
You must be logged in as root to use this utility.
imsimta start [component] |
If a component parameter is specified, then only detached processes associated with that component are started. The standard component names are:
dispatcher—Multithreaded Service Dispatcher.
job_controller—Schedules deliveries (dequeues messages).
Use the following command to start the MTA Job Controller and MTA Service Dispatcher:
imsimta start |
The imsimta stop command shuts down the MTA Job Controller and the MTA Dispatcher. Shutting down the MTA Dispatcher shuts down all services (for example, SMTP) being handled by the Dispatcher. It can also be used to stop the SMTP, LMTP, SMTP_SUBMIT servers. Note that you can only restart a Dispatcher service that is currently running. If you do imsimta shutdown smtp, you must restart the Dispatcher to start the SMTP service again.
You must be logged in as root to use this utility.
imsimta stop [dispatcher|job_controller|smtp|smtp_submit|lmtp] |
Use the following command to shut down the MTA jobs:
imsimta stop |
The imsimta submit command directs the Job Controller to fork a process to execute the messages queued to the channel specified by the channel parameter.
imsimta submit [channel] [poll] |
The parameters for this command are:
Parameter |
Description |
---|---|
channel |
Specifies the channel to be processed. The default, if this parameter is not specified, is the local channel 1. |
poll |
If poll is specified, the channel program runs even if there are no messages queued to the channel for processing. |
Use the following command to process any messages in the tcp_local channel:
imsimta submit tcp_local |
The imsimta test utilities perform tests on various areas of functionality of the MTA.
imsimta test -mapping tests the behavior of a mapping table in the mapping file. The result of mapping an input string will be output along with information about any meta characters specified in the output string.
If an input string is supplied on the command line, then only the result of mapping that input string will be output. If no input string is specified, imsimta test -mapping will enter a loop, prompting for an input string, mapping that string, and prompting again for another input string. imsimta test -mapping will exit when a CTRL-D is entered.
imsimta test -match tests a mapping pattern in order to test wildcard and global matching.
imsimta test -match prompts for a pattern and then for a target string to compare against the pattern. The output indicates whether or not the target string matched. If a match was made, the characters in the target string that matched each wildcard of the pattern is displayed. The imsimta test -match utility loops, prompting for input until the utility is exited with a CTRL-D.
imsimta test -rewrite provides a test facility for examining the MTA's address rewriting and channel mapping process without actually sending a message. Various qualifiers can be used to control whether imsimta test -rewrite uses the configuration text files or the compiled configuration (if present), the amount of output produced, and so on.
If a test address is specified on the command line, imsimta test -rewrite applies the MTA address rewriting to that address, reports the results, and exits. If no test address is specified, imsimta test -rewrite enters a loop, prompting for an address, rewriting it, and prompting again for another address. imsimta test -rewrite exits when CTRL-D is entered.
When testing an email address corresponding to a restricted distribution list, imsimta test -rewrite uses as the posting address the return address of the local postmaster, which is usually postmaster@localhost unless specified by the MTA option RETURN_ADDRESS in the MTA Option file.
imsimta test -url tests an LDAP queury URL. Note that the LDAP server to query is controlled by the setting of the MTA option LDAP_SERVER in local.conf.
imsimta test -rewrite [-alias_file=filename] [-channel | -nochannel [-check_expansions | -nocheck_expansions] [-configuration_file=filename ] [-database=database_list] [-debug | -nodebug] [-delivery_receipt | -nodelivery_receipt] [-destination_channel=channel] [-filter | -nofilter] [-from=address | -nofrom] [-image_file=filename | -noimage_file] [-input=input-file] [-local_alias=value | -nolocal_alias] [-mapping_file=file | -nomapping_file] [-option_file=filename | -nooption_file] [-output=output-file] [-read_receipt | -noread_receipt] [-restricted=setting] [-sender=from_address] [-source_channel=channel] [-noreprocess] |
imsimta test -mapping [input_string] [-debug | -nodebug] [-flags=chars | -noflags] [-image_file=filename | -noimage_file] [-mapping_file=filename] [-option_file=filename | -nooption_file] [-table=table-name] [address] |
imsimta test -match |
imsimta test -url [-debug | -nodebug] [ldap_url] |
imsimta test -message=message-file -exp -mm [-block] [-input=input-file] [-output=output-file] |
The options for this command are:
This example shows typical output generated by imsimta test -rewrite. The most important piece of information generated by imsimta test -rewrite is displayed on the last few lines of the output, which shows the channel to which imsimta test -rewrite would submit a message with the specified test address and the form in which the test address would be rewritten for that channel. This output is invaluable when debugging configuration problems.
imsimta test -rewrite Address: joe.blue channel = l channel description = channel description = channel flags #1 = BIDIRECTIONAL MULTIPLE IMMNONURGENT NOSERVICEALL channel flags #2 = NOSMTP POSTHEADBODY HEADERINC NOEXPROUTE channel flags #3 = LOGGING NOGREY NORESTRICTED channel flags #4 = EIGHTNEGOTIATE NOHEADERTRIM NOHEADERREAD RULES channel flags #5 = channel flags #6 = LOCALUSER NOX_ENV_TO RECEIPTHEADER channel flags #7 = ALLOWSWITCHCHANNEL NOREMOTEHOST DATEFOUR DAYOFWEEK channel flags #8 = NODEFRAGMENT EXQUOTA REVERSE NOCONVERT_OCTET_STREAM channel flags #9 = NOTHURMAN INTERPRETENCODING text/plain charset def = (7) US-ASCII 5 (8) ISO-8859-1 51 channel envelope address type = SOURCEROUTE channel header address type = SOURCEROUTE channel official host = mailserver.eng.alpha.com channel local alias = channel queue name = channel after param = channel daemon name = channel user name = notices = channel group ids = header To: address = joe.blue@mailserver.eng.alpha.com header From: address = joe.blue@mailserver.eng.alpha.com envelope To: address = joe.blue@mailserver.eng.alpha.com (route (mailserver.eng.alpha.com,mailserver.eng.alpha.com)) envelope From: address = joe.blue@mailserver.eng.alpha.com name = mbox = joe.blue Extracted address action list: joe.blue@mailserver.eng.alpha.com Extracted 733 address action list: joe.blue@mailserver.eng.alpha.com Expanded address: joe.blue@mailserver.eng.alpha.com Submitted address list: ims-ms joe.blue@ims-ms-daemon (sims-ms-daemon) *NOTIFY FAILURES* *NOTIFY DELAYS* Submitted notifications list: Address: # |
In the following example, the sample PAGER mapping is tested. The -mapping_file option is used to select the mapping file pager_table.sample instead of the default mapping file.
imsimta test -mapping -noimage_file \ -mapping_file=msg_svr_base/config/pager_table.sample |
In the following example, the sample mapping pattern $[ax1]*@*.xyz.com is tested for several sample target strings:
imsimta test -match Pattern: $[ax1]*@*.xyz.com [ 1S] cglob [1ax] [ 2] "@" [ 3S] glob, req 46, reps 2 [ 4] "." [ 5] "x" [ 6] "y" [ 7] "z" [ 8] "." [ 9] "c" [ 10] "o" [ 11] "m" Target: xx11aa@sys1.xyz.com Match. 0 - xx11aa 1 - sys1 Pattern: $[ax1]*@*.xyz.com Target: 12a@node.xyz.com No match. Pattern: $[ax1]*@*.xyz.com Target: 1xa@node.acme.com Match. 0 - 1xa 1 - node Pattern: ^D % |
The imsimta version command prints out the MTA version number, and displays the system's name, operating system release number and version, and hardware type.
imsimta version |
To check the version of MTA you are running, execute the following command:
% imsimta version
The imsimta view utility displays log files.
imsimta view file-pattern [-f offset-from-first] [-l offset-from-last] |
The options for this command are:
Option |
Description |
---|---|
-f=offset-from-first |
Displays the specified version of the log file (starting from 0). For example, to find the earliest (oldest) version of the file, specify -f=0. By default, imsimta view finds the most recent version of the log file. |
-l=offset-from-last |
Displays the last version of the specified file. For example, to display the most recent (newest) version of the file, specify -l=0. By default, imsimta view finds the most recent version of the file. |
file-pattern |
Specifies a filename pattern to view. |