.\"TOPICS "Topics:"
.TH Qsmtpd 8 "December 2008" "Qsmtp Version @QSMTP_VERSION_MAJOR@.@QSMTP_VERSION_MINOR@@QSMTP_VERSION_EXTRAVERSION@" "Qsmtpd"
.SH NAME
Qsmtpd \- receive mail via (E)SMTP
.SH SYNOPSIS
.B Qsmtpd
[
.I hostname
.I checkprogram
.I subprogram
]
.SH DESCRIPTION
.B Qsmtpd
behaves more or less like
.B qmail-smtpd(8)
, but adds better spam filtering capabilities, better RfC compliance, IPv6 support and more SMTP extensions
out-of-the-box.

.B Qsmtpd
receives mail messages via the Simple Mail Transfer Protocol (SMTP)
and invokes
.B qmail-queue
to deposit them into the outgoing queue.
.B Qsmtpd
must be supplied several environment variables;
see
.BR tcp-environ(5) .

.B Qsmtpd
accepts messages sent as SMTP or ESMTP. The extensions ENHANCEDSTATUSCODES, PIPELINING, 8BITMIME and SIZE 
are always announced in ESMTP mode. CHUNKING is also announced if it has been enabled at compile time. If 
.IR hostname
, 
.IR checkprogram
and 
.IR subprogram
arguments are present and 
.IR checkprogram
exists the AUTH extension is announced. If a TLS certificate is present the STARTTLS extension is also announced.

.B Qsmtpd
counts the number of Recevied:-lines in the mail header.
It rejects any message with 100 or more
.B Received:
header fields.

.B Qsmtpd
can accept LOGIN, PLAIN, and CRAM-MD5 AUTH types.  They can be limited
using the
.IR authtypes
file. It invokes
.IR checkprogram ,
which reads on file descriptor 3 the username, a 0 byte, the password
or challenge derived from
.IR hostname ,
another 0 byte, a CRAM-MD5 response (if applicable to the AUTH type),
and a final 0 byte.
.I checkprogram
invokes
.I subprogram
upon successful authentication, which should in turn return 0 to
.BR Qsmtpd .
.B Qsmtpd
will reject the authentication attempt if it receives a nonzero return
value from
.I checkprogram
or
.IR subprogram .
.SH TRANSPARENCY
.B Qsmtpd
converts the SMTP newline convention into the UNIX newline convention
by converting CR LF into LF.
It returns a permanent error on bare CRs or LFs as well as lines with
more than 1000 characters. Messages that contain non-ASCII characters are
rejected if the client announced the message to be pure ASCII or if the
connection is not in ESMTP mode.

.SH RECIPIENTS
.B Qsmtpd
tries to figure out if local recipients or sender addresses exist. All addresses
that fail this check will be rejected. These tests only work for virtual domains
(e.g. created by vpopmail), local users will not be checked.

.SH "CONTROL FILES"

These files are used for configuring several aspects of
.B Qsmtpd
. Some of them may also be present in the recipient or recipient domain directory
if the domain is controlled by vpopmail. In this case the more local file overrides
the global files. Only files marked with
.I (user)
can be used in user or domain directories.

.TP 4
.I authtypes
A list of all auth types that should be announced. Empty lines and lines beginning
with # are ignored.

.TP 4
.I badmailfrom
.B (user)
Unacceptable envelope sender addresses.
.B Qsmtpd
will reject every recipient address for a message
if the envelope sender address is listed in
.IR badmailfrom .
A line in
.I badmailfrom
may be of the form
.BR @\fIhost\fR ,
meaning every address at
.IR host .
If an entry does not contain a '@' the domain and all subdomains
are rejected.

.EX
    example.com
.EE

would block emails from *@example.com as well as *@*.example.com.
In contrast if the entry does not contain a '@' and begins with '.'
only subdomains will be blocked:

.EX
    .example.org
.EE

would block emails from *@*.example.org, but *@example.org would pass.

.TP 4
.I badcc
.B (user)
Unacceptable CC addresses.
.B Qsmtpd
will reject mails where a recipient address that matches an expression
in this file is already present. The format of the file is the same as for 
.IR badmailfrom .

.TP 4
.I clientca.pem
A list of Certifying Authority (CA) certificates that are used to verify
the client-presented certificates during a TLS-encrypted session.

.TP 4
.I databytes
Maximum number of bytes allowed in a message,
or 0 for no limit.
Default: 0.
If a message exceeds this limit,
.B Qsmtpd
returns a permanent error code to the client;
in contrast, if
the disk is full or
.B Qsmtpd
hits a resource limit, a temporary error code is retuned.

.I databytes
counts bytes as stored on disk, not as transmitted through the network.
It does not count the
.B Qsmtpd
Received line, the
.B qmail-queue
Received line, or the envelope.

.TP 4
.I localiphost
Replacement host name for local IP addresses.
Default:
.IR me ,
if that is supplied.
.B Qsmtpd
is responsible for recognizing dotted-decimal addresses for the
current host.
When it sees a recipient address of the form
.IR box@[d.d.d.d] ,
where
.I d.d.d.d
is a local IP address,
it replaces
.IR [d.d.d.d]
with
.IR localiphost .
This is done before
.IR rcpthosts .

.TP 4
.I rcpthosts
Allowed RCPT domains.
If
.I rcpthosts
is supplied,
.B Qsmtpd
will reject
any envelope recipient address with a domain not listed in
.IR rcpthosts .

.I rcpthosts
may include wildcards:

.EX
   example.org
   .example.com
.EE

The only allowed envelope recipient address without @ sign is postmaster.

.TP 4
.I rsa512.pem
If this 512 RSA key is provided,
.B Qsmtpd
will use it for TLS sessions instead of generaring one on-the-fly.

.TP 4
.I servercert.pem
SSL certificate to be presented to clients in
TLS-encrypted sessions. Certifying Authority
(CA) and intermediate certificates can be added at the end of the file.

.TP 4
.I timeoutsmtpd
Number of seconds
.B Qsmtpd
will wait for each new buffer of data from the remote SMTP client.
Default: 1200.

.TP 4
.I tlsclients
A list of email addresses. When relay rules would reject an incoming message,
.B Qsmtpd
can allow it if the client presents a certificate that can be verified against
the CA list in
.I clientca.pem
and the certificate email address is in
.IR tlsclients .

.TP 4
.I tlsserverciphers
A set of OpenSSL cipher strings. Multiple ciphers contained in a
string should be separated by a colon. If the environment variable
.B TLSCIPHERS
is set to such a string, it takes precedence.

.TP 4
.I filterconf
.B (user)
Configures several binary or integer settings. See filterconf(5).

.TP 4
.I forcesslauth
If file contents is a number and not 0, AUTH extension will only be announced
if STARTTLS has been sent by client before and succeeded.

.TP 4
.I vpopbounce
A .qmail-default file with the same contents as this file will be used as sign
that this recipient does not exist. Normally vadddomain(5)

.TP 4
.I rspf
.B (user)
If a domain does not specify a SPF record check for TXT records for this
.I remote SPF 
lists.

.I MAIL FROM:<foo@example.com>
and a rspf containing the line 

.EX
   rspf.example.org
.EE

would cause a DNS TXT lookup for 
.IR example.com.rspf.example.org .
If this query returns a valid SPF string this will be taken as if example.com had this entry itself.

.TP 4
.I spfstrict
.B (user)
List of domains where every mail not explicitely allowed by SPF will be rejected. This means if the 
domain has a SPF entry ending with "~all" the mail will be blocked.

.TP 4
.I spfignore
.B (user)
List of hosts that are known to forward mail to us. Mails from this host will never be blocked because 
of SPF entries.

.TP 4
.I spffriends
List of hosts where no SPF checks will be done at all, neither there will be a \fIReceived-SPF:\fR-line. 
Matches in this file will override \fIspfstrict\fR.

.TP 4
.I wildcardns
A list of top level domains and their wildcard NS entries. Format is "TLD_IPv6address", where TLD is
the name of the top level domain (without leading dot) and IPv6address is an IPv6 literal. There are
no spaces allowed anywhere in a line containing an entry, but normal comments (lines beginning with #,
empty lines) are allowed. If a TLD has multiple wildcard entries use multiple lines with the same TLD
name and one entry each.

.TP 4
.I authhide
If this file contains a positive integer number the name and IP address of the sending host will not
be written to the \fIReceived:\fR line in the mail body if the client is authenticated. Use this if
your users want some extra privacy.

.TP 4
.I nomail
.B (user)
Reject all mail to this user with the given message. If the file exists but is empty a general
rejection message will be announced. The message may start with a rejection code like:

.EX
550 5.7.1
.EE

The rejection code must be of the form given in the example. The first digit of both blocks must match, 
all other digits may be of any value. The two blocks must be separated by exactly one space. After the 
second block must be at least one more space.

If the code does not match this requirements or is not found at all the code given in the example will be 
used. The rejection line may be of any length, the message will be folded if necessary. The file may contain 
comments, but only one valid line.

.TP 4
.I relayclients

Holds a list of IPv4 addresses allowed for relaying. Every address is followed by a netmask length specifying
if a whole network is allowed to relay. Use the
.B addipbl
command to add new entries to this file.

.TP 4
.I relayclients6
Works the same as
.IR relayclients ,
but for IPv6 addresses.

.SH RELAYING

By default
.B Qsmtpd
does not allow relaying. Contrary to
.B qmail-smtpd
it will not look at the
.I RELAYCLIENT
environment variable.

Relaying is permitted in one of two cases: the user has authenticated himself using SMTP AUTH or a SSL client
certificate, or the IP address of the client is found in one of the
.I relayclients
or
.I relayclients6
control files (see above).

.SH DEBUGGING
If
.B Qsmtpd
has been with the
.I DEBUG_IO
flag the contents of the SMTP transmissions can be recorded. They will
be sent to the syslog daemon with facility mail and log level debug. The contents of the SMTP DATA phase will
never be logged for privacy reasons.

Logging is not enabled by default. If
.B Qsmtpd
finds an environment variable
.I QSMTPD_DEBUG
with a non-empty
value or a file
.I control/Qsmtpd_debug
exists on startup it will log. Therefore it will usually not harm to
compile that facility into the program.

.SH "SEE ALSO"
tcp-env(1),
filterconf(5),
tcp-environ(5),
qmail-control(5),
qmail-inject(8),
qmail-queue(8),
qmail-smtpd(8)
.SH AUTHOR
Rolf Eike Beer
.SH WEBSITE
http://opensource.sf-tec.de/Qsmtp/