pfqueue - A queue realtime scanner for MTA
] [-b postfix1|postfix2|exim
] [-q queue#
] [-m maxmsg
] [-l seconds
] [-B backends_path
] [-c config_path
] [-d seconds
is a simple console tool for managing MTA (Mail Transfer Agent)
message queues. It handles queues through 'backends', libraries that interact
with the MTA, and displays informations through a console, ncurses based
Currently, pfqueue has backends for Postfix (both 1.x and 2.x) and Exim (both
version 3 and 4).
pfqueue returns 0 if everything goes fine, or:
- -1 if pfqueue library cannot be initialized
- -2 if frontend cannot be initialized
- -3 if you are not root
- -4 if pfqueue library cannot be started
accepts the following options, which are common to any backend:
- -B backends_path
- Tell pfqueue where backends are located. They should be
automatically found, since your installation should have placed them in a
standard lib dir. If not so, use this option to force it.
- -b backend
- Load a given backend. It can be autodetect,
postfix1, postfix2 or exim. Backends are libraries
named pfq_backendname.so, located in the installation library path (except
for autodetect, which is only a virtual backend that will try to guess
what kind of MTA is installed on the machine, and to load the proper
- Show version.
- Show usage.
- -c config
- Use a custom MTA configuration; note that the meaning of
'configuration' may vary: for example, postfix needs a directory, exim
needs a file.
- -m max
- Set the maximum number of messages shown in a queue. The
default is 200.
- -s seconds
- Set the display autorefresh rate in seconds. Default is
- Start reading from/to fields from message envelope instead
of headers, if the backend (and MTA) supports it.
- -p directory
- Set MTA executables path.
- -q queue_num
- Start by scanning the queue number queue_num: 1 for
deferred, 2 for active, 3 for incoming, 4 for hold, whatever the MTA calls
them. Some backends may not support all of these queues.
- -l limit
- Make pfqueue limit the time for scanning the queue tree and
for retreiving messages informations to this number of seconds; time is
not that accurate, since blocking I/O operations may cause lags, but it
shouldn't go too far. Obviously, limiting process run time may lead to
uncomplete results. Use this option just in case pfqueue takes too long in
performing operations, or you have a very slow machine, or you have very
- -d seconds
- Seconds to wait between queue scans. Default is
- Toggle colors off; note that use of colors can be toggled
also when pfqueue is running, with '+' key.
- Remote host to connect to. This implies a spfqueue instance
running on the remote host.
During program run, what you see is a window divided into two sections: the
upper one is the list of messages found in the current queue, and the lower
one is a small selection of details for the current message.
A number of operation can then be done on a single message, or on a bunch of
- UP/DOWN arrow keys
- Move the cursor up/down.
- HOME/END or g/G
- Move to the top/bottom of the list.
- 1, 2, 3, 4, 5
- Select queue to show. Every MTA handles queues in its own
way, so these are general keys that cannot be generically described. For
Postfix, they will select respectively 'deferred', 'active', 'incoming',
'hold' and 'corrupt' queues. For Exim, they will have no effect since the
backend (and Exim, really) does not archive messages in different queues
depending on their status.
- Delete message.
- Hold message.
- Release message.
- Requeue message.
- Mark current message: this will "mark" the
message as the start of a block, and the following 't' key (see below)
will tag all messages between that and the tagged one.
- Tag/untag message; tagged messages will be shown in
bold. To operate on all the tagged messages at once, use ';' key
(see below). If a mark (see above) is present, all messages between the
tagged and the marked will be tagged.
- Tag all messages.
- Untag all messages.
- Make delete/hold/release/requeue actions work on all of the
tagged messages at once.
- Toggle auto-work-on-tagged: when activated, and if there
are tagged messages, actions will work on tagged indipendently of
work-on-tagged status (';' key).
- Toggle reading from/to fields from envelope or headers, if
the backend supports it.
- Show current message details.
- Find first message matching a POSIX regexp; the regexp you
use can be prefixed by one of f:, t:, e:, s: which will limit the search
in, respectively, the From, To, From-or-To, Subject fields. The default is
to search everywhere.
- Find next message matching last used regexp.
- Find previous message matching last used regexp.
- Search and tag messages: all messages matching the regexp
will be tagged; the same prefixes described in '/' search can be
- Enable/disable confirmation request for action on
- Toggle queue scanning on/off. Use it when you have a fast
changing situation and you want to freeze it for further examination. Note
that then scanning is disabled, the messages you see in the list may have
gone away (delivered?) in the meantime.
- Toggle colors on/off.
- Increase body window height.
- Decrease body window height.
- Scroll body window up.
- Show/hide body window.
- Scroll body window down.
- Toggle body automatic show on/off.
- Show body in a new window.
- Sort queue by from/to/subject. Keep in mind that it may
slow down interface, since the full queue must be read in order to be
- Show body of current message (if automatic show is off): if
body window is not enabled, it behaves like 's' key.
Stefano Rivoir <firstname.lastname@example.org>
pfqueue was originally thought as a dedicated Postfix tool, and actually it has
been so up to version 0.3.8; since version 0.4.0 it has been extended to use
pluggable libraries in order to support virtually any kind of MTA.