root/doc/Lancelot-HOWTO.txt

= Project Lancelot HOWTO =

== Overview ==

This document gives a brief introduction to installing and operating
Project Lancelot lists.


== Creating a list ==

To create a Project Lancelot list, invoke the pl-init(1) command with
the list address and the list owner's (your) address as its
arguments. For the purposes of this example, let's assume that the
list is to be called ''test@example.com'', and that you're Alfred
E. Newman at ''alfred@example.com'':
{{{
  $ pl-init test@example.com alfred@example.com
}}}
This will create a ''.pl'' directory inside your home directory (if it
doesn't already exist) and, within that directory, a directory called
''test@example.com'' containing a file called ''list.db''. This file
is a database that stores the list configuration and (usually)
subscriber addresses and options.

The next step is to ensure that mail sent to ''test@example.com''
actually reaches Project Lancelot. How to do this in general is beyond the
scope of this document, but one approach might involve setting up an
''alias'' such as
{{{
   test: "|/usr/local/bin/pl-incoming --user alfred test@example.com"
}}}
in your system's alias database (usually /etc/aliases). You will probably
need system administrator privileges to change this file.

'''Note:''' Project Lancelot will be responsible not just for the
''test@example.com'' address, but for all addresses of the form
''test+SOMETHING@example.com'', too. You will need to make sure that your
mail server actually accepts messages to all these addresses (for
Postfix, check the ''recipient_delimiter'' parameter); Lancelot will
take care of them.

== Configuring the new list ==

The new list should come with a fairly sensible configuration already, but
it is more than likely that you will want to change this and that. Refer
to LancelotConfiguration to see the most important parameters that you
can set.

Use the pl-conf(1) to look at and change configuration parameters. You can
inspect all of the configuration using
{{{
  $ pl-conf -q test@example.com
  digests.enable = 0
  digests.maxperiod = 0
  digests.maxsize = 0
  list.address = test@example.com
  ...
}}}
(note that not all parameters in this list are actually used yet). To change
individual parameters from the command line, use
{{{
  $ pl-conf -s test@example.com "list.ownername = Alfred E. Newman"
}}}
You can also write the whole configuration to a file and work this over
using your favourite text editor, then reimport the configuration:
{{{
  $ pl-conf -q test@example.com >test.conf
  $ emacs test.conf
  $ pl-conf -i test@example.com <test.conf
}}}
Blank lines and comment lines (starting with ''#'') are ignored when
a configuration is imported, so feel free to add comments to test.conf --
you just need to force yourself not to use "pl-conf -s" to change parameters
behind test.conf's back.


== Sending Mail to the List ==

You can now send messages to the new mailing list at test@example.com
(but for the fact that there are no subscribers to receive them). (As
a matter of fact, the list won't even accept them until you have
subscribed ''yourself''.) See the next section.


== Managing Subscribers ==

Like most mailing list management programs, Project Lancelot allows users
to subscribe or unsubscribe themselves by sending messages to
addresses such as ''test+subscribe@example.com''. But you can still
change the subscription database manually. Here's how to add subscribers:
{{{
  $ pl-subscribe test@example.com joe.blow@example.org sue.foo@example.net
}}}
This will add Joe Blow's and Sue Foo's addresses to the subscriber
database. Project Lancelot uses the same code to parse the address
arguments to pl-subscribe(1) that it uses to pass ''From'' headers in
e-mail, so you can say
{{{
  $ pl-subscribe test@example.com "Joe Blow <joe.blow@example.org>"
}}}
and "Joe Blow" will be noted as the name going with the address,
''joe.blow@example.org''.

pl-subscribe(1) takes arbitrarily many (well almost)
addresses on the command line, but if you do not give any, pl-subscribe(1)
will read its standard input instead:
{{{
  $ pl-subscribe test@example.com <members-list.txt
}}}
Use pl-list(1) to check who's subscribing:
{{{
  $ pl-list test@example.com
  sue.foo@example.net
  joe.blow@example.org
}}}
If you try to add an address that is already subscribing to the list,
you will see a nasty message from the database, but the address will
not be added a second time.

You can remove subscribers again using the pl-unsubscribe(1) command,
which works essentially like pl-subscribe(1):
{{{
  $ pl-unsubscribe test@example.com joe.blow@example.org
}}}

== List Aliases ==

It is extremely tedious to have to type command lines like
{{{
  $ pl-subscribe foobar-announce@lists.marketing.example.com ...
}}}
so (fortunately) there is a helpful shortcut. A command like
{{{
  $ pl-conf --alias foobar-announce@lists.marketing.example.com fba
}}}
lets you use ''fba'' in place of the long address in commands:
{{{
  $ pl-subscribe fba ...
}}}
This form of "aliasing" applies to all Project Lancelot command-line
tools. The command
{{{
  $ pl-conf --alias foobar-announce@lists.marketing.example.com
}}}
(without an alias) will enumerate the current alias (or aliases --
you can have as many as you like) for that list. If you're ever unsure
exactly what list an alias points to, use a command like
{{{
  $ pl-conf -qh fba list.address
}}}

Project Lancelot maintains an "automatic" alias to the last list
address you used in a Project Lancelot command. In
{{{
  $ pl-subscribe test@example.org joe.blow@example.org
  $ pl-subscribe . sue.foo@example.net
}}}
the second ''pl-subscribe'' command also applies to
''test@example.org''. (You will be relieved to hear that this works
for all Project Lancelot command-line tools except pl-incoming(1),
which deals with incoming mail, and pl-janitor(1), which performs
periodic cleanups. These commands will be invoked at various times
either from the mail system or cron, and it would be confusing for
them to reset Project Lancelot's notion of the "current list" while
you may be typing interactive commands.

List aliases are really just symbolic links in the ''.pl'' directory.
If you want to remove an alias, simply delete the symbolic link in
question. (The "." alias is really a symbolic link called
''.default-list''.)


== Incoming Mail ==

Here's what happens when Project Lancelot receives a message to the
list submission address (''test@example.com'', right?). At least this is
what happens unless you change things completely, which you are
absolutely free to do but probably shouldn't until you have learned
more about Project Lancelot's internals.

First of all, Project Lancelot creates a ''workflow'' that governs
further processing of the message. For mail to the submission address,
you can look at the value of the lists's '''mail.workflow.submit'''
parameter in order to see the individual steps. Each step corresponds
to a Project Lancelot ''processing module'' that does something with
the message. You can change how a message is processed by deleting or
inserting processing modules from or into the workflow.

The steps taken for submitted messages include:

 * Optionally checking that the message is indeed addressed to the list.
 * Optionally checking that the message sender subscribes to the list.
 * Checking whether the message looks reasonable from a MIME point
   of view, i.e., has significant plain-text content and does not contain
   fishy-looking attachments, which might harbour spam or viruses.
   This step also gets rid of everything that is not plain text.
 * Adding RFC2919 and (optionally) RFC2369 headers to the message.
 * Optionally adding a "tag" to the message's ''Subject:'' header.
 * Adjusting the message's ''Reply-To:'' header if desired (we have heard
   everything about how this will cause the milk in one's fridge to curdle
   but we think the feature has its uses even so, so spare us the
   philosophy).
 * Sending the message out to the subscribers, optionally only if the
   sender is an actual list subscriber.

And here is what happens when someone sends mail to a list's subscribe
address:

 * Project Lancelot checks whether '''subscribe.confirm''' is set for
   this list.  If so, the prospective subscriber is sent another
   message containing a ''magic cookie'' -- a long random string that
   is impossible to guess --, and invited to return that cookie to
   Project Lancelot. Once Project Lancelot receives this cookie back,
   the sending address of ''that'' message is added to the subscriber
   database. This feature is used to keep you safe from practical
   jokers who enjoy putting your address on 10.000 different mailing
   lists.

The confirmation mechanism in Project Lancelot is very general and can
be used to safeguard arbitrary addresses. Project Lancelot uses the
same code also for unsubscription and configuration requests.

The workflows for the unsubscription, config, owner and help
addresses are much more boring by far, once you have seen these.

See LancelotModules for more information on Project Lancelot's
processing modules.

Feel free to come up with new and interesting processing modules that
do stuff which is not on this list. You may want to check in with the
Project Lancelot developers' list (see below) to see whether anybody
else is working on stuff that you have in mind.


== Finished ==

This concludes our lightning tour of Project Lancelot. Feel free to
browse the [http://code.anselms.net/projects/lancelot/ Project
Lancelot web site], and to send mail to the
[mailto:lancelot-dev@anselms.net Project Lancelot developers' mailing
list] giving suggestions, encouragement, and helpful feedback. (As far
as flames are concerned, you know where you can stick those.)

Project Lancelot is very much a work in progress, and we hope that its
obvious major problems will very shortly be either removed or replaced
with new major problems. Stay tuned.