=========================== Minimalist =============================

I. Common information

Minimalist is a MINImalist MAiling LIST manager. It is fast, extremely easy
to setup and support. It is written in Perl and full tested on FreeBSD and
Linux, where it works pretty well. However there aren't causes not to use
Minimalist on any other Unix system, because it doesn't use any
system-dependent features.

Minimalist has these features:

 . subscribing/unsubscribing users by request
 . support for write-only option of subscription
 . several levels of security
 . additional services such as information about list, archiving lists,
      information about users of list and so on.
 . support for read-only/closed/mandatory lists
 . support for external delivery of processed message
 . support for Blacklist
 . logging activity

Minimalist has also a notion of 'administrators'. They have full rights to
subscribe/unsubscribe other users; get any information related to lists and
users.

All commands must be in mail's subject. Supported commands are:

subscribe <list> [<email>]:
	subscribe user to a mailing list
unsubscribe <list> [<email>]:
	unsubscribe user from a mailing list
auth <code> :
	confirm command, which need to be confirmed. This command isn't
	standalone, it must be used after certain other commands.
which [<email>] :
	get list of lists, to which user subscribed
who <list>:
	gives information about users, subscribed to <list>
info [<list>]:
	gives information about existing lists or information about <list>
help:
	help message

Note:
1. Only administrators allowed to use <email> in commands subscribe and
    unsubscribe.
2. Only administrators can run commands with <list>.

----------------------------------------------------------------------------
II. Install

To install place minimalist.pl somewhere (in /usr/local/sbin for example).
This path must be accessible for MTA and minimalist.pl must be executable
by your MTA. Then copy minimalist.conf-sample to
/usr/local/etc/minimalist.conf. If you wish to place it in different
location, use -d switch, followed by directory name, where appropriate
config located. Set variables in config accordingly to your needs (defaults
are useful in most cases).

The next step is creating alias for minimalist that pipes message to the
program. The often place of aliases file is /etc/aliases. Add this line at
the end of file:

minimalist:		"|/usr/local/sbin/minimalist.pl"

If you are using sendmail, you must to execute 'newaliases' after changes
in /etc/aliases.

After this you must create directory which Minimalist will use for his work.
It is defined in the minimalist.conf by directive 'directory'. This
directory must be *WRITABLE* by your MTA (check next section for information
how to detect Minimalist's EUID/EGID).

----------------------------------------------------------------------------
III. Creating lists

1. In the main Minimalist's directory create directory, named exactly as
list you creating. This directory and it's contents must be owned by
uid/gid of your MTA (it's because Minimalist will write here some control
information - subscribed users, archived messages, etc). The simple and right
method to know MTA's euid/egid is:

 . create in /etc/aliases such entry:
 	mtaid:	"|tee /tmp/mtaid.tst"
 . mail message to mtaid
 . check owner/group of resulted /tmp/mtaid.tst and chown main Minimalist's
   directory to this owner/group
 . delete 'mtaid' alias from /etc/aliases

2. Add list's name and short description of it into lists.lst file (in the
main Minimalist's directory). This file will be shown by the command
<info>. Example of this file's contents:

list	This is testing list
info	General information, news, etc

3. Create in the list's directory some files:

 a) config.
     Private settings for this list, which override global parameters.
     There is may be any directive from minimalist.conf except 'directory'
     and 'admin'.

 b) info.
     Common information about list, used when user subscribes to the list
     and requests information about list.

 c) footer.
     This file will be appended to any message, passed via list.

There are some useful macros can be used in 'info' and 'footer' files:

 \a	will be expanded to administrator's email
 \d	will be expanded to <domain>
 \l	will be expanded to <list>
 \o	will be expanded to <list>-owner@<domain>

4. Add some lines to /etc/aliases file:

list:		"|/usr/local/sbin/minimalist.pl list"
list-owner:	user@somewhere

----------------------------------------------------------------------------
IV. Check configuration

You always can check configuration with command:

 minimalist.pl - [listname [listname ... ]]
 
where 'listname' is existing list's name.  If there are errors in they will
be reported. It is recommended always check configuration after any
changes either in global configuration file or in list's config.

----------------------------------------------------------------------------
V. Security

There is directive 'password' in the global and private configs, which
contains password for trusted users. You must set owner and permissions of
this configs to allow your MTA access configs and disallow access for
unprivileged users.

----------------------------------------------------------------------------
VI. Enjoy :)

There is sample directory sample/ in the distribution with examples of
configuration files.

Archives are located under list's directory in archive/yyyy./mm./dd./[0-9]*
in format one file per one message. DON'T DELETE "SEQUENCE" file in this
directory - there is a number of a last archived message!

There is mailing list about Minimalist. Please, mail to
minimalist@kiev.sovam.com with subject of 'subscribe mml-general' to subscribe
on this list.

Please, mail me about any errors in software. I will fix them and then
release fixed version. Thank you very much.

Vladimir Litovka, <doka@kiev.sovam.com>
http://www.mml.org.ua/
