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.