Anatomy of Postfix

Postfix supports information sources that are not built on top of Postfix and that aren't even under your direct control, such as blacklists (DNSBL and RHSBL lists), DNS-based lists, and other external sources. Blacklists are almost exclusively used in smtpd_*_restrictions parameters in order to reject mail coming from clients or senders listed in DNSBL- or RHSBL-style lists (see Chapter 7).

As with any external query, these lookups can fail due to connectivity problems, denial-of-service attacks against the blacklist servers, and other problems. In case of a timeout or other failure, Postfix may still accept mail (bypassing a possible restriction), but it will log an appropriate warning to the mail log.

Postfix ships with a number of command-line utilities to assist you with administration tasks. Although they perform different functions (such as querying maps, examining queue files, dequeuing and requeuing messages, and changing the configuration), they all have one thing in common--their names start with "post."

postfix

The postfix command stops, starts, and reloads the configuration with the stop, start, and reload options.

postalias

The postalias command creates an indexed alias map from an alias file. It works just like the postmap command (described shortly), but it pays special attention to the notation in an alias file (where a colon separates the key and value). postalias must be used on alias files.

postcat

The postcat command displays the content of a message in a mail queue.

To read a message in a mail queue, you need its queue ID. Run mailq for a list of queue IDs. For example, the queue ID of the following message is F2B9715C0B3:

# mailq
F2B9715C0B3 2464 Mon Oct 13 15:29:39 markus.herrmann@example.com
            (connect to mail.example.com[217.6.113.151]: Connection timed out)
            torsten.hecke@example.net
-- 2 Kbytes in 1 Requests.

After obtaining a queue ID, use it as an option to postcat to see the contents of the queue file:

# postcat -q F2B9715C0B3

postmap

The postmap command's primary purpose is to build indexed maps from flat files. For example, to build /etc/postfix/virtual.db from /etc/postfix/virtual, run the following command.

# postmap hash:/etc/postfix/virtual

The postmap command can do more. Among its most useful features is the ability to test any kind of map that your Postfix installation supports. This is extremely helpful when debugging a configuration where lookups to the maps appear to fail, and you are unsure whether the key and value are actually visible to Postfix.

Debugging an Entry in a Lookup Table

To determine whether Postfix can find an entry in a map, use postmap -q. For example, the following command returns the value assigned to the key <sender@example.com> in the map /etc/postfix/sender_access (type hash):

# postmap -q sender@example.com hash:/etc/postfix/sender_access
OK

It's important to note that postmap does not look for the terms <sender@>, <example.com>, and <com>, even though these terms are in the access(5) manual page. You need to perform those lookups manually:

# postmap -q sender@ hash:/etc/postfix/sender_access
# postmap -q example.com hash:/etc/postfix/sender_access
# postmap -q com hash:/etc/postfix/sender_access

postdrop

The postdrop command reads mail from the standard input and drops the result into the maildrop directory. This program works in conjunction with the sendmail utility.

postkick

The postkick command sends a request to a Postfix daemon through a local transport channel, making Postfix interprocess communication accessible to shell scripts and other programs.

Requeuing a Message

The following advanced postkick example shows how to requeue a message for immediate redelivery:

# cat queueidlist | postsuper -r -
postkick public pickup W

This sequence of commands moves all selected messages listed in queueidlist to the maildrop queue with the postsuper -r - command, where the pickup daemon would process them like any other piece of mail. By doing this, you reset the content filter to the setting appropriate for local submission and add an extra Received: header.

The postkick command requests an immediate maildrop queue scan. Otherwise, the messages would stay in the maildrop queue for a maximum of 60 seconds. The pickup daemon submits the message to the cleanup daemon, where it gets a new queueid and is deposited into the incoming queue. The whole point is to move the message to the active queue as quickly as possible.

postlock

The postlock command gives you exclusive access to mbox files that Postfix writes, and then it runs a command while holding the lock. The lock you get from postlock is compatible with the Postfix local delivery agent. Postfix does not touch the file while your command executes. Here is an example:

# postlock /var/mail/user from

postlog

The postlog command allows external programs, such as shell scripts, to write messages to the mail log. This is a Postfix-compatible logging interface; by default, it logs the text from the command line as a single record. Here's a very simple example:

# postlog This is a test
postlog: This is a test
# grep "This is a test" /var/log/mail.log
Feb 20 11:50:16 mail postlog: This is a test

postqueue

The postqueue command is a user interface to Postfix queues, giving you functionality that is traditionally available with the sendmail command.

postsuper

The postsuper command maintains jobs inside Postfix queues. Unlike postqueue, this command is restricted to the superuser, and it can run while Postfix is down. Some postsuper features are needed to check the queue before daemon processes are started. Table 5-1 shows what the postsuper command can do.

One of the most frequent uses of postsuper is deleting a message from the mail queue with postsuper -d queueid. Doing this manually is tedious, especially when deleting many files. The following Perl script (delete_from_mailq) makes it easier:

#!/usr/bin/perl
$REGEXP = shift || die "no email-address given (regexp-style, e.g. bl.*\@yahoo.com)!";
@data = qx</usr/sbin/postqueue -p>;
for (@data) {
	if (/^(\w+)(\*|\!)?\s/) {
		$queue_id = $1;
	}
	if($queue_id) {
		if (/$REGEXP/i) {
			$Q{$queue_id} = 1;
			$queue_id = "";
		}
	}
}
#open(POSTSUPER,"|cat") || die "couldn't open postsuper" ;
open(POSTSUPER,"|postsuper -d -") || die "couldn't open postsuper" ;
foreach (keys %Q) {
	print POSTSUPER "$_\n";
};
close(POSTSUPER);

Here's how you'd use it:

# mailq
C73A015C095     7509 Mon Oct 13 14:56:17 MAILER-DAEMON
	(connect to mx5.ancientaward.com[64.156.166.211]: Connection refused)
 
National_Nosepicking_Month@mx5.ancientaward.com

Notice that the sender is identified as <MAILER-DAEMON> here. To remove these bounces, run delete-from-mailq as root:

# delete-from-mailq MAILER-DAEMON
postsuper: C73A015C095: removed
postsuper: Deleted: 1 message