petidomo/docs/petidomo.tex

\documentclass[a4paper,10pt]{scrreprt}
%
% Petidomo Manual
%
% $Header$
%
\typearea[2cm]{12}
\fussy

\begin{document}
\title{The Petidomo Mailing List Manager}
\author{Peter Simons $<$simons@computer.org$>$}
\date{February 2001}
\maketitle

\tableofcontents
\clearpage

\chapter{Installing Petidomo}

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

\section{Getting it}

    {\sf This section has not been written yet, because the means of
    obtaining Petidomo from the Internet are not entirely defined at
    the moment. I put all my hope into the most kind Mister
    Engelschall to fill in the details here. }

\section{Building the Binaries}

Untar the source archive of Petidomo in a directory of your choice
like {\sf /usr/local/src} or your home directory. This will create a
directory called {\sf petidomo-VERSION}, where the ``{\sf 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
\begin{quote}
\begin{verbatim}
./configure
\end{verbatim}
\end{quote}
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:
\begin{description}

\item[{-}{-}help] Display the complete list of command line options.

\item[{-}{-}prefix] The the {\sf PREFIX} for all following paths. The
default is {\sf /usr/local}.

\item[{-}{-}exec-prefix] Set the {\sf 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
{\sf EPREFIX} is identical to {\sf PREFIX}. The default is {\sf
PREFIX}.

\item[{-}{-}bindir] Set the directory where the binaries should be
installed. The default is {\sf EPREFIX/bin}.

\item[{-}{-}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 {\sf EPREFIX/libexec}.

\item[{-}{-}datadir] Set the directory where read-only
architecture-independent data files should be installed (like the help
file). The default is {\sf PREFIX/share}.

\item[{-}{-}sysconfdir] Set the directory where read-only
configuration files should be installed. The default is {\sf
PREFIX/etc}.

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

\item[{-}{-}mandir] Set the directory where man documentation files
should be installed. The default is {\sf PREFIX/man}.

\end{description}

Please note that the directories you specify here are only the default
settings that are compiled into Petidomo. You can modify \emph{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:
\begin{quote}
\begin{verbatim}
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
\end{verbatim}
\end{quote}

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:
\begin{description}
\item[CC] The name of the C compiler to use.

\item[CPPFLAGS] Flags to pass to the preprocesser before compiling a
source code file.

\item[CFLAGS] Flags to pass to the compiler when compiling a C source
code file.

\item[LDFLAGS] Flags to pass to the linker when linking the binaries.

\end{description}

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:
\begin{quote}
\begin{verbatim}
CFLAGS=-O3 LDFLAGS=-s ./configure
\end{verbatim}
\end{quote}

Anyway, once the configure script has been run, just call
\begin{quote}
\begin{verbatim}
make
\end{verbatim}
\end{quote}
to start the building process. Petidomo has been tested with various
flavours of the make utility and all of them seem to work fine. If in
doubt, try GNU Make, which is available from {\sf 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.

\section{Installing the Binaries}

To install the software to your system, all you have to do is execute
\begin{quote}
\begin{verbatim}
make install
\end{verbatim}
\end{quote}
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
\begin{quote}
\begin{verbatim}
make install-testlist
\end{verbatim}
\end{quote}
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:
\begin{quote}
\begin{verbatim}
/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/
\end{verbatim}
\end{quote}
If you run the ``install-testlist'' target, the following
directory/files will be created additionally:
\begin{quote}
\begin{verbatim}
/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
\end{verbatim}
\end{quote}

\section{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 {\sf aliases} file, which usually resides in
{\sf /etc/aliases} or, with newer sendmail versions, in {\sf
/etc/mail/aliases}:
\begin{quote}
\begin{verbatim}
petidomo-manager:   postmaster
petidomo:           "|/usr/local/bin/petidomo --mode=listserv"
petidomo-approve:   "|/usr/local/bin/petidomo --mode=approve"
\end{verbatim}
\end{quote}
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 \emph{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:
\begin{quote}
\begin{verbatim}
testlist:           "|/usr/local/bin/petidomo --mode=deliver testlist"
testlist-request:   "|/usr/local/bin/petidomo --mode=listserv testlist"
testlist-owner:     petidomo-manager
\end{verbatim}
\end{quote}
Having done all this, execute the {\sf newaliases} utility to rebuild
sendmail's internal database. Your changes will not have any effect
unless you do this.

\section{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
\emph{may} be something else, so we better figure it out for sure.

Add the line
\begin{quote}
\begin{verbatim}
foobar:             "/tmp/foobar-mail"
\end{verbatim}
\end{quote}
to your aliases file and execute {\sf newaliases}. Then send an e-mail
to the address ``foobar''. The contents of this mail will be stored in
the file {\sf /tmp/foobar-mail} then and we are interested in the user
who owns this file:
\begin{quote}
\begin{verbatim}
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
\end{verbatim}
\end{quote}
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'' --- {\sf /usr/local/var/petidomo} per default. You
can ensure this by executing the command:
\begin{quote}
\begin{verbatim}
chown -R daemon /usr/local/var/petidomo
\end{verbatim}
\end{quote}

This is a rather simplistic solution to the permisson problem; you
\emph{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 {\sf ack-queue} located
in it.

Of course, you do not necessarily need to have the {\sf ack-queue}
directory owned by ``daemon'', you can also set the group permissions
apropriately. Furthermore, Petidomo will usually want to write to the
{\sf 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 {\sf
LOG\_MAIL} facility --- this is where Petidomo logs its error messages.

\section{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 {\sf /usr/local/etc}. There you will find two files: {\sf
petidomo.conf-sample} and {\sf petidomo.acl-sample}. Just rename them
to {\sf petidomo.conf} and {\sf petidomo.acl} respectively and fire up
your favorite text editor to edit the file {\sf 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 {\sf /usr/sbin/sendmail}, but at
{\sf /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.

\section{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:
\begin{quote}
\begin{verbatim}
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
\end{verbatim}
\end{quote}

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 {\sf LOG\_MAIL} facility now --- this is usally {\sf
/var/log/messages} or {\sf /var/log/maillog} ---, you will find that
Petidomo logged entries there that look pretty much like the following
ones. The backslash (``\verb#\#'') 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.
\begin{quote}
\begin{verbatim}
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
\end{verbatim}
\end{quote}

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 {\sf
/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:

\begin{quote}
\begin{verbatim}
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 ...
\end{verbatim}
\end{quote}

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 \emph{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 {\bf Petidomo Mailing
List Manager!}

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

\end{document}