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 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 , \ relay=simons@localhost petidomo[8706]: Petidomo 4.0b1 (18-Jan-2001) starting up; \ mode=listserv, listname=, \ 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 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.