mvmf: mvmtr qmail-smtpd compatibility

Intro

Compabitility notes

The configure option "--enable-qmail-compatibility" will cause mvmtr to be
compiled with basic qmail-smtpd compatibility.  The goal is to allow mvmtr
to be phased into a qmail environment; if it can be dropped in and simply
run without major changes to the control environment, it can then be further
configured using mvmtr controls.

The qmail-smtpd compatibility is against stock qmail-1.03 without patches.
Since mvmtr is its own thing, representing an attempt to get away from
qmail-style controls as well as the whole endlessly variable qmail-smtpd
patch suite, supporting anything but the basic qmail-smtpd would be going
down the wrong path.  (That said, it's possible that some compatibility with
some common patches might be supported at some time.)

This compatibility is primarily with qmail-smtpd controls, and only
secondarily with its operation.  That is, the qmail-smtpd controls will
be used by mvmtr in its own way.

The rest of this file describes that control compatibility.  There is a
block (in this document) for each qmail-smtpd control item.  In that block
there is a description of what qmail-smtpd does with the control (or at
least how I interpret it), and then some words about how mvmtr is or is not
compatible with it.  Controls are either files (in the qmail/control
directory) or environment variables.  There is also a section on
command-line arguments.

On startup, the qmail control files are read before the mvmtr startup
file- this lets the mvmtr start file override anything set by
those control files.

All of the qmail/control files read by mvmtr have extended handling, in
the following ways:

  - lines beginning with "#" are ignored (as comment lines);
  - blank lines are also ignored;
  - any line beginning with backslash is accepted (without the backslash),
    which allows you to provide an otherwise blank or "#"-starting line;
  - Any line ending with a backslash has the next non-comment non-blank
    line appended to it.


====================

FILE:	me

qmail:	optional; contains a string that is the default hostname for the
	local host.

mvmtr:	Sets the "usehostname" -- the hostname used in the smtpd greeting.


====================

FILE:	smtpgreeting

qmail:	optional; contains a string for the greeting banner.

	Must contain the entire smtp greeting, only a single line is
	handled correctly.  User must be relied upon to start this string
	with the hostname, as required per RFC[2]821.

	If this file is missing, qmail-smtpd uses the value of "me" .
	If then that is missing, qmail-smtpd will consider it an error.
	Thus, it is mandatory that the greeting be set by either the
	"smtpgreeting" or "me" file.


mvmtr:	will set the "smtp_server_greeting" control.

	mvmtr always emits the first line of greeting in its own way (which
	may be influenced by other controls).  The value of the
	"smtp_server_greeting" control will supply any text that follows the
	first line.  If any additional greeting text is supplied (either
	here or via mvmtr's own control mechanism), mvmtr will then add a
	final line of its own in order to help assure compatibility with
	clients that for whatever reason expect the final line to be
	formatted in a particular way.

	As implied, this control may be multi-line.

	Since mvmtr supplies its own first line of greeting, a value for
	this control is not mandatory.

====================

FILE:	localiphost

qmail:	optional; contains the hostname to use instead of a local IP
	 address in a 'RCPT TO' domain, when such address is seen in
	 square brackets.  e.g. mem@[10.0.0.1] will be replaced with
	 mem@localiphost.

	If missing, and the value of "me" is present, that value is used.

mvmtr:	Sets the "smtp_server_localip_host" control.

	If missing, uses the value of "usehostname" which may have been
	set from the "me" control.  Thus, the functionality is essentially
	the same.


====================

FILE:	timeoutsmtpd

qmail:	optional; specifies the timeout for waiting for data from a client.
	Default is 1200.

mvmtr:	Sets the "smtp_server_timeout" value, which is the general timeout
	 for receiving data in the smtp dialog.

	mvmtr has other timeout controls; the general timeout is the one
	 that is used when a more specific one is not used.  For example,
	 the "HELO" timeout is different than the general timeout.
	 mvmtr's default is likely different than 1200.

====================

FILE:	rcpthosts

qmail:	optional; contains a list of domain names (one per line) that we
	 will receive mail for.  A domain name beginning with "." is a
	 wildcard for subdomains within that domain.

	Any 'RCPT TO' host not listed in rcpthosts will not be accepted.

mvmtr:	Essentially the same.  mvmtr will emulate this qmail-smtpd
	 behaviour when qmail-smtpd compatibility is enabled.  The
	 qmail-smtpd compatible address checking is the last test done;
	 so if any mvmtr-specific checks have already decided the address
	 acceptance one way or another, the qmail-smtpd compatible test
	 doesn't get get a chance to override it.  This allows you to
	 start with qmail-smtpd compatible checking, and then add
	 mvmtr-style address checking that supplants it.

====================

FILE:	badmailfrom

qmail:	optional; Contains a list of unacceptable sender addresses, one
	 per line.  The "MAIL FROM" address is checked against this list.
	 A line of the form "@domain" is a wildcard for a domain.

	If the address is matched, qmail-smtpd will note it and reject
	 any following "RCPT TO" command in the smtpd dialog.

mvmtr:	Used in the same way.  This test, however, is done after any
	 mvmtr-style checks of the "MAIL FROM" address (including MFL
	 hooks), and only if the decision has not already been made.  As
	 with the rcpthosts/morercpthosts, this allows you to start with
	 qmail-smtpd checking, and add mvmtr-style checking that overrides
	 it.

	If an address is matched, mvmtr may do the rejecting in a
	 different way, i.e. at a different point in the SMTP dialog.
	 The result is, however, the same.

====================

FILE:	databytes

qmail:	optional; specifies the maximum message size acceptable.
	Default is 0, which means no maximum.
	May be overridden by environment variable DATABYTES.

mvmtr:	Sets the "smtp_server_msgsize_max" control, which is the
	 message size limit.
	May be overridden by environment variable DATABYTES.

====================

FILE:	morercpthosts.cdb

qmail:	optional.  This is treated as an extension of the rcpthosts
	 file, although accessed in a different way.

mvmtr:	Same as for rcpthosts.

====================

env:	DATABYTES

	See "databytes" control file above.

====================

env:	TCPREMOTEIP, TCPREMOTEHOST, TCPLOCALIP, TCPLOCALHOST

qmail:	These are environment variables set by the ucspi-tcp/tpserver
	 package, which invokes qmail-smtpd when an incoming connection
	 is opened.  qmail-smtpd uses these values for information about
	 the TCP/IP environment.

mvmtr:	Ditto, when used in ucspi-tcp/tcpserver mode (which is the only
	 mode implemented so far.)

====================

env:	RELAYCLIENT

qmail:	Set via ucspi-tcp/tcpserver if the connecting client is allowed to
	 relay mail to third parties.  stock qmail-smtpd will also append
	 the value of this variable to all "RCPT TO" envelope addresses.

mvmtr:	Also pays attention to RELAYCLIENT when in ucspi-tcp/tcpserver
	 mode.  However, mvmtr does NOT append the value of this variable
	 to the recipient address.  Also, mvmtr will take its relay
	 permission from other sources, including mvmcas if enabled.

====================

command-line

qmail:	stock qmail-smtpd doesn't take a command line argument.
	A number of patches to qmail-smtpd add things like hostname and
	checkpassword program names.

mvmtr:	without qmail-smtpd compatibility enabled, mvmtr will complain
	about extra arguments on the command line.  With qmail-smtpd
	compatibility enabled, mvmtr will simply skip them.  Any
	requirements of your patched qmail-smtpd will have to be
	met by using mvmtr-style controls and arguments.

====================