SYNOPSIS

       qmail-smtpd [ checkprogram subprogram ]



DESCRIPTION

       qmail-smtpd  receives mail messages via the Simple Mail Transfer	Proto-
       col (SMTP) and invokes qmail-queue to deposit them  into	 the  outgoing
       queue.	qmail-smtpd  must  be  supplied	with several environment vari-
       ables; see tcp-environ(5).

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

       qmail-smtpd supports ESMTP and offers 8BITMIME, DATA, PIPELINING, SIZE,
       AUTH, and STARTTLS options.  qmail-smtpd	includes a "Mail From:"	param-
       eter  parser  and  obeys	"Auth" and "Size" advertisements.  qmail-smtpd
       STARTTLS	implementation requires	 the  use  of  sslserver  from	ucspi-
       ssl.0.9x	and the	OpenSSL	library.

       Authentication  mode  is	 facilitated  in case the environment variable
       SMTPAUTH	is set which tells qmail-smtpd to  accept  LOGIN,  PLAIN,  and
       eventually  CRAM-MD5  AUTH types	and if additionally a PAM checkprogram
       is available which reads	on file	descriptor 3 the username, a  0	 byte,
       the  password or	CRAM-MD5 digest/response derived from the SMTP client,
       another 0 byte, a CRAM-MD5 challenge (if	applicable to the Auth	type),
       and  a  final  0	byte.  checkprogram invokes subprogram upon successful
       authentication, which should return 0 to	qmail-smtpd, effectively  set-
       ting   the  environment	variables  RELAYCLIENT	and  TCPREMOTEINFO  or
       TCP6REMOTEINFO (any supplied  value  replaced  with  the	 authenticated
       username).   qmail-smtpd	 will  reject the authentication attempt if it
       receives	a nonzero return value from checkprogram or subprogram.

       STARTTLS	support	is enabled setting the environment variable  UCSPITLS.
       In  this	 case,	qmail-smtpd  communicates  with	 the sslserver program
       interface through a control socket,  a  reading	and  a	writing	 pipe,
       dynamically  defined  during the	session	start to be used for transport
       layer encryption.  qmail-smtpd provides mutual authentication based  on
       X.509  client certs and relaying	with additional	SMTP Return-Path vali-
       dation.

       qmail-smtpd may employ additional DNS look-ups  for  the	 "Mail	From:"
       envelope	 sender	 address and/or	the HELO/EHLO greeting string from the
       MTA client.

       qmail-smtpd implements a	SPF record check for the domain	 part  of  the
       received	Mail-From: <return-path> address or the	HELO/EHLO statement in
       case the	domain information is missing.	This behavior is triggered  by
       the environment variable	SPF.



TRANSPARENCY

       qmail-smtpd  converts the SMTP newline convention into the UNIX newline
       convention by converting CR LF into LF.  Usually, it returns  a  tempo-
       rary error and drops the connection on bare LFs.

       qmail-smtpd accepts messages that contain long lines or non-ASCII char-
       acters, even though such messages violate the SMTP protocol.

CONTROL FILES

       badhelo
	    Unacceptable HELO/EHLO greeting strings.  qmail-smtpd will  reject
	    every  connection  attempt  if the client MTA's HELO/EHLO greeting
	    compares with a wildmat pattern provided in badhelo  in  case  the
	    environment variable HELOCHECK is set.  badhelo checks have prece-
	    dence over DNS lookups.   DNS  lookups  can	 be  avoided,  if  the
	    announced  HELO/EHLO greeting string is concatinated with a	trail-
	    ing	'!' and	included in badhelo:

	      localhost
	      localhost.localdomain
	      127.0.0.1
	      mygreetingstring
	      [192.168.1.2]!


       badmailfrom
	    Unacceptable envelope sender addresses.  qmail-smtpd  will	reject
	    every  recipient  address  for  a  message	if the envelope	sender
	    address is listed in badmailfrom.  A line in badmailfrom may be of
	    the	 form @host, meaning every address at host.  Additionally, any
	    envelope sender address can	be filtered with a wildmat check:

	      *@earthlink.net
	      !fred@earthlink.net
	      [0-9][0-9][0-9][0-9][0-9]@[0-9][0-9][0-9].com
	      answerme@save*
	      *%*
	      @yahoo.com-
	      @hotmail.com=
	      @mydomain.tld+
	      ~yahoo.com
	      ?nobody@example.com

	    A badmailfrom file with this contents reject all mail from	Earth-
	    link except	from fred@earthlink.net. It also rejects all mail with
	    addresses like: 12345@123.com and answerme@savetrees.com. Further,
	    any	 mail  with  a sender address containing a percent sign	(%) is
	    rejected.

	    This implementation	recognises 'extended' addresss in  badmailfrom
	    allowing to	reject mails with particluar spoofed domain addresses:

	    (1)	The address is appended	with a '-'.  Now, if  TCP(6)REMOTEHOST
	    equals   'unknown',	 mails	with  the  corresponding  address  are
	    rejected (badmailfromunknown).

	    (2)	The address is appended	with a '='.  In	case TCP(6)REMEOTEHOST
	    is	set  mails,  whose  domain  part of the	envelope addresses not
	    matching the corresponding entry  are  rejected  (badmailfromwell-
	    known).

	    (3)	The address is appended	with a '+'.  If	RELAYCLIENT is not set
	    and	the sender address matches a corresponding entry  (anti-spoof-
	    ing	for internal addresses).

	    (4)	 The  address is enhanced with a leading '~'.  This requires a

	      *
	      !
	      !*@*.*
	      *viagra*


       badloadertypes.cdb
	    Unacceptable base64	loader types in	the message.  qmail-smtpd will
	    reject every message if 5 significant characters (eg.  Mi5kb) any-
	    ware  in  the base64 encoded attachment is identical to those com-
	    piled into badloadertypes.cdb.  Use	qmail-badloadertypes to	derive
	    badloadertypes.cdb	from  badloadertypes.	In  order  to make the
	    search efficient, all bad loader types have	to start with the same
	    character (eg. "M").  The control file badloadertypes.cdb is eval-
	    uated if the environment variable  BADLOADERTYPE  is  set  to  the
	    first character according to the contents of badloadertypes.

       badmimetypes.cdb
	    Unacceptable  base64  encoded  MIME	types in message.  qmail-smtpd
	    will reject	every message if the first  9  significant  characters
	    (eg.   TVqQAAMAA)  of any of it's embedded MIME types is identical
	    with one compiled into badmimetypes.cdb.   Use  qmail-badmimetypes
	    to	derive	badmimetypes.cdb  from badmimetypes.  The control file
	    badmimetypes.cdb is	evaluated if the environment variable BADMIME-
	    TYPE  is  set.  In addition, irregular BASE64 attachments carrying
	    whitespaces	can be rejected	defining BADMIMETYPE='!'.

       badrcptto
	    Unacceptable  envelope  recipient  addresses.   qmail-smtpd	  will
	    reject every incoming message if the envelope recipient address is
	    listed in badrcptto.  This control file is complementary  to  bad-
	    mailfrom.	A  line	in badrcptto may be of the form	@host, meaning
	    every address at host.   badrcptto	employes  the  same  filtering
	    logic  for	the  envelope  recipient as badmailfrom.  Effectively,
	    badrcptto allows a "whitelisting" of envelope recipient addresses:

	      *
	      !user1@mydomain.com
	      !user2@mydomain.com
	      !*@anotherdomain.com

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

	    databytes  counts  bytes  as  stored  on  disk, not	as transmitted
	    through the	network.  It does not count the	 qmail-smtpd  Received
	    line, the qmail-queue Received line, or the	envelope.
	    Extra allowed RCPT domains.	 If rcpthosts and  morercpthosts  both
	    exist, morercpthosts is effectively	appended to rcpthosts.

	    You	must run qmail-newmrh whenever morercpthosts changes.

	    Rule  of  thumb  for  large	 sites:	Put your 50 most commonly used
	    domains into rcpthosts, and	the rest into morercpthosts.

       mailfromrules
	    Acceptable "Mail From:" addresses for  RELAYCLIENTs	 are  included
	    here. Use qmail-mfrules to derive

       mailfromrules.cdb
	    from mailfromrules.

       rcpthosts
	    Allowed  RCPT domains.  If rcpthosts is supplied, qmail-smtpd will
	    reject any envelope	recipient address with a domain	not listed  in
	    rcpthosts.

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

	    rcpthosts may include wildcards:

	       heaven.af.mil
	       .heaven.af.mil

	    Envelope  recipient	 addresses  without @ signs are	always allowed
	    through.

       recipients
	    List of external resources	providing  acceptable,	full-qualified
	    envelope  addresses	 ('RCPT	 to:  <recip@domain>')	to be used for
	    recipient verification during the SMTP session.

	    The	external sources can  be  either  fastforward  compliant  cdbs
	    including  the  envelope addresses,	where the path to a cdb	has to
	    be referenced relative to Qmail's home directory - or - checkpass-
	    word  compatible  Plugable Authentication Modules (PAM), receiving
	    the	envelope address on FD 3 as 'recip@domain\0\0\0' and returning
	    '0'	in a case of success and '1' in	case of	failure.  The use of a
	    PAM	is indicated with a delimiting '|' and it will be called  with
	    up to five additional parameters; while a cdb follows a ':', which
	    can	be omitted.

	    The	list of	external sources is consulted  line-by-line  for  each
	    recipient  envelope	 address until the first positive answer, or a
	    final negative response is encountered.  Which external source  to
	    be	queried,  depends on the domain	part of	the recipient envelope
	    address specified on the left side of the recipients  file,  while
	    the external resource is provided right from the delimitor.

	    The  addresses'  domain  part is evaluated in lower-case. An exact
	    domain match can be encompassed by means of a  leading  '@'.   The
	    '*'  is  a generic wildcard for all domains.  Specific domains can
	    be excluded from the lookup by means of a leading  '!';  thus  all
	    recipient addresses are accepted for this domain.  Additionally, a
	    '!*' can be used as  wildcard  for  all  domains  not  encountered
	    before in recipients (pass-thru).

	    A     recipients     file     is     always    constructed    like
	    domain:cdb','domain|pam', or simply 'cdb':

	       @mydomain.com:users/recipients.cdb
	       example.com|bin/qmail-smtpam mx.example.com
	       *:etc/fastforward.cdb
	       *|PATH/ldapam ldapserver	host port DN passwd
	       !*

	    Lagacy format:

	       users/recipients.cdb
	       etc/fastforward.cdb

	    Note: Excluded domains starting with a '!'	should	be  placed  in
	    the	 beginning  of	the  recipients	 file for performance reasons,
	    while the pass-thru	statement '!*' has to be  on  the  last	 line.
	    The	recipients check is applied after the rcpthosts	evaluation.

	    qmail-recipients  may  be used to construct	a users/recipients.cdb
	    from users/recipients.

	    The	qmail-smtpd  recipients	 mechanism  supports  Qmail's  address
	    extension  (VERP).	 Unqualified  envelope recipients are appended
	    with '@localhost'.

       smtpgreeting
	    SMTP greeting message.  Default: me, if that is  supplied;	other-
	    wise qmail-smtpd will refuse to run.  The first word of smtpgreet-
	    ing	should be the current host's name.

       spfexplain
	    An additional SPF explanation can be given here  to	 provide  more
	    specific  information  for	the  sender  in	case of	a reject.  SPF
	    macro expansion is possible. It will  override  the	 default  one,
	    e.g.:

	    See	https://example.com/spfrules.html (#5.7.1)

       spflocalrules
	    As	'last  resort',	it is possible to include SPF local rules here
	    (on	one line), that	will be	applied	before other SPF  rules	 would
	    fail.   This can be	used to	allow certain MX to send mails anyway.
	    Example:

	    include:spf.trusted-forwarder.org

       timeoutsmtpd
	    Number of seconds qmail-smtpd will wait for	 each  new  buffer  of
	    data from the remote SMTP client.  Default:	1200.



CONDITIONAL CONTROL FILES

       The  control  files  rcpthosts,	morecpthosts,  recipients, badhelo are
       "conditional" control files and evaluated only if the environment vari-
       Environment  variables  may  be	defined	 globally  in  the qmail-smtpd
       startup script and/or individually as part of the tcpserver's cdb data-
       base.   The  environment	variables may be quoted	("variable", or	'vari-
       able') and in case of global use, have  to  be  exported.   qmail-smtpd
       supports	the following legacy environment variables, typically provided
       by   tcpserver	or   sslserver:	   TCP(6)REMOTEIP,    TCP(6)REMOTEHOST
       TCP(6)REMOTEINFO	 and  TCPLOCALPORT  as well as RELAYCLIENT.  Addition-
       ally, qmail-smtpd may use several environment variables	for  different
       purposes.

       Controlling the SMTP HELO/EHLO:


       HELOCHECK=''
	    enables  a	check  of  the provided	HELO/EHLO greeting against the
	    content of the control file	badhelo.  In case no HELO/EHLO	greet-
	    ing	 is  given, SMTP connections can be rejected, if HELOCHECK='!'
	    is set. Checks on the presence and the content  of	the  HELO/EHLO
	    greeting string is facilitated, setting HELOCHECK='.'.  To enforce
	    the	match of the HELO/EHLO greeting	with the remote	host's FQDN  (
	    TCP(6)REMOTEHOST), use HELOCHECK='='.

       HELOCHECK='A'|HELOCHECK='M'
	    enable  DNS	 A/MX  lookup  for  the	HELO/EHLO greeting string.  In
	    addition, the HELO/EHLO string is checked against the  content  of
	    badhelo.

       Controlling the SMTP Mail From:


       LOCALMFCHECK
	    is	used  to  enable a "Mail From:"	address	Verification (MAV) for
	    RELAYCLIENTs.  Thus, the domain part of the	"Mail From:"  envelope
	    sender address has to match	an entry in rcpthosts or morercpthosts
	    control files, if not explicitly defined otherwise.

	    If LOCALMFCHECK='!'	is set,	the control file mailfromrules.cdb  is
	    evaluated  and  the	 MAV  is facilitated employing the environment
	    variables TCP(6)REMOTEINFO,	TCP(6)REMOTIP, or TCP(6)REMOTEHOST  as
	    a key.  However, if	LOCALMFCHECK='=' is provided, TCP(6)REMOTEINFO
	    (i.e. set by Auth) has to match the	"Mail From:" envelope  address
	    (case  insensitive).   Alternativley,  using  LOCALMFCHECK='?' the
	    email address embedded in the DN of	a X.509	 client	 is  used  and
	    compared  against  the  "Mail From:" envelope address.  Of course,
	    this requires sslserver  to	 request  a  client  cert  for	mutual
	    authentication.

	    Note:  Adding a qualifier to LOCALMFCHCEK, the entire "Mail	From:"
	    address is verified; not only the domain part.

       MFDNSCHECK
	    enable DNS MX lookup for the domain	part of	the "Mail From:" enve-
            lope sender address.
  
       SPF='0'|'1'|'2'|'3'|'4'|'5'|'6'
            SPF Records will be evaluated for the current SMTP session in case
            SPF is defined. The value of SPF may be given between 1 and  6  to
            enable  SPF  checks.  1 selects 'annotate-only' mode, where qmail-
            smtpd will annotate incoming email with a Received-SPF header,  but
            will  not  reject any messages.  2 will produce temporary failures
            on DNS lookup problems so you can be sure always to have  meaning-
            ful Received-SPF headers.  3 selects 'reject' mode, where incoming
            mail will be rejected if the SPF record says 'fail'.  4 selects  a
            more  stricter rejection mode, which is like 'reject' mode, except
            that incoming mail will also be rejected, when the SPF record says
            'softfail'.  Further, 5 will reject when the SPF record says 'neu-
            tral', and 6 rejects, if no SPF records are available at all (or a
            syntax  error  was encountered).  If SPF is given as 0, SPF checks
            are disabled.

            Note: Additional control files are spfexplain and spflocalrules.
 
       Controlling the SMTP RCPT TO:


       MAXRECIPIENTS
	    is the number of Rcpt To:'s	qmail-smtpd will accept	in a SMTP ses-
	    sion.  If MAXRECIPIENTS ist	not set, any number is allowed.

       TARPITCOUNT
	    is	the  number  of	 Rcpt To: qmail-smtpd accepts before it	starts
	    tarpitting.	 Default: 0 which means	no tarpitting.

       TARPITDELAY
	    tarpitdelay	is the time in seconds of delay	to be introduced after
	    each subsequent Rcpt To:.

	    Smart  Rejection  Notes: If	TARPITCOUNT is set and TARPITDELAY = 0
	    (default) qmail-smtpd will	issue  after  recognising  TARPITCOUNT
	    invalid  Rcpt  To:	a  Recipient failure; thus additional Rcpt Tos
	    will not be	accepted.  If, however TARPITCOUNT is set and  TARPIT-
	    DELAY  = 999 qmail-smtpd will issue	after TARPITCOUNT invalid Rcpt
	    To:	a Recipient failure

       RECIPIENTS450
	    tells to issue a SMTP reply	'450'  (temporary  rejection)  instead
	    the	 default  '550'	 in  case  the recipient was not listed	in any
	    recipients cdb.

       REPLYMAV
	    allows the setting of customized SMTP reply	messages in case of  a
	    MAV	mismatch.

       Controlling the email body:


       BADLOADERTYPE='c'
	    tells  qmail-smtpd	to evaluate the control file badloadertypes.cdb
	    with the starting string 'c'.  If BADLOADERTYPE='-'	 is  set,  the
	    check  is  disabled.   In  case  BADLOADERTYPE='+' is defined, the
	    check is disabled for RELAYCLIENTS.

       BADMIMETYPE
	    see	control	file badmimetypes.cdb.	 In  case  BADMIMETYPE='-'  is
	    set;  badmimetypes.cdb  is	not considered;	thus the check is dis-
	    abled.  Providing BADMIMTETYPE='+' the check  is  disabled	if  in
	    addition RELAYCLIENTS are recognized.

       BASE64
            tells  QHPSI  to  enable  virus  checking only if a base64 encoded
            attachment was identified.

       DATABYTES
            see control file databytes.

       QHPSI
            is used by qmail-smtpd to supply the name of the virus scanner and
            it's path.

       Environment variables for SMTP authentication:

       SMTPAUTH
	    is	used to	enable SMTP Authentication for the qmail-smtpd Auth types
	    LOGIN and PLAIN.  In case

       SMTPAUTH='+cram'
	    is defined,	qmail-smtpd  honors  LOGIN,  PLAIN,  and  additionally
	    CRAM-MD5 authentication.  Simply

       SMTPAUTH='cram'
	    restricts authentication just to CRAM-MD5.	If however

       SMTPAUTH='!'
	    starts  with  an exclamation mark Auth is	required.  You
	    can	enforce	'Submission' using this	option and binding qmail-smtpd
	    to the SUBMISSION port '587'.  In particular,

       SMTPAUTH='!cram'
	    may	be useful.  In opposite, if

       SMTPAUTH='-'
	    starts  with a dash, Auth is disabled for particular con-
	    nections.  Note: The use of	'cram'	requires  a  CRAM-MD5  enabled
	    PAM.

       Setting up the TLS/STARTTLS environment:


       UCSPITLS
	    enables   encrypted	  SMTP	communication  via  STARTTLS  in  case
	    sslserver is provided.   If	 UCSPITLS='!'	is  set,  STARTTLS  is
	    required;  while setting UCSPITLS='-' disables STARTTLS.  Further,
	    UCSPITLS='?'  may be used to force the client to present  a	 X.509
	    cert  for  authentication  purpose which may be refined requesting
	    UCSPITLS='@' to additionally fetch	the  email  address  from  the
	    client's cert to be	perhaps	subject	of LOCALMFCHECK.

       Other environment variables used:


       DELIVERTO
	    mail address for special recipients.

       RBLSMTPD
	    feed  from	rblsmtpd  including  the information received from the
	    inquired RBL hosts and displayed as	X-RBL-Info: message header.



ENVIRONMENT VARIABLES SET

       By means	of the following environment variables,	the SMTP session can be
       interrogated:

       HELOHOST
            the HELO/EHLO greeting of the SMTP client.

        AUTHPROTOCOL
            the ESMTPA protocol used for authentication.

        AUTHUSER
            the supplied username for authentication.

        MAILFROM
            containes the received "Mail From:" address.

        RCPTTO
	    containes all received "Rcpt To:" addresses	separated by blanks.

       TCP(6)REMOTEINFO
	    in authentication mode set to the accepted username.

       SSL_*
	    information	from sslserver,	if applicable.


SEE ALSO

       tcp-environ(5),	 qmail-control(5),  qmail-inject(8),  qmail-newmrh(8),
       qmail-newbmt(8),	 qmail-authuser(8),  qmail-recipients(8),   qmail-smt-
       pam(8),	 qmail-mfrules(8),   qmail-queue(8),  qmail-remote(8),	qmail-
       send(8),	qmail-log(8), tcpserver(8), sslserver(8).




				       8		 s/qmail:(qmail-smtpd)

Man(1) output converted with man2html
and me.