20000212    (c) Frederik Lindberg, lindberg@id.wustl.edu (GPL)
		(No warranties. If you want Y2K certification
		and other warranties, send me a check ;-).


PURPOSE:

Users of ezmlm lists sometimes do not know their subscription address
when they want to unsubscribe. Not all get the "Return-Path" header from
their delivery agent/MUA, and of the ones that do, many can still not
decipher the information. rfc2369 provides a standard way to supply
unsubscribe information. For the header to work optimally, it should
contain the command adapted to the subscriber's subscription address.

These patches enable qmail to replace tags with the subscribers address.
This is normally done ONLY in headers to avoid the risk of message corruption.
If for some reason no substitution is done, the header remains in its
original form, which is harmless as far as message integrity is concerned.

If any header starts with '#' this character is removed and substitution
will be extented into the body. This is safe since no legal header starts
with '#'. It is assumed that for messages with this flag it is desired
that any tag in the message is substituted.

##L => local part
##H => host part

Assume: Subscriber=user@host, list=list@listhost.

and header added by ezmlm:
	List-Unsubscribe: <mailto:list-unsubscribe-##L=##H@listhost>

Then: Header after qmail processing:
	List-Unsubscribe: <mailto:list-unsubscribe-user=host@listhost>


CONTENTS:

This package contains 2 patches for qmail-1.03:

qmail-remote.diff:
	Handles subscribers remote to the list host. The recipient address
	is taken from the recipient argument to qmail-remote. Substitution
	is done only if there is a single recipient (always the case for
	normal qmail-1.03). This suffices if your list serves only remote
	subscribers, or if your local subscribers do not need the info.

qmail-local.diff:
	Here the recipient address is the local mailbox, which may not
	be the subscription address. For this reason, we look for a VERP
	SENDER, and extract the information from it. Substitutions are
	done only if a ezmlm-style VERP SENDER of the format

	llll-return-y-zzz=www@hhhh

	is seen. ``zzz'' is the subscriber local part, ``www'' the host.
	``llll'' is the list local name, ``y'' the message number, and
	``hhhh'' the list host. The reason for this restriction is that
	it otherwise is impossible for qmail-local to dissect the VERP
	SENDER as it would require knowledge about the local part of the
	real sender. ``zzz'' and ``www'' may contain '-'. ``y'' may
	not contain '-'. In the unlikely case that ``-y-'' or ``-zzz''
	contain ``-return-'', the VERP header will be incorrectly
	interpreted. This results in an incorrect substitution, but has
	no other negative consequences.

	Substitutions are done for file and maildir delivery, as well as
	for forwarding. It is not done for program delivery, since this
	would require writing of a temporary file, and since it is normally
	not desired for e.g. delivery to ezmlm lists.

	This patch is useful if you have local subscribers. qmail-remote with
	patch will be very consistent in its substitutions. qmail-local after
	patching makes certain assumptions and may result in differences
	between delivery modes (i.e. program delivery and other delivery).
	Thus, you may chose to use only the qmail-remote patch or both.


USE:

For a general header for ezmlm+ezmlm-idx-0.32 lists (automatically adjusted
for the digest list) place the following in DIR/headeradd:

List-Unsubscribe: <mailto:<#l#>-unsubscribe-##L=##H@<#h#>>

Of course, you could substitute e.g. ##L into Subject:, etc.


ezmlmrc.diff will modify any ezmlmrc file from ezmlm-idx->=0.40 to take
advantage of the new qmail functionality. Apply by (assuming that you've
build ezmlm with ezmlm-idx, configured correctly, etc):

	% cd ezmlm-0.53
	% patch ezmlmrc < ezmlmrc.diff

If you do this, testing is easy. Just send a message to a list you're subscibed
to and look at the headers.

INSTALLATION:

1. Go to the qmail-1.03 build directory.
	% cd qmail-1.03

2. Apply the qmail-remote patch with GNU patch or equivalent. Unless you have
   moved the patches to the qmail directory, you need to specify a path to them.
	% patch <qmail-remote.diff

3. Optionally, apply the qmail-local patch (normally, you don't need to do this
   for mailing list hosts):
	% patch <qmail-local.diff

4. Rebuild and install qmail.
	% make
	% su
	  [stop qmail]
	# make setup check

5. Verify that qmail works correctly per qmail docs.

6. Restart qmail.

7. Test a header like the one above:
	% cat >msg <<EOF
	List-Unsubscribe: <mailto: list-unsubscribe-##L=##H@host>
	Subject: test

	Body ##L##H (should stay intact)
	EOF
	% qmail-inject -f'list-return-1-zzz=www@host' my@myhost<msg

   Put in your address instead of ``my@myhost''. If ``my@myhost'' is
   a remote address, the header should have ``my'' instead of ``##L''
   and ``myhost'' instead of ``##H''. If the address is local and you
   have applied the qmail-local patch, the Header should have
   ``zzz'' in place of ``##L'' and ``www'' in place of ``##H'', but the
   body should be unchanged. For a normal ezmlm message, ``zzz'' would
   equal ``my'' and ``www'' would equal ``myhost'' making the result of
   the substitutions the same for both local and remote delivery.

   NOTE: The message to the local address will remain unchanged if you use
   program delivery, such as procmail, even if you applied the qmail-local
   patch.

   To get substitution even in the body, prefix one of the headers with '#'.
   This allows you to e.g. put unsubscribe instructions in the trailer
   and prefix e.g. the Precedence: header in DIR/headeradd with '#'.

Send comments to lindberg@id.wustl.edu.


CHANGES:

qmail-verh-0.06 20000212
========================
-###L => #reciplocal, i.e. ##L and ##H are recognized independent of context.
 Substitution is no longer disabled by ##x where x != 'L' and x != 'H'. This
 will make it consistent with the algorithm used in ezmlm-idx-0.41 ezmlm-send
 to test if the message is safe for substitution.

qmail-verh-0.05 19991225
========================
-Fixed problems in 0.04: The patch was against verh-0.03 instead of plain
 qmail-1.03, this file was incompletely updated, and ezmlmrc.diff was missing.


qmail-verh-0.04 19991223
========================
-Modified so that '#' at pos 1 of a header line signals to continue
substitution in the body as well. This will be used in ezmlm to read the
message, and enable the trailer only if '##' is not present in the message.
This way, the trailer can have customized unsubscribe info. This is not in
ezmlm-idx-0.40, but planned for 0.41.


qmail-verh-0.03	19990512
========================
- Added ezmlmrc.diff to make use easier. No changes to the qmail patches
  themselves.


qmail-verh-0.02	19990301
========================
- Substitution in qmail-remote is aborted if a sequence ``##x'' is found, where
  ``x'' is not ``L'' or ``H''. This is to further decrease the chance of
  incorrectly modifying a header. qmail-local does the same.

