.TH FLUSH 8 
.ad
.fi
.SH NAME
flush
\-
Postfix fast flush server
.SH SYNOPSIS
.na
.nf
\fBflush\fR [generic Postfix daemon options]
.SH DESCRIPTION
.ad
.fi
The flush server maintains a record of deferred mail by destination.
This information is used to improve the performance of the SMTP
\fBETRN\fR request, and of its command-line equivalent,
\fBsendmail -qR\fR.
This program expects to be run from the \fBmaster\fR(8) process
manager.

The record is implemented as a per-destination logfile with
as contents the queue IDs of deferred mail. A logfile is
append-only, and is truncated when delivery is requested
for the corresponding destination. A destination is the
part on the right-hand side of the right-most \fB@\fR in
an email address.

Per-destination logfiles of deferred mail are maintained only for
eligible destinations. The list of eligible destinations is
specified with the \fBfast_flush_domains\fR configuration parameter,
which defaults to \fB$relay_domains\fR.

This server implements the following requests:
.IP "\fBFLUSH_REQ_ADD\fI sitename queue_id\fR"
Inform the fast flush server that the specified message is queued for
\fIsitename\fR. Depending on logging policy, the fast flush server
stores or ignores the information.
.IP "\fBFLUSH_REQ_SEND\fI sitename\fR"
Request delivery of mail that is queued for \fIsitename\fR.
If the destination is eligible for a fast flush logfile,
this request triggers delivery of messages listed in that
destination's logfile, and the logfile is truncated to zero length;
if mail is undeliverable it will be added back to the logfile.
.sp
If the destination is not eligible for a fast flush logfile,
this request triggers delivery of all queued mail.
.IP \fBTRIGGER_REQ_WAKEUP\fR
This wakeup request from the master is an alternative way to
request \fBFLUSH_REQ_REFRESH\fR.
.IP "\fBFLUSH_REQ_REFRESH\fR (completes in the background)"
Refresh non-empty per-destination logfiles that were not read in
\fBfast_flush_refresh_time\fR hours, by simulating
send requests (see above) for the corresponding destinations.
.sp
Delete empty per-destination logfiles that were not updated in
\fBfast_flush_purge_time\fR days.
.IP "\fBFLUSH_REQ_PURGE\fR (completes in the background)"
Refresh all non-empty per-destination logfiles, by simulating
send requests (see above) for the corresponding destinations.
This can be incredibly expensive when logging is enabled for
many destinations, and is not recommended.
.sp
Delete empty per-destination logfiles that were not updated in
\fBfast_flush_purge_time\fR days.
.PP
The server response is one of:
.IP \fBFLUSH_STAT_OK\fR
The request completed normally.
.IP \fBFLUSH_STAT_BAD\fR
The flush server rejected the request (bad request name, bad
request parameter value).
.IP \fBFLUSH_STAT_FAIL\fR
The request failed.
.SH SECURITY
.na
.nf
.ad
.fi
The fast flush server is not security-sensitive. It does not
talk to the network, and it does not talk to local users.
The fast flush server can run chrooted at fixed low privilege.
.SH DIAGNOSTICS
.ad
.fi
Problems and transactions are logged to \fBsyslogd\fR(8).
.SH BUGS
.ad
.fi
Fast flush logfiles are truncated only after a \fBFLUSH_REQ_SEND\fR
request, not when mail is actually delivered, and therefore can
accumulate outdated or redundant data. In order to maintain sanity,
\fBFLUSH_REQ_REFRESH\fR must be executed periodically. This can
be automated with a suitable wakeup timer setting in the
\fBmaster.cf\fR configuration file.

Upon receipt of a request to deliver all mail for an eligible
destination, the \fBflush\fR server requests delivery of all messages
that are listed in that destination's logfile, regardless of the
recipients of those messages. This is not an issue for mail
that is sent to a \fBrelay_domains\fR destination because
such mail typically only has recipients in one domain.
.SH FILES
.na
.nf
/var/spool/postfix/flush, location of "fast flush" logfiles.
.SH CONFIGURATION PARAMETERS
.na
.nf
.ad
.fi
See the Postfix \fBmain.cf\fR file for syntax details and for
default values. Use the \fBpostfix reload\fR command after a
configuration change.
.IP \fBfast_flush_domains\fR
What destinations can have a "fast flush" logfile. By default,
this is set to \fB$relay_domains\fR.
.IP \fBfast_flush_refresh_time\fR
Refresh a non-empty "fast flush" logfile that was not read in
this amount of time (default time unit: hours), by simulating
a send request for the corresponding destination.
.IP \fBfast_flush_purge_time\fR
Remove an empty "fast flush" logfile that was not updated in
this amount of time (default time unit: days).
.SH SEE ALSO
.na
.nf
smtpd(8) Postfix SMTP server
qmgr(8) Postfix queue manager
syslogd(8) system logging
.SH LICENSE
.na
.nf
.ad
.fi
The Secure Mailer license must be distributed with this software.
.SH AUTHOR(S)
.na
.nf
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA