path: root/qmail-smtpd.8

.TH qmail-smtpd 8
.SH NAME
qmail-smtpd \- receive mail via SMTP
.SH SYNOPSIS
.B qmail-smtpd
[
.I hostname
.I checkprogram
.I subprogram
]
.SH DESCRIPTION
.B qmail-smtpd
receives mail messages via the Simple Mail Transfer Protocol (SMTP)
and invokes
.B qmail-queue
to deposit them into the outgoing queue.
.B qmail-smtpd
must be supplied several environment variables;
see
.BR tcp-environ(5) .

If the environment variable
.B SMTPS
is non-empty,
.B qmail-smtpd
starts a TLS session (to support the deprecated SMTPS protocol,
normally on port 465). Otherwise,
.B qmail-smtpd
offers the STARTTLS extension to ESMTP.

.B qmail-smtpd
is responsible for counting hops.
It rejects any message with 100 or more 
.B Received
or
.B Delivered-To
header fields.

.B qmail-smtpd
supports ESMTP, including the 8BITMIME, PIPELINING, and AUTH options.

.B qmail-smtpd
can accept LOGIN, PLAIN, and CRAM-MD5 AUTH types.  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 qmail-smtpd ,
effectively setting the environment variables RELAYCLIENT and TCPREMOTEINFO
(any supplied value replaced with the authenticated username).
.B qmail-smtpd
will reject the authentication attempt if it receives a nonzero return
value from
.I checkprogram
or
.IR subprogram .
.SH TRANSPARENCY
.B qmail-smtpd
converts the SMTP newline convention into the UNIX newline convention
by converting CR LF into LF.
It returns a temporary error and drops the connection on bare LFs;
see
.BR http://pobox.com/~djb/docs/smtplf.html .

.B qmail-smtpd
accepts messages that contain long lines or non-ASCII characters,
even though such messages violate the SMTP protocol.
.SH "CONTROL FILES"
.TP 5
.I badmailfrom
Unacceptable envelope sender addresses.
.B qmail-smtpd
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 ,
meaning every address at
.IR host .

.TP 5
.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 5
.I clientcrl.pem
A list of Certificate Revocation Lists (CRLs). If present it
should contain the CRLs of the CAs in
.I clientca.pem
and client certs will be checked for revocation.

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

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

If the environment variable
.B DATABYTES
is set, it overrides
.IR databytes .

.TP 5
.I dh2048.pem
If these 2048 bit DH parameters are provided,
.B qmail-smtpd
will use them for TLS sessions instead of generating one on-the-fly
(which is very timeconsuming).
.TP 5
.I dh2048.pem
2048 bit counterpart for
.B dh2048.pem.

.TP 5
.I localiphost
Replacement host name for local IP addresses.
Default:
.IR me ,
if that is supplied.
.B qmail-smtpd
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 5
.I morercpthosts
Extra allowed RCPT domains.
If
.I rcpthosts
and
.I morercpthosts
both exist,
.I morercpthosts
is effectively appended to
.IR rcpthosts .

You must run
.B qmail-newmrh
whenever
.I morercpthosts
changes.

Rule of thumb for large sites:
Put your 50 most commonly used domains into
.IR rcpthosts ,
and the rest into
.IR morercpthosts .
.TP 5
.I rcpthosts
Allowed RCPT domains.
If
.I rcpthosts
is supplied,
.B qmail-smtpd
will reject
any envelope recipient address with a domain not listed in
.IR rcpthosts .

Exception:
If the environment variable
.B RELAYCLIENT
is set,
.B qmail-smtpd
will ignore
.IR rcpthosts ,
and will append the value of
.B RELAYCLIENT
to each incoming recipient address.

.I rcpthosts
may include wildcards:

.EX
   heaven.af.mil
   .heaven.af.mil
.EE

Envelope recipient addresses without @ signs are
always allowed through.

.TP 5
.I rsa512.pem
If this 512 bit RSA key is provided,
.B qmail-smtpd
will use it for TLS sessions instead of generating one on-the-fly.

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

.TP 5
.I smtpgreeting
SMTP greeting message.
Default:
.IR me ,
if that is supplied;
otherwise
.B qmail-smtpd
will refuse to run.
The first word of
.I smtpgreeting
should be the current host's name.
.TP 5
.I timeoutsmtpd
Number of seconds
.B qmail-smtpd
will wait for each new buffer of data from the remote SMTP client.
Default: 1200.

.TP 5
.I tlsclients
A list of email addresses. When relay rules would reject an incoming message,
.B qmail-smtpd
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 5
.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.

.SH "SEE ALSO"
tcp-env(1),
tcp-environ(5),
qmail-control(5),
qmail-inject(8),
qmail-newmrh(8),
qmail-queue(8),
qmail-remote(8)
.SH "HISTORY"
The patch enabling the ESMTP AUTH option is not part of the standard
qmail-1.03 distribution.