petidomo/INSTALL

                         Installing Petidomo

The installation of the Petidomo Mailing List Manager is simple and
straight forward; do not be scared by the length of this document.
There are many different ways and options how to install it and I have
tried my best to cover *all* of them. If you are not interested in
every little detail, you will be able to skim over most of the text
here.

                                   Peter Simons <simons@computer.org>


Building the Binaries
=====================

Untar the source archive of Petidomo in a directory of your choice
like /usr/local/src or your home directory. This will create a
directory called petidomo-VERSION, where the "VERSION" part is called
exactly as in the file name of the tar archive. Change into this
directory.

Now you have to run the configure script

    ./configure

which will determine the characteristics of your system and create the
files required to actually build Petidomo. You may provide several
parameters to the script. The interesting ones, including the default
values if unspecified, are:

   --help
        Display the complete list of command line options.

   --prefix
        The the PREFIX for all following paths. The default is
        /usr/local.

   --exec-prefix
        Set the EPREFIX for all following paths. This is useful in
        case you want to install binaries into a different directory
        hierarchy than normal text files, but usually the EPREFIX is
        identical to PREFIX. The default is PREFIX.

   --bindir
        Set the directory where the binaries should be installed. The
        default is EPREFIX/bin.

   --libexecdir
        Set the directory where executables should be installed that
        will be called by Petidomo but not by the user directly (like
        posting filters). The default is EPREFIX/libexec.

   --datadir
        Set the directory where read-only architecture-independent
        data files should be installed (like the help file). The
        default is PREFIX/share.

   --sysconfdir
        Set the directory where read-only configuration files should
        be installed. The default is PREFIX/etc.

   --localstatedir
        Set the directory where modifiable data files should be
        installed (like the approve-queue or the mailing list config
        files). The default is PREFIX/var.

   --mandir
        Set the directory where man documentation files should be
        installed. The default is PREFIX/man.

Please note that the directories you specify here are only the default
settings that are compiled into Petidomo. You can modify *all* paths
at run-time via the command line and through the configuration files.
So don't waste to much time figuring out what you want here, you can
change anything later without having to recompile Petidomo.

Finally, here is an example output of the configuration script when
run without any parameters on a Linux machine:

    simons@peti:~/projects/petidomo-4.0b1$ ./configure
    Configuring OSSP Petidomo, Version 4.0b1 (18-Jan-2001)
    creating cache ./config.cache
    checking for gcc... gcc
    checking whether the C compiler (gcc  ) works... yes
    checking whether the C compiler (gcc  ) is a cross-compiler... no
    checking whether we are using GNU C... yes
    checking whether gcc accepts -g... yes
    checking for ranlib... ranlib
    checking for flex... flex
    checking for yywrap in -lfl... yes
    checking for bison... bison -y
    checking size of unsigned short... 2
    checking size of unsigned int... 4
    checking size of unsigned long... 4
    checking how to run the C preprocessor... gcc -E
    checking for ANSI C header files... yes
    checking for ssize_t... yes
    updating cache ./config.cache
    creating ./config.status
    creating Makefile

Often, you may want to pass certain flags to the compiler or the
linker to modify the building process. To achieve this, you can set
certain environment variables before calling the configure script.
These variables are:

   CC
        The name of the C compiler to use.

   CPPFLAGS
        Flags to pass to the preprocesser before compiling a source
        code file.

   CFLAGS
        Flags to pass to the compiler when compiling a C source code
        file.

   LDFLAGS
        Flags to pass to the linker when linking the binaries.

I personally find this useful to raise the level of compiler
optimization or to add linker flags that tell the linker to strip
unnecessary symbols from the binaries. To achive these effects, I call
the configure script like this:

    CFLAGS=-O3 LDFLAGS=-s ./configure

Anyway, once the configure script has been run, just call

    make

to start the building process. Petidomo has been tested with various
flavours of the make(1) utility and all of them seem to work fine. If
in doubt, try GNU Make, which is available from ftp.gnu.org.

Petidomo has also been built using parallel builds. This is useful if
you have a multi-processer system. You can do this with most make
utilities by adding the flag "-j4" with "4" being the number of
processes you want to spawn simultaneously. Please note, though, that
some make utilities have problems with the rules that translate the
yacc-modules included in Petidomo correctly when building in parallel.
If you experience any trouble, just build it conventionally and you
should be fine.


Installing the Binaries
=======================

To install the software to your system, all you have to do is execute

    make install

This will copy the Petidomo binary, the posting filters included in
the distribution, the sample config files and the manual pages into
the directories you chose at configure time earlier. If you're a
first-time user, you may also want to execute

    make install-testlist

which will create a sample mailing list called "testlist" for you.

Assuming you used the default paths when running configure, the
install process will create the follwing directories, respectively
copy the following files to your system:

    /usr/local/
    /usr/local/bin/
    /usr/local/bin/petidomo
    /usr/local/bin/petidomo-approve
    /usr/local/bin/petidomo-kickout
    /usr/local/etc/
    /usr/local/etc/petidomo.acl-sample
    /usr/local/etc/petidomo.conf-sample
    /usr/local/libexec/
    /usr/local/libexec/petidomo/
    /usr/local/libexec/petidomo/insert-name-in-subject.sh
    /usr/local/libexec/petidomo/pgp-decrypt.sh
    /usr/local/libexec/petidomo/pgp-encrypt.sh
    /usr/local/libexec/petidomo/rfc2369.sh
    /usr/local/man/
    /usr/local/man/man1/
    /usr/local/man/man1/petidomo.1
    /usr/local/share/
    /usr/local/share/petidomo/
    /usr/local/share/petidomo/help
    /usr/local/var/
    /usr/local/var/petidomo/
    /usr/local/var/petidomo/ack-queue/
    /usr/local/var/petidomo/index
    /usr/local/var/petidomo/lists/

If you run the "install-testlist" target, the following
directory/files will be created additionally:

    /usr/local/var/petidomo/lists/testlist/
    /usr/local/var/petidomo/lists/testlist/config
    /usr/local/var/petidomo/lists/testlist/acl
    /usr/local/var/petidomo/lists/testlist/list


Configuring Sendmail
====================

Before you can use Petidomo, you have to configure sendmail so that it
knows about Petidomo -- I assume that you have sendmail installed
already. If you are using an MTA other than sendmail, you are on your
own from here on, I am afraid. Any users who have successfully
installed Petidomo on a qmail-, vmailer-, or postfix-based system are
more than welcome to contribute to this documentation to help other
users.

To run Petidomo via sendmail -- what is what you want to do --, you
have to create apropriate aliases for it. You can do this by adding
the folling lines to your aliases file, which usually resides in
/etc/aliases or, with newer sendmail versions, in /etc/mail/aliases:

    petidomo-manager:   postmaster
    petidomo:           "|/usr/local/bin/petidomo --mode=listserv"
    petidomo-approve:   "|/usr/local/bin/petidomo --mode=approve"

In case you installed the Petidomo binary to some other location, you
will have to change the paths here apropriately of course. You may
also chose that mail for the "petidomo-manager" should go to some
different address than "postmaster", if that suits your needs better;
the main point is that somebody actually *reads* what arrives there.

If executed the "install-testlist" target earlier and thus have the
example mailing list from the distribution installed, you may also
want to add the lines:

    testlist:           "|/usr/local/bin/petidomo --mode=deliver testlist"
    testlist-request:   "|/usr/local/bin/petidomo --mode=listserv testlist"
    testlist-owner:     petidomo-manager

Having done all this, execute the newaliases(1) utility to rebuild
sendmail's internal database. Your changes will not have any effect
unless you do this.


Configuring the File Permissions
================================

The final step, before Petidomo is successfully installed, is to set
the right permissions to the installation directories and installed
files. Unfortunately, the installation process can not do this
automatically; you have to chose what permissions are "right"
yourself. If works like this: Petidomo will be called from sendmail,
thanks to the aliases you just created. That means, that sendmail
determines under what user to start Petidomo. In 99% of all
configurations I have ever seen, that user is "daemon", but it *may*
be something else, so we better figure it out for sure.

Add the line

    foobar:             "/tmp/foobar-mail"

to your aliases file and execute newaliases(1). Then send an e-mail to
the address "foobar". The contents of this mail will be stored in the
file /tmp/foobar-mail then and we are interested in the user who owns
this file:

    root@peti:/# sendmail -v foobar </dev/null
    foobar... aliased to "/tmp/foobar-mail"
    "/tmp/foobar-mail"... Sent
    root@peti:/# ls -l /tmp/foobar-mail
    -rw-------   1 daemon   daemon        269 Feb 12 17:57 /tmp/foobar-mail

See? On my system it is "daemon" indeed. On your system it may be
someone else. Now that we know, you may remove the foobar-line from
the aliases file again.

OK, sendmail starts Petidomo under user id "daemon". This means that
"daemon" must have read access to virtually any file in the Petidomo
installation. This is the default, because all files are installed
with read permisson for everybody. Also, all directories allow access
to anybody by default. But "daemon" also needs write access to the
"localstatedir" -- /usr/local/var/petidomo per default. You can ensure
this by executing the command:

    chown -R daemon /usr/local/var/petidomo

This is a rather simplistic solution to the permisson problem; you
*can* use much more fine-grained settings if you like to. But I
figured that if you are the kind of person who wants to do things like
this, you won't need an explanation how to do it anyway. Just that
much information for you: Petidomo does not actually write to the
"localstatdir", but only to the subdirectory ack-queue located in it.

Of course, you do not necessarily need to have the ack-queue directory
owned by "daemon", you can also set the group permissions
apropriately. Furthermore, Petidomo will usually want to write to the
lists directory located in the "localstatedir", because most list
administrators tend to place the mailing list archives there, but you
can enable write access according to the list's configuration once you
know how you're mailing lists are configured. In case something does
not work as expected, check out the syslog messages for the LOG_MAIL
facility -- this is where Petidomo logs its error messages.


Configuring Petidomo
====================

The last step before we can test our installation is to configure
Petidomo. This is really simple. List the contents of the "sysconfdir"
you chose. If you did not change the default paths, this is
/usr/local/etc. There you will find two files: petidomo.conf-sample
and petidomo.acl-sample. Just rename them to petidomo.conf and
petidomo.acl respectively and fire up your favorite text editor to
edit the file petidomo.conf.

Uncomment the options "Hostname", "AdminPassword", and "MTA" and set
the values correctly. "Hostname" should be the fully qualified domain
name of the machine running Petidomo. It is essential that this name
can receive e-mail, that is, that is has an MX record. (Talk to the
person administrating the domain name service of your organization if
this doesn't make any sense to you.) As "AdminPassword", you can chose
pretty much any text you like, just make sure you remember it. The
"MTA" setting will usually be alright the way it is. You may want to
check whether sendmail does actually live at this path; on some
Unixes, it is not installed at /usr/sbin/sendmail, but at
/usr/lib/sendmail. Change the setting if this is the case. You can
ignore all other settings right now. Come back and configure those
once you have read the apropriate sections of this manual. If you're
an experienced Unix wizard, the comments in the config file will
probably be enough for you to guess what these options do, though.

Once you have done this, your installation is ready to be tested.


Testing the Installation
========================

Asserting you followed all steps described above, you have a working
Petidomo installation now. Occasionally, some minor permisson problem
may still remain to be fixed, or you may want to customize some texts.
To figure out what is left to do (or to realize that there is nothing
left do to), send an e-mail to the "petidomo" user on your machine and
put the word "help" into the mail body -- without the quotes of
course.

On my system, this looks like this:

    simons@peti:~/projects/petidomo$ echo help | sendmail -v petidomo
    petidomo... aliased to "|/usr/local/bin/petidomo --mode=listserv"
    "|/usr/local/bin/petidomo --mode=listserv"... Connecting to prog...
    "|/usr/local/bin/petidomo --mode=listserv"... Sent

Once you sent the e-mail, sendmail will start up Petidomo and feed the
mail text into it for processing. If you take a look at the syslogfile
containing the LOG_MAIL facility now -- this is usally
/var/log/messages or /var/log/maillog --, you will find that Petidomo
logged entries there that look pretty much like the following ones.
The backslash ("\") characters at the end of some of these lines
denote that the line has been wrapped for readability. In reality,
this would be one single large line.

    sendmail[8705]: f1CIHWJ08705: from=simons, size=5, class=0, \
	    nrcpts=1, msgid=<200102121817.f1CIHWJ08705@peti.cryp.to>, \
	    relay=simons@localhost
    petidomo[8706]: Petidomo 4.0b1 (18-Jan-2001) starting up; \
	    mode=listserv, listname=<none>, \
	    masterconf=/usr/local/etc/petidomo.conf, \
	    approved=false, ruid=2, euid=2, gid=2, egid=2
    petidomo[8706]: simons@peti.cryp.to: help
    sendmail[8707]: f1CIHX508707: from=petidomo-manager@peti.cryp.to, \
	    size=2091, class=-100, nrcpts=1, \
	    msgid=<200102121817.f1CIHX508707@peti.cryp.to>, \
	    relay=daemon@localhost
    sendmail[8705]: f1CIHWJ08705: \
	    to="|/usr/local/bin/petidomo --mode=listserv", \
	    ctladdr=petidomo (2/0), delay=00:00:01, xdelay=00:00:01, \
	    mailer=prog, pri=30005, dsn=2.0.0, stat=Sent
    sendmail[8709]: f1CIHX508707: to=simons@peti.cryp.to, delay=00:00:00, \
	    xdelay=00:00:00, mailer=local, pri=212091, dsn=2.0.0, stat=Sent

As you can see, Petidomo logged how it was started, where it is
expecting its master config file and under which user- and group id it
is running. Then it logs that it has received a HELP request. This
request will be answered by sending the file
/usr/local/share/petidomo/help back to the person who requested help,
and if everthing worked, you will now find that mail in your mail box.

If something went wrong, Petidomo will tell you what went wrong. So,
please fix the problem and try again. In 99% of all cases, the error
will say something like "opening file XYZ failed: permission denied".
Then all you have to do is to make sure that the user under which
Petidomo has been started (you have the numeric id in the logfile) has
read access to that file. If the user has but Petidomo keeps
complaining, check, whether that user has access to the directory at
all!

Those of you who executed the "install-testlist" target earlier in
the "Building the Binaries" chapter may also want to test whether
this mailing list is working. To do so, send another mail to Petidomo
and put the command "subscribe YOUR-ADDRESS testlist" in the mail
body -- without the quotes! "YOUR-ADDRESS" naturally means that you
should insert your e-mail address here. This command will subscribe
your e-mail address to the "testlist" mailing list; you should
receive a confirmation about that via e-mail within moments. Once that
is accomplished, send another e-mail to the "testlist" address on
your system. The e-mail may look like whatever you want.

Within seconds, you should get the mail back from the mailing list
server -- and so will all other addresses that are subscribed to the
list. My personal test mail looked like this:

    From testlist-owner@peti.cryp.to  Mon Feb 12 19:43:56 2001
    Received: (from daemon@localhost)
	    by peti.cryp.to id f1CIhuA08872 for simons@peti.cryp.to;
	    Mon, 12 Feb 2001 19:43:56 +0100
    Received: (from simons@localhost)
	    by peti.cryp.to id f1CIhJY08853 for testlist;
	    Mon, 12 Feb 2001 19:43:19 +0100
    Date: Mon, 12 Feb 2001 19:43:19 +0100
    From: Peter Simons <simons@peti.cryp.to>
    Message-Id: <200102121843.f1CIhJY08853@peti.cryp.to>
    Subject: Petidomo absolutely rules the known earth!
    Reply-To: testlist@peti.cryp.to
    Sender: testlist-owner@peti.cryp.to
    Precedence: list

    It does ...

If this all worked for you, you have a your Petidomo installation up
and running. Men will envy you and women will desire you -- unless, of
course, you *are* a woman, then it is vice versa. You will be able to
stop smoking any time you want, you may eat anything you like and as
much as you like, but you will never gain a single pound. Your sex
life will improve dramatically, your boss will like you, your hard
drives will never crash and your Internet connections will always be
fast. All this, thanks to the wonders of the Petidomo Mailing List
Manager!

In case any of the benefits promised above stays away, please consult
paragraphs 11 and 12 of the file COPYING included in this
distribution.