Chapter 2
Message Transfer Agent Command-line Utilities
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 server_root/msg-instance/ directory.
server-root represents the directory path in which you install the server, and the variable instance in msg-instance represents the server instance you use when you install it (or your host machine name).
The commands are listed in Table 2-1.
Table 2-1 MTA Commands
|
Command
|
Description
|
|
imsimta cache
|
Performs operations on the queue cache.
|
|
imsimta chbuild
|
Compiles the MTA character set conversion tables.
|
|
imsimta cnbuild
|
Compiles the MTA configuration files.
|
|
imsimta convertdb
|
Reads the entries in an MTA with version 5.2 or earlier crdb database and writes out the entries to a current format MTA crdb database.
|
|
imsimta counters
|
Performs operations on the channel counters.
|
|
imsimta crdb
|
Creates an MTA database.
|
|
imsimta dirsync
|
Recreates or updates the MTA directory cache.
|
|
imsimta find
|
Locates the precise filename of the specified version of an MTA log file
|
|
imsimta kill
|
Terminates the specified process.
|
|
imsimta process
|
Lists currently running MTA jobs.
|
|
imsimta process_held
|
Processes the messages stored in the hold queue channel.
|
|
imsimta program
|
Manipulates the MTA program delivery options.
|
|
imsimta purge
|
Purges MTA log files.
|
|
imsimta qclean
|
Holds or deletes message files containing specific substrings in their envelope From:address, Subject: line, or content.
|
|
imsimta qm
|
Manages MTA message queues.
|
|
imsimta qtop
|
Displays the most frequently occurring envelope From: Subject:, or message content fields found in message files in the channel queues.
|
|
imsimta recover-crash
|
Removes corrupted databases and restores them from the backup.
|
|
imsimta refresh
|
Combines the functionality of the imsimta cnbuild and imsimta restart utilities.
|
|
imsimta renamedb
|
Renames a MTA database.
|
|
imsimta restart
|
Restarts detached MTA processes.
|
|
imsimta return
|
Returns (bounces) a mail message to its originator.
|
|
imsimta run
|
Processes messages in a specified channel.
|
|
imsimta start
|
Starts the MTA Job Controller and Dispatcher.
|
|
imsimta stop
|
Shuts down the MTA Job Controller and the MTA Dispatcher.
|
|
imsimta submit
|
Processes messages in a specified channel.
|
|
imsimta test
|
Performs tests on mapping tables, wildcard patterns, address rewriting, and URLs.
|
|
imsimta version
|
Prints the MTA version number.
|
|
imsimta view
|
Displays log files.
|
|
configutil
|
Enables you to list and change Messaging Server configuration parameters, including some MTA configuration parameters. See "configutil" for full syntax and description of configutil.
|
Command Descriptions
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).
imsimta cache
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.
Syntax
|
imsimta cache -sync | -view [channel]
|
|
Options
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 /server_root/msg-instance/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
|
Examples
To synchronize the queue cache:
To view entries in the queue cache for the tcp_local channel, execute the command:
|
imsimta cache -view tcp_local
|
|
imsimta chbuild
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.
Syntax
|
imsimta chbuild [-image_file=file_spec | -noimage_file]
[-maximum | -nomaximum]
[-option_file=[option_file] | -nooption_file] [-remove]
[-sizes |-nosizes] [-statistics | -nostatistics]
|
|
Options
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-instance/imta/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-instance/imta/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-instance/imta/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-instance/imta/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-instance/imta/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.
|
Example
The standard command you use to compile character set conversion tables is:
imsimta cnbuild
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 msg-instance/imta/lib/config_data by the IMTA_CONFIG_DATA option of the MTA tailor file, msg-instance/imta/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, IMTA_CONVERSION_FILE, and IMTA_SECURITY_CONFIG_FILE respectively, which usually point to the following files:
msg-instance/imta/config/imta.cnf
msg-instance/imta/config/aliases
msg-instance/imta/config/mappings
msg-instance/imta/config/option.dat
msg-instance/imta/config/conversions
msg-instance/imta/config/security.cnf
|
Note
|
Until the configuration is rebuilt, changes to any of these files are not visible to the running MTA system.
|
Syntax
|
imsimta cnbuild [-image_file=file_spec | -noimage_file]
[-maximum | -nomaximum]
[-option_file=[option_file] | -nooption_file] [-remove]
[-sizes | -nosizes] [-statistics | -nostatistics]
|
|
Options
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-instance/imta/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-instance/imta/config/maximum.dat is read in addition to the file named by the IMTA_OPTION_FILE option in the MTA tailor file, msg-instance/imta/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-instance/imta/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-instance/imta/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-instance/imta/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-instance/imta/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.
|
Examples
To regenerate a compiled configuration enter the following command:
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
|
|
|
Note
|
imsimta cnbuild is executed whenever the imsimta refresh command is invoked.
|
imsimta convertdb
The format of MTA databases has changed from PMDF or SIMS. The imsimta convertdb utility reads the entries from PMDF 6.0 or SIMS 4.0 databases and writes out the entries to an iPlanet Messang Server database.
The imsimta convertdb utility can also read an iPlanet Messang Server 5.0 or later database as input.
Syntax
|
imsimta convertdb input-database-spec output-database-spec
|
|
Parameters
The parameters for this command are:
|
Parameter
|
Description
|
|
input-database-spec
|
The name of the MTA database (usually one created while running an earlier version of a related MTA) from which to read entries.
|
|
output-database-spec
|
The name of the MTA version 5.0 or later MTA database to which to write the entries stored in the input MTA database. Special keywords such as IMTA_ALIAS_DATABASE, IMTA_REVERSE_DATABASE, IMTA_FORWARD_DATABASE, IMTA_GENERAL_DATABASE, IMTA_DOMAIN_DATABASE, and IMTA_PIPE_DATABASE are supported; the use of such a special keyword tells the MTA to write the database specified by the corresponding tailor file option.
|
Examples
The following example converts an MTA alias database to the most current format. The input database, for example, might be a SIMS 4.0 alias database that is being converted to an iPlanet Messang Server 5.2 format.
|
imsimta convertdb aliasesdb.dat IMTA_ALIAS_DATABASE
|
|
imsimta counters
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.
Syntax
|
imsimta counters -clear
|
imsimta counters -create [-max_channels=value]
|
imsimta counters -delete
|
imsimta counters -show [-associations | noassociations]
[-channels | -nochannels] [-headers | -noheaders]
[-output=file_spec] [-today | -notoday]
|
|
Options
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. Do not use this option if you already have in-memory counters. imsimta start creates the in-memory counters. Note that this option should never be used unless you have manually deleted the counters using the -delete option.
|
|
-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.
|
|
-today | -notoday
|
Specifies whether or not to show the MTA's count for the number of messages processed on this day. The -today option is the default. This option is only used with the -show option.
|
Examples
To display the counters for all channels:
imsimta crdb
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.
Syntax
|
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]
|
|
Options
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.
|
Example
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
|
|
imsimta crdb -dump
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.
|
Note
|
Make sure you are logged in as mailsrv (the mail server user) before performing this command.
|
Syntax
|
imsimta crdb -dump input-database-spec [output-file-spec]
|
|
Parameters
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.
|
Examples
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
|
|
imsimta dirsync
The imsimta dirsync utility recreates or updates the MTA directory cache.
This utility is normally run by the Job Controller so there should not be a need to run it manually. imta dirsync needs to run any time directory data that affects message delivery changes.
In order to perform imsimta dirsync, the stored utility must be running. Thus, if the administrator wishes to run imsimta dirsync without starting up all the services, the stored service should be started up before running imsimta dirsync.
|
Note
|
You must be logged in as root in order to run imsimta dirsync.
|
|
Note
|
This command is not needed if the MTA is running in direct LDAP mode.
|
Syntax
|
imsimta dirsync [-l localhost1, localhost2,...] [-F] [-L] [-i ldap_filter]
[-t] [-s] [-v] [-V]
|
|
Options
The options for this command are:
|
Option
|
Description
|
|
-F
|
Performs a full synchronization. By default, the imsimta dirsync command performs an incremental synchronization of the directory cache, which means that only entries that have been added or modified in the directory since the last synchronization are updated. The -F option causes the directory cache to be completely regenerated, thus creating a faithful image of the directory. The SMTP services are restarted after a full synchronization.
|
|
-i ldap_filter
|
Uses the specified filter, instead of the default filter, which is, any entry that has a modifytimestamp or createtimestamp later than the previous dirsync's timestamp.
|
|
-t
|
Execute imsimta dirsync in the test mode. Searches the directory and prints out the details on invalid entries, if there are any. No changes are made to the cache itself. For details on all entries, test also in verbose mode (run both the -t and -v options).
|
|
-s
|
Registers a persistent search with the directory server and performs immediate database updates. This removes the need to run incremental dirsync.
|
|
-v
|
Runs this command in verbose mode. A trace file is created in the log directory.
|
|
-V
|
Prints a summary line that displays the number of entries added to alias and reverse databases.
|
Example
To perform a full directory cache synchronization, execute the following command:
imsimta find
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.
Syntax
|
imsimta find file-pattern [-f=offset-from-first] [-l=offset-from-last]
|
|
Options
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.
|
Examples
The following command prints out the filename of the tcp_local_slave.log-uniqueid file most recently created:
|
imsimta find server_root/msg-instance/imsimta/log/tcp_local_slave.log
|
|
The following command displays the filename of the oldest tcp_bitnet_master.log-uniqueid file:
|
imsimta find \
server_root/msg-instance/imsimta/log/tcp_bitnet_master.log -f=0
|
|
imsimta kill
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.
Syntax
|
Note
|
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.
imsimta process
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.
Syntax
Example
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
/export/ims/bin/msg/imta/bin/dispatcher
mailsrv 15337 S 21088 10968 17:32:45 0:01
/export/ims/bin/msg/imta/bin/tcp_smtp_server
mailsrv 15338 S 21080 11064 17:32:45 0:01
/export/ims/bin/msg/imta/bin/tcp_smtp_server
mailsrv 15349 S 21176 10224 17:33:02 0:02
/export/ims/bin/msg/imta/bin/job_controller
|
|
imsimta process_held
The imsimta process_held command processes the messages stored in the hold queue channel. It then attempts to deliver the messages.
Messages become queued to the hold channel when the delivery option for a user is set to "hold." Messages are not delivered until the user's delivery option is changed and the imsimta proces_held command is run.
Syntax
|
imsimta process_held -uid=xxx -domain=yyy [-new_uid=zzz]
[-new_domain=aaa] [-verbose]
|
|
Options
The options for this command are:
|
Option
|
Description
|
|
-uid=xxx
|
Specifies the mail user id of the held messages. If uid is not specified, all messages addressed to users belonging to domain are processed.
|
|
-domain=yyy
|
Specifies the mail user's mail domain to which the moving user or users belong. If not specified, only messages addressed to users belonging to the MTA canonical domain can be processed.
|
|
-new_uid=zzz
|
Specifies the new user id if the move includes renaming the user id.
|
|
-new_domain=aaa
|
Specifies the new domain name if the move includes renaming the domain.
|
|
-verbose
|
Requests that the utility displays operation information.
|
imsimta program
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 iPlanet Messang Server, but could be whatever the specified user name for the Messaging Server is when iPlanet Messang Server is installed.
A change in an existing program delivery option will take effect only after the next full dirsync is performed.
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.
Syntax
|
imsimta program -a -m method -p program [-g argument_list]
[-e exec_permission]
|
imsimta program -d -m method
|
imsimta program -c -m method -p program | -g argument_list |
-e exec_permission
|
|
Options
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 (server-root/msg-instance/imta/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.
|
Examples
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
|
|
imsimta purge
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.
Syntax
|
imsimta purge [file-pattern] -day=dvalue -hour=hvalue -num=nvalue
|
|
Options
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 msg-instance/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.
|
Example
To purge all but the last five versions of each type of log file in the msg-instance/log/imta directory:
imsimta qclean
The imsimta qclean utility holds or deletes message files containing specific substrings in their envelope From:address, Subject: line, or content.
Syntax
|
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]
|
|
Options
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.
|
imsimta qm
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:
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" for descriptions of all available sub-commands. Each sub-command indicates the mode for which mode it is available.
Sub-Commands
clean
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.
|
|
-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.
|
counters clear
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.
counters create
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.
|
counters delete
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 show
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.
|
counters today
Displays the count of messages processed so far today.
Available for both interactive and non-interactive modes.
date
Displays the current time and date in RFC 822, 1123 format.
Available for both interactive and non-interactive modes.
delete
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.
directory
Generates a listing of queued message files. By default, the msg-instance/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.
|
|
-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.
|
exit
Exits the imsimta qm utility. Synonymous with the quit sub-command.
Available for both interactive and non-interactive modes.
held
Generates a listing of message files which have been marked as held. This listing is always generated from the msg-instance/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.
|
history
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.
hold
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.
quit
Exits the imsimta qm utility. Synonymous with the exit sub-command.
Available in both interactive and non-interactive modes.
read
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.
release
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.
return
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.
run
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.
|
start
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.
The channel parameter specifies the channel to restart.
stop
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.
The channel parameter specifies the channel to stop.
summarize
The summarize sub-command displays a summary listing of message files.
|
summarize [-database | -directory_tree] [-heading | -noheading]
[-held | -noheld] [-trailing | -notrailing]
|
|
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.
|
top
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]]
[-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.
|
|
-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.
|
view
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 msg-instance/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.
imsimta qm Options
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".
Examples
Non-Interactive Mode
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
|
|
Interactive Mode
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: 1
|
|
imsimta qtop
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.
Syntax
|
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]
|
|
Options
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.
|
imsimta recover-crash
The imsimta recover-crash utility removes the apparently corrupted databases and restores them from the backup, if available. An incremental dirsync will be run if the backup is available. If the back up is not available, then the administrator is advised to run a full dirsync.
|
Note
|
This command should not be run in direct LDAP mode.
|
Syntax
|
imsimta recover-crash [-i]
|
|
Option
This option for this command is:
|
Option
|
Description
|
|
-i
|
Run the incremental dirsync in the foreground. By default, the imsimta recover-crash utility runs an incremental dirsync in the background if backup is available. If the backup is not available and a full dirsync is needed. With this option, the administrator will be prompted and asked if a full dirsync should be run at that time. If the administrator answers yes (y), then a full dirsync is run. By default, a message is displayed advising the administrator to run a full dirsync in order to correct the problem.
|
imsimta refresh
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.
|
Note
|
You must be logged in as root to run imsimta refresh.
|
Syntax
|
imsimta refresh [job_controller | dispatcher]
|
|
Options
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.
imsimta renamedb
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.
Syntax
|
imsimta renamedb old-database-spec new-database-spec
|
|
Parameters
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.
|
Example
The following command renames the database tmpdb to be the actual MTA alias database (usually msg-instance/imta/db/aliasesdb).
|
imsimta renamedb tmpdb IMTA_ALIAS_DATABASE
|
|
imsimta restart
The imsimta restart command stops and restarts the Job Controller and Service Dispatcher. This causes all MTA master and slave programs to be restarted.
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.
|
Note
|
You must be logged in as root to use this utility.
|
Syntax
|
imsimta restart [job_controller | dispatcher]
|
|
Restarting the MTA Service Dispatcher effectively restarts all the service components it handles. If no component name is given, all active components are restarted.
Example
To restart the MTA Job Controller and channel master programs:
|
imsimta restart job_controller
|
|
imsimta return
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-instance/imta/config/locale/C/LC_MESSAGES directory. The second part of the returned message contains the original message.
Syntax
|
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.
Example
The following command causes the specified the message to be returned to its originators.
|
imsimta return /imta/queue/l/ZZ0FRW00A03G2EUS.00
|
|
imsimta run
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.
Syntax
Parameters
The parameter for this command is:
|
Parameter
|
Description
|
|
channel
|
Specifies the channel to be processed. This parameter is mandatory.
|
Example
Type the following command to process any messages in the tcp_local channel:
imsimta start
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.
|
Note
|
You must be logged in as root to use this utility.
|
Syntax
|
imsimta start [component]
|
|
If a component parameter is specified, then only detached processes associated with that component are started. The standard component names are:
Example
Use the following command to start the MTA Job Controller and MTA Service Dispatcher:
imsimta stop
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.
|
Note
|
You must be logged in as root to use this utility.
|
Syntax
|
imsimta stop [dispatcher | job_controller]
|
|
Example
Use the following command to shut down the MTA jobs:
imsimta submit
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.
Syntax
|
imsimta submit [channel] [poll]
|
|
Parameters
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.
|
Example
Use the following command to process any messages in the tcp_local channel:
imsimta test
The imsimta test utilities perform tests on various areas of functionality of the MTA.
imsimta test -mapping
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
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
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
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.
Syntax
|
imsimta test -rewrite [address] [-alias_file=filename]
[-channel | -nochannel]
[-check_expansions | -nocheck_expansions]
[-configuration_file=filename ] [-database=database_list]
[-debug | -nodebug] [-delivery_receipt | -nodelivery_receipt]
[-destination_channel=channel] [-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]
[-source_channel=channel]
|
|
|
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]
|
|
|
imsimta test -url [-debug | -nodebug] [ldap_url]
|
|
Options
The options for this command are:
|
Option
|
Description
|
|
address
|
Specifies the test address to be rewritten. If this option is omitted, then the command prompts for an address. Used with the -rewrite option.
|
|
input_string
|
The string to be matched in the left side of a mapping table. Used with the -mapping option.
|
|
ldap_url
|
The LDAP URL that imsimta test -url attempts to resolve.
|
|
-alias_file=filename
|
Specifies an alternate alias file for imsimta test -rewrite to use. imsimta test -rewrite normally consults the default alias file named by the IMTA_ALIAS_FILE option of the MTA tailor file, msg-instance/imta/config/imta_tailor, during the rewriting process. This option has no effect unless -noimage_file is specified or no compiled configuration exists; any compiled configuration precludes reading any sort of alias file.
|
|
-channel | -nochannel
|
Controls whether imsimta test -rewrite outputs detailed information regarding the channel an address matches (e.g., channel flags).
|
|
-check_expansions | -nocheck_expansions
|
Controls checking of alias address expansion. Normally the MTA considers the expansion of an alias to have been successful if any of the addresses to which the alias expands are legal. The -check_expansions option causes a much stricter policy to be applied: imsimta test -rewrite -check_expansions checks each expanded address in detail and reports a list of any addresses, expanded or otherwise, that fail to rewrite properly.
|
|
-configuration_file=file
|
Specifies an alternate file to use in place of the file named by IMTA_CONFIG_FILE. Normally, imsimta test -rewrite consults the default configuration file named by the IMTA_CONFIG_FILE option of the MTA tailor file, msg-instance/imta/config/imta_tailor, during the rewriting process. This option has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration precludes reading any sort of configuration file.
|
|
-database=database-list
|
Disables references to various databases or redirects the database paths to nonstandard locations. imsimta test -rewrite normally consults the usual MTA databases during its operation. The allowed list items are alias, noalias, domain, nodomain, general, nogeneral, reverse, and noreverse. The list items beginning with "no" disable use of the corresponding database. The remaining items require an associated value, which is taken to be the name of that database.
|
|
-debug | -nodebug
|
Enables the production of the additional, detailed explanations of the rewriting process. This option is disabled by default.
|
|
-delivery_receipt | -nodelivery_receipt
|
Sets the corresponding receipt request flags. These options can be useful when testing the handling of sent or received receipt requests when rewriting forwarded addresses or mailing lists.
|
|
-destination_channel=channel
|
Controls to which destination or target channel imsimta test -rewrite rewrites addresses. Some address rewriting is destination channel specific; imsimta test -rewrite normally pretends that its channel destination is the local channel l.
|
|
-from=address | -nofrom
|
Controls what envelope From: address is used for access control probes when the -from option is specified. If address is omitted, the postmaster return address is used for such probes. If the -nofrom option is specified, the MTA uses an empty envelope From: address for access probes.
|
|
-flags=chars | -noflags
|
Specifies particular flags to be set during the mapping test when the -flags option is specified. For example, chars can be E (envelope), B (header/body), or I (message id) when testing a REVERSE mapping. Used with the -mapping option only.
|
|
-image_file=[filename] | -noimage_file
|
The -noimage_file option instructs the command to unconditionally ignore any previously compiled configuration and to read configuration information from the various text files instead. When the -image_file option is specified without an optional file name, the compiled configuration is loaded from the file named by the IMTA_CONFIG_DATA option into the MTA tailor file, msg-instance/imta/config/imta_tailor, which is usually msg-instance/imta/config/imta.cnf. If, instead, a file name is specified, then the compiled configuration is loaded from the specified file.
|
|
-input=input-file
|
Specifies a source for input to imsimta test -rewrite. By default, imsimta test -rewrite takes input from stdin.
|
|
-local_alias=value | -nolocal_alias
|
Controls the setting of an alias for the local host. The MTA supports multiple "identities" for the local host; the local host may have a different identity on each channel. This option may be used to set the local host alias to the specified value; appearances of the local host in rewritten addresses are replaced by this value.
|
|
-mapping_file=file | -nomapping_file
|
Instructs the command to use the specified mapping file rather than the default mapping file named by the IMTA_MAPPING_FILE option in the MTA tailor file, msg-instance/imta/config/imta_tailor, which is usually the file named msg-instance/imta/config/mappings. This option has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration precludes reading the mappings file. Use of the -nomapping_file option will prevent the IMTA_MAPPING_FILE file from being read in when there is no compiled configuration.
|
|
-option_file=filename | -nooption_file
|
Instructs the command to use the specified option file rather than the default option file named by the IMTA_OPTION_FILE option in the MTA tailor file, msg-instance/imta/config/imta_tailor, which is usually the file msg-instance/imta/config/options.dat. This option has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration precludes reading any sort of option file. Use of the -nooption_file option prevents the IMTA_OPTION_FILE file from being read in when there is no compiled configuration.
|
|
-output=output_file
|
Directs the output of imsimta test -rewrite. By default, imsimta test -rewrite writes output to stout.
|
|
-read_receipt | -noread_receipt
|
Sets the corresponding receipt request flags. This option can be useful when testing the handling of receipt requests at the time of rewriting forwarded addresses or mailing lists.
|
|
-restricted=setting
|
Controls the setting of the restricted flag. By default, this flag has value 0. When set to 1, -restricted=1, the restricted flag is set on and addresses are rewritten using the restricted mailbox encoding format recommended by RFC 1137. This flag is used to force rewriting of address mailbox names in accordance with the RFC 1137 specifications.
|
|
-source_channel=channel
|
Controls which source channel is performing the rewriting. Some address rewriting is source channel-specific; imsimta test -rewrite normally assumes that the channel source for which it is rewriting is the local channel l.
|
|
-table=table-name
|
Specifies the name of the mapping table to test. If this option is not specified, then imsimta test -mapping prompts for the name of the table to use.
|
Example
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-instance/imta/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
%
|
|
imsimta version
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.
Syntax
Example
To check the version of MTA you are running, execute the following command:
% imsimta version
imsimta view
The imsimta view utility displays log files.
Syntax
|
imsimta view file-pattern [-f offset-from-first] [-l offset-from-last]
|
|
Options
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.
|
Previous
Contents
Index
Next