=for comment $Id: asmtpd.conf.pod,v 1.44 2006/07/15 16:41:58 dm Exp $

=head1 NAME

F<asmtpd.conf> - Avenger SMTP Daemon configuration file

=head1 DESCRIPTION

F<asmtpd.conf> is the configuration file for L<asmtpd(8)|asmtpd(8)>,
the Mail Avenger mail server.  The file contains a series of
directives, where each directive takes zero or more arguments.  Blank
lines and lines beginning with C<#> (for comments) are ignored.  If a
line ends with the C<\> character, the C<\> is ignored and the
following line is appended.  In this way you can break a long list of
argument over multiple "continuation" lines.

Arguments are separated by spaces.  However, you can include space in
an argument by surrounding the argument with double-quote (C<">)
characters.  A backslash (C<\>) followed by any other character is
interpreted as that character.  Thus, a literal C<"> or C<\> character
can be included as C<\"> or C<\\>, and an alternative to putting
double quotes around an argument with spaces is simply to put a C<\>
before each space.

If you change F<asmtpd.conf> while asmtpd is running, you must send it
a SIGHUP signal for it to read the new changes.  (Note, however, that
asmtpd will re-read the B<AliasFile>, B<DomainFile>, or
B<SPFHostsFile> automatically if you change these.)

The rest of this man page details the various directives.  Directives
are case-insensitive.  Depending on the directive, the arguments may
or may not be case sensitive.

=head2 GENERAL CONFIGURATION DIRECTIVES

=over

=item B<Separator> I<Character>

This is the only option that probably needs to be set at all sites.
I<Character> is a single character that separates usernames from the
rest of the local part of an email address.  For example, with
sendmail, mail for <name+extra@host.domain> is usually delivered to
user name.  Thus, a C<+> should be specified for I<Character>.  With
qmail, it is <name-extra@host.domain> that belongs to user name
(though routing is handled differently).  Thus, qmail users will want
to specify C<->.  The default is not to have a separator.  This is
probably wrong for most sites, but is a lot less bad than selecting
the wrong character!

=item B<Hostname> I<name>

C<Hostname> specifies the hostname that asmtpd should use in the SMTP
protocol.  Ordinarily, this name should map to the IP address of your
server (or one of the IP addresses of your server).  The default is to
use the local hostname (as returned by the C<gethostname> system
call), with the default DNS domain name appended if your hostname does
not include any C<.> characters.

=item B<LogPriority> I<priority>

This directive sets the priority with which diagnostic messages are
sent to the system log.  The default value is C<mail.info>.

=item B<EtcDir> I<directory>

Sets the directory in which asmtpd will search for various
configuration files, including F<aliases>, F<domains>, and F<spfhosts>
(see below), as well as four special rule files run under the
B<AvengerUser> UID:  F<default>, F<unknown>, F<secondary>, and
F<relay>.

The file F<unknown> consists of avenger rules that get run for any
local user that does not exist in the password file, or that exists
but has a UID of 0 (root), or that exists but has an invalid shell
(not listed in F</etc/shells>).  These rules are not run for normal
users, even if those users do not have a F<.avenger> directory.

The F<default> file consists of rules that are run after the rules in
F<unknown> or after the rules in a user's F<.avenger> directory, so
long as these rules did not immediately reject, defer, accept,
redirect, or bodytest the mail.  If a user does not have a F<.avenger>
directory, the rules in F<default> are always run.

The F<secondary> ruleset contains rules that are run if B<MxLocalRcpt>
has been set to 1, mail is received for I<user>B<@>I<hostname>, and
the mail server is an MX record for I<hostname>, but not the highest
priority MX record.  If the ruleset does not exist or simply exits,
the default is to spool the mail.

The F<relay> ruleset consists of rules that are run when mail is
received for I<user>B<@>I<hostname> where I<hostname> is not in the
F<domains> file (and, if B<MxLocalRcpt> is 1, the server is not an MX
record for I<hostname>).  In such circumstances, if the sender address
is local, asmtpd will first attempt to execute an appropriate C<mail>
(as opposed to the usual C<rcpt>) ruleset in the user's F<.avenger>
directory.  If that ruleset does not exist or simply exits, or
I<hostname> is not local, then asmtpd runs F<relay>.  If the rules in
F<relay> simply exit or the file does not exist, the default is to
reject the mail.

The default value of B<EtcDir> is F<@etcdir@>.

=back

=head2 NETWORK CONFIGURATION PARAMETERS

=over

=item B<BindAddr> I<IP-address> [I<port-no>]

C<BindAddr> specifies the IP address on which the server should
listen.  The default is 0.0.0.0 (INADDR_ANY), meaning to accept
incoming connections on any IP address.  By default the server uses
TCP port 25, but I<port-no> can be also specified to chose a different
port number.

=item B<MaxClients> I<val>

Specifies the maximum number of concurrent TCP connections from
clients that asmtpd should allow.  The default value is 60.

=item B<MaxConPerIP> I<val>

Specifies the maximum number of incoming TCP connections asmtpd should
accept from a single IP address.  The default value is 10.

=item B<SMTPFilter> I<prog>

Specifies the name of a program asmtpd can invoke to enable packet
filtering of incoming SYN packets from a particular IP address for the
SMTP port (25 by default).  Note that this program should filter only
TCP packets to the SMTP port that have the TCP SYN flag set and the
ACK flag cleared.  It is very important that this rule B<not>
interfere with previously established TCP connections, since asmtpd
uses this to block new connections when the per-IP-address limit has
been reached.

The program will be run three different ways:

=over

=item I<prog> B<clear>

=item I<prog> B<add> I<IP-addr>

=item I<prog> B<del> I<IP-addr>

=back

The B<clear> command should cause all previously filtered IP addresses
to be re-enabled.  The B<add> command says to add the particular IP
address to the list of filtered addresses.  B<del> says to remove an
IP address from the list of addresses.

Since the details of how to filter IP packets depend entirely on the
particular operating system and firewall software being run, this task
is best handled by a shell script written by the system administrator.
An example script for use with OpenBSD's pf packet filter can be found
in F<@sampledir@/smtp-filter.pf>.  An example for use with Linux's
iptables firewall can be found in F<@sampledir@/smtp-filter.iptables>.

=item B<MaxMsgsPerIP> I<msgs-per-hour> [I<msgs-max>]

Specifies the maximum rate at which asmtpd will allow successful SMTP
RCPT commands from a particular IP address.  After this limit is
reached, further RCPT commands will be rejected with a temporary SMTP
error code saying too much load.  I<msgs-per-hour> is the number of
RCPT commands per hour.  I<msgs-max> is the hard limit after which
further RCPTs are refused.  I<msgs-max>, if not specified, defaults to
the same value as I<msgs-per-hour>.  However, it can be set to a
greater value to accept bursts of traffic.

=item B<MaxErrorsPerIP> I<msgs-per-hour> [I<msgs-max>]

Similar to B<MaxMsgsPerIP>, except this parameter specifies the
maximum rate at which clients from a particular IP address can issue
SMTP commands that return errors.  If a client is issuing too many
commands that cause errors (as can often happen with spambots that
don't check the results of commands, or that relay spam through HTTP
proxies), asmtpd will temporarily filter new connections from that
client if B<SMTPFilter> has been specified.  Otherwise, it will
immediately shutdown any incoming new TCP connections from the client
with a temporary SMTP error code.

=item B<MaxMsgsPerUser> I<msgs-per-hour> [I<msgs-max>]

Specifies the maximum rate at which asmtpd will allow successful SMTP
RCPT commands from a particular authenticated user.  The name used for
the check is either the username from SASL authentication, or the
common name of the client certificate with SSL authentication.  With
this feature, you can prevent people who have legitimate relay
privileges from sending bulk mail, as might happen if a spammer
somehow stole a SASL password.

=item B<MaxRcpts> I<val>

Specifies the maximum number of recipients on a single message.  Once
this number is reached, asmtpd rejects further recipients with a
temporary SMTP error code, causing the sender to send a separate copy
of the message to the remaining recipients.  The default value is 5.
(Note that this limit does not apply to trusted clients.)

=item B<MaxRelayRcpts> I<val>

If I<val> is greater than the number of recipients specified for
B<MaxRcpts>, then this specifies a higher limit on the number of
recipients when recipients are accepted by the F<relay> script.

=item B<MaxMsgSize> I<bytes>

The largest mail message asmtpd should accept.  The default value is
104,857,600 (100 MBytes).

=item B<SMTPTimeout> I<seconds>

Determines how long asmtpd will keep an open connection from a client
while awaiting an SMTP command.

=item B<DataTimeout> I<seconds>

Determines how long asmtpd will keep an idle connection from a client
open while waiting for mail message contents (after the SMTP DATA
command).  It is advisable to set a reasonable B<DataTimeout> even if
B<SMTPTimeout> is short, so as not to force a client behind an
unreliable network connection to keep having to start over.

=item B<SMTPCB> [0|1]

If set to 1 (the default), asmtpd will attempt to verify the sender
address of mail messages by going through the initial steps of sending
back a bounce message, a technique known as an "SMTP callback."  If
the mail cannot get through, the B<SENDER_BOUNCERES> environment
variable will contain an SMTP error code, and B<MAIL_ERROR> will be
set to reject the mail by default.  The next several parameters
(B<ClientTimeout>, B<VrfyDelay>, B<VrfyCacheTime>, and
B<MaxRevClients>) control the behavior of SMTP callbacks, and have no
effect when B<SMTPCB> is set to 0.

=item B<ClientTimeout> I<seconds>

Specifies the SMTP timeout for asmtpd when it acts as an SMTP client,
probing remote servers to check the validity of the sender address on
incoming mail messages.  The default value is 300.

=item B<VrfyDelay> I<seconds>

When probing a remote SMTP server to validate an email address, asmtpd
will keep the TCP connection open at least this long (after sending an
HELO/EHLO command) before probing the address.  The idea is to make
bulk mailing harder by preventing remote servers from validating more
than a few thousand (or a few tens of thousands of) email addresses
per second.  The default value for I<seconds> is 2.

=item B<VrfyCacheTime> I<seconds>

If asmtpd probes a remote server and discovers that it cannot send
bounce messages to an address, it caches the result for this amount of
time.  If someone is mailbombing an asmtpd server from a forged
address, this option prevents asmtpd from initiating too many
connections to the forgery victim's mail server.  (Of course, if the
victim publishes an SPF record, asmtpd will never contact the server
and this is not an issue.)  The default vaule for I<seconds> is 300.

=item B<MaxRevClients> I<val>

The number of idle reverse SMTP connections (to remote SMTP servers)
to cache when not in use.  These connections are used to validate
sending addresses of received mail.  This number is approximate.

=item B<SynFp> [0|1]

If set to 0, disables the collection of SYN fingerprint information,
which asmtpd ordinarily includes in headers of mail messages and in
the B<CLIENT_SYNFP> environment variable of avenger processes.  The
default value is 1.

=item B<SynFpWait> I<msec>

Sets the number of milliseconds after accepting a TCP connection that
asmtpd should wait to receive the full SYN packet from the packet
filter (bpf) device.  If the time is exceeded, no SYN fingerprint will
be recorded for the connection.  The default value is 500.

=item B<SynFpBuf> I<count>

Sets the maximum number of SYN fingerprints to keep around while
waiting for the corresponding connections.  The default value is 100.

=item B<SynOsMTU> I<size>

Sets an additional size to try for the network's maximum transmission
unit (MTU) when guessing the client operating system.  If I<size> is
set to 0, asmtpd will only try the value in the TCP MSS option + 40
bytes.  (Otherwise, when I<size> is non-zero, asmtpd tries both MSS +
40 and I<size>.)  The default for I<size> is 1500.

=item B<NetPath> [0|1]

If set to 0, disables the collection of IP "traceroute" information,
which is normally included in the headers of mail messages and in the
B<CLIENT_NETPATH> environment variable of avenger processes.  The
default value is 1.

=back

=head2 MAIL PROCESSING DIRECTIVES

=over

=item B<TrustedNet> I<IP-addr>B</>I<len>

If the first I<len> bits of a client's IP address match I<IP-addr>,
the client will be considered trusted.  Trusted clients can relay mail
through asmtpd to arbitrary addresses, and do not undergo any checks
or processing by any avenger scripts.  This option can be given
multiple times to list multiple networks.

=item B<TrustedDomain> I<domain>

If a client's verified DNS name is I<domain> or ends B<.>I<domain>,
the client will be considered trusted, and as described above will be
allowed to relay mail unchecked.  This option can be given multiple
times to list multiple domains.

=item B<SASL> [0|1|2]

This option only exists if asmtpd has been compiled with SASL support
(via the B<--enable-sasl> option to C<configure>).  If set to 0 (the
default), the AUTH SMTP verb is disabled, and asmtpd performs no SASL
authentication.  If set to 1, asmtpd performs SASL authentication when
requested by clients, but does not inherently trust SASL-authenticated
users.  You must check the B<AUTH_USER> environment variable in the
system-wide F<relay> script and explicitly permit users to relay mail.

If B<SASL> is set to 2, then clients that have authenticated via SASL
can relay mail just like B<TrustedNet> and B<TrustedDomain>
machines--no further scripts are run.  However, the authenticated user
name is still recorded in the Received: header to track abuse, and
B<MaxMsgsPerUser> is still enforced to prevent bulk mailing.  2 is a
reasonable value for ordinary usage, since users without permission to
relay mail have no reason to be listed in the SASL database file.

For more information on SASL, see the SASL home page at
L<http://asg.web.cmu.edu/sasl/>.

=item B<MxLocalRcpt> [0|1]

If set to 1, asmtpd will accept mail for I<user>B<@>I<host> even if
I<host> does not appear in B<DomainFile>, as long as the local
server's IP address corresponds to one of the DNS MX records for
I<host>.  Decisions about accepting mail will be made by the policies
in the file F<secondary> in B<EtcDir>.

=item B<AvengerUser> I<username>

Specifies the user in the password file whose identity asmtpd should
assume when running system-wide default rules, as well as the mail
injection program specified by B<Sendmail>.  The default value is
C<avenger>.  Note that for efficiency, asmtpd will cache the user and
group IDs of this user.  If for instance, you change the
B<AvengerUser>'s group membership, you will have to send asmtpd a
SIGHUP signal (or restart it).

=item B<Sendmail> I<program> [I<arg> ...]

Specifies the program to run to inject new mail messages into the
system.  The default value is:

    sendmail -oi -os -oee

Whatever arguments you give, asmtpd will additionally supply the
sender and recipient(s) by appending the following options:

=over

-f I<sender> -- I<recipient-1> [I<recipient-2> ...]

=back

The B<-oee> flag tells sendmail always to exit cleanly even if it
generated a bounce message.  Without it, sometimes sendmail generates
a bounce for a message and exits with an error code, which would cause
asmtpd to generate an error despite the fact that the message has
already been bounced.  This results in multiple bounces for the same
message.

Note that some sendmail replacements (including Exim) do not support
the B<-oee> flag.  However, these systems typically behave correctly
even without the B<-oee> flag, meaning their sendmail programs exit
cleanly if and only if the sender no longer needs to worry about the
message.  If your sendmail executable rejects the argument B<-oee>,
try using B<-oem> instead.

=item B<EmptySender> I<sender>

In some old versions of sendmail, running

    sendmail -f ''

(where '' is a zero-length argument) does not produce an empty
envelope sender, as should happen for bounces.  B<EmptySender> lets
you specify an alternate sender to use for the empty envelope sender.
Try using the single-character string C<@>--that seems to produce the
desired envelope sender (which turns into MAILER-DAEMON) with both old
and new versions of sendmail, though it is not necessarily compatible
with other MTAs.

=item B<SendmailPriv> [0|1]

By default, asmtpd drops privilege to run B<Sendmail> as
B<AvengerUser>.  If, however, you specify B<SendmailPriv 1>, asmtpd
will instead run B<Sendmail> as root.  One possible use of this, for
users of the sendmail MTA, is to invoke sendmail with the B<-Am> flag,
which requires root privileges but bypasses an extra level of queuing.
(Note that with newer versions of sendmail, if you do not run sendmail
as a daemon on address 127.0.0.1, you will have to configure asmtpd to
use the B<-Am> flag.)

=item B<SendmailFromLine> [0|1]

If you set this value to 1, the message fed to the B<Sendmail> program
will start with a UNIX mailbox style "From " line (which is not
actually part of the message header).  The default value is 0.

=item B<AliasFile> I<path>

Specifies the path of the user-mapping file, which by default is
the file F<aliases> in the directory specified by B<EtcDir>.  Each
line of this file is of the form:

=over

I<prefix>B<:> I<replacement>

=back

Before deciding which user's rules to process for a particular mail
message, the local part of the email address is transformed based on
the aliases file.  An address of I<prefix> is replaced by the
I<replacement>.  In addition, if the B<Separator> character has been
defined, then if an address begins with I<prefix> followed immediately
by the separator character, I<replacement> is also substituted.  If
the alias file contains multiple matching prefixes, the longest one is
chosen.  Alias substitution continues recursively unless a loop is
detected or the recursion reaches a depth of 20.

Note:  It is important to emphasize that the aliases mechanism only
governs which user checks the validity of a particular piece of mail.
It does not affect where the mail is eventually delivered, should the
resulting rules accept the mail.

=item B<DomainFile> I<path>

Specifies the path of the domain-mapping file, which by default is the
file F<domains> in the directory specified by B<EtcDir>.  This file
allows one to map responsibility for all users in a domain onto a
particular local user.  Each line of the file must have one of the
following forms:

=over

=item S<    >I<domain>B<:>

=item S<    >I<domain>B<:> I<user>

=item S<    >I<domain>B<:> I<user>I<SEPARATOR>

=back

In the first case, when receiving mail for I<local>B<@>I<domain>, the
local part I<local> is simply taken as is and treated as a local
username (with the first separator character and anything following
removed).  In the second case, the mail is checked by I<user> instead.
In the third case, I<SEPARATOR> is the separator character, which must
have been declared with a B<Separator> directive.  Here, I<user> and
the separator character are pre-pended to I<local>.  For instance, if
I<SEPARATOR> is B<->, the mail would be checked by
I<user>B<->I<local>.  In all cases, the result of the mapping is
subject to alias substitution as described for B<AliasFile>.

Note:  As with B<AliasFile>, the domain mechanism only governs which
user checks the validity of a particular piece of mail.  It does not
affect where the mail is eventually delivered, should the resulting
rules accept the mail.

=item B<Env> I<var>[B<=>I<value>]

Specifies an environment variable to supply when running avenger.
Ordinarily, avenger is run with a clean environment, with only a few
variables such as B<PATH> passed through.  If the B<Env> directive
specifies a value, the environment variable will be be set to this
value.  If B<=>I<value> is omitted, asmtpd will pass through the value
of the environment variable it inherits, or leave the variable unset
if it is not set in the environment in which asmtpd is run.

=item B<AvengerMaxPerUser> I<val>

Specifies how many concurrent avenger processes to launch for a
particular user.  If a particular user already has this many avenger
processes running, and another SMTP client issues an RCPT command that
resolves to the same local user (or another local user with the same
numeric UID), then asmtpd will wait for one of the existing avenger
processes to exit before launching a new avenger to evaluate the new
RCPT command.  The default for I<val> is 5.  This limit does not apply
to the system-wide F<unknown>, F<default>, and F<relay> files
processed under the B<AvengerUser> UID.  (Note that bodytests run for
a particular user are also included in that user's count of avenger
processes.)

=item B<AvengerTimeout> I<seconds>

Specifies a timeout value after which asmtpd will attempt to kill an
avenger process, in case the process has somehow gotten stuck.  asmtpd
does this, before launching avenger, by setting an alarm for the
process.  The default for I<seconds> is 600.

=item B<NoCheck> I<user>[<@>I<host>]

Specifies that asmtpd's internal checks for email validity should be
bypassed for email to a particular email address.  If I<host> is not
specified, then this applies to I<user> at any acceptable local host
(asmtpd still will not allow relaying, of course).  It is a good idea
to enable this for usernames specified in RFC 2142, such as
B<postmaster> and B<abuse>.

=item B<RBL> [B<-i>] [B<-p>] [B<-f>] B<-s> I<score> I<domain>

Checks real-time blackhole list I<domain>.  If B<-i> is present, looks
up the client's IP address reversed (i.e., for client 1.2.3.4, this
will match when DNS name 4.3.2.1.I<domain> exists).  If B<-p> is
present, the name of the client (as specified by a verified PTR DNS
record) will be looked up.  If B<-f> is present, the hostname from the
envelope sender (the address in the SMTP MAIL) command will be looked
up (i.e., mail from I<user>B<@>I<host> matches if I<host>B<.>I<domain>
exists).  If none of B<-i>, B<-p>, or B<-f> is specified, B<-i> is
assumed by default. 

I<score> is an integer (which can be negative).  The scores of all
matching RBLs are added together, and a message is rejected if the
total is greater than or equal to 100.

=item B<UserMail> [0|1]

If set to 0, asmtpd will not chack F<mail*> files in users'
F<.avenger> directories, but will always use the system-wide F<relay>
file (and F<secondary> file) to decide whether to relay mail.  The
default value is 0.

=item B<UserRcpt> [0|1]

If set to 0, asmtpd will not chack F<rcpt*> files in users'
F<.avenger> directories, but will always use the system-wide
F<default> file.  The default value is 1.

=item B<AllowPercent> [0|1]

If set to 0 (the default), asmtpd will reject any email whose local
part contains a C<%> character.  This is because many MTAs will relay
mail for users of the form B<user%host1@host2> to B<user@host1>.
While of course it is possible to reject such messages with the
F<@etcdir@/unknown> file, it is easy to forget to do so.  Failing to
do so can get your site listed in various spam source lists, which
will have some serious consequences.  For that reason, B<AllowPercent>
is 0 by default.  Set it to 1 if you really do want mail for users
with C<%> characters.

=item B<AllowDNSFail> [0|1|2]

Upon accepting a connection from a client, asmtpd attempts to resolve
the client's IP address to a hostname.  If a temporary DNS error
occurs and B<AllowDNSFail> is set to 0 (the default), asmtpd will
reject the connection immediately.  If B<AllowDNSFail> is set to 1,
however, then asmtpd will accept the connection and continue.
However, in this case that the B<CLIENT_DNSFAIL> environment variable
will be set to an error message, and mail will still be rejected by
default unless an rcpt script explicitly calls B<accept>.  If
B<AllowDNSFail> is set to 2, then B<CLIENT_DNSFAIL> will still be set,
but by default mail will be accepted unless explicitly rejected.

Note that this option has no effect on IP addresses that don't resolve
to a domain name (e.g., where a lookup of the in-addr.arpa domain
returns an empty result or the NXDOMAIN error).

=back

=head2 SSL CONFIGURATION PARAMETERS

=over

=item B<SSL> [0|1|2]

This and the following options are supported if Mail Avenger has been
compiled with support for the STARTTLS command (using the
B<--enable-ssl> option to C<configure>).  If B<SSL> is set to 0, then
the STARTTLS command will be disabled.

If B<SSL> is set to 1 (the default), then STARTTLS will be enabled
profiled the private key and certificate files can be found.  (Since
these files will not exist by default, STARTTLS is still disabled by
default.)  Relaying based on client certificates can be enabled by
checking the B<SSL_ISSUER> and B<SSL_SUBJECT> environment variables in
the F<relay> script.

If B<SSL> is set to 2, then authentication with I<any> valid client
certificate will allow mail relaying with no further checks.  This
value makes sense only if your organization runs a private certificate
authority and you only place your local CA key in the B<SSLCAcert>
file, as otherwise you will have no control over who can relay mail
through your machine.

=item B<SSLCAcert> I<path>

B<SSLCAcert> specifies the certificate authorities allowed to sign
client certificates.  I<path> must be a file containing one or more
trusted CA certificates in PEM format.  If <path> is not an absolute
path name, asmtpd will look for the file in B<EtcDir>.  The default
I<path> is F<cacert.pem>.

=item B<SSLCRL> I<path>

If SSL is in use, I<path> specifies a PEM-format certificate
revocation list.  The default value is F<crl.pem>.

=item B<SSLkey> I<path>

If SSL is in use, I<path> specifies a PEM-format file containing the
server's private key.  If the file is not present, the STARTTLS
command will be disabled.  The default I<path> is F<privkey.pem>.

=item B<SSLcert> I<path>

If SSL is in use, I<path> specifies a PEM-format file containing a
certificate for the public key corresponding to private key B<SSLkey>.
If the file is not present, the STARTTLS command will be disabled.
The default I<path> is F<cert.pem>.

=item B<SSLciphers> I<string>

I<string> specifies the preference for ciphers with SSL.  For example,
to allow all ciphers except anonymous Diffie-Hellman, low key sizes,
exportable ciphers, and MD%-based MAC, and to sort ciphers by
strength, you might use the following I<string>>:

        ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH

By default, asmtpd just uses the OpenSSL library's default cipher
preferences.


=back

=head2 SPF CONFIGURATION PARAMETERS

=over

=item B<SPFfail> [I<SPF-rule> ...]

SPF (Sender Policy Framework) is a mechanism to prevent forgery of
email sender addresses.  (More information is available at
L<http://www.openspf.org/> and in the forthcoming RFC 4408.)  asmtpd
always runs SPF checks on incoming email.  An SPF check returns one of
seven possible results:  B<none>, B<neutral>, B<pass>, B<fail>,
B<softfail>, B<error>, or B<unknown>.  asmtpd will reject mail if the
result is B<fail> (and defer mail if the result is B<error>).

The SPFfail directive provides a second chance to mail that would
otherwise resolve to B<fail>.  If SPF rules are provided with this
directive, and the SPF check on a message resolves to B<fail>, then
asmtpd will re-evaluate the message with the rules from the SPFfail
directive.  If the SPFfail rules evaluate to B<none>, B<neutral>, or
B<unknown>, then the original B<fail> result will remain.  Otherwise,
the result of the SPFfail rules overrides the B<fail> result.

This directive can be used to work-around the problem of sites, such
as evite.com, that forge email, but do not actually send spam.
L<trusted-forwarder.org> maintains a white-list of such sites, and it
is highly recommended that you use this whitelist until SPF is more
widely deployed.  To do so, you can use the configuration line:

	SPFfail include:spf.trusted-forwarder.org

=item B<SPFnone> [I<SPF-rule> ...]

This directive is similar to SPFfail, but supplies additional SPF
rules to be run in the event that the SPF result for a message
resolves to B<none>--meaning that the domain from which the mail comes
does not publish an SPF record.  One possible use might be the
following:

    SPFnone a/24 mx/24 ptr

This rule says that if the sending domain does not publish an SPF
record, consider its result to be B<pass> nonetheless as long as the
sending host shares a 24-bit IP prefix with the address of the domain,
or the address of any of the mail exchangers (DNS MX records) for the
domain, or if the domain name of the sending machine has the sender
domain name as a suffix.

=item B<SPFlocal> [I<SPF-rule> ...]

Unlike the previous two rules, which provide hooks to run after an SPF
result has been determined, SPFlocal supplies SPF rules to be run
before even attempting SPF rules for the domain.  If the local rules
return B<pass>, B<fail>, B<softfail>, or B<error>, this reult becomes
the SPF result for the message.  Otherwise, asmtpd evaluates the
appropriate rules for the domain as usual.

An example use might be to reject mail from a real-time black hole
list (RBL), such as spamcop:

    SPFlocal -exists:%{ir}.bl.spamcop.net

=item B<SPFexp> [I<explanation> ...]

Provides a default explanation for an SPF failure, if the sender
domain does not have one.  The default is:

    SPFexp See http://www.openspf.org/why.html?sender=%{S}&ip=%{I}

=item B<SPFHostsFile> I<path>

This specifies the pathname of a file that contains "fallback" SPF
records for domains that fail to supply SPF records themselves.  This
file effectively achieves the same result as B<SPFNone>, but on a
per-hostname basis.  The default I<path> is F<spfhosts> in the
directory specified by B<EtcDir> (or F<@etcdir@> by default).  Each
line of the file has the form:

=over

I<domain>B<:> I<SPF-rules>

=back

I<domain> is the domain name for which the I<SPF-rules> apply.  If
I<domain> starts with a C<.>, then the rule matches all host names
with I<domain> as a suffix.  In other words, C<.yahoo.com> matches
C<mail.yahoo.com>, C<mx.yahoo.com>, but not C<yahoo.com>.  Note that
if a domain publishes an SPF record through DNS, the record in DNS
overrides the record specified in this file.

As an example, suppose Microsoft does not publish an SPF record in
DNS, but you happen to know that all mail from users at
C<microsoft.com> comes from machines whose reverse DNS mapping ends
either C<microsoft.com> or C<msft.com>, or else whose IP addresses
share a 16-bit prefix with one of the mail exchangers for
C<microsoft.com>.  You might place the following line in your
F<spfhosts> file:

        microsoft.com: ptr ptr:msft.com mx/16 ~all

Here C<~all> resorts to B<softfail> when the sender does not match,
which tags the message but does not reject it.  Use C<-all> to reject
the mail outright.  Note that if Microsoft ever starts publishing an
SPF record in DNS, it will override the above line.

=back

=head2 DEBUG PARAMETERS

=over

=item B<DebugSMTP> [0|1]

When set to 1, causes asmtpd to log a complete trace of all SMTP
traffic to and from connecting clients.  Produces a large amount of
data, but can be useful for debugging.  Each trace line list the name
of the connecting client and asmtpd's file descriptor number in
parentheses.

=item B<DebugSMTPc> [0|1]

When receiving mail, asmtpd connects to remote mail servers to ensure
the envelope sender addresses of incoming messages are valid email
addresses, and in particular that they can receive bounces.  When
B<DebugSMTPc> is set to 1, all outgoing SMTP connection traffic from
SMTPc is logged.  The output format is similar to B<DebugSMTP>, but
file descriptor numbers are prefixed with C<R> to indicate this is a
reverse connection.

=item B<DebugAvenger> [0|1]

Prints a trace of input and output to all avenger processes run.  The
name also has a file descriptor number prefixed with C<a> for avenger.

=back

=head1 FILES

=over

=item F<@etcdir@/asmtpd.conf>

default location of file

=item F<@etcdir@>

default for B<EtcDir>, location of other configuration files

=item F<aliases>, F<domains>, F<spfhosts>

see the descriptions of B<AliasFile>, B<DomainFile>, and
B<SPFHostsFile> above

=item F<unknown>, F<default>, F<secondary>, F<relay>

avenger rules to be run by the B<AvengerUser> under different
circumstances; see the description of B<EtcDir> above, and the manual
page for L<avenger(1)|avenger(1)>

=item F<@piddir@/asmtpd.pid>

File containing the process ID of a running asmtpd process.  You must
send this process a SIGHUP signal for it to re-read the F<asmtpd.conf>
file.

=item F<@sampledir@/asmtpd.conf>

=item F<@sampledir@/unknown>

Example configuration files.

=item F<@sampledir@/smtp-filter.pf>

=item F<@sampledir@/smtp-filter.iptables>

Example scripts for the B<SMTPFilter> directive.


=head1 SEE ALSO

L<asmtpd(8)|asmtpd(8)>,
L<avenger(1)|avenger(1)>

The Mail Avenger home page: L<http://www.mailavenger.org/>.

=head1 AUTHOR

David MaziE<egrave>res