Queue Tools

Postfix provides command-line tools for displaying and managing the messages in your queue. The primary commands are postsuper and postqueue. You can perform the following tasks on messages in the queue:

• Listing messages
• Deleting messages
• Holding messages
• Requeuing messages
• Displaying messages
• Flushing messages

Each of the tasks, and the commands to accomplish them, are explained in the sections that follow.

5.2.1 Listing the Queue

The queue display contains an entry for each message that shows the message ID, size, arrival time, sender, and recipient addresses. Deferred messages also include the reason they could not be delivered. Messages in the active queue are marked with an asterisk after the Queue ID. Messages in the hold queue are marked with an exclamation point. Deferred messages have no mark.

You can list all the messages in your queue with the postqueue -p command. Postfix also provides the mailq command for compatibility with Sendmail. The Postfix replacement for mailq produces the same output as postqueue -p.

A typical queue entry looks like the following:

$ postqueue -p
-Queue ID- --Size-- ----Arrival Time---- -Sender/Recipient-------
DBA3F1A9 553 Mon May 5 14:42:15 [e-mail]
 (connect to mail.ora.com[192.168.155.63]: Connection refused)
 [e-mail]

Since this entry is not marked with either an asterisk or an exclamation point, it is in the deferred queue.

5.2.2 Deleting Messages

The postsuper command allows you to remove messages from the queue. To remove the message in the sample entry displayed above, execute postsuper with the -d option:

# postsuper -d DBA3F1A9
postsuper: DBA3F1A9: removed
postsuper: Deleted: 1 message

If you have a lot of messages to remove, you can clear out your entire queue with the ALL argument:

# postsuper -d ALL
postsuper: Deleted: 23 messages

The ALL argument must be capitalized. Be very careful when using the command, since it will delete all queued messages without asking any questions.

Rather than deleting all of the queued messages or just one at a time, frequently you want to delete messages with a specific email address. Example 5-1 is a Perl script that provides a convenient way to specify an email address to delete particular messages from the queue.

Example 5-1. Perl script to delete queued messages by email address

#!/usr/bin/perl -w
#
# pfdel - deletes message containing specified address from
# Postfix queue. Matches either sender or recipient address.
#
# Usage: pfdel 
#

use strict;

# Change these paths if necessary.
my $LISTQ = "/usr/sbin/postqueue -p";
my $POSTSUPER = "/usr/sbin/postsuper";

my $email_addr = "";
my $qid = "";
my $euid = $>;

if ( @ARGV != 1 ) {
 die "Usage: pfdel 
";
} else {
 $email_addr = $ARGV[0];
}

if ( $euid != 0 ) {
 die "You must be root to delete queue files.
";
}


open(QUEUE, "$LISTQ |") || 
 die "Can't get pipe to $LISTQ: $!
";

my $entry = ; # skip single header line
$/ = ""; # Rest of queue entries print on
 # multiple lines.
while ( $entry =  ) {
 if ( $entry =~ / $email_addr$/m ) {
 ($qid) = split(/s+/, $entry, 2);
 $qid =~ s/[*!]//;
 next unless ($qid);

 #
 # Execute postsuper -d with the queue id.
 # postsuper provides feedback when it deletes
 # messages. Let its output go through.
 #
 if ( system($POSTSUPER, "-d", $qid) != 0 ) {
 # If postsuper has a problem, bail.
 die "Error executing $POSTSUPER: error " .
 "code " . ($?/256) . "
";
 }
 }
}
close(QUEUE);

if (! $qid ) {
 die "No messages with the address <$email_addr> " .
 "found in queue.
";
}

exit 0;

5.2.3 Holding Messages

The hold queue is available for messages you would like to keep in your queue indefinitely. Figure 5-2 shows the hold queue and how you can move messages into the hold queue where they will not be delivered until you specifically remove them or move them back for normal queue processing. To place the example message into the hold queue, use the postsuper command with the -h option:

# postsuper -h DBA3F1A9

The queue entry now contains an exclamation point to show that the message is on hold:

-Queue ID- --Size-- ----Arrival Time---- -Sender/Recipient-------
DBA3F1A9 ! 553 Mon May 5 14:42:15 [e-mail]
 (connect to mail.ora.com[192.168.155.63]: Connection refused)
 [e-mail]

Figure 5-2. Putting messages on hold

To move the message back into the normal queue for regular processing, execute the command with a capital -H option instead:

# postsuper -H DBA3F1A9

After the message is moved back, the queue manager marks it for redelivery according to its normal scheduling, or you can flush the message to have it sent out immediately (see Section 5.2.6).

5.2.4 Requeuing Messages

If you have messages that were deferred because of a configuration problem that has been corrected, you may have to requeue the messages to have them delivered successfully. If the misconfiguration caused Postfix to store incorrect information about the next hop or transport method, or to rewrite the address incorrectly, requeuing causes Postfix to update the incorrect information based on your new configuration. The postsuper command uses the -r option to requeue messages. You can specify a queue ID for a single message, or the word ALL in capital letters to requeue everything:

# postsuper -r ALL

Requeued messages get a new queue ID and an additional Received: header.

5.2.5 Displaying Messages

The postcat command displays the contents of a queue file:

# postcat -q DBA3F1A9

Earlier versions of postcat did not support the -q option but required the full path to the queue file. Since a message can be in any of the queue compartments (maildrop, incoming, active, deferred, hold), and each of these has multiple subdirectories, the path to a particular queue file is not immediately apparent. If you are using an earlier version of postcat, which doesn't support the -q option, you can create a shell script like the one in Example 5-2 as a convenient way to view a queue file by specifying only the queue ID. The script accepts one queue ID as an argument, checks all of the queue directories to locate the queue file, and executes postcat with the full path as its argument. The contents are then displayed. This simple script displays only one queue file at a time.

Example 5-2. Shell script wrapper for postcat

#!/bin/sh

PATH=/usr/bin:/usr/sbin
QS="deferred active incoming maildrop hold"
QPATH=`postconf -h queue_directory`

if [ $# -ne 1 ]; then
 echo "Usage: pfcat "
 exit 1
fi

if [ `whoami` != "root" ]; then
 echo "You must be root to view queue files."
 exit 1
fi

if [ ! -d $QPATH ]; then
 echo "Cannot locate queue directory $QPATH."
 exit 1
fi

for q in $QS
do
 FILE=`find $QPATH/$q -type f -name $1`
 if [ -n "$FILE" ]; then
 postcat $FILE
 exit 0
 fi
done

if [ -z $FILE ]; then
 echo "No such queue file $1"
 exit 1
fi

5.2.6 Flushing Messages

Flushing the queue causes Postfix to attempt to deliver messages in the queue immediately. You can flush queue messages with the postqueue -f command. However, unless you have a reason to expect successful deliveries, it's best to leave redelivery attempts to the Postfix queue manager. Repeated attempts to flush the queue can have a severe performance impact on your mail server.

You can flush messages destined for a particular site with the -s option. The site must be eligible for fast flush in order for this to work. To be eligible, the site must be listed in the fast_flush_domains parameter. By default, fast_flush_domains includes all of the hosts listed in relay_domains, but you can add additional sites if you want to flush them before the normally scheduled redelivery attempt.

fast_flush_domains = $relay_domains example.com

If you know that a previously unavailable, eligible site is ready to accept mail, execute postqueue with the -s option and name the site:

# postqueue -s example.com

See Chapter 9 for more information about fast flush and the SMTP command ETRN.