The Petidomo Mailing List Manager

Peter Simons <simons@petidomo.com>

August 23, 1998

This version of the Petidomo Mailing List Manager must not be used for commercial purposes.

Petidomo Mailing List Manager is copyrighted in 1997 by CyberSolutions GmbH and Peter Simons. All rights are reserved.

The Petidomo Mailing List Manager may only be obtained directly from CyberSolution's WWW site, at http://www.petidomo.com/. Re-distribution of the package is prohibited.

You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to use the program. These actions are prohibited by law if you do not accept this license. Therefore, by using the program, you indicate your acceptance of this license to do so, and all its terms and conditions.

Because the program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. CyberSolutions GmbH provides the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event will CyberSolutions GmbH be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if CyberSolutions has been advised of the possibility of such damages.

Contents

1 Quickstart for the impatient

 

We know you feel now. You just downloaded the new software package and are eager to see it work as fast as possible. So, even though it is kind of mad to write this long manual with the knowledge that the vast majority of users will never read it, here is a step by step quickstart guide.

  1. Get the distribution for your Unix platform.
  2. Unpack the tar archive: gunzip <archivename | tar xf -
  3. su to the super user.
  4. Create a user petidomo and a group petidomo. The home directory of this user is the place where the whole package will be installed. The user doesn't need a valid password and shell.
  5. As superuser, cd into the directory `petidomo- your-architecture-name' and start ./install.sh or sh install.sh.
  6. Answer all questions asked by the script truthfully.
  7. If no error occurs, send an e-mail to the Petidomo Mailing List Manager: mail petidomo </dev/null and see what happens.
  8. Now use your WWW browser to access `http://localhost/cgi-bin/petidomoconf.cgi' and create any mailing lists you'd like to have.
  9. Be happy.
  10. Now read the blasted user manual. It was a lot of work to write it.

2 Introduction

Congratulations. Obviously you are a clever person. Not only did you choose the Petidomo Mailing List Manager to run your mailing lists, you also decided to read the user manual. I really appreciate that, mostly because I strongly dislike writing user manuals and it gives the whole process at least some sense that someone actually reads it.

For a start, I think, I will bore you with a few historical facts, which you can absolutely afford to skip if you're in a hurry. What you probably are. I'll recount the story of Petidomo nonetheless.

2.1 History of Petidomo

Thanks to using version control systems consequently, I was able to determine that I started working on Petidomo exactly at fourty minutes after midnight on the December 26th, 1993. I was in desperate need of a mailing list server for my Amiga computer and so I queried ``archie'' for source codes. (Does anybody remember the days when ``archie'' was still popular?)

What I found was a Unix package called ``Listserv'', which implemented some basic functionality like subscribing and unsubscribing a mailing list automatically. Unfortunately there are many differences between Unix and the AmigaOS, which my computer had. It took until January 9th, 1994 before I had a running version of the program and not even the small number of commands the Unix version originally had worked.

Anyway, I had my mailing list server and eventually I was able to release it to the public under the name ``AmigaListserv''. Since it was the only mailing list server in existance for the Amiga platform, it became pretty popular after a while and I was flooded with bug reports, enhancement requests, proposals of marriage and insults of my general ability to program. So I turned the project into a shareware product and spent countless hours improving the code and adding new features. If I remember correctly, I was able to bring two more major releases out until I had reached ``AmigaListserv version 3.0''.

At some point, though, I became more and more discontend with the abilities of the Amiga's operating system as an Internet server and at last I switched to Unix. After looking at various mailing list servers for the Unix operating system and disliking them thoroughly, I started porting my own program back to Unix, where it came from originally.

It took quite a while before I had a running version again, but on December 30th, 1995 ``Listserv 4.0 beta'' took over my mailing lists on Unix. Needless to say that porting a souce code between two different systems twice leaves traces behind. The source code was a mess and the number of recursive defines, redefining what other defines had been redefined before had increased beyond the point where you call a source code ``spaghetti code''.

Nonetheless, around May 1996 I faithfully release the 1.0 version to the public under GNU General Public License and waited for feedback. The first mail that arrived after my announcement in the USENET-news was a mail from an L-Soft employee who told me that I would be sued if I wouldn't change the name of my package, because they were selling a program called ``LISTSERV'' for years already and had protected the name.

So I renamed my package to ``Petidomo 1.0'' and released it again.

The number of installations Petidomo quickly had, and the number of positive feedback I received exceeded my expectations by far. Clearly, I must have been doing something right, if a serious number of people preferred my package over the way more powerful alternatives for Unix, like Majordomo, Smartlist, Procmail and LISTSERV.

Again I started improving the functionality, cleaning up the code, making it more portable and stable and so on... Petidomo reached release number 1.3 on December 27th, 1996, almost exactly three years after I started working on the very first version.

Petidomo 1.3 was a widely used and appreciated package, it was stable, very portable, easy to understand and to maintain and it was all in all pretty neat. So I deleted all the source codes and started re-writing it from the scratch.

Don't ask why, programmers do these things occasionally.

The result of this effort is Petidomo 2.1, as you can see. The 2.1 version exceeds Petidomo 1.x's functionality and power in absolutely every aspect, while being even easier to setup and to maintain. Not a single line of code from the original 1.x version was used and the benefit of this is a very modern and efficient design that I am quite proud of.

Some people are disappointed that the 2.1 version is a commercial product now, but too much time and effort has been put into it to give it away for free, I am afraid. But I think the ``free for non-commercial use'' clause is fair for everybody.

Well, thanks for bearing with me during all this gossip, but I felt obligated to tell this story.

And now have fun with the technical part of the manual and I hope you like my program.

2.2 Acknowledgments

Many people contributed to the development of Petidomo directly or indirectly, and we would like to thank everybody for their help at this point.

Hey, all you beta testers: This paragraph is for you. I bet you still can't believe that there's an actual manual for Petidomo available now. Be assured of our deep respect and gratitude for managing to use a software package that was sometimes unstable and weird, and always undocumented except for a totally outdated README file.

A big ``thank you'' to Markus Fleck of the University of Bonn for providing us with an FTP mirror of the Petidomo Beta distributions.

Furthermore, our appreciation to Gray Watson for writing the excellent ``argv'' and ``dmalloc''-libraries, which have been used in the Petidomo Mailing List Manager during the beta testing phase.

And last, but not least, the developers would like to thank the team of CyberSolutions GmbH for their support during the development, for taking over all the marketing stuff while we were programming and for providing the Internet WWW server for Petidomo.

3 What is a mailing list anyway?

This chapter is meant as an introduction into the principles of mailing lists, the way a mailing list server works and the terminology commonly used in this context. For the beginner, it is recommended to read this chapter carefully, as many of the terms used in the rest of the manual will be explained here. Advanced readers can safely skip this chapter because it does not describe the Petidomo mailing list server in particular and is not relevant for configuring and using the package.

Electronic mail is still the most-used service in the Internet, and not the WWW, as one might expect. It use it for causual conversations between people all over the world, for discussions of all kind of topics, for transmitting data files through the net or for distributing information amongst colleagues in a world-wide company. Even in Intranets electronic mail is very useful, because it is quick, easy to archive and reliable.

Electronic mail is not limited to conversations between only two peers. A mail may have several recipients unlike a paper letter. Hence, discussions between groups of people can be held with this media easily. Everybody sends the mail to all persons involved in the discussion and everybody can reply in a way that all others see his text, too.

For larger groups of people, though, this becomes inconvenient. When exchanging e-mail in a larger group of recipients, people tend to accidently forget persons in the list of recipients, they send their replies to the wrong person, they have to keep their aliases up-to-date for the mail to reach the person, etc...

To remedy these shortcomings, the idea of the mailing list was developed. A mailing list is (hosted)  on a central server, which has the addresses of the people who are on that mailing list. Then a special account is created, called the  mailing list address, to which people can send the mail they want to be distributed to all receivers.

  figure66
Figure 3.1: A mail is posted to the mailing list.

The machine accepts the mail, looks up the list of addresses in the list, and re-sends the mail to all those people. If one of the persons on the list wants to reply to a mail he or she has received via the mailing list, he or she sends the reply to the mailing list address again and it is automatically distributed among all recipients again.

The list of addresses on the machine hosting the mailing list is called the  list of subscribers and a person who is on that list is consequently called a  mailing list subscriber. The process of sending an e-mail to the special address with the intention to get it distributed to all subscribers is called  posting to a list.

  figure75
Figure 3.2: A subscriber replies to the mail.

The advantage of this setup is that each subscriber only has to know the address of the mailing list and not all the addresses of all the subscribers. In fact, a subscriber doesn't even have to know who is subscribed to the mailing list at all.

Imagine the company you're working for would have a mailing list where all employees are subscribed with their current e-mail address. The mailing list address would then be, say, ``all-employees@enterprise.com''. If you'd like to inform all your colleagues about an important happening, you'd simply send an e-mail to that address and everybody would receive it. If a person leaves the company, or a new employee comes to the company, only the list of subscribers on the mailing list server has to be updated and everything would work fine.

Basically, this is what a mailing list server does: It is nothing more than a program that stores a list of addresses, receives mail under a special mailing list address and then re-sends the mail to all subscribers.

Of course you're not limited to one mailing list, you can host as many as you like. Not only a list for all employees, but also discussion forums for the management of the company, for all members of a certain department or all the left-handers. Privately, you can use mailing lists to discuss your favourite hobby with other interested people, you can spread basketball statistics or the latest version of a program all the subscribers are using. There's no limitation. Whenever a group of people has to exchange electronic mail on a regular basis, a mailing list is a good way to do it.

As you can probably imagine, the task of keeping the list of subscribers up-to-date becomes a bit difficult when the number of subscribe addresses grows beyond a few dozen, because people tend to change their e-mail addresses from time to time, for various reasons. On a mailing list for a thousand subscribers from all over the world, the maintainer of the list would probably spend most of his time editing the list file, removing or adding addresses.

That is why Petidomo allows people to do that themselves. Additionally to the part that re-sends the mail to all subscribers, there's a program included in the package that understands a number of commands, like ``subscribe'' or ``unsubscribe''.

If you want to have your address added to a mailing list, you do not contact the maintainer of the list, but you send an e-mail to Petidomo and put the command ``subscribe'' into the mail. Petidomo\ will then add your address to the list automatically. Not only is this easier and more convenient for you, it is also a lot faster. Usually, Petidomo will process a subscription request for a mailing list in a tenth of a second, 24 hours a day, while a human maintainer of the list would probably need several hours or even days to cope with the incoming e-mail.

Similarly you can remove your address from a mailing list, or you can change the address you are subscribed under within a few moments and now human interaction is required.

So how does this work? It's very easy in fact: The command interpreter of the mailing list server has a special address, too. This is the name of the list, with the text ``-request'' append to it. All e-mails directed to this account will be processed by the server. If, for example, you want to subscribe to a mailing list with the name ``basketball'', which has the address ``basketball@nba.com'', you'd send an e-mail to the address ``basketball-request@nba.com'' and put the word ``subscribe'' in the body of the mail.

Petidomo would then receive the mail a few moments later, process it, add your address to the list of subscribers and send you a short recipt back to let you know that your subscription was successful.

It is very important that you know the difference between the address of the mailing list itself, and the program that is maintaining the list of addresses. If you'd write your mail to ``basketball@nba.com'' -- to stick with our example -- instead of ``basketball-request@nba.com'', your command would not be processed by the server but would be re-sent to all subscribers. This is a common mistake beginners make and it is a particular annoying one, because the subscribers are bothered with the useless article on the list, and secondly, because the person who tried to subscribe will not get what he or she wanted: To be subscribed to the list.

The type of mailing list we have described so far is known as a  public mailing list. That is a list that is open to everyone to subscribe. Opposed to that is a  closed mailing list. That is a mailing list where only certain people may subscribe or where every subscription requests needs the approval of the list maintainer to succeed.

The public mailing list is widely used in the Internet for all kind discussion forums, while a closed mailing list is typically used by companies or organizations for maintaining internal forums, that are not meant for everybody. Petidomo can maintain both kind of lists, of course, and a number of variations between the public and the closed list, so it will usually suit your needs just fine.

4 Installing Petidomo

The installation of the Petidomo Mailing List Manager is mostly handled by the script install.sh, which is included in the distribution. But before the script can be run, a few preperations have to be done manually.

Just follow the steps as described below:

  1. Become `root'. You will need super user privileges.
  2. Create a user   `petidomo' using vipw(8), adduser(8) or whatever method your system uses. The user should not have a valid shell, nor a valid password because it is very unlikely that anybody ever needs to log in as `petidomo'. The home directory, though, is of some importance because the directory you specify here is the base directory for the whole Petidomo installation. An example entry in /etc/passwd looks like this:

         petidomo:*:300:300:Petidomo Mailing List Manager:
             /usr/local/petidomo:/usr/bin/true

    This means that all files belonging to Petidomo 2.1 live in the /usr/local/petidomo tree. The entry in the password file can be changed at any time. Hence it is very easy to move Petidomo\   to a different location or to de-install the whole package.

  3. Create a group `petidomo' and make the `petidomo'-user a member of it. You should also add all users of your system, that will administrate the mailing list server. Membership in the `petidomo' group will give these users full access to all configuration files, so be careful who to add.
  4. indexinstall.sh   As `root', execute the install script included in the distribution with `./install.sh' The script will ask you a couple of questions about your system and insert the appropriate values in the config files. Ones the script is finished, your Petidomo-Installation is complete and ready to run.

If choose not to let the install script create the required aliases for Petidomo, you will have to do that manually as described in section 4.6 of the manual.

4.1 Logfiles

Reading the log files Petidomo writes the single most important thing you have to do whenever something unexpected happens. Often enough the problem is very easy to to fix, if you know what the problem actually is. To support you in locating problems, Petidomo\ does extensive logging, espcially in case of an error.

For this, Petidomo uses the syslog(3) functionality, which is part of every major Unix derivate today. Petidomo uses the MAIL-facility to log via syslog, so it is recommended, that you check your /etc/syslog.conf file, whether you are writing the MAIL-facility into a file or not. Typically an entry in /etc/syslog.conf would look like this:

mail.*                           /var/log/maillog

If you are unfamiliar with the syslog-functionality, please read the following man pages: syslog.conf(5), syslogd(8) and syslog(3). They explain all the features briefly and you will greatly benefit from the knowlege -- not only for using Petidomo, but for maintaining your whole system.

4.2 Directory Structure

   figure101
Figure: The Petidomo directory structure.

Before we dive into the details configuration of Petidomo, it is necessary to describe the directory structure  of the package. Petidomo's base path, which we call  ~petidomo throughout the manual, is the home directory of the `petidomo' user. Relative to this directory, Petidomo accesses its master config file as etc/petidomo.conf. This is the so called  master config file, which sets globally required options such as the path to the mail transport agent (MTA), the fully qualified domain name of the machine, Petidomo is running on, etc...

Each list now has a config file of its own, where various settings are configured that are valid only for that list locally. All mailing lists live in the path lists/<listname>, with ``<listname>'' being the name of the mailing list. The config file for the mailing list ``testlist'' can congruously be found under the path lists/testlist/config, relative to the base directory of course.

4.3 The Config-Files

We will describe the master config file first now, followed by the options you can set on a per-list basis. You won't have to edit all these files yourself. The CGI manager, which is described in detail in section 4.4.2, is usually a more comfortable way of configuring Petidomo. You should read the following description nonetheless, because you need to know what an option means, even if you don't have to set it with a text editor.

4.3.1 Config File Syntax

All configuration files in the Petidomo-package  , have the following format:

keyword         parameter

The ``keyword''-part must start at the first column of the line and is followed by one or several blanks or tabs. The first non-blank character then is interpreted as the parameter for this keyword. The following line, for example:

Hostname        petidomo.is.great
will tell Petidomo that the name of the machine it is running on is called ``petidomo.is.great''. If the parameter contains any blanks, what is not very likely for a hostname, but may happen with other settings, you should enclose it in double quotes, like this:
AdminPassword   "open sesame"

Quoting the parameter is not strictly necessary, though, Petidomo's config file parser will get it right anyway. You only have to quote the parameter, if it contains blanks as first or last character, what is rather unlikely to happen. If you're using the CGI manager for the configuration, you won't have to worry about quoting at all.

Furthermore all empty lines are ignored. So are lines that start with a `#' sign. You can use this for writing comments for the reader into the config file.

4.3.2 The Master Config File

 

Petidomo expects its master config file to be found under ~petidomo/etc/petidomo.conf. The following keywords are recognized:

Hostname
``hostname.domainname''  

This entry specifies the fully qualified domain name of the machine, Petidomo is running on. A fully qualified domain name  is the hostname of the machine with the domain name appended with a dot. The following, for example:

HostName        listserver.foo.bar
would be a valid statement. Normally this option has been set by the install script correctly already.

The name you set here is not necessarily the name, Petidomo will use when delivering mailing list-postings to the subscribers, or when answering requests, because you can specify a different fully qualified domain name for every mailing list you host. This is known as  virtual hosting.

This option is required. Petidomo will abort with an error, if the master config file doesn't set it.

AdminPassword
``password''  

This tag sets the master password, which authenticiates the administrator of the Petidomo Mailing List Manager. Here is an example:

AdminPassword   "open sesame"
Normally this option has been set by the install script already.

Please chose this password carefully. Knowledge of the master password will enable you to access all mailing lists running on this system.

The password comparison both Petidomo and the CGI manager do, are always case insensitiv. That means, that the passwords ``Open SESAME'', ``open sesame'' and ``OPEN seSAme'' are all the same.

This option is required. Petidomo will abort with an error, if the master config file doesn't set it.

MTA
/path/to/sendmail   

The MTA tag tells Petidomo which mail transport agent should be used to deliver outgoing emails. Normally this option has been set by the install script already, so you don't need to worry about this anymore.

An example setting is:

MTA     "/usr/sbin/sendmail"
but Petidomo will run fine with other mail transport agents, too. So far, the system has been tested with the Allman sendmail, SMail and qmail without any problems.

This option is required. Petidomo will abort with an error, if the master config file doesn't set it.

MTA_Options
``string''  

This tag is a bit tricky and in ninety-nine out of hundred cases you should simply leave this option undefined as it is rarely required anyway.

This entry sets the options which will be handed over to the MTA when it is called. The following example

MTA_Options "-odq -v -f%s"
will yield a call ``<MTA> -odq -v -f<envelope>''. The `%s' is replaced with the envelope the mail should be sent under.

Adding options to the execution call of the mail transport agent can be useful to enable or disable certain features for mailing lists only, while leaving them on for all other mail. The `-odq' setting is a fine example. This parameter will tell the Allmann sendmail to queue all mail, instead of trying to deliver it immediately.

DetachImmediately
``yes'' or ``no''  

This option decides whether Petidomo will run in syncronous or asyncronous mode. When a part of the package is called, it expects an incoming email message on standard input, which has usually been received by the SMTP daemon before. So the daemon will pipe the mail into the program.

In syncronous mode, Petidomo will process the mail completely, before it terminates. Hence, the SMTP daemon has to wait until the whole mail is processed, before it can terminate itself. This may cause memory problems at high-load servers, where several dozen, or even hundreds of emails can arrive at the same time.

In asyncronous mode, Petidomo will read the mail and then detach itself. The advantage is that the SMTP daemon can terminate immediately and doesn't have to wait until Petidomo is finished processing the mail. The disadvantage is that in case of an error, the SMTP daemon will not receive the return code from Petidomo. For smaller servers, syncronous mode is recommended -- larger servers should use asyncronous mode.

To run in syncronous mode, set the parameter to ``no'':

DetachImmediately       no
to run in asyncronous mode, set the parameter to ``yes'':
DetachImmediately       yes

The default, if the option is unset, is to operate syncronously.

ShowStatistics
``yes'' or ``no''  

Petidomo will append a small signature to all request-mails it processes. This signature looks like this:

--
 /*
  * Listserver software: Petidomo 2.2-beta-2 (non-commercial)
  * Server hardware    : NetBSD-i386
  * Utilized cpu time  : 0.125863 seconds
  * Utilized memory    : 227 KByte
  */

In the commercial version of Petidomo, you can switch this behavior off by setting this option to ``no''.

4.3.3 The list config file

 

While the master config file sets options which are relevant for the Petidomo package as a whole, the list config file  sets options which are valid only locally for the mailing list. Each mailing list expects its local config file to be found at ~petidomo/lists/<listname>/config, with ``<listname>'' being the name of the mailing list.

For a description of the config file format, please refer to section 4.3.1 of the user manual. We will only describe the various settings here.

ListType
``open'', ``closed'' or ``moderated''  

There are three types of mailing lists Petidomo knows about: ``Open lists'' (or ``public lists''), ``closed lists'' and ``moderated lists''. The difference betweem the three types is, who is allowd to post an article on the mailing list.

If you want everybody to be able to post to the mailing list, whether he is subscribed or not, you should set this entry like this:

ListType        open

If you want to allow only postings from people, who are subscribed to the list, set the entry as follows instead:

ListType        closed

Or, if you want to allow only a small number of people to post, set the list to ``moderated'':

ListType        moderated

Please note that the ``ListType'' tag specifies only who is allowed to post, not who is allowed to subscribe to the list.

The list type you will usually use is ``open'', at least for a public mailing list where everybody is free to subscribe. The ``closed'' list has been added, because open mailing lists are frequently abused by a few people who use them to distribute commercial advertisement. Because these people (common known as  Spammers) do not actually subscribe to the list, but merely post their junk to it, their abuse will be rejected on a closed forum, while all the regular users can post without any problems.

The problem is, though, that the distinction between a subscriber and a non-subscriber is made by the address the e-mail is coming from. This causes problems when a person is subscribed to a list as ``example@address.net'', but tries to post from a different account than that one. Petidomo tries to recognize that as far as it can. It doesn't matter, for example, whether you are posting from ``address@host1.address.net'' or ``address@host2.address.net''. Petidomo will handle that. But if the article comes from ``example@private.account'', it will be rejected, even though the sender might be a valid subscriber.

It depends on the subscribers of the mailing list, whether this is a problem or not.

A moderated list, finally, is a list where all postings will be rejected unless they have a valid password included in the mail. This type of list is useful for a mailing list that is meant to distribute certain information to a group of people, but not for discussion. Everybody, who wants to have an article delivered to the subscribers, will send it to the mailing list. The list server will then forward the article to the list maintainer for approval.

The list maintainer can now either drop the mail, if it doesn't fit into the list's topic, or he can post it to the list, using the propper password. How this is done in detail is exlained in section 6 of the user manual.

This option is required. Petidomo will abort with an error, if the list config file doesn't set it.

AllowPublicSubscription
``yes'' or ``no''  

Set this entry to either ``yes'' or ``no'', depending on whether you want the mailing list to be open for everybody to subscribe or not.

If somebody tries to subscribe to a mailing list, which has been set to ``no'' here, the request will be forwarded to the list administrator for approval by Petidomo.

If this option is unset, the default to allow public subscription.

AllowAlienSubscription
``yes'' or ``no''  

Please excuse the name of this tag, but no matter how hard we thought, we were unable to come up with a better name for it. If you have any suggestions, please send them to <simons@petidomo.com>.

Anyway, this option specifies whether it is allowed to subscribe or to unsubscribe an address not equal to the one, the mail has been sent from. Set the option to ``yes'' to allow un-/subscribing a different address, or to ``no'' to disallow it.

AllowMembersCommand
``yes'' or ``no''  

Petidomo knows a command ``members'' or ``who'', which can be sent to the server and it will reply with the complete list of subscribed addresses for the mailing list. This may be useful for list administrators, but it can be abused easily by spammers, to collect addresses where to send their unsolicted commercial e-mail to.

Furthermore, with certain mailing lists it may be undesirable that one can see ``who else'' is subscribed to that list. That's why this option has been added. If you set it to ``no'', the ``members''-command will be diabled for this list. (This is also the default if the option is not specified in the config file.)

If you set it to ``yes'', the ``members''-comman will work.

ShowOnIndex
``yes'' or ``no''  

Petidomo allows people to request a list of mailing list running on the server, using the ``index'' command. While it is generally a good thing that everybody can look up what mailing lists exist, there are mailing lists that you don't want to make publically known, such as internal lists of your company, etc...

If you set this option to ``no'', the mailing list will not appear on the index listing. The default, if this option is unset, though, is ``yes'' -- to show the mailing list.

Hostname
``hostname.domainname''

This options tells Petidomo to use this hostname for the mailing list, instead of the one configured in ~petidomo/etc/petidomo.conf. This feature is useful to do virtual hosting.

Virtual hosting  is required when several mailing lists run on the same server, but they have to look like they would coming from different machines. Let's use an example: The internet service provider ``Inter.Net'' offers its customers to host mailing lists for them. A small software house of the name ``Petiware'' wants to provide a mailing list for all its customers, but they don't have a dedicated Internet line.

So they use the service provided by Inter.Net and let them host the mailing list on their machine. The mailing list server at Inter.Net has the fully qualified domain name ``mail.inter.net''. Petiware, though, wants the list to run under the name ``customers@petiware.com'' and not ``customers@inter.net'' -- what would a be misleading.

So all the mailing list guru from Inter.Net has to do is to set the entry

Hostname        petiware.com
in the config file of the ``customers'' mailing list (~petidomo/lists/customers/config). Petidomo will now use the hostname ``petiware.com'' in all mails that are posted to that list, instead of ``mail.inter.net''.

You can specify a different hostname for every mailing list, using this feature. That is ``virtual hosting''. Further details on virtual hosting can be found in section 8.3 of the user manual.

If this entry is unset, the name configured in the master config file will be used as hostname for this mailing list.

AdminPassword
``password''   

This tag sets the master password, which authenticiates the administrator of this mailing list. The administrator has special priviledes, such as deleting other users, overriding access control restrictions or un-/subscribing users to closed mailing lists. This is described briefly in section 6 of the user manual.

Please note that passwords are always case-insensitive. It is also worth noting that the master password is always valid as administrator password for the list, also.

Leave this entry blank, if you don't want to enable remote administration of the mailing list.

PostingPassword
``password''   

This tag sets the ``posting password''. The posting password allows to post an article to a moderated mailing list, but it does not allow any administration of the list itself. On lists that are of a different type than moderated, setting a posting password does usually not make any sense and you can leave this entry unset.

ReplyTo
``email@address.net'' or ``none''

This tag controls the `Reply-To:' field, which Petidomo adds to posted articles before it is delivered to the recipients. Using this option, you can force Petidomo to insert a `Reply-To:' which points to a certain address. On a moderated list, for example, you can set this as follows:

ReplyTo         moderator@address.net
to direct all replies to the posting to the moderator again, regardless of what address is noted in the `From:' line of the mail.

If you set ``none'', Petidomo will not add a `Reply-To:' header at all.

If this option is unset, Petidomo will to insert a `Reply-To:' header that directs replies back to the mailing list, so that subscribers can conveniently post simply by hitting the `reply' function in their mail reader.

PostingFilter
``bourne shell command''  

If you specify a posting filter, this program or script will be started by Petidomo before it sends a posting out to the subscribers. The programm will receive the article, as it has been prepared by Petidomo, on standard input and is expected to write the final version of the mail to standard output. The posting filter can be used to manipulate the headers for special purposes.

An example for a postin filter that wouldn't modify the mail at all is the following:

PostingFilter   /bin/cat

A detailed discussion of posting filters can be found in section 8.1 of the manual.

If the filter program exits with a returncode not equal to 0 (zero), Petidomo will not post the article and terminate.

Archive
/path/of/archive

If this option is set, Petidomo will archive all articles that have been posted on that mailing list. The parameter for this tag may either be the name and path of a file or of a directory.

The path may either be absolute (/var/archive/list) or relative (archive). For relative paths the current directory is the home directory of the mailing list this option is set for.

If the ``Archive''-tag is set to a file, Petidomo will append every posted article to that file. If it is a directory, each posting will be stored in that directory in a seperate file.

Creating a mailing list archive is discussed in greater deatil in the section 8.4 of the user manual.

If this option is unset, posted articles will not be archived at all.

4.4 The CGI Manager

Petidomo comes with a CGI program, that lets you do all the configuration out of your favourite WWW-Browser. This program is called  petidomoconf.cgi and it is installed by the install-script into the cgi-bin directory of your HTTP daemon -- unless you skipped that part, of course.

4.4.1 Installing the CGI Manager

If you did, you can still ``install'' the CGI manager simply by copying the petidomoconf.cgi binary from ~petidomo/bin/petidomoconf.cgi into the appropriate directory. The binary should be owned by `root:petidomo' and be installed with the ``setuid'' and ``setguid'' flag set. You can do this by executing the commands

$ chown root petidomoconf.cgi
$ chgrp petidomo petidomoconf.cgi
$ chmod 6555 petidomoconf.cgi

Superuser privileges are required only when creating or removing a mailing list with the CGI manager. In all other cases, the program will give up the super user privileges immediately, to reduce the chance of any abuse.

If you don't want to grant `root'-access to the CGI manager, you should install it with the `petidomo'-user as owner and still set the `setuid' and `setguid' flags. If you're creating a mailing list in such a setup, you will have to add the appropriate aliases manually, though. How this is done is explained in section 4.6 of the manual.

The only way around this is to make the /etc/aliases file writable for the user or group `petidomo'. Then the CGI manager will be able to access the file without `root' privileges.

It is recommended, though, to grant `root'-privileges to the CGI manager as this makes the administration of your mailing list server a great deal easier.

It should be noted that the CGI manager will run the ``newaliases'' command after you have created a new mailing lists, or removed an existing list with it, because these operations change the alias file and sendmail won't notive that until ``newaliases'' is run. For this to succeed, you must have this program into the execution path of your shell, because the CGI manager doesn't know about the full path where ``newaliases'' is. On all systems we used to test this, the CGI manager ran ``newaliases'' successfully, so you probably shouldn't worry about this.

But if you notice that the changes made with the CGI manager don't take effect immediately, you should either fix the $PATH variable on your system, or copy the ``newaliases'' into a directory, where the CGI manager can find it, for example /usr/bin.

4.4.2 Using the CGI manager

  

   figure190
Figure 4.2: The CGI manager login screen.

The CGI manager is rather easy to use. Once it is propperly installed in the cgi-bin directory of your WWW server, you can access it under the URL: ``http://localhost/cgi-bin/petidomoconf.cgi''. Please note that the CGI manager must be installed on the same machine as the mailing list server. It has to modify the config files on the harddisk and obviously can't succeed when it is running on a different machine, say, a dedicated web server.

If you access the CGI manager from your WWW browser, you'll see the login screen, as shown in figure 4.2. The CGI manager prompts you for the password to authenticate yourself. Please enter the password, you specified to the install-script now, choose the ``Configure Petidomo 2.1'' button and click on ``Submit Query''.

Your WWW browser will now present you a page with several text fields, where you can enter the parameters you'd like to set. If you change and submit the changes, they will be written back to the master config file in ~petidomo/etc/petidomo.conf. The meaning of the parameters here is the same as described in section 4.3.2.

If you choose ``Configure an existing mailing list'', the CGI manager will present you a list of lists it has found. Select the list you''d like to configure and hit ``Submit Query'' to enter the actual configuration page.

It should be noted that you will only see the mailing lists, that you password is valid for. If you entered the master password, which is configured in the master config file, you will have access to all mailing lists running on the machine. It is possible, though, to set an admin password (see section 4.3.3) for a mailing list, too. If you entered this password, instead of the master password, you'd see only this particular list at the moment. In case several mailing lists have the same admin password, you'll see all of them.

This behavior is very useful if you are hosting mailing lists that are administrated by other people. Just tell the administrator of the hosted mailing lists ``their'' password and the URL of the CGI manager, and thez will be able to configure ``their'' mailing lists remotely  without gaining access to the other mailing lists running on the server.

Anyway, select the ``testlist'' entry now and enter the configuration. As before, a page will be shown where you can customize all the options that have been described in the section 4.3.3 of the manual. The changes you make will then be written back into the list's config file. In our example, this would be ~petidomo/lists/testlist/config.

The remaining two choices on the main page of the CGI manager are ``Create a new mailing list'' and ``Remove an existing mailing list''. These two should be pretty self-explanatory. If you chose to remove a mailing list, you will be prompted for the list you'd like to remove and by submitting the selection, it will be deleted from the server.

Creating a new mailing list works exactly like configuring a new mailing list except for the fact you'll notice four additional text fields at the top of the page, compared to the configuration page. The first text field is for entering the name of the mailing list.   You must choose a list name, that doesn't contain any special characters, like the slash ('/'), the colon (':') or the point ('.'), as these have special meanings to either the file system or to the mail transport agent. The best is to stick with normal characters and numbers, plus the minus (`-'), for example: ``basketball-fans'' or ``petidomo-support''.

In the second text field, you should enter a short description  of the purpose and topic of the mailing list. This text is displayed when a user requests the index of available mailing lists from the server and it can be requested by sending the command ``HELP listname'' to the list server. For our example mailing list ``basketball-fans'', a good description would probably be:

This mailing list is a public forum meant for discussion of the topic of ``basketball'' or all related topics. This is not a fan list for a particular basketball team or player, but a forum for all fans of the sport basketball.

A similar function has the third text field. Here you can enter an ``introduction text '', which is sent to all new subscribers of the mailing list automatically. This text should explain the topic and purpose of the mailing list plus the rules of the list and other important things, a new subscriber needs to know. Again an example for our ``basketball-fan'' mailing list:

Welcome to the ``basketball-fans'' mailing list!

This forum is meant for discussion of the topic of ``basketball'' or related topics. This is not a fan list for a particular basketball team or player, we don't want any bashing of players or teams here.

Also not welcome are postings which contain large binary data such as pictures, logos or sound files. Neither should you post articles that have been published on the WWW or in the news already, Please post just the URL where anybody interested in them can obtain the files himself.

Other than that, you can talk about pretty much anything you like. Have fun! :-)

The last additional text field on this page finally is used to enter a signature  for the mailing list. This signature is appended to every article that is posted to the mailing list. Naturally, the signature should be short and contain only important information. You should actually consider whether you want to add a signature at all. Nonetheless, here is an example of a good signature:

--
 Mailinglist Archive: http://www.nba.com/bbfans/ml-archive/

It is recommended, to enter one or two blanks line before you start the actual text, because it looks better if there's a little space between the end of the posted article and the appended signature.

The rest of the configuration options on the page are the same options again as on the ``Configure an existing mailing list'' page.

4.5 The Binaries

The Petidomo package consists of mainly three binaries: petidomoconf.cgi, hermes and listserv. All three files are located in the ~petidomo/bin directory. In fact, ``hermes'' and ``listserv'' are the same binary, but they do different things when called under the appropriate program name, like many other commands of the Unix operating system do. They are only links of the petidomo , which has no purpose at all, but we thought it would be weird to deliver a package called Petidomo without actually having a binary of that name in there. Since these three are all links to the same files, it doesn't consume any diskspace anyway.

4.5.1 listserv

  

The ``listserv'' program is the tool that handles incoming requests like subscribing an address to a list, unsubscribing it again or generating an index of available mailing lists for the server. ``listserv'' will usually not be started from a shell, but from the sendmail daemon. Further details on that can be found in section 4.6 of the user manual.

4.5.2 hermes

  

``hermes'' is the program that processes and delivers an incoming e-mail. It does not understand any commands but simply takes an e-mail from the standard input file stream, re-writes the headers a bit and then calls the mail transport agent with the result to be delivered to the list of subscribers.

4.6 Aliases

 

The binaries of the Petidomo package are usually not called manually from the shell, but by the mail transport agent. This works as follows: You create an e-mail account, which serves the purpose of accepting the incoming e-mail and piping it into the appropriate binary.

This is archieved with the ``alias''-function of your mail transport agent. Most MTAs, like sendmail, have a file where a list of special account names is given together with the instructions what to do with any mail received for that account. This file is usually located in /etc/aliases .

One thing, aliases can do is to pipe the mail into a program for processing. This is the mechanism Petidomo uses. Petidomo requires you to add the following aliases to your system:

#
# Mailing List Stuff
#
petidomo-manager: root
petidomo: "|/usr/local/petidomo/bin/listserv"

The lines starting with the `#' character are only comments and are ignored by the mail transport agent. The fourth line, though, is the first command. It tells the MTA to accept mail for an user of the name ``petidomo-manager'' and to re-direct the e-mail to an user of the name ``root'' -- the system administrator.

Petidomo will send notifications of an error and administrative things like that to the address ``petidomo-manager''. By setting this alias to a certain user name, you can control who will receive those mails.

The next line now tells the MTA to pipe any incoming mail for the user ``petidomo'' into the ``listserv'' program, instead of delivering it into a mailbox. ``listserv'' will then parse the mail for commands and react accordingly. Hence, the address people can send their subscription requests to is ``petidomo@your.host.name''.

These aliases have been created by the install script, unless you told it not to, and you don't need to worry about them.

Furthermore, each mailing list on your server requires three aliases, as shown in the example below, which is written for the ``testlist'' mailing list that comes with the distribution:

testlist: "|/usr/local/petidomo/bin/hermes testlist"
testlist-request: "|/usr/local/petidomo/bin/listserv testlist"
testlist-owner: petidomo-manager

The first alias, ``testlist'' is the address to which people can send their mail in order to post to the mailing list. Any incoming mail for that account will be piped into the ``hermes'' binary, which will process the mail and then re-send it to all subscribers of the mailing list. In order to let ``hermes'' know, for which mailing list the posting was meant, the parameter ``testlist'' has to be specified on the command line. If the name of the mailing list was ``foobar'', the line would look like this:

foobar: "|/usr/local/petidomo/bin/hermes foobar"

The second alias is a special request address, to which users can send their commands. The difference between this address and the ``petidomo'' alias described above is that ``listserv'' is being given a default listname on the command line. The difference is this: If ``listserv'' receives a mail, which has the command ``subscribe'' in it, without any further parameters, it will reject the command with an error, because it doesn't know to which list the sender wants to be added.

If the command ``subscribe'' is sent to the ``testlist-request'' address, though, it will assume that the user wants to be subscribed to the ``testlist'' mailing list, as this is the default list for this address.

The name of this alias should always be the name of the mailing list with the string ``-request'' appended. Theoretically you could choose a different name, but this unwritten standard is wide accepted throghout the Internet for several years now.

The last alias is the name of the mailing list with the string ``-owner'' appended. This alias points to the person who is responsible for managing the ``testlist'' mailing list. Petidomo\ will send all e-mail concerning the administration of the mailing list to the address ``listname-owner''. Usually this will ultimately be the same person as the ``petidomo-manager'', but you are free to direct mail for this account to somebody else, or to several persons.

These aliases are created automatically, when you add a mailing list with the CGI manager included in the distribution, but knowing how they work is very useful if you want to customize the settings for your needs manually. It is recommended to read the aliases(5) and the newaliases(1) man page of your system for further details.

5 Using Petidomo as user

    

In this chapter, we will describe the commands, that are understood by the ``listserv'' program. ``listserv'' is the interface for the users of the mailing lists, where they can send their requests to in order to be subscribed to a mailing list, be unsubscribed again and similar things. The text here is mostly identical with the default help text   that is sent to the user whenever he or she issues a command that is syntactically incorrect. This text is stored in the file ~petidomo/etc/help  and can be customized to fit the requirements of your site.

User commands always have to be sent to the request address  of the mailing list -- not to the mailing list itself. Petidomo\ will try to recognize commands that are sent to the mailing list and redirect them to the ``listserv'' program, but naturally this will not work in all cases. The address, where requests should be directed to, is always the address of the mailing list with the string ``-request'' appended to the username. If the mailing list is called ``politics@foo.bar'', the appropriate request address is ``politics-requst@foo.bar''.

Alternatively, commands can always be sent to the address ``petidomo@your.address'', but the ``-request''-address is preferable, for the fact that the ``listserv'' will have a default listname for this address and thus understand a simpler command syntax.

5.1 SUBSCRIBE

  

The ``subscribe'' command will add the address of the user to a mailing list. When using the ``-request''-address, only the word ``subscribe'' is required for the request to suceed. If the command is sent to the ``petidomo'' address, the user will have to specify an additional parameter: The name of the mailing list he or she wants to be added to, like in the following example:

subscribe politics

If the user wants to add an address that is not equal to the one he or she is sending the e-mail from, the e-mail address will have to be specified, too:

subscribe politics joe@foo.bar

The order in which the e-mail address and the mailing list name are provided does not matter. Please note that the administrator can configure Petidomo to disallow un-/subscring other addresses than the one, the request is sent from, using the ``AllowAlienSubscription'' option in the list's config file.

The command ``add'' is synonymous to ``subscribe''.

5.2 UNSUBSCRIBE

   

The syntax and usage of the ``unsubscribe`` command are the same as the ``subscribe'' command. The difference is, though, the the user's address is removed from the mailing list rather than added to it.

``delete'' and ``remove'' can be used synonymously to ``unsubscribe''.

5.3 INDEX

   

The ``index'' command does not need any parameters. Sending it to the server will return a list of available mailing lists on this server. This is useful in case you want to subscribe to a list but can't remember the exact name anymore.

The commands ``lists'' and ``longindex'' are synonyms to ``index''.

5.4 HELP

 

If the server receives the command ``help'', it will send the file ~petidomo/etc/help back. If ``help'' has a parameter, Petidomo will check whether this is a valid name of an existing mailing list, and if it is, it will return the description file for this mailing list, rather than the help-file.

5.5 MEMBERS

  

The ``members'' command will return the addresses of all subscribers of the mailing list, if the administrator chose to allow this command. When ``members' is sent to the ``-request''-address, the default list will be used by Petidomo. Otherwise, the name of the mailing list which's subscribers should be listed, has to be specified as an option like in the following example:

members politics

The command ``who'' can be used synonymously to ``members''.

6 Using Petidomo as Administrator

 

On the ``other side'' of Petidomo, from the user's perspective, is the administrator of the mailing list -- also called the  mailing list owner ). Each mailing list has an alias ``listname-owner'' (see section 4.6), where the mail address of the person who is responsible for this mailing list should be specified. Per default, this is the user who is known as ``petidomo-manager''. But you are free to direct mail for this accoun to any other person -- or several persons.

The list owner will receive administrative e-mail from Petidomo in the following cases:

These mails are merely for information purposes and do not necessarily require an action from the admin. There are cases, where the list owner will receive mails from Petidomo, though, that require some kind of reaction.

6.1 Bounces

While maintaining mailing list with a larger number of subscribers, it happens regularly that subscribed addresses become invalid or are temporarily not reachable. In this case postings will  bounce. You will then receive a mail from a mail server telling you, that the delivery of the mail failed.

Often, addresses become unreachable due to a misconfiguration of a machine, so it is not always necessary to remove that address from the list immediately, but when an addresses bounces for several days in a row, it is a good idea to delete that address from the mailing list. You should do that by sending an ``unsubscribe'' command for that address to the ``-request''-address of the mailing list.

If you have configured Petidomo to disallow the unsubscription of addresses not equal to the address the mail is sent from, you will have to specify your admin password in the mail, to override the barrier. How this is done is described in section 6.3 later.

6.2 Closed and moderated lists

If you have configured a mailing list to reject postings under certain circumstances, such as a closed or moderated mailing list, these rejected articles will be forwarded to you for approval. When you receive such a rejected article , you can either silently discard it, contact the author or post it to the mailing list with your approval.

You can approve an article with the master password for Petidomo, the admin password of the mailing list in question or the posting password (see section 4.3.3 of that list. This is useful because you can give other people the posting password to allow them to approve articles, without them being able to access the configuration of that list through the CGI manager.

6.3 Approving requests

  

To approve an article, you have several ways of specifying the appropriate password. They are all the same for Petidomo and it is only a matter of taste, which scheme you use.

When sending a command to the ``listserv'' program, though the ``-request'' or ``petidomo''-address, it is easy. Just preface your commands with a ``password''  command, like in the following example:

To: testlist-request@foo.bar
Subject:

password open sesame
subscribe some@one.else
subscribe someone@even.elser

One ``password'' command sets your password for all the commands to follow. If you want to use one mail to send requests for several mailing lists with different passwords, just give a ``password'' command again:

To: petidomo@foo.bar
Subject:

password open sesame
subscribe user@inter.net testlist1
password let me in
subscribe user@inter.net testlist2

Instead of ``password'', you can also use the commands ``passwd'', or ``approve'', they are all synonymous.

6.4 Approving postings

  

If you want to approve a posting for a mailing list, just send the article to the mailing list and specify your password either in the header or in the body of the mail.

If you choose to approve the mail in the body, add line with the command ``approve'' to the mail as first line of the body. Petidomo\ will strip that line before actually posting the article then. You can also use the synonyms ``approved'', ``password'' or ``passwd'' instead. Here is an example:

From: simons@petidomo.com (Peter Simons)
Subject: Cats are the most beautiful animals in the world.

approve let me post
It's not that I wouldn't like animals like dogs, birds
or fishes, but for me, a cat is *the* animal to have.
[...]

The line ``approve let me post'' will be stripped by Petidomo and then the article will be sent out.

If you want to specify the password in the headers, just add an header of the name ``Approved'' or ``Approve'' to the headers of the mail. (Unfortunately, many mail readers do not allow you to modify the headers of outgoing mail. That is why the body-approval has been added.) Here is the same example as above now using the headers:

From: simons@petidomo.com (Peter Simons)
Subject: Cats are the most beautiful animals in the world.
Approve: let me post

It's not that I wouldn't like animals like dogs, birds
or fishes, but for me, a cat is *the* animal to have.
[...]

Please note that you have to add a colon to the keyword to make a valid RFC mail-header.

7 The Access Control Language

Unfortunately, we live in a world where some people are trying to abuse services like mailing lists for their entertainment or for commercial purposes. It is also not uncommon that among thousands of mailing list subscribers, there is one particular moron who simply can't behave. That is why access control is a useful feature, even though it contradicts the idea of a mailing list: To be a media for communication.

Writing and understanding ACL files is, to be honest, not very easy and the novice mailing list administrator should better be careful when using them, because a wrong access control rule might cause more trouble than it is worth, but the experienced administrator will certainly appreciate their power. Understanding how ACL files work will also require you to know a bit about the syntax of an RFC format e-mail. A good place to start is to take a look at RFC822 and its sons.

In Petidomo, two places exist to control who is allowed to do what: The global acl file ~petidomo/etc/acl  and the acl file that is local to the mailing list: ~petidomo/lists/listname/acl. While the latter is valid only for the list in which's home directory it is stored, the globl acl file will be parsed for all your mailing lists. ACL files are only relevant for mailing list postings, the ``listserv'' program does not use them.

The syntax of an ACL file  is similar to the C programming language, as you can see in the following example:

if (envelope matches "mailer-daemon@") then
        forward "petidomo-manager";

This is a simple version of the default ACL file which comes with the Petidomo distribution and is installed in ~petidomo/etc/acl. It tells hermes to forward all postings to a mailing list, where the envelope of the mail matches the regular expression ``mailer-daemon@''. This rule is included in the default distribution to make sure that bounces of articles will not be posted to the list again, thus causing an infinite mail loop. The syntax of an ACL statement is shown in figure 7.1.

   figure295
Figure 7.1: The Access Control Language syntax.

Admittedly, the figure is rather impossible to understand without further explaination, don't worry if things are still a bit unclear after looking at it.

Every ACL statement looks like this: ``IF condition THEN action ;''. The condition may or may not be enclosed in brackets. Several conditions can be combined with the keywords ``OR'' and ``AND''. Furthermore every condition can prefaced with a ``NOT'', which will reverse the outcome of the condition.

Let's explain this all at a concrete example: You want to reject all postings which come from the addresses ``moron@moron.net'' and ``spam@spam.net'', because these people have constantly been abusing your mailing list service. This can be done with the following two statements:

IF from == "moron@moron.net" THEN reject;
IF from == "spam@spam.net" THEN reject;

Using the ``OR'' statement you can combine this into one statement:

IF from == "moron@moron.net" OR
   from == "spam@spam.net" THEN
      reject;

And now we include brackets for readability:

IF (from == "moron@moron.net") OR
   (from == "spam@spam.net") THEN
      reject;

The keyword ``from'' stands for the address, noted in the ``From:'' header line of the mail and, the ``== "address"'' means that the condition if this address is equal to the one written in quotes thereafter. (You can also use a single `=' character, if you prefer that over two equal-characters.) This is a verbatim match. If we'd use the ``match'' or ``matches'' keyword instead of the ``=='', the parameter would be interpreted as an extended regular expression and the condition would be true if the addresses matched this pattern. (Regular expressions are described in the re_format(7) man page, or in the manpages of sed(1), grep(1) or egrep(1).)

Other keywords than ``from'' for the first part of the conditional are ``subject'' (the contents of the ``Subject:'' header), ``envelope'' (the envelope of the mail), header and body. The latter two represent the whole header or body of the mail and should be used only for regular expression matches and not for verbatim matches.

A short comment on the difference between ``redirect'' and ``forward'': The ``redirect'' action will send the mail to the specified address without changing anythin in the mail. All the headers are left untouched and thus the mail will look as if it has been sent by the person to that address right away. This is useful for redirecting mails to daemons or programs, but it will usually confuse a human recipient

The ``forward'' action, though, will send a mail to the specified address with a new set of headers, which identify the Petidomo Mailing List Manager as originator and then it will quote the mail that has been forwarded in the mail body.

Valid actions are ``pass'' (post the mail immediately), ``drop'' (discard the mail without further notice), ``reject'' (send a mail to the poster, telling him his posting was rejected), ``rejectwith'' (sending mail to the poster, too, but with the contents of a specified file), ``redirect'' (redirect the mail to a specified address), ``forward'' (like ``redirect'' but preface the mail with a note telling why the mail was re-sent) or ``filter'' (pipe the mail into the specified filter script and post the mail as the filter writes it to the standard output).

Here are a few more examples in the hope that they make this all easier to understand: Let's assume you would like to catch all postings to your mailing lists, that contain the words ``MAKE MONEY FAST'' in the subject. Then one way of doing this is the following statement:

IF (subejct matches "make money fast") THEN
      rejectwith "/usr/local/petidomo/etc/make-money-fast.txt";

The file /usr/local/petidomo/etc/make-money-fast.txt could, for example, contain the following text:

Dear poster,

your mail has been rejected. Please note that chain letters like the ``make money fast'' text you tried to post are illegal throughout the world and your are likely to get in trouble if you continue to spread them.

If someone tried to post the chain letter to your mailing lists now, he would receive a mail like that:

Date: Sat, 28 Jun 1997 19:59:18 +0200 (MET DST)
From: testlist-owner@peti.cys.de (Petidomo Mailing List Server)
To: simons@cys.de
Cc: testlist-owner@peti.cys.de
Subject: Your posting to list "testlist" was rejected
Precedence: junk
Sender: testlist-owner@peti.cys.de

Dear poster,

your mail has been rejected. Please note that chain
letters like the ``make money fast'' text you tried
to post are illegal throughout the world and your are
likely to get in trouble if you continue to spread them.

>From simons  Sat Jun 28 19:59:17 1997
Received: from [[UNIX: localhost]]
        by peti.cys.de (8.8.5/8.8.4) id TAA16959
Date: Sat, 28 Jun 1997 19:59:17 +0200 (MET DST)
Message-Id: <199706281759.TAA16959@peti.cys.de>
From: Peter Simons <simons@cys.de>
To: testlist
Subject: MAKE MONEY FAST
Mime-Version: 1.0 (generated by tm-edit 7.92)
Content-Type: text/plain; charset=US-ASCII

Hi, my name is David Rodes...

A few more words about how the ACL files are parsed:

One last example and then we'll come to the filters. The following statement rejectes a mail based on a match in the headers. This is very useful for rejecting mail from known spam domains. You usually can't rely on the spammer to use a valid ``From:'' header and hence the ``from''-match is useless to catch them. But the following statement will usually get them nonetheless:

if (header matches "^Received:.*from spam.domain") then
     forward "petidomo-manager";

If you thought, the Access Control Language is powerful so far, take a look at the things you can do using filters. Rather than the syntax described below, you can use the following statement:

if ("/usr/local/petidomo/bin/CheckPosting") then reject;

This is a special form of the usual ACL statements and it means the following: The mail in question is piped into the ``CheckPostin'' script. The script or program can perform various tests and when it exists, the action part is executed depending on the return code the script exited with. A return code of zero (0) means ``true'' and the action will be executed. A return code of one (1) ``false'' and the action will not be executed.

Any other return code will cause Petidomo to abort with an error and to save the mail. By using this mechanism, you can program even the most sophisticated tests and hook them into the access control mechanism.

Another feature that hasn't been described yet is the action ``filter''. The filter-action is pretty much the same as the posting filter, but it allows you to re-write the posting depending on who posted it or other criteria. Please note that this filter is executed additionally to a regular posting filter you might have configured.

A nice example for what this feature can be used is the following:

if (address == "simons@petidomo.com") then
       filter "/usr/local/petidomo/bin/simons.filter";

The script simons.filter would then look like this:

#! /bin/sh

cat
echo
echo "-- "
echo " Hold your breath -- this is *the* Peter Simons!"

We resisted the temptation of adding this ACL statement into the default configuration of Petidomo.

8 Miscellaneous Topics

8.1 Using posting filters

 

The posting filter functionality of Petidomo 2.1 is a very useful mechanism for you, if you run mailing lists where you want to guarantee certain formal criteria, because you can hook a script or program of your into the posting process and use it to re-format or re-write the article that is going to be posted.

  We have included one script into the distribution, ~petidomo/bin/InsertNameInSubject.sh, which adds a string into the subject line of every posting. The script is pretty short and used sed(1) to perform its function.

To use it, just add the line

PostingFilter     ~petidomo/bin/InsertNameInSubject.sh listname
with ``listname'' being the name of the mailing list.

If the mailing list name was ``testlist'', for example, then this posting filter would re-write the subject line

Subject: Hi everbody
to
Subject: [testlist] Hi everbody

It is recommended to take a look at the script itself to understand how this works. You will need a bit of knowledge of the Unix scripting language and tools like sed(1) to program more complex posting filter, we're afraid.

As the last point it should be made clear, that the string you specify as a filter is interpreted by the bourne shell for execution. It is thus absolutely possible, to use a posting filter like that

PostingFilter "/bin/cat | /bin/cat ; echo ; echo testing"
even though one might argue whether this particular example is a useful thing. Anyway... you know what we wanted to demonstrate.

8.2 PGP-encrypted mailing lists

Another very useful feature of the posting filter and the access control languange is the ability to maintain  encrypted mailing lists. The idea is very simple: You create a PGP key pair for your mailing list and spread the public key among the subscribers of your mailing list. In turn you collect their public keys and store them on the mailing list server.

Whenever a subscriber wants to post an article to the mailing list, he will encrypt it with the public key of the list server before transferring it through the Internet. Petidomo will then receive the mail, decrypt and process it and encrypt it again, with the public keys of the subscribers. Once encrypted again, the mail is distributed to the readers.

Please note that at no time the mail was sent through the Internet in clear text. Hence this mode is well-suited for maintaining internal discussion lists for, say, software development among a few people who know each other but live spread throughout the world. Included in the distribution are two scripts, pgp-encrypt.sh and pgp-decrypt.sh, which realize this. The setup needs a bit of work, but once you understand the principle, it is rather easy. Just follow the steps described below.

  1. Get the PGP software package from `http://www.pgpi.com/', you will need the PGP 2.6.2 version or later -- 5.x won't work, as far as I know, maybe someone wants to adapt the PGP-mechanism to PGP 5.x, any volunteers are welcome, and install it.
  2. Log in as user ``petidomo''.
  3. Create a directory ~petidomo/.pgp and set the $PGPPATH variable to it.
  4. Create a PGP key pair by calling `pgp -kg''. As user-id enter the address of the mailing list itself, for example: ``The secret mailing list <secretlist@petidomo.com>''.
  5. Create a config.txt file for PGP in ~petidomo/.pgp and insert the appropriate user id there.
  6. Distribute the newly created PGP key of the mailing list among the subscribers.
  7. Add the PGP keys of the subscribers to Petidomo's keyring.
  8. Edit the following definitions in ~petidomo/bin/pgp-encrypt.sh:

    #
    # Please customize these things for your system.
    #
    PGP=/usr/local/bin/pgp
    PASSWORD="DecryptMe"
    PGPPATH=$PDHOME/.pgp

    You will need to change the location of the PGP binary and insert the password you chose for the secret key. For security reasons, the script itself should be owned by ``petidomo'' as user- and group id, and it should have the permission ``110'', so that only Petidomo can execute it.

  9. Edit the equivalent definitions in ~petidomo/bin/pgp-encrypt.sh.
  10. Now create the mailing list in question. In our example that would be ``secretlist''. Naturally the mailing list should not be open for public subscription.
  11. Edit the ACL file of the ``secretlist'' to contain the following line:

    if (body matches "^-----BEGIN PGP MESSAGE-----$") then
            filter "~petidomo/bin/pgp-decrypt.sh";
  12. Edit the config file to have the following posting filter:

    PostingFilter   "~petidomo/bin/pgp-encrypt.sh secretlist"

    Please note that you must provide the name of the mailing list on the command line as parameter to pgp-encrypt.sh, so that it know which list file it should take the subscriber addresses from.

  13. Do a test posting and that's it.

There are a few things you should take care of: First of all, you must make sure that you have the PGP public keys of all subscribers in the keyring belonging to the ``petidomo'' user, or some of them won't be able to decipher the mail posted via the list. You must also take care that the addresses these people are subscribed under, are actually listed in their public key, or PGP won't be able to recognize who is who, when being called by pgp-encrypt.sh.

Finally, make sure that you do this only with the correct versions of the software. Petidomo needs to be version 2.1 or later, earlier versions won't work. The PGP binary needs to understand the -@ operator on the command line, which has been added in PGP 2.6i at some time. gif

One last hint: If PGP-encryption or decryption doesn't work, it will usually help to remove the $LOGFILE parameter from the trap command in the scripts:

trap 'rm -f $TMPFILE $HEADER $BODY $NEWBODY $LOGFILE; exit'...
                                            ^^^^^^^^

As a result, the script won't delete the output PGP issued when called after exiting. Thus you will find the file still lying in /tmp and can easily investigate what's wrong.

8.3 Virtual hosting and sendmail

 

A very useful things is Petidomo's virtual hosting feature. Unfortunately, there are a few traps into which you might run when you are trying to use it together with the Allmann sendmail. But we'll start at the beginning.

If you host mailing lists for domains other than your own, you can tell Petidomo to use this name instead of the local one for certain mailing lists in the list config file by setting the appropriate ``HostName''. Now all mail posted to this list, or sent to the ``-request'' address of the list, will appear to be coming from the domain name you configured, rather than your own.

When you are using sendmail v8, you will have to write these names to the $w$ class in your sendmail.cf file, or the corresponfing M4 config. This is done by adding the line

Cwdomain.name1 domain.name2 ...
to the file.

This will tell sendmail that these names are to be accepted and delivered locally rather than to the MX of these entries.

Doing this might deliver a surprise, though, if you are using sendmail's masquerading abilities to hide the various hostname of your domain. Per default, sendmail masquerades not only the domain names you told him with the MASQUERADE_DOMAIN() command, it automatically masquerades all domain names of the $w$ class, too.

The result is that Petidomo's fine virtual hosting is gone immediately, because sendmail will re-write the name to your own domain name. The fix for this is rather easy: Add the command ``FEATURE(limited_masquerade)'' to your M4 file and sendmail won't touch the names that are stated only in the $w$ class.

8.4 Mailing list archives

 

If your are hosting a public mailing list, you might want to offer a mailing list archive, that is accessible through the WWW and has all the postings available for immediate access. We were in the midst of developing a tool that does this for you when we came accross a brilliant tool named ``MHonArc''. We installed it, tested it, and deleted all attempts of writing something like that ourselves immediately.

We strongly recommend looking at MHonArc, if you want to offer a WWW archive of your mailing lists. You can find more information about MHonArc at the following location: `http://www.oac.uci.edu/indiv/ehood/mhonarc.html'

The installation of the tool itself is very easy. Once you have MHonArc running, just enable the archiving feature in Petidomo and feed the archives into MHonArc. That's it.

8.5 Verifying the address lists

Petidomo tries its best to make sure that only syntactically correct addresses are subscribed to mailing lists, and if you stick to the listserv interface, there's very little chance, an incorrect address will make it into the list file.

Sometimes, it is necessary to edit these files manually, though, or Petidomo's address validation algorithm fails. Once you have an incorrect address in your list file, sendmail will abort with an error, without trying to deliver the mail at all.

To clarify, this does not happen when an address is not reachable, this happens only when you subscribe something like hey@this@is@wrong..... Once you suspect that your address list has been corrupted, there's an easy way to find out, which addresses are wrong. Simply use sendmail's address verification mode like this:

 $ xargs <list sendmail -bv | sed -e '/deliverable/d'
 > @bogus.address.here... user address required

This call will find all incorrect address and notify you. The 'sed' call will filter out all correct addresses for your convenience.

9 If something doesn't work...

Even though it is highly unlikely that Petidomo will not work as you expect it to (`Highly unlikely' is actually an understatement. It is so amazingly breath-takingly mind-boggingly stunningly unlikely, even less probable than the absolute impossible and totally unthinkable, so flabbergastingly unlikely that we actually wonder why we have that section at all...), you have several means of getting help:

  1. Before anything else, please take a look at the logfile. Petidomo hardly ever does anything without making an entry in the logfile. Usually, your problem is caused by a wrong file permission or a misspelled keyword. These things can easily be found and fixed if you read the logfile.
  2. Take a look at the logfile again.
  3. If the logfile doesn't help, you can post a description of your problem to the ``petidomo-users'' mailing lists, where the CyberSolutions staff and many other users might be able to help you. To subscribe to the mailing list, send an ``subscribe'' request to the address: ``petidomo-users-request@petidomo.com''.
  4. You can contact Peter Simons <simons@petidomo.com> directly via e-mail.

9.1 Reporting problems

  

If something turns out to be a bug... uh, undocumented feature in Petidomo, please report your finding to CyberSolutions GmbH using the send-pr   script included in the distribution. This script will file your problem report in a way our automated problem-report system can handle. This is the best way to file your report.

If the script doesn't work correctly (what is highly unlikely, by the way), you should (a) file an appropriate problem report using the send-pr script included in the distribution and (b) send your problem report as an ordinary e-mail to the address ``bugs@petidomo.com ''.

You will receive a recipt for your problem report within a few moments, that your problem report has been received and been added to our database. The Petidomo customer service will do its best to process and solve any incoming problem report, but please understand if we can't reply all reports immediately.

If you need guaranteed customer support, please obtain the commercial version of Petidomo, which has several additional features and comes with a manual that doesn't have as much non-sense in it like this one.

9.2 The mail-rescue mechanism

Petidomo 2.1 has not lost a single e-mail due to a bug or a faulty configuration yet and we are optimistic that it will stay that way. The reason for this belief is the mail-rescue mechanism, which works as follows: Whenever either ``listserv'' or ``hermes'' are started, the program will read the complete mail it is receiving and immediately stores it under an unique filename in the directory ~petidomo/crash.

When this file has been created, the program will start to actually process the mail. If a situation arises that Petidomo can't handle, like a syntax error in the ACL files, a missing keyword in the master config file, or a faulty file permission of a file Petidomo needs to read, Petidomo will notify the ``petidomo-manager'' via e-mail and terminate without deleting the mail in the rescue-directory. Even in case of a core dump, the mail is still there. Only if Petidomo has succeeded in processing the request or posting completely, the rescue file will be deleted.

So in case your installation can't process a request or posting for whatever reasons, all you have to do is to fix the problem and then to feed the mail from the rescue-directory into the program again to process it.

Please note that Petidomo might not be able to send the notification mail out (for example if the reason that it aborted in the first place was that it couldn't start the mail transport agent), so you should check the ~petidomo/crash directory from time to time, probably in your daily- or weekly script, which is run by cron.

It might also be a good idea to take a look at the logfiles occasionally, even when Petidomo is running fine, just to make sure it stays that way.

A Humor

 

Here are some things to cheer you up when administrating mailing lists annoys the hell out of you.

A.1 Changing lightbulbs and mailinglists

 

The following article was posted to various newsgroups and appeared on several WWW servers. Unfortunately the original author is unknown. We publish it here without explicit permission in the hope, that whoever wrote this extremely funny text, does not mind.

Question: How many internet mail list subscribers does it take to change a light bulb?

Answer: 1331.

Here's a detailed list why:

1
to change the light bulb and to post to the mail list that the light bulb has been changed

14
to share similar experiences of changing light bulbs and how the light bulb could have been changed differently.

7
to caution about the dangers of changing light bulbs.

27
to point out spelling/grammar errors in posts about changing light bulbs.

53
to flame the spell checkers

156
to write to the list administrator complaining about the light bulb discussion and its inappropriateness to this mail list.

41
to correct spelling in the spelling/grammar flames.

109
to post that this list is not about light bulbs and to please take this email exchange to ``alt.lite.bulb''.

203
to demand that cross posting to ``alt.grammar'', ``alt.spelling'' and ``alt.punctuation'' about changing light bulbs be stopped.

111
to defend the posting to this list saying that we are all use light bulbs and therefore the posts are relevant to this mail list.

306
to debate which method of changing light bulbs is superior, where to buy the best light bulbs, what brand of light bulbs work best for this technique, and what brands are faulty.

27
to post URLs where one can see examples of different light bulbs

14
to post that the URLs were posted incorrectly, and to post corrected URLs.

3
to post about links they found from the URLs that are relevant to this list which makes light bulbs relevant to this list.

33
to concatenate all posts to date, then quote them including all headers and footers, and then add ``Me Too''.

12
to post to the list that they are unsubscribing because they cannot handle the light bulb controversey.

19
to quote the ``Me Too''s to say, ``Me Three''.

4
to suggest that posters request the light bulb FAQ.

1
to propose new ``alt.change.lite.bulb'' newsgroup.

47
to say this is just what ``alt.physic.cold_fusion'' was meant for, leave it here.

143
votes for ``alt.lite.bulb''.

A.2 Unsubscribe me

 

Since the very first day mailing list existed, people did not get the difference between the mailing list address and the address where commands for the list server should be sent to. Because of that, every mailing list in the known universe receives an article with only the word ``unsubscribe'' in the body occasionally, usually followed by a lengthy flame war. (The only exception to this are mailing lists with no susbcribers at all -- they just receive postings with only the word ``subscribe'' in the body occasionally.)

Anyway, a pretty good reply to people posting their unsubscribe command to the mailing list is the following text. It has supposedly been written by KJ Fisher <fisherkj@snydelab.delhi.edu>, but we were not able to verify this.

> someonme get me off this fucking mailing list

First, ask your Internet Provider to mail you an Unsubscribing Kit. Then follow these directions.

The kit will most likely be the standard no-fault type. Depending on requirements, System A and/or System B can be used. When operating System A, depress lever and a plastic dalkron unsubscriber will be dispensed through the slot immediately underneath. When you have fastened the adhesive lip, attach connection marked by the large `X' outlet hose. Twist the silver- coloured ring one inch below the connection point until you feel it lock.

The kit is now ready for use. The Cin-Eliminator is activated by the small switch on the lip. When securing, twist the ring back to its initial condition, so that the two orange lines meet. Disconnect. Place the dalkron unsubscriber in the vacuum receptacle to the rear. Activate by pressing the blue button.

The controls for System B are located on the opposite side. The red release switch places the Cin-Eliminator into position; it can be adjusted manually up or down by pressing the blue manual release button. The opening is self- adjusting. To secure after use, press the green button, which simultaneously activates the evaporator and returns the Cin-Eliminator to its storage position.

You may log off if the green exit light is on over the evaporator . If the red light is illuminated, one of the Cin-Eliminator requirements has not been properly implemented. Press the ``List Guy'' call button on the right of the evaporator . He will secure all facilities from his control panel.

To use the Auto-Unsub, first undress and place all your clothes in the clothes rack. Put on the velcro slippers located in the cabinet immediately below. Enter the shower, taking the entire kit with you. On the control panel to your upper right upon entering you will see a ``Shower seal'' button. Press to activate. A green light will then be illuminated immediately below. On the intensity knob, select the desired setting. Now depress the Auto-Unsub activation lever. Bathe normally.

The Auto-Unsub will automatically go off after three minutes unless you activate the ``Manual off'' override switch by flipping it up. When you are ready to leave, press the blue ``Shower seal'' release button. The door will open and you may leave. Please remove the velcro slippers and place them in their container.

If you prefer the ultrasonic log-off mode, press the indicated blue button. When the twin panels open, pull forward by rings A & B. The knob to the left, just below the blue light, has three settings, low, medium or high. For normal use, the medium setting is suggested.

After these settings have been made, you can activate the device by switching to the ``ON'' position the clearly marked red switch. If during the unsubscribing operation, you wish to change the settings, place the ``manual off'' override switch in the ``OFF'' position. You may now make the change and repeat the cycle. When the green exit light goes on, you may log off and have lunch. Please close the door behind you.

Index

~petidomo
4.2 Directory Structure
~petidomo/bin/hermes
4.5.2 hermes
~petidomo/bin/listserv
4.5.1 listserv
~petidomo/bin/petidomo
4.5 The Binaries
~petidomo/bin/send-pr
9.1 Reporting problems
~petidomo/etc/acl
7 The Access Control
~petidomo/etc/help
5 Using Petidomo as
/etc/aliases
4.6 Aliases
ACL file
7 The Access Control
ADD
5.1 SUBSCRIBE
AdminPassword
4.3.2 The Master Config , 4.3.3 The list config
AllowAlienSubscription
4.3.3 The list config
AllowMembersCommand
4.3.3 The list config
AllowPublicSubscription
4.3.3 The list config
Approval
6.3 Approving requests, 6.4 Approving postings
APPROVE
6.4 Approving postings
bounce
6.1 Bounces
petidomo.com
9.1 Reporting problems
CGI Manager
4.4.2 Using the CGI
closed mailing list
3 What is a
commands
5 Using Petidomo as
Config file;tex2html_html_special_mark_quot;format
4.3.1 Config File Syntax
default help text
5 Using Petidomo as
DELETE
5.2 UNSUBSCRIBE
description
4.4.2 Using the CGI
DetachImmediately
4.3.2 The Master Config
directory structure
4.2 Directory Structure
encrypted mailing;tex2html_html_special_mark_quot;lists
8.2 PGP-encrypted mailing lists
fully qualified domain name
4.3.2 The Master Config
HELP
5.4 HELP
help text
5 Using Petidomo as
hermes
4.5.2 hermes
hosting a mailing;tex2html_html_special_mark_quot;list
3 What is a
Hostname
4.3.2 The Master Config
humor
A Humor
INDEX
5.3 INDEX
InsertNameInSubject.sh
8.1 Using posting filters
Install script
4 Installing Petidomo
introduction text
4.4.2 Using the CGI
lightbulb
A.1 Changing lightbulbs and
list config file
4.3.3 The list config
list of subscribers
3 What is a
LISTS
5.3 INDEX
listserv
4.5.1 listserv
ListType
4.3.3 The list config
LONGINDEX
5.3 INDEX
mail transport agent
4.3.2 The Master Config
mailing list address
3 What is a
mailing list names
4.4.2 Using the CGI
mailing list owner
6 Using Petidomo as
mailing list subscriber
3 What is a
master config;tex2html_html_special_mark_quot;file
4.2 Directory Structure
MEMBERS
5.5 MEMBERS
Moving Petidomo
4 Installing Petidomo
MTA
4.3.2 The Master Config
MTA_Options
4.3.2 The Master Config
owner
6 Using Petidomo as
PASSWORD
6.3 Approving requests
petidomo-user
4 Installing Petidomo
petidomoconf.cgi
4.4 The CGI Manager
posting to a list
3 What is a
PostingFilter
4.3.3 The list config
PostingPassword
4.3.3 The list config
problem reports
9.1 Reporting problems
public mailing list
3 What is a
quickstart
1 Quickstart for the
rejected article
6.2 Closed and moderated
remote configuration
4.4.2 Using the CGI
REMOVE
5.2 UNSUBSCRIBE
reporting problems
9.1 Reporting problems
request address
5 Using Petidomo as
send-pr
9.1 Reporting problems
ShowOnIndex
4.3.3 The list config
ShowStatistics
4.3.2 The Master Config
signature
4.4.2 Using the CGI
Spammer
4.3.3 The list config
SUBSCRIBE
5.1 SUBSCRIBE
UNSUBSCRIBE
5.2 UNSUBSCRIBE
unsubscribe me
A.2 Unsubscribe me
user commands
5 Using Petidomo as
virtual hosting
4.3.2 The Master Config , 4.3.3 The list config
WHO
5.5 MEMBERS
...time.
Curious people might want to take the PGP source code and look up, who added this code back then. :-)
 


Peter Simons <simons@petidomo.com>


Banner.Novgorod.Ru