README for minordomo 0.7

Minordomo is a minimalist mailing list manager. It can be considered a
feature limited replacement of majordomo.  

Supported commands are:

subscribe <list>:	subscribes to a mailing list
unsubscribe <list>:	unsubscribes from a mailing list
info [<list>]:		gets information on a list or server
list <list>:		returns a subscriber list if enabled


Minordomo Quickstart

     If you don't know what you're doing, skip this section and go to
the next section, "Minordomo Installation Instructions".

     If you do know what you're doing, do the following for a quick,
default installation. The paths given are suggestions; you can change
them to suit your system.  If you do, make sure you update the line
near the top of minordomo.pl that points to minordomo.conf, and the
line in minordomo.conf that points to the minordomo directory.

     To set up minordomo itself:
          cp minordomo.pl   /usr/local/sbin/minordomo.pl
          cp minordomo.conf /etc/minordomo.conf
          mkdir             /var/lib/minordomo 

          (optional, for web archives)
          cp minorweb.pl    /path/to/your/cgi-bin
                - or -
          cp minorweb.pl    /path/to/your/mod_perl

          add a minordomo mail alias line in /etc/aliases
               minordomo:	   "|/usr/local/sbin/minordomo.pl"

     For each mailing list you want to set up:
          add a mailing list mail alias line in /etc/aliases:
               mymailinglist:	   "|/usr/local/sbin/minordomo.pl mymailinglist"

          mkdir /var/lib/minordomo/mymailinglist 
          # Make sure this directory is readable/writable by sendmail 
          # (or whatever MTA you use). Normally, the following commands should
          # work:
          chown mail.mail /var/lib/minordomo/mymailinglist
          chmod 775 /var/lib/minordomo/mymailinglist

     Optionally, for each mailing list you can also:
               
          cp libdir/sample-list/config /var/lib/minordomo/mymailinglist/config
          cp libdir/sample-list/info   /var/lib/minordomo/mymailinglist/info
          cp libdir/sample-list/footer /var/lib/minordomo/mymailinglist/footer

     And then edit config, info, and footer to contain appropriate text.
     Refer to the section below and the contents of the libdir/sample-list files
     for details.

     That's it.  Send e-mail to minordomo@yourhostname to subscribe to
the new mailing list.


Minordomo Installation Instructions

To install minordomo itself, place minordomo.pl someplace
(/usr/local/sbin is OK) where it will be executable by your MTA.  
Then copy minordomo.conf.sample to /etc/minordomo.conf.

minordomo.conf file is fairly self explanatory.  If you wish to place
minordomo.conf in a different location, edit the appropriate line at
the top of minordomo.pl.

You will also need to add a mailing alias for minordomo that pipes
messages to the program. For example, with sendmail at the following
line to /etc/aliases and run newaliases:

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

If you wish to have a simple web based interface to your list archives, the
provided minorweb.pl script will be useful. It can be placed in your system's
cgi-bin directory. Also, this script should work with mod_perl, the Apache
module that improves performance of perl scripts. See http://perl.apache.org/
or http://apache.perl.org/ for more information on mod_perl. To use minorweb.pl
with mod_perl, simply place it in your mod_perl directory. Note, minorweb.pl
also uses the /etc/minordomo.conf file, so if you placed this file in another
location, you will need to edit the top of minorweb.pl to point to the correct
location.


Creating minordomo Mailing Lists

Creating lists is a relatively simple process. 

First, create a directory for the list in your minordomo directory
(from minordomo.conf). This directory must be read/writeable by your
MTA. The name of the directory should be that of the list.

If you place a file named "config" in this directory, it will override
the minordomo.conf config file.  This is useful when you have mailing
lists that need to use different values for domain name, archive
address, etc (for example, lists that serve a virtual domain).

In the directory, you should have a file called info which contains
the information returned when a user subscribes or sends the 
"info <list>" command.  

It is also advisable to put a line or two in a file called info in the
main minordomo directory describing the list.

You may also optionally put a file called footer in the directory. This 
file will be automatically appended to all messages going through the
list. It is a plain text file with the following escape sequences
allowed:

\a:			expands to the administrator's e-mail address
\d:			expands to the domain name
\l:			expands to the mailing list name (without the domain)
\u:			expands to the URL of the list archive

You can look in the libdir/sample-list directory for examples of these files. 

Once you have created the directory and files, add another alias like this:

mymailinglist:			"|/usr/local/sbin/minordomo.pl mymailinglist"

That is all there is to it. If you have any questions or comments, subscribe to
the minordomo mailing list. Send a message to minordomo@nodomainname.net with a
subject of "subscribe minordomo-list" (no quotes).


Notes On sendmail restricted shell (smrsh)

On some sendmail based systems, you may get an error similar to the following
when trying to mail to minordomo or a minordomo managed list:

  ----- Transcript of session follows -----
sh: minordomo.pl not available for sendmail programs
554 "|/usr/local/sbin/minordomo.pl"... Service unavailable

If you get this, you are likely running sendmail with the restricted shell
(smrsh) option. In this case, you need to create a symbolic link to the
minordomo.pl script in /etc/smrsh. For example:

   cd /etc/smrsh
   ln -s /usr/local/sbin/minordomo.pl .

That should clear up the problem.

Jakob 'sparky' Kaivo
jkaivo@nodomainname.net
