19991223 (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 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.
The address is quoted and any '\n' in the address removed to avoid the
risk of corrupting the message if the recipient address is bad. The
following substitutions are made:

##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>

NOTE: In both cases, sequences like ###L are NOT substituted, and longer
sequences ##...##L may or may not be, depending on the number of '#'s.
This makes processing simpler and more efficient in qmail-remote, and
such sequences do not make sense in headers anyway.


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.

	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.

	The qmail-local solution could also easily be modified to itself
	add a header with unsubscribe information for all messages from
	local or remote ezmlm lists. This allows you to help local users
	of remote ezmlm lists that do not use this patch. Send me an E-mail
	if this is of interest to you.


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.33x 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 <remote.diff

3. Optionally, apply the qmail-local patch:
	% patch <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.

Send comments to lindberg@id.wustl.edu.


CHANGES:

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.

