wiki:LancelotHowto

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@…, and that you're Alfred

  1. Newman at alfred@…:
      $ 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@… 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@… 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@… address, but for all addresses of the form test+SOMETHING@…, 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@… (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@…. 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@….

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@…. (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@…, 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@… 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.

Last modified 10 years ago Last modified on May 7, 2008, 11:17:49 AM