Add ERRORS and otherwise clarify manpages.

qmail-qfilter-queue.8

@@ -1,4 +1,4 @@
-.TH QMAIL-QFILTER-QUEUE 8 2018-12-30
+.TH QMAIL-QFILTER-QUEUE 8 2020-12-15
 .SH NAME
 qmail-qfilter-queue \- run a sequence of pre-queue filters
 .SH SYNOPSIS
@@ -22,22 +22,30 @@ so that incoming and submitted messages are filtered before
 entering the queue.
 .SH "ENVIRONMENT VARIABLES"
 To have
+.B qmail-smtpd
+and/or
+.B ofmipd
+invoke
 .B qmail-qfilter-queue
-invoked in place of
+in place of
 .BR qmail-queue ,
 set
 .B QMAILQUEUE
 to
 .I /var/qmail/bin/qmail-qfilter-queue
-(typically in your
+in your
 .BR tcpserver 's
-tcprules).
+tcprules (and restart).
 .PP
-To run pre-queue filters, set
+To have
+.B qmail-qfilter-queue
+filter messages before they reach the queue, also set
 .B QMAILQUEUEFILTERS
-with the path to the control file
-containing your sequence of filter programs (one per line).
+to the relevant control file (and restart
+.BR tcpserver ).
 .SH "CONTROL FILES"
+.B qmail-qfilter-queue
+expects a sequence of filter programs.
 Typical values for
 .BR QMAILQUEUEFILTERS :
 .TP 5
@@ -46,6 +54,26 @@ For incoming messages.
 .TP 5
 .I control/ofmipfilters
 For submitted messages.
+.P
+Filter programs must be listed one per line,
+with no arguments.
+Changing the sequence takes effect immediately (no restart required).
+If the control file is empty,
+contains only comments,
+or doesn't exist,
+messages are passed to
+.BR qmail-queue .
+.SH "ERRORS"
+Some typical SMTP error messages and their likely causes:
+.TP 5
+.I "451 mail server temporarily rejected message (#4.3.0)"
+.B qmail-qfilter
+is not installed in
+.IR "$PATH" .
+.TP 5
+.I "451 qq internal bug (#4.3.0)"
+The control file lists a program that doesn't exist
+or otherwise can't be executed.
 .SH "EXAMPLES"
 See
 .IR https://schmonz.com/qmail/rejectutils .

qmail-qfilter-viruscan.8

@@ -1,4 +1,4 @@
-.TH QMAIL-QFILTER-VIRUSCAN 8 2018-12-30
+.TH QMAIL-QFILTER-VIRUSCAN 8 2020-12-15
 .SH NAME
 qmail-qfilter-viruscan \- viruscan patch as standalone program
 .SH SYNOPSIS

qmail-rcptcheck-badrcptto.8

@@ -1,4 +1,4 @@
-.TH QMAIL-RCPTCHECK-BADRCPTTO 8 2018-12-30
+.TH QMAIL-RCPTCHECK-BADRCPTTO 8 2020-12-15
 .SH NAME
 qmail-rcptcheck-badrcptto \- badrcptto patch as standalone program
 .SH SYNOPSIS

qmail-rcptcheck-realrcptto.8

@@ -1,4 +1,4 @@
-.TH QMAIL-RCPTCHECK-REALRCPTTO 8 2018-12-30
+.TH QMAIL-RCPTCHECK-REALRCPTTO 8 2020-12-15
 .SH NAME
 qmail-rcptcheck-realrcptto \- realrcptto patch as standalone program
 .SH SYNOPSIS

qmail-rcptcheck.8

@@ -1,4 +1,4 @@
-.TH QMAIL-RCPTCHECK 8 2018-12-30
+.TH QMAIL-RCPTCHECK 8 2020-12-15
 .SH NAME
 qmail-rcptcheck \- run a sequence of sender/recipient checks
 .SH SYNOPSIS
@@ -30,17 +30,17 @@ set
 .B RCPTCHECK
 to
 .I /var/qmail/bin/qmail-rcptcheck
-(typically in your
+in your
 .BR tcpserver 's
-tcprules).
+tcprules (and restart).
 .PP
-To write a check:
+To perform checks, inspect these variables:
 .TP 5
 .I SENDER
-contains the envelope sender.
+Contains the envelope sender.
 .TP 5
 .I RECIPIENT
-contains the envelope recipient.
+Contains the envelope recipient.
 .SH "CONTROL FILES"
 To run under
 .BR qmail-spp :
@@ -55,18 +55,33 @@ To run under
 .BR RCPTCHECK :
 none needed.
 .PP
-To control
+In either case, to control
 .BR qmail-rcptcheck :
 .TP 5
 .I rcptchecks
-Sequence of checks (one per line).
+Sequence of checks.
+.P
+RCPTCHECK-compatible programs must be listed one per line,
+with no arguments.
+Changing the sequence takes effect immediately (no restart required).
+If the control file is empty,
+contains only comments,
+or doesn't exist,
+messages are not rejected.
+.P
+To test your configuration, as
+.IR root ,
+in
+.IR /var/qmail :
+.P
+# env SENDER=a RECIPIENT=b setuidgid qmaild qmail-rcptcheck; echo $?
 .SH "EXIT CODES"
 As defined by the
 .B RCPTCHECK
 interface,
 .I 120
 is reserved.
-Programs should exit
+Recipient-checking programs should exit
 .I 111
 when unable to verify,
 .I 100
@@ -78,6 +93,12 @@ programs can run unmodified under
 .B qmail-spp
 simply by running them from
 .BR qmail-rcptcheck .
+.SH "ERRORS"
+Some typical SMTP errors and their likely causes:
+.TP 5
+.I "421 unable to execute recipient check (#4.3.0)"
+The control file lists a program that doesn't exist
+or otherwise can't be executed.
 .SH "EXAMPLES"
 See
 .IR https://schmonz.com/qmail/rejectutils .