root/doc/remote-admin.txt

= Remote Administration of Project Lancelot Lists =

== Abstract ==

This document explains how to administer Project Lancelot mailing
lists by e-mail.

== Prerequisites ==

The methods described here require a version of Project Lancelot that
is at least 0.2.99. We assume the following:

 * We are dealing with a list called ''list@example.com''.

 * The list was created by the system administrator of
   ''example.com'', who we shall call ''sysadmin@example.com''.

 * The list is to be administered remotely by the list administrator,
   who we shall call ''listadmin@example.com''.

We explain remote administration from the list administrator's point
first, stipulating that everything has been set up correctly by the
system administrator. Issues pertaining to list setup for remote
administration are explained at the end of this document.

== Remote Administration for List Administrators ==

=== Introduction ===

List administrators can ''administer'' Project Lancelot by sending
bahn.specially formatted e-mail messages to the list's ''administrative
address'', which is (by convention) ''list+admin@example.com''
(''NOTE:'' Depending on local usage this address may be different in
practice. In particular, it could be ''list-admin@example.com'').

The following operations are allowed in principle:

 * Adding new subscribers to the list

 * Removing existing subscribers from the list

 * Changing the properties of an existing subscription

 * Obtaining a list of current subscribers

 * Retrieving and changing the list configuration

Any of these operations may be disallowed by the system administrator
on a per-list basis.


=== Authentication ===

It is clear that not just anybody is supposed to be able to change the
mailing list. Therefore, as a list administrator you must
''authenticate'' a message to ''list+admin@example.com'' so that
Project Lancelot can be reasonably sure that the message was, in fact,
sent by you. There are currently two ways of doing so. Your system
administrator will tell you which one is in operation.

 * ''Password authentication.'' The first line of text in your message
   must contain a secret password, as in »'''password''' secret«. (Your
   system administrator will be able to tell you the correct
   password.) This method is reasonably secure; it is what most other
   mailing list programs use, too.

 * ''GnuPG authentication.'' Your message must be signed using a GnuPG
   key whose public key is part of the list's administrator
   keyring. (If this is all Greek to you, then have your system
   administrator explain it in more detail.) This is about as secure
   as things get in e-mail.


=== Adding New Subscribers ===

To add a new subscriber, send an authenticated message like
{{{
  subscribe Alfred E. Newman <alfred@example.net>
}}}
to ''list+admin@example.com''. (Use
{{{
  password secret
  subscribe Alfred E. Newman <alfred@example.net>
}}}
if your list uses password authentication and your password is
''secret''. We won't bother repeating this in the other examples.)

You may leave off the name and give just the e-mail address:
{{{
  subscribe alfred@example.net
}}}

You may add several subscribers either by giving multiple
'''subscribe''' commands as in
{{{
  subscribe Alfred E. Newman <alfred@example.net>
  subscribe Mickey Mouse <mickey.mouse@example.org>
}}}
or by using an ''end marker'' as in
{{{
  subscribe <<END
  Alfred E. Newman <alfred@example.net>
  Mickey Mouse <mickey.mouse@example.org>
  END
}}}
The second method is convenient if you have to add a lot of
subscribers from a pre-existing list. Whatever comes after the
'''<<''' on the first line of the command must occur on a line by
itself at the end of the list.

By default, subscribers are added as regular (non-digest) subscribers
with no special options such as ''nomail''. To add a subscriber as a
digest or non-receiving subscriber, use
{{{
  subscribe --digest Alfred E. Newman <alfred@example.net>
  subscribe --nomail Mickey Mouse <mickey.mouse@example.org>
}}}
where »--digest« adds a digest subscriber, and »--nomail« adds an
address that will not receive mail but will be allowed to submit
messages to the list.


=== Removing Subscribers ===

To remove an existing subscriber, send a message like
{{{
  unsubscribe alfred@example.net
}}}
You just need to provide the subscriber's e-mail address (their name
will be ignored if given). There are no options for unsubscribing, but
you can mass-unsubscribe a list of subscribers using the end-marker
method as shown in the previous section.


=== Obtaining a List of Subscribers ===

To receive a message containing a list of subscribers to the mailing
list, send a message like
{{{
  list
}}}
You will receive a list looking like
{{{
  SA---- admin@example.com List Administrator
  S---n- mickey.mouse@example.net Mickey Mouse
  S--d-- alfred@example.org Alfred E. Newman
}}}
This list is ordered by domain and gives all subscribers' addresses
and (if available) names. At the beginning of each line there is a
word of ''flags'' telling which options are set for this subscription:
''S'' means the subscription is ''active''. The next five characters
are either ''-'' (if the corresponding option is not set) or one of
the option letters ''A'' (list administrator), ''M'' (list moderator),
''d'' (digest subscriber), ''n'' (non-receiving subscriber), ''m''
(moderated subscriber).

You can give a search pattern on the '''list''' command in order to
restrict the resulting list to a certain subset of the
subscribers. For example,
{{{
  list *@example.com
}}}
would list just the subscribers in the ''example.com'' domain.


=== Changing Subscription Options ===

(To be written.)


=== Retrieving and Changing the List Configuration ===

(To be written.)


== Setting Up a List for Remote Administration ==

To enable remote administration for a list, the system administrator
must add an appropriate workflow like
{{{
  mail.workflow.admin = authenticate(level=1) admin
}}}
This enables the ''list+admin@example.com'' address and requires
password authentication (minimally -- GnuPG authentication would also
be fine).

The system administrator must also designate one or more list
administrators and configure a suitable authentication method for
them:
{{{
  pl-subchange --admin --auth=password:secret list@example.com \
      listadmin@example.com
}}}

There are some list configuration parameters that deal with remote
administration:

'''admin.allowed'''::
  If this is set, it contains a space-delimited list of commands that
  the remote administration interface will honour. Use this, e.g., to
  prevent list administrators from changing the list configuration.

'''admin.setconfig.refuse''::
  If this is set, it contains a regular expression to be applied to
  the names of configuration parameters in a '''setconfig''' command.
  Any parameter whose name matches this regular expression will be
  ignored.

'''admin.setconfig.allow''::
  If this is set, it contains a regular expression to be applied to
  the names of configuration parameters in a '''setconfig''' command.
  Any parameter whose name does not match this regular expression
  will be ignored.