root/doc/INSTALL.txt

= Lancelot Installation =

== Abstract ==

This document explains how to install Project Lancelot on your
computer.

== Getting and unpacking the distribution ==

Project Lancelot is best installed on your mail server. This is
because it is integrated into your mail system so that incoming
messages that are to do with lists managed by Project Lancelot are
diverted to a Project Lancelot program, which handles the posting,
subscribing, etc. that the messages ask for.

First of all, you have to obtain the software, e.g., from the
[http://lancelot.anselms.net/download/ Project Lancelot download site].
Change to a suitable directory on your system and unpack the TAR.GZ
archive:
{{{
  $ wget http://lancelot.anselms.net/download/lancelot-current.tar.gz
  $ tar xvzf lancelot-current.tar.gz
}}}
This will create a directory called ''lancelot-''VERSION, which
contains the actual Project Lancelot code, documentation, etc.

Project Lancelot is essentially a set of Perl modules, and can be
''compiled'' like other Perl modules, using
{{{
  $ perl Makefile.PL
  $ make test
}}}
(the tests that come with the package are scanty, though).

You will probably have to become ''root'' to be able to install
Project Lancelot to wherever Perl-related stuff installed on your
system:
{{{
  # make install_site
}}}
This will usually put the Perl modules, executable programs, man
pages, etc. somewhere below ''/usr/local''. You can select an
alternative destination directory by using something like
{{{
  $ perl Makefile.PL PREFIX=/opt/lancelot
}}}
when creating the package Makefile.


== Mail server issues ==

Project Lancelot can work together with a wide variety of mail server
programs (MTAs). If you get Project Lancelot to run with a MTA not
listed here and have something useful to tell us (and other Project
Lancelot users), feel free to let us know!

=== Generic Sendmail-like ===

The easiest way to create mailing lists using Project Lancelot, on a
MTA that handles mail redirection the way Sendmail does (such as
Sendmail itself, Exim, or Postfix), is by using the /etc/aliases file
(called /etc/mail/aliases on some systems) to direct mail to "list
addresses" to the ''pl-incoming'' program. This is best done using the
''address extension'' facility available in recent versions of
Sendmail (and the others). An alias like
{{{
  list: "|/usr/local/bin/pl-incoming list@example.com"
}}}
is used to handle mail to any address of the form
''list+SOMETHING@example.com'', like ''list+subscribe@example.com''
etc. Note that the address extension facility may have to be enabled
in your MTA, e.g., by using the '''recipient_delimiter''' parameter in
Postfix.

=== Postfix ===

Project Lancelot can be installed for Postfix as per the ''generic
Sendmail-like'' instructions above; however, there is a more
convenient method if you are in a position to set aside a whole
subdomain to your mailing lists (such as ''lists.example.com''). This
works as follows:

First create a special user for your Project Lancelot lists, such as
''lancelot'':
{{{
  # useradd -m lancelot
}}}
The user does not require login permission; i.e., no password must be
set.

Then change ''/etc/postfix/master.cf'' to add a "transport" for
Project Lancelot as follows:
{{{
  lancelot unix - n n - - pipe
    flags=DRh user=lancelot
    argv=/usr/local/bin/pl-incoming ${user}@${nexthop}
}}}
And direct all mail to your mailing list subdomain to that transport
by entering
{{{
  lists.example.com    lancelot:
}}}
into your "transport table" (usually in ''/etc/postfix/transport'').
Don't forget to do
{{{
  # postmap hash:/etc/postfix/transport
}}}
(or whatever is suitable for your system).

You may also want to ensure that messages sent to more than one
list on your system are passed to individual instances of
''pl-incoming'', by adding the following lines to
''/etc/postfix/main.cf'':
{{{
  lancelot_destination_concurrency_limit = 1
  lancelot_destination_recipient_limit = 1
}}}
Also make sure that your '''recipient_delimiter''' is set to something
sensible such as "+" ("-" will also do but then you will not be able
to use "-" within mailing list names). All the addresses used by
Project Lancelot mailing lists will then look like
''list+SOMETHING@example.com''.

You can now add mailing lists as the ''lancelot'' user:
{{{
  # /bin/su - lancelot
  lancelot$ pl-init test@lists.example.com admin@example.com
}}}
This requires no further per-list configuration of your mail server,
except that your '''mail.delimiter''' parameter should be set to match
your Postfix '''recipient_delimiter'''. The most convenient method of
ensuring this is to add something like "mail.delimiter = +" to your
''/etc/lancelot/defaults.conf'' file.

=== Other MTAs ===

If you get Project Lancelot to run with another MTA such as Exim or
Qmail, do let us know how so we can add this information here.

== pl-janitor and cron ==

The pl-janitor(1) program is essential for automatic bounce
processing. You will want to run this from cron at periodic intervals.
Add a cron job like
{{{
  33 */6 * * * lancelot /usr/local/bin/pl-janitor /home/lancelot/.pl
}}}
(where ''/home/lancelot/.pl'' is the directory where the mailing lists
live). pl-janitor(1) picks up all mailing lists in the directories
passed on the command line. You may also pass the names of mailing
lists directly but the directory method is usually more convenient.

You should be able to get by with one pl-janitor(1) instance per user
who is managing mailing lists; individual users should add a line
similar to the one above to their personal crontabs using the
crontab(1) command but omit the first ''lancelot'' which is only
necessary in a system-wide crontab file. See crontab(5) for details.

One good method, if you're using the ''lancelot'' user for system-wide
mailing lists as suggested above, is to add a user-specific crontab
for ''lancelot'' by logging in as that user and executing ''crontab
-e''.

The period at which pl-janitor(1) runs is related to your bounce
parameter settings; if you use the standard setup then running
pl-janitor(1) once per day would probably be quite sufficient, but
four times (as above) isn't wrong, either.