.TH qmail-banner 1
.SH NAME
qmail-banner \- present a banner to an SMTP client
.SH SYNOPSIS
Invoked from
.BR tcpserver :

.B tcpserver ... qmail-banner
[
.I arg ...
]
.I prog
.SH DESCRIPTION
.I qmail-banner
can send an SMTP banner to a client, with delays before and after
the banner, and then executes
.I prog.
If a client sends commands or closes the connection
before the banner is finished,
.I qmail-banner
can set environment variables for use by
.I prog.

If the variable
.B BANNERPRESLEEP
is set and non-null,
.I qmail-banner
will wait for the indicated number of seconds before
sending the banner to the client.

If the variable
.B BANNER
is set and non-null, the content is used as the banner.

If the variable
.B BANNERFILE
is set and non-null, the content of the indicated file will be 
used as the banner.

.B BANNER
is used in preference to
.B BANNERFILE.

Each line sent to the client
will be prefixed with "220-" and
terminated with "\\r\\n".  If the text does not end
with a newline character, one will be added.  Backslash
substitution is performed for the following strings:

.RS
\\r
\\a
\\n
\\t
\\xHH
\\d
\\dd
\\ddd
.RE

where
.B HH
are hex digits and
.B d/dd/ddd
are octal digits.

Variable substitution is performed where a
.B $
is followed by a variable name.  A variable name
is composed of up to 32 uppercase alphabetic characters
and is optionally enclosed in curly braces.

If not overridden by an environment variable,
the following variables names are handled internally:

.TP
.B ME
The contents of the file
.B control/me

.TP
.B DATE
The current date.  If the variable
.B DATEFMT
is found in the environment, the value will be used by
.I strftime(1)
in formatting the value of
.B DATE,
otherwise the RFC2822 date format will be used.

.TP
.B PID
The current process ID.

.TP
.B RANDOM
A random number.

.TP
.B SECONDS
Unix epoch.

.PP
If a variable is not found, the variable is not substituted.

.PP
If the variable
.B BANNERPOSTSLEEP
is set and non-null,
.I qmail-banner
will wait for the indicated number of seconds after
sending the banner to the client before executing the
.I prog
specified on the command line.

.PP
If the client interrupts the banner,
.I qmail-banner
will examine the environment for variables whose names
start with the string "BANNER", excluding the variables
listed above.  Any variables found will have "BANNER"
removed from the start of the name.

.SH OPTIONS

.I qmail-banner
accepts additional arguments of the form

.B -x file.cdb

where
.B file.cdb
is a CDB file in the same format as used by
.I tcpserver.
.I qmail-banner
uses the value of the variable 
.B TCPREMOTEIP
or shorter and shorter prefixes ending with a dot when
looking for rules.  Multiple arguments may be supplied;
.I qmail-banner
will stop searching on the first match.  It is not an
error to provide a file name that doesn't exist.

Any variables in the rule match will be exported
to the environment.

.SH ENVIRONMENT

.TP
.B BANNER
Text to be sent as banner to client

.TP
.B BANNERFILE
Contents of file to be sent as banner to client

.TP
.B BANNERPRESLEEP
Number of seconds to wait before sending banner

.TP
.B BANNERPOSTSLEEP
Number of seconds to wait after sending banner

.SH EXAMPLE

.nf
69.112-119:allow,BANNER="Dyn optonline clients wait",BANNERPOSTSLEEP="20"
:allow,BANNER="${ME} ESMTP NO-UCE\\nHi, [$TCPREMOTEIP], logged at $DATE"
:allow,BANNERPOSTSLEEP="2",BANNERRBLSMTPD="-Impatience rejected"
:allow,BANNERPRESLEEP="2",BANNERLOG="/usr/local/bin/recordio"

.SH "SEE ALSO"
tcpserver, tcprules