1 files changed, 343 insertions, 0 deletions
diff --git a/man/man1/postsuper.1 b/man/man1/postsuper.1
new file mode 100644
index 0000000..885330f
--- /dev/null
+++ b/man/man1/postsuper.1
@@ -0,0 +1,343 @@
+.TH POSTSUPER 1 
+.ad
+.fi
+.SH NAME
+postsuper
+\-
+Postfix superintendent
+.SH "SYNOPSIS"
+.na
+.nf
+.fi
+\fBpostsuper\fR [\fB\-psSv\fR]
+        [\fB\-c \fIconfig_dir\fR] [\fB\-d \fIqueue_id\fR]
+        [\fB\-e \fIqueue_id\fR] [\fB\-f \fIqueue_id\fR]
+        [\fB\-h \fIqueue_id\fR] [\fB\-H \fIqueue_id\fR]
+        [\fB\-r \fIqueue_id\fR] [\fIdirectory ...\fR]
+.SH DESCRIPTION
+.ad
+.fi
+The \fBpostsuper\fR(1) command does maintenance jobs on the Postfix
+queue. Use of the command is restricted to the superuser.
+See the \fBpostqueue\fR(1) command for unprivileged queue operations
+such as listing or flushing the mail queue.
+
+By default, \fBpostsuper\fR(1) performs the operations
+requested with the
+\fB\-s\fR and \fB\-p\fR command\-line options on all Postfix queue
+directories \- this includes the \fBincoming\fR, \fBactive\fR,
+\fBdeferred\fR, and \fBhold\fR directories with message
+files and the \fBbounce\fR,
+\fBdefer\fR, \fBtrace\fR and \fBflush\fR directories with log files.
+
+Options:
+.IP "\fB\-c \fIconfig_dir\fR"
+The \fBmain.cf\fR configuration file is in the named directory
+instead of the default configuration directory. See also the
+MAIL_CONFIG environment setting below.
+.IP "\fB\-d \fIqueue_id\fR"
+Delete one message with the named queue ID from the named
+mail queue(s) (default: \fBhold\fR, \fBincoming\fR, \fBactive\fR and
+\fBdeferred\fR).
+
+To delete multiple files, specify the \fB\-d\fR option multiple
+times, or specify a \fIqueue_id\fR of \fB\-\fR to read queue IDs
+from standard input. For example, to delete all mail
+with exactly one recipient \fBuser@example.com\fR:
+.sp
+.nf
+postqueue \-j | jq -r '
+    # See JSON OBJECT FORMAT section in the postqueue(1) manpage
+    select(.recipients[0].address == "user@example.com")
+    | select(.recipients[1].address == null)
+    | .queue_id
+ ' | postsuper \-d \-
+.fi
+.sp
+(note the "jq -r" option), or the historical form:
+.sp
+.nf
+mailq | tail \-n +2 | grep \-v '^ *(' | awk  'BEGIN { RS = "" }
+    # $7=sender, $8=recipient1, $9=recipient2
+    { if ($8 == "user@example.com" && $9 == "")
+          print $1 }
+ ' | tr \-d '*!' | postsuper \-d \-
+.fi
+.sp
+Specify "\fB\-d ALL\fR" to remove all messages; for example, specify
+"\fB\-d ALL deferred\fR" to delete all mail in the \fBdeferred\fR queue.
+As a safety measure, the word \fBALL\fR must be specified in upper
+case.
+.sp
+Warning: Postfix queue IDs are reused (always with Postfix
+<= 2.8; and with Postfix >= 2.9 when enable_long_queue_ids=no).
+There is a very small possibility that postsuper deletes the
+wrong message file when it is executed while the Postfix mail
+system is delivering mail.
+.sp
+The scenario is as follows:
+.RS
+.IP 1)
+The Postfix queue manager deletes the message that \fBpostsuper\fR(1)
+is asked to delete, because Postfix is finished with the
+message (it is delivered, or it is returned to the sender).
+.IP 2)
+New mail arrives, and the new message is given the same queue ID
+as the message that \fBpostsuper\fR(1) is supposed to delete.
+The probability for reusing a deleted queue ID is about 1 in 2**15
+(the number of different microsecond values that the system clock
+can distinguish within a second).
+.IP 3)
+\fBpostsuper\fR(1) deletes the new message, instead of the old
+message that it should have deleted.
+.RE
+.IP "\fB\-e \fIqueue_id\fR"
+.IP "\fB\-f \fIqueue_id\fR"
+Request forced expiration for one message with the named
+queue ID in the named mail queue(s) (default: \fBhold\fR,
+\fBincoming\fR, \fBactive\fR and \fBdeferred\fR).
+.RS
+.IP \(bu
+The message will be returned to the sender when the queue
+manager attempts to deliver that message (note that Postfix
+will never deliver messages in the \fBhold\fR queue).
+.IP \(bu
+The \fB\-e\fR and \fB\-f\fR options both request forced
+expiration. The difference is that \fB\-f\fR will also release
+a message if it is in the \fBhold\fR queue. With \fB\-e\fR, such
+a message would not be returned to the sender until it is
+released with \fB\-f\fR or \fB\-H\fR.
+.IP \(bu
+When a deferred message is force\-expired, the return message
+will state the reason for the delay. Otherwise, the reason
+will be "message is administratively expired".
+.RE
+.IP
+To expire multiple files, specify the \fB\-e\fR or \fB\-f\fR
+option multiple times, or specify a \fIqueue_id\fR of \fB\-\fR
+to read queue IDs from standard input (see the \fB\-d\fR option
+above for an example, but be sure to replace \fB\-d\fR in
+the example).
+.sp
+Specify "\fB\-e ALL\fR" or "\fB\-f ALL\fR" to expire all
+messages; for example, specify "\fB\-e ALL deferred\fR" to
+expire all mail in the \fBdeferred\fR queue.  As a safety
+measure, the word \fBALL\fR must be specified in upper case.
+.sp
+These features are available in Postfix 3.5 and later.
+.IP "\fB\-h \fIqueue_id\fR"
+Put mail "on hold" so that no attempt is made to deliver it.
+Move one message with the named queue ID from the named
+mail queue(s) (default: \fBincoming\fR, \fBactive\fR and
+\fBdeferred\fR) to the \fBhold\fR queue.
+
+To hold multiple files, specify the \fB\-h\fR option multiple
+times, or specify a \fIqueue_id\fR of \fB\-\fR to read queue IDs
+from standard input.
+.sp
+Specify "\fB\-h ALL\fR" to hold all messages; for example, specify
+"\fB\-h ALL deferred\fR" to hold all mail in the \fBdeferred\fR queue.
+As a safety measure, the word \fBALL\fR must be specified in upper
+case.
+.sp
+Note: while mail is "on hold" it will not expire when its
+time in the queue exceeds the \fBmaximal_queue_lifetime\fR
+or \fBbounce_queue_lifetime\fR setting. It becomes subject to
+expiration after it is released from "hold".
+.sp
+This feature is available in Postfix 2.0 and later.
+.IP "\fB\-H \fIqueue_id\fR"
+Release mail that was put "on hold".
+Move one message with the named queue ID from the named
+mail queue(s) (default: \fBhold\fR) to the \fBdeferred\fR queue.
+
+To release multiple files, specify the \fB\-H\fR option multiple
+times, or specify a \fIqueue_id\fR of \fB\-\fR to read queue IDs
+from standard input.
+.sp
+Note: specify "\fBpostsuper \-r\fR" to release mail that was kept on
+hold for a significant fraction of \fB$maximal_queue_lifetime\fR
+or \fB$bounce_queue_lifetime\fR, or longer.
+.sp
+Specify "\fB\-H ALL\fR" to release all mail that is "on hold".
+As a safety measure, the word \fBALL\fR must be specified in upper
+case.
+.sp
+This feature is available in Postfix 2.0 and later.
+.IP \fB\-p\fR
+Purge old temporary files that are left over after system or
+software crashes.
+The \fB\-p\fR, \fB\-s\fR, and \fB\-S\fR operations are done
+before other operations.
+.IP "\fB\-r \fIqueue_id\fR"
+Requeue the message with the named queue ID from the named
+mail queue(s) (default: \fBhold\fR, \fBincoming\fR, \fBactive\fR and
+\fBdeferred\fR).
+
+To requeue multiple files, specify the \fB\-r\fR option multiple
+times, or specify a \fIqueue_id\fR of \fB\-\fR to read queue IDs
+from standard input.
+.sp
+Specify "\fB\-r ALL\fR" to requeue all messages. As a safety
+measure, the word \fBALL\fR must be specified in upper case.
+.sp
+A requeued message is moved to the \fBmaildrop\fR queue,
+from where it is copied by the \fBpickup\fR(8) and
+\fBcleanup\fR(8) daemons to a new queue file. In many
+respects its handling differs from that of a new local
+submission.
+.RS
+.IP \(bu
+The message is not subjected to the smtpd_milters or
+non_smtpd_milters settings.  When mail has passed through
+an external content filter, this would produce incorrect
+results with Milter applications that depend on original
+SMTP connection state information.
+.IP \(bu
+The message is subjected again to mail address rewriting
+and substitution.  This is useful when rewriting rules or
+virtual mappings have changed.
+.sp
+The address rewriting context (local or remote) is the same
+as when the message was received.
+.IP \(bu
+The message is subjected to the same content_filter settings
+(if any) as used for new local mail submissions.  This is
+useful when content_filter settings have changed.
+.RE
+.IP
+Warning: Postfix queue IDs are reused (always with Postfix
+<= 2.8; and with Postfix >= 2.9 when enable_long_queue_ids=no).
+There is a very small possibility that \fBpostsuper\fR(1) requeues
+the wrong message file when it is executed while the Postfix mail
+system is running, but no harm should be done.
+.sp
+This feature is available in Postfix 1.1 and later.
+.IP \fB\-s\fR
+Structure check and structure repair.  This should be done once
+before Postfix startup.
+The \fB\-p\fR, \fB\-s\fR, and \fB\-S\fR operations are done
+before other operations.
+.RS
+.IP \(bu
+Rename files whose name does not match the message file inode
+number. This operation is necessary after restoring a mail
+queue from a different machine or from backup, when queue
+files were created with Postfix <= 2.8 or with
+"enable_long_queue_ids = no".
+.IP \(bu
+Move queue files that are in the wrong place in the file system
+hierarchy and remove subdirectories that are no longer needed.
+File position rearrangements are necessary after a change in the
+\fBhash_queue_names\fR and/or \fBhash_queue_depth\fR
+configuration parameters.
+.IP \(bu
+Rename queue files created with "enable_long_queue_ids =
+yes" to short names, for migration to Postfix <= 2.8.  The
+procedure is as follows:
+.sp
+.nf
+.na
+# postfix stop
+# postconf enable_long_queue_ids=no
+# postsuper
+.ad
+.fi
+.sp
+Run \fBpostsuper\fR(1) repeatedly until it stops reporting
+file name changes.
+.RE
+.IP \fB\-S\fR
+A redundant version of \fB\-s\fR that requires that long
+file names also match the message file inode number. This
+option exists for testing purposes, and is available with
+Postfix 2.9 and later.
+The \fB\-p\fR, \fB\-s\fR, and \fB\-S\fR operations are done
+before other operations.
+.IP \fB\-v\fR
+Enable verbose logging for debugging purposes. Multiple \fB\-v\fR
+options make the software increasingly verbose.
+.SH DIAGNOSTICS
+.ad
+.fi
+Problems are reported to the standard error stream and to
+\fBsyslogd\fR(8) or \fBpostlogd\fR(8).
+
+\fBpostsuper\fR(1) reports the number of messages deleted
+with \fB\-d\fR, the number of messages expired with \fB\-e\fR,
+the number of messages expired or released with \fB\-f\fR,
+the number of messages held or released with \fB\-h\fR or
+\fB\-H\fR, the number of messages requeued with \fB\-r\fR,
+and the number of messages whose queue file name was fixed
+with \fB\-s\fR. The report is written to the standard error
+stream and to \fBsyslogd\fR(8) or \fBpostlogd\fR(8).
+.SH "ENVIRONMENT"
+.na
+.nf
+.ad
+.fi
+.IP MAIL_CONFIG
+Directory with the \fBmain.cf\fR file.
+.SH BUGS
+.ad
+.fi
+Mail that is not sanitized by Postfix (i.e. mail in the \fBmaildrop\fR
+queue) cannot be placed "on hold".
+.SH "CONFIGURATION PARAMETERS"
+.na
+.nf
+.ad
+.fi
+The following \fBmain.cf\fR parameters are especially relevant to
+this program.
+The text below provides only a parameter summary. See
+\fBpostconf\fR(5) for more details including examples.
+.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
+The default location of the Postfix main.cf and master.cf
+configuration files.
+.IP "\fBhash_queue_depth (1)\fR"
+The number of subdirectory levels for queue directories listed with
+the hash_queue_names parameter.
+.IP "\fBhash_queue_names (deferred, defer)\fR"
+The names of queue directories that are split across multiple
+subdirectory levels.
+.IP "\fBimport_environment (see 'postconf -d' output)\fR"
+The list of environment parameters that a privileged Postfix
+process will import from a non\-Postfix parent process, or name=value
+environment overrides.
+.IP "\fBqueue_directory (see 'postconf -d' output)\fR"
+The location of the Postfix top\-level queue directory.
+.IP "\fBsyslog_facility (mail)\fR"
+The syslog facility of Postfix logging.
+.IP "\fBsyslog_name (see 'postconf -d' output)\fR"
+A prefix that is prepended to the process name in syslog
+records, so that, for example, "smtpd" becomes "prefix/smtpd".
+.PP
+Available in Postfix version 2.9 and later:
+.IP "\fBenable_long_queue_ids (no)\fR"
+Enable long, non\-repeating, queue IDs (queue file names).
+.SH "SEE ALSO"
+.na
+.nf
+sendmail(1), Sendmail\-compatible user interface
+postqueue(1), unprivileged queue operations
+postlogd(8), Postfix logging
+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
+
+Wietse Venema
+Google, Inc.
+111 8th Avenue
+New York, NY 10011, USA