--- petidomo.pod 2001/01/20 13:34:57 1.1
+++ petidomo.pod 2004/03/19 15:36:12 1.2
@@ -27,11 +27,13 @@
=head1 SYNOPSIS
-B<petidomo>
-[B<--mode=>I<MODE>]
-[B<--listname=>I<NAME>]
-[B<--masterconf=>I<FILE>]
-[B<--approved>]
+B<petidomo> B<--mode=>I<deliver|dump> B<--listname=>I<NAME> [B<--masterconf=>I<FILE>]
+
+B<petidomo> B<--mode=>I<listserv> [B<--listname=>I<NAME>] [B<--masterconf=>I<FILE>]
+
+B<petidomo> B<--mode=>I<approve> [B<--masterconf=>I<FILE>]
+
+B<petidomo> [B<--approved>]
=head1 DESCRIPTION
@@ -41,37 +43,104 @@
still performed by an MTA like B<Sendmail>.
B<Petidomo> provides only the most important features of B<Majordomo>, but
-is
+should be considered as rather complete. It will handle nearly most of the
+task you come across in handling several mailing lists.
=head1 COMMAND LINE OPTIONS
-The C<petidomo> program provides the following command line options:
+The B<Petidomo> program provides the following command line options:
=over 4
-=item B<--masterconf>=I<FILE>
+=item B<--mode>=I<MODE>
-The path to the global B<Petidomo> configuration file.
+The mode parameter is the only mandatory parameter and it will
+determine what mode B<Petidomo> runs in:
+I<listserv>, I<deliver>, I<approve>, I<dump>.
-=item B<--mode>=I<MODE>
+=over 4
+
+=item I<listserv>
+
+In this mode, B<Petidomo> will expect to read an e-mail from standard
+input, which contains commands like I<subscribe>, I<index> or
+I<help>. These commands will be carried out and notifications be sent
+back to the mail's originator if apropriate.
+
+=item I<deliver>
-...
+This mode will cause B<Petidomo> to read the incoming e-mail from
+standard input and post it to the mailing list, which's name has been
+provided via the I<listname> option.
+
+=item I<approve>
+
+When running in this mode, B<Petidomo> will read the incoming mail from
+standard input and search for any cookies that mail might contain.
+If it does, it checks the I<ack-queue> for a mail that has been deferred
+until confirmation that matches that cookie and processes the mail.
+
+=item I<dump>
+
+In this mode, B<Petidomo> will expect the name of a mailing list on
+the command line --- the I<listname> option --- and dump the list of
+subscribed addresses on that list to standart output.
+
+=back
=item B<--listname>=I<NAME>
-...
+The name of the mailing list B<Petidomo> should work on.
+
+=item B<--masterconf>=I<FILE>
+
+Using this parameter you can tell Petidomo to use a different location
+for the master config file than the one that has been compiled in.
=item B<--approved>
-...
+This flag is for internal purposes and should not be specified by the
+administrator. It will tell Petidomo that, whatever it is supposed to
+do now, is the result of a received confirmation cookie. This will
+effectively tell the checks for posting (in B<ListType> I<acknowledged>
+and I<acknowledged-once> mode) and un-/subscription (in B<SubscriptionType>
+I<acknowledged> mode) that everything is fine and that the request should
+be carried out.
=back
=head1 CONFIGURATION
-=head2 Global Configuration
+=head2 Petidomo Global Configuration
+
+The global B<Petidomo> configuration is stored in
+B<@PREFIX@/etc/petidomo/petidomo.conf>.
-The global B<Petidomo> configuration provides the following directives:
+=head2 Syntax
+
+=over 4
+
+=over 4
+
+B<keyword parameter>
+
+=back
+
+=back
+
+If the parameter contains any blank characters, it has to be quoted, ie.:
+
+=over 4
+
+=over 4
+
+B<AdminPassword "open sesame">
+
+=back
+
+=back
+
+=head2 The following directives are supported:
=over 4
@@ -80,7 +149,9 @@
This entry specifies the fully qualified domain name, B<Petidomo>
should use. This will usually be the FQDN of the machine the software
is running on. This option is mandatory. B<Petidomo> will abort with an
-error, if it is unset. Example: C<Hostname petidomo.example.org>
+error, if it is unset.
+
+Example: B<Hostname petidomo.example.org>
=item B<AdminPassword> I<string>
@@ -89,31 +160,1306 @@
Knowledge of the master password will enable you to access ALL mailing
lists running on this system. Passwords are always case-insensitive.
This option is mandatory. B<Petidomo> will abort with an error, if it is
-unset. Example: C<AdminPassword "open sesame">
+unset.
+
+Example: B<AdminPassword "open sesame">
+
+=item B<MTA> I<string>
+
+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.
+
+Example: B<MTA @PREFIX@/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. B<Petidomo> will abort with an error,
+if the master config file doesn't set it.
+
+=item B<MTAOptions> I<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. You usually won't change this.
+
+Example: B<MTAOptions "-odq -i -f%s">
+
+This will yield a call "$<$MTA$>$ -odq -i -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.
+
+=item B<ListDirectory> I<string>
+
+Here you can tell B<Petidomo> the path to the directory where the mailing
+list config files reside. The compiled-in default is B<@PREFIX@/etc/petidomo>.
+When B<Petidomo> tries to find the configuration of list, say, "foobar",
+it will look for any of the following files in this directory:
+I<foobar.conf, foobar.config, foobar/conf or foobar/config>.
+
+=item B<AckQueueDirectory> I<string>
+
+This tag will tell B<Petidomo> where to store files that need to be
+queued for later processing --- for example subscribe requests that
+need to be acknowledged by the user before they'll be carried out. The
+default location is B<@PREFIX@/var/petidomo>.
+Please note that Petidomo will need permission to write to that directory
+in order for things to work.
+
+=item B<HelpFile> I<string>
+
+This tag will tell B<Petidomo> where to find the text file that will be
+sent back to a user sending in a B<help> command. The default
+location is B<@PREFIX@/etc/petidomo/petidomo.help>.
+
+=item B<IndexFile> I<string>
+
+Similarly to "HelpFile" this tag will tell B<Petidomo> where to find
+the text file that will be sent back to a user requesting the server's
+"index". The default location is B<@PREFIX@/etc/petidomo/petidomo.index>.
+
+=item B<ACLFilePre> I<string>
+
+=item B<ACLFilePost> I<string>
+
+This tags tell B<Petidomo> the path to the system-wide ACL files for pre-
+and postprocessing. The default location is
+B<@PREFIX@/etc/petidomo/petidomo.acl-[pre|post]>.
+This ACLs will be run against all incoming mails first before the mail is
+checked against the list specific ACLs.
+Rules from an ACL-Pre file will be matched against incoming mail before certain
+processing in lists with ListType I<acknowledged> and I<acknowledged-once>
+mode set will take place.
+The rules in an ACL-Post file is matched against the original posting after the
+approval process.
+
+=back
+
+=head2 Petidomo List Configuration
+
+While the master config file sets options which are relevant for the
+B<Petidomo> package as a whole, the list config file sets options which
+are valid only locally for the mailing list.
+
+The list specific configuration is stored in
+B<@PREFIX@/etc/petidomo/$listname.conf>.
+
+=head2 Syntax
+
+=over 4
+
+=over 4
+
+B<keyword parameter>
+
+=back
+
+=back
+
+If the parameter contains any blank characters, it has to be quoted, ie.:
+
+=over 4
+
+=over 4
+
+B<AdminPassword "open sesame">
+
+=back
+
+=back
+
+=head2 The supported keywords are as follows :
+
+=over 4
+
+=item B<ListType> I<open | closed | moderated | acknowledged | acknowledged-once>
+
+
+This option tells B<Petidomo> who is allowed to post to the mailing
+list.
+
+If this option is unset, the default is to run an open list.
+
+=over 4
+
+=item I<open>
+
+On this type mailing list, everybody is allowed to post, whether he's
+subscribed or not.
+
+=item I<closed>
+
+In this case only subscribers are allowed to post. That means that
+only mails coming from an address found on the list's address
+database will go through. All other mails will be sent back to the
+person trying to post with the comment that he should subscribe first.
+
+Please note that a closed list may not do exactly what you want,
+because when a person is subscribed to a list as
+C<"example@address.net">, but tries to post from a different account
+than that one, Petidomo will not let him post. It tries to recognize
+this case as far as possible: For example, it doesn't matter whether
+you are posting from C<"address@host1.address.net"> or
+C<"address@host2.address.net">, B<Petidomo> will handle that. But if
+the article comes from C<"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.
+
+=item I<acknowledged>
+
+=item I<acknowledged-once>
+
+These types are better ways off keeping spam off your lists.
+In this case every time someone tries to post, he will get a short
+reply back which contains some cryptographic cookies. Furthermore
+the mail will tell him to please concatenate the cookies and sent it
+back B<Petidomo>. Once that is accomplished, B<Petidomo> will let
+the posting pass.
+
+This means that only people will be able to post, that have a valid
+envelope or from address --- something spammers usually do not. Since
+the request for confirmation never reaches them, their postings will
+not go through. Everybody else can acknoledge the posting by sending
+the cookie back and thus get by that hurdle.
+
+The difference between the I<acknowledged> and I<acknowledged-once>
+mode is, that in the latter mode, people have to send that
+confirmation back only B<once>, while in the first mode, they have
+to send it in every time they're trying to post. B<Petidomo> will keep a
+database of addresses that have been confirmed by that mechanism and
+these addresses are allowed to post from now on without having to
+confirm their posting again. Please note that this list of addresses
+is not related to the list of subscribers!
+
+=item I<moderated>
+
+Here nobody is allowed to post unless he can provide the correct
+posting- or administrator password for the list.
+
+=back
+
+=item B<SubscriptionType> I<public | admin | acknowledged>
+
+This option specifies who may subscribe to a mailing list.
+
+If this option is unset, the default will allow public subscription.
+
+=over 4
+
+=item I<public>
+
+In this case anybody may subscribe any address to the list.
+
+=item I<admin>
+
+Only the person knowing the admin password of the mailing list is allowed
+to subscribe or unsubscribe addresses. All other requests that aren't properly
+authenticated will be forwarded to the list owner for approval.
+
+=item I<acknowledged>
+
+Anybody can issue a subscribe command, but the address will not be added
+to the list (or removed from the list in case of an B<unsubscribe>) unless
+the request has been confirmed. B<Petidomo> will send a random cookie to the
+address in question and ask to send the concatenated cookie back to acknowledge
+the request. Once the cookie has been send back, the request is carried out.
+
+This mode is useful to prevent people from adding random addresses to
+the list or to prevent them from removing other people from the list
+without their consensus.
+
+=back
+
+=item B<AllowMembersCommand> I<yes | no>
+
+B<Petidomo> knows a command B<"members"> or B<"who">, which can be sent
+to the server, which will reply with the complete list of subscribed
+addresses of the specified 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 I<no>, the
+B<members> command will be diabled for this list. This is also the
+default if the option is not specified in the config file.
+
+=item B<Hostname> I<string>
+
+This options tells B<Petidomo> to use this hostname for the mailing list,
+instead of the one configured in the master configuration file. This
+feature is useful to do virtual hosting.
+If this entry is unset, the name configured in the master config file
+will be used as hostname for this mailing list.
+
+Example: B<Hostname petidomo.example.org>
+
+Virtual hosting is required if several mailing lists run on
+the same server, but they have to look like they would coming from
+different machines. For a more detailed explanation look further down in
+the administration section.
+
+
+=item B<AdminPassword> I<string>
+
+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.
+
+Example: B<AdminPassword "open sesame">
+
+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.
+
+
+
+=item B<PostingPassword> I<string>
+
+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.
+
+Example: B<PostingPassword "open sesame">
+
+
+=item B<ReplyTo> I<[none | address]>
+
+This tag controls the C<"Reply-To:"> field, which B<Petidomo> adds to
+posted articles before it is delivered to the recipients. Using this
+option, you can force Petidomo to insert a C<"Reply-To:"> which points
+to a certain address. On a moderated list, for example, you can set
+this as follows:
+
+Example: B<ReplyTo moderator@petidomo.net>
+
+to direct all replies to the posting to the moderator again,
+regardless of what address is noted in the C<"From:"> line of the mail.
+
+If you set C<"none">, B<Petidomo> will not add a C<"Reply-To:"> header at
+all.
+
+If this option is unset, B<Petidomo> will insert a C<"Reply-To:">
+header that directs replies back to the mailing list, so that
+subscribers can conveniently post simply by hitting the C<"reply">
+function in their mail reader.
+
+
+=item B<Archive> I<string>
+
+This option tells B<Petidomo> to 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 I<"/var/archive/list"> or relative
+I<"archive">. For relative paths, the directory where the list's
+config file resides will be used as starting point. If the
+B<Archive> tag points to a file, B<Petidomo> will append every posted
+article to that file. If it points to a directory, each posting will be
+stored as a separate file in that directory.
-=item ...
+If is unset, posted articles will not be archived at all.
+
+=item B<IntroductionFile> I<string>
+
+This tag specifies the path to the introduction file.
+Every time an address is added to the mailing list, B<Petidomo> will send
+the contents of this file to the new subscriber. This should be
+used to inform the new subscriber about the list's topic, habits
+etc. If the file does not exist, no mail is sent out.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.intro>.
+
+
+=item B<DescriptionFile> I<string>
+
+This tag specifies the path to the description file.
+This file is supposed to contain a short description of the mailing
+list's topic and purpose. It's contents will be sent back if a user
+requests the command B<"help listname">.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/listname.desc>.
+
+=item B<SignatureFile> I<string>
+
+The contents of the file this tag points to will be appended to
+every posting on this list. This may be used to add a
+list-specific signature.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.sig>.
+
+=item B<AddressFile> I<string>
+
+This option specifies the path to the file, which B<Petidomo> uses to
+store the list of subscribed addresses.
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.list>.
+
+=item B<AcknowledgementFile> I<string>
+
+This option specifies the path to the file, which B<Petidomo> uses to
+store the list of addresses that have been verified by the
+I<acknowledgement-once> mechanism.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.ack>.
+
+
+=item B<HeaderFile> I<string>
+
+The contents of this file specified in this option will be added to the
+header of posting on this list. This may be used to add custom headers like:
+
+Example: B<X-List-Archive-is-at: http://list-archive.example.org/>
+
+Please note that the contents of this file will be added
+as is!!! So don't include empty lines in here, as empty
+lines mark the end of the mail headers! Generally, please use this
+feature with care; most mailing list administrators tend to
+overestimate the importance of custom headers on their mailing list.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.hdr>.
+
+=item B<ACLFilePre> I<string>
+
+=item B<ACLFilePost> I<string>
+
+This option specifies the path to the list-specific ACL files for pre-
+and postprocessing. This ACLs will be run against all incoming mails after
+the mail was checked against the global ACLs.
+Rules from an ACL-Pre file will be matched against incoming mail before certain
+processing in lists with ListType B<acknowledged> and B<acknowledged-once>
+mode set will take place.
+The rules in an ACL-Post file is matched against the original posting after the
+approval process.
+
+If the path specified has no trailing "/", it is interpreted to be
+relative to the directory where the list's config file has been found.
+The default path is B<@PREFIX@/etc/petidomo/$listname.acl-[pre|post]>.
+
+=item B<PostingFilter> I<string>
+
+Here you can specify the path to a program through which every message deliverd to
+the list will be passed. For example this comes in useful, if you would like to
+bring the message in a certain format or would like to manipulate the C<"Subject:">
+line before realy posting the article to the list. Keep in mind that this filter
+will be applied after all ACL processing has taken place, thus after an ACL I<filter>
+action eventually has been applied.
+
+The path can be given without quotes, but if you want to pass arguments or want to
+specify complicated shell expressions, you will have to use double quotes.
+
+The filter is given the message on sB<tdin> and B<Petidomo> expects the output
+on B<stdout> of the filter.
+
+Example:
+
+=over 4
+
+=over 4
+
+B<PostingFilter "@PREFIX@/etc/petidomo/filter.sh listname">
+
+=back
=back
-=head2 List Configuration
+Example:
+
+=over 4
+
+=over 4
+
+B<PostingFilter "/bin/cat | /bin/cat; echo ; echo Testing"">
+
+=back
+
+=back
+
+Example for a filter that expects the listname as parameter and inserts the string
+B<[listname-list]> At the beginning of the if it's not already there:
+
+=over 4
+
+=over 4
+
+=item B<#! /bin/sh>
+
+=item B<SUB="[$1-list]">
+
+=item B<awk -v "SUB=$SUB" \>
+
+=item B<'>
+
+=item B<BEGIN { found=0 }>
+
+=item B</^Subject:/ {>
+
+=item B< if (index($0,SUB)) print $line;>
+
+=item B< else {>
+
+=item B< if (found==0) {>
+
+=item B< s=sprintf( "Subject: %s", SUB)>
+
+=item B< $1=s>
+
+=item B< print $0>
+
+=item B< }>
+
+=item B< }>
+
+=item B< found=1>
+
+=item B< next>
+
+=item B<}>
+
+=item B</.*/ { print }>
+
+=item B<'>
+
+=item B<exit 0>
+
+=back
+
+=back
+
+=back
=head2 Access Control Lists (ACL)
-=head1 EXAMPLE
+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 files and the ACL files that are local to the mailing
+list. While the latter are valid only for the list for which they
+are configured for, the global ACL files will be parsed for
+B<all> your mailing lists. ACL files are only relevant for mailing
+list postings, Petidomo does not use them in I<listserv> mode.
-=head2 Sendmail Configuration
+The syntax of an ACL file is similar to the C programming
+language, as you can see in the following example:
-C<aliases>:
+=over 4
-=head2 Petidomo Global Configuration
+B<if (envelope matches "mailer-daemon@") then
+ forward "petidomo-manager";>
-C<petidomo.conf>:
+=back
-C<petidomo.acl>:
+This expression tells Petidomo to forward all postings to the
+manager of the mailing list, if the envelope of the mail matches the regular
+expression ``mailer-daemon@''. It will make sure that bounces of articles
+will not be posted to the list again, causing an infinite mail loop.
-=head2 Petidomo List Configuration
+The syntax of ACL statements is shown here:
+
+=over 4
+
+B<IF ( (Condition) [ AND | OR ] (Condition) ............ )
+ THEN Action ;>
+
+=back
+
+Or more Detailed:
+
+=over 4
+
+B<
+IF ( (Source [NOT] MatchCode "Expression") [ AND | OR ]
+ (Source [NOT] MatchCode "Expression") [ AND | OR ]
+ ([NOT] "Filter Expression) .......... )
+ THEN Action ;>
+
+B<
+IF ([NOT] "Filter Expression") [ AND | OR ]
+ ([NOT] "Filter Expression") [ AND | OR ]
+ (Source [NOT] MatchCode "Expression") .......... )
+ THEN Action ;>
+
+=back
+
+Where:
+
+=item B<Source>
+
+=over 4
+
+Specifies the source to match against. This can be one of the following:
+I<envelope> | I<from> | I<subject> | I<header> | I<body>
+
+=over 4
+
+=item I<envelope>
+
+References the envelope line of the message.
+
+=item I<from>
+
+References the C<"From:"> line of the message.
+
+=item I<subject>
+
+References the C<"Subject"> line of the message.
+
+Example:
+
+=over 4
+
+=over 4
+
+=item B<IF (subejct == "make money fast") THEN>
+
+=item B< rejectwith "/usr/local/share/petidomo/make-money-fast.txt";>
+
+=back
+
+=back
+
+=item I<header>
+
+References a specific line in the message header. The line to match is also expressed
+in the I<Expression>. Is meant to be used with regular expression matching.
+
+Example:
+
+=over 4
+
+=over 4
+
+=item B<IF (header matches "^Received:.*from spam.domain") THEN>
+
+=item B< forward "petidomo-manager";>
+
+=back
+
+=back
+
+=item I<body>
+
+References the body of the message. Is meant to be used with
+regular expression matching.
+
+Example:
+
+=over 4
+
+=over 4
+
+=item B<IF (body matches>
+
+=item B<".*[Vv][^a-zA-Z]*[iI][^a-zA-Z]*[aA][^a-zA-Z]*[gG][^a-zA-Z]*[rR][^a-zA-Z]*[aA].*") THEN>
+
+=item B<rejectwith "/usr/local/share/petidomo/no-viagra.txt";>
+
+C<>
+
+=back
+
+=back
+
+=back
+
+=back
+
+=item B<MatchCode>
+
+=over 4
+
+Tell the ACL how to match. There are two possibilities here:
+I<match> / I<matches> | I<=> | I<==>
+
+=over 4
+
+=item I<match> | I<matches>
+
+Does an extended regular expression match using the I<Expression> parameter.
+
+=item I<= | ==>
+
+Does an exact string match using the string given in the I<Expression> parameter.
+
+=back
+
+=back
+
+=item B<"Expression">
+
+=over 4
+
+Depending on I<MatchCode> used, can be an extended regular expression or just
+a plain string. In both cases the match is case insensitiv and has to be quoted.
+
+=back
+
+=item B<"Filter Expression">
+
+=over 4
+
+This a special feature, as you specify an external program to do the matching for
+you. This can be a very useful tool. Dependant on the return code of the external
+program the I<Action> part is executed or not. As in the shell an exit code of B<0>
+means B<true> and of B<1> means B<false>. The path name has to be quoted.
+
+
+Example: B<("/usr/local/bin/very_important.filter") THEN
+ forward "petidomo-manager";>
+
+=back
+
+=item B<Action>
+
+=over 4
+
+
+The I<Action> part specifies what to do after a match occured.
+
+=over 4
+
+=item I<drop>
+
+Just drops the message without firther notice to the sender or list manager.
+
+=item I<pass>
+
+Posts the message onto the list immediately.
+
+=item I<approve>
+
+Will flag the message as approved, bypassing all other checks for approval.
+
+=item I<reject>
+
+Rejects the message from the list, sending a status message to the sender.
+
+=item I<rejectwith "file">
+
+Rejects the message, sending a status message to the user including the contents of
+I<"file"> as the message body. The parameter has to be quoted.
+
+Example:
+
+=over 4
+
+B<IF (header matches "^Received:.*from spam.domain") THEN
+ rejectwith "@PREFIX@/etc/petidomo/spam.txt";>
+
+=back
+
+=item I<forward "address">
+
+Forwards the message to the given I<address>. Originator will be the Mailing
+List Manager. The original message will be quoted in the mail body.
+The I<address> has to be quoted.
+
+=item I<redirect "address">
+
+Just resends the message to the given I<address> without changing any of the headers.
+The message will still look as if it has been sent by the original poster.
+The I<address> has to be quoted.
+
+=item I<filter "script">
+
+This B<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 and before a regular posting filter you might have configured.
+The filter is given the message on sB<tdin> and B<Petidomo> expects the output
+on B<stdout> of the filter.
+
+A nice example for what this feature can be used is the following:
+
+Example:
+
+=over 4
+
+B<if (from == "simons@computer.org") then
+ filter "/@PREFIX@/etc/petidomo/simons.filter";>
+
+=back
+
+=back
+
+=back
+
+C<>
+
+=head1 Administration
+
+Each mailing list has an alias C<"listname-owner"> (see section
+B<Sendmail Configuration>), 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 C<"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 B<Petidomo> in
+the following cases:
+
+=item B<subscribe | unsubscribe>
+
+=over 4
+
+When a new user subscribes, or a subscriber removes himself from
+the list, a carbon copy of the recipt will be sent to the owner. By
+looking at these mails, the owner can check whether a B<subscribe> or
+B<unsubscribe> command looks bogus. He or she can also keep track of
+who is on the list and who is not.
+
+=back
+
+=item B<members | who>
+
+=over 4
+
+If a B<members> command is received for a mailing list where
+this command has been disabled, this will also be forwarded to the
+owner.
+
+=back
+
+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 B<Petidomo>, though, that require some
+kind of reaction.
+
+=head2 Closed an 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 B<AdminPassword> for B<Petidomo>, the
+B<AdminPassword> of the mailing list in question or the B<PostingPassword>.
+
+
+=head2 Approving requests
+
+To approve requests, you have several ways of specifying the
+appropriate password. They are all the same for B<Petidomo> and it is
+only a matter of taste, which scheme you use.
+
+When sending a command to Petidomo in B<listserv> mode through the
+B<listname-request> or B<petidomo> address, just preface your
+commands with a B<password> command, like in the following example:
+
+=over 4
+
+=over 4
+
+=item B<To: testlist-request@foo.bar>
+
+=item B<Subject:>
+
+C<>
+
+=item B<password open sesame>
+
+=item B<subscribe some@one.else>
+
+=item B<subscribe someone@even.elser>
+
+=back
+
+=back
+
+One B<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 B<password>
+command again:
+
+=over 4
+
+=over 4
+
+=item B<To: petidomo@foo.bar>
+
+=item B<Subject:>
+
+C<>
+
+=item B<password open sesame>
+
+=item B<subscribe user@inter.net testlist1>
+
+=item B<password let me in>
+
+=item B<subscribe user@inter.net testlist2>
+
+=back
+
+=back
+
+Instead of B<password>, you can also use the commands B<passwd>, or
+B<approve>, they are all synonymous.
+
+Caution, the command can only be parsed, if they start at the beginning of
+the line and have no junk appended.
+
+
+=head2 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 B<approve> to the mail as first line of the body. B<Petidomo>
+will strip that line before actually posting the article . You can
+also use the synonyms B<approved>, B<password> or B<passwd>
+instead. Here is an example:
+
+=over 4
+
+=over 4
+
+=item B<From: simons@computer.org (Peter Simons)>
+
+=item B<Subject: Cats are the most beautiful animals in the world.>
+
+C<>
+
+=item B<approve let me post>
+
+=item B<It's not that I wouldn't like animals like dogs, birds>
+
+=item B<or fishes, but for me, a cat is *the* animal to have.>
+
+=item B<[...]>
+
+=back
+
+=back
+
+The line B<approve let me post> will be stripped by B<Petidomo> and
+the article will then be sent out.
+
+If you want to specify the password in the headers, just add an header
+of the name B<Approved:> or B<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:
+
+=over 4
+
+=over 4
+
+=item B<From: simons@computer.org (Peter Simons)>
+
+=item B<Subject: Cats are the most beautiful animals in the world.>
-Petidomo C<foo.conf>:
+=item B<Approve: let me post>
+
+C<>
+
+=item B<It's not that I wouldn't like animals like dogs, birds>
+
+=item B<or fishes, but for me, a cat is *the* animal to have.>
+
+=item B<[...]>
+
+=back
+
+=back
+
+Please note that you have to add a colon to the keyword to make a
+valid RFC mail-header.
+
+=head2 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 B<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 B<unsubscribe> command for that
+address to the B<listname-request> address of the mailing list.
+
+If you have configured B<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.
+
+
+=head2 Verifying the address list
+
+B<Petidomo> tries its best to make sure that only syntactically correct
+addresses are subscribed to mailing lists, and if you stick to the
+correct mail interface, there's very little chance, an incorrect
+address will make it into the B<Listname.list> file.
+
+Sometimes, it is necessary to edit these files manually, though, or
+B<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
+I<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:
+
+=over 4
+
+=over 4
+
+=item B<$ xargs < listname.list sendmail -bv | grep -vi deliverable>
+
+=item B<hey@this@is@wrong ... Invalid route address>
+
+=back
+
+=back
+
+This call will find all incorrect address and notify you. The 'sed'
+call will filter out all correct addresses for your convenience.
+
+=head2 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 B<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:
+B<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.
+
+=head2 Sendmail configuration
+
+Before you can use B<Petidomo>, you have to configure sendmail so that it
+knows about Petidomo. If you are using an MTA other than sendmail,
+the configuration might be slightly different.
+
+You will have to create apropriate aliases for B<Petidomo> and its lists.
+You do this by adding the folling lines to your aliases file. For the exact
+location of this file refer to the documentation on your system.
+
+=over 4
+
+=over 4
+
+=item B<petidomo-manager: postmaster>
+
+=item B<petidomo: "| @PREFIX@/bin/petidomo --mode=listserv">
+
+=item B<petidomo-approve: "| @PREFIX@/bin/petidomo --mode=approve">
+
+=back
+
+=back
+
+In case you installed the B<Petidomo> binary to some other location, you
+will have to change the paths here apropriately of course. You may
+also chose that mail for the B<petidomo-manager> should go to some
+different address than B<postmaster>, if that suits your needs
+better. It's important that somebody actually reads what
+arrives there.
+
+For every mailing list you want to install on your system, you will have
+to add the following lines :
+
+=over 4
+
+=over 4
+
+=item B<testlist: "| @PREFIX@/bin/petidomo --mode=deliver testlist">
+
+=item B<testlist-request: "| @PREFIX@/bin/petidomo --mode=listserv testlist">
+
+=item B<testlist-owner: petidomo-manager>
+
+=item B<owner-testlist: testlist-owner>
+
+=back
+
+=back
+
+Having done all this, execute the newaliases(1) utility to rebuild
+sendmail's internal database. Your changes will not have any effect
+unless you do this.
+
+=head2 Virtual Hosting
+
+Virtual hosting is required if you want to host several mailing
+lists that have to run under different domain names.
+After registering these domains to point to your machine, you will have
+to configure B<Petidomo> and your MTA to make use of this feature.
+As an example for MTA configuration, the B<sendmail> system is used here.
+
+To configure B<Petidomo>, all you have to do is, set the B<Hostname> parameter in the
+lists config file B<listname.conf> to the required name (see above).
+You can do this for every list you want to run. If you do not specify a B<Hostname>
+in the lists config file, the name configured in the global config file
+B<petidomo.conf> will be used.
+
+But to get this feature really running, you will have to make your local mail
+agent (MTA) aware of the additional domains it has to recognize as local.
+
+For the B<sendmail v8> system, you will have to write these additional domais to
+the B<w> class in your B<sendmail.cf> file, or the corresponfing M4
+config. This is done by adding the line:
+
+=over 4
+
+=over 4
+
+B<Cwdomain.name1 domain.name2 ...>
+
+=back
+
+=back
+
+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 not lead to the expected behavior, if you are using
+B<sendmail>'s masquerading functionality, which isused to hide the various
+hostnames and subdomains in your domain.
+By default, sendmail not only masquerades the domain names
+it was configured to with the B<MASQUERADE_DOMAIN()> command, it will also
+automatically masquerades all domain names configured in the B<w> class.
+
+As a result the virtual hosting you configured in B<Petidomo> will
+be overwritten.
+To fix for this behavior you will have to add the command
+B<FEATURE(limited_masquerade)> to your M4 file and sendmail won't
+touch the names that are stated only in the B<w> class anymore.
+
+
+=head1 USER COMMANDS
+
+In this chapter, we will describe the commands, that are understood in
+B<listserv> mode, eg. B<listname-request@yourhost.dom>. This is the
+interface for the users of the mailing lists, where they can send their
+requests to in order to be subscribed or unsubscribed to or from a mailing.
+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.
+
+User commands always have to be sent to the request address of
+the mailing list not to the mailing list itself!
+
+Alternatively, commands can always be sent to the address
+B<petidomo@yourhost.dom>, but the B<listname-request@yourhost.dom> address is
+preferable, since B<Petidomo> will have a default
+listname for this address and thus understand a simpler command
+syntax.
+
+
+=head2 Subscribe
+
+The B<subscribe> command will add the address of the user to a
+mailing list. The behavior of the list software on such a request is dependant
+on the setting of the list parameter B<SubscriptionType>. Have a look there for
+a brief explanation.
+
+The command B<add> is synonymous to B<subscribe>.
+
+When using the B<listname-request> address, only the word
+B<subscribe> is required for the request to suceed. If the command is
+sent to the B<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:
+
+=over 4
+
+=over 4
+
+B<subscribe politics>
+
+=back
+
+=back
+
+If the user wants to add an address that is not equal to the one he
+is sending from, the e-mail address will have to be specified as well:
+
+=over 4
+
+=over 4
+
+B<subscribe politics joe@foo.bar>
+
+=back
+
+=back
+
+The order in which the e-mail address and the mailing list name are
+provided does not matter.
+
+=head2 Unsubscribe
+
+The syntax and usage of the B<unsubscribe> command is the same as the
+B<subscribe> command. The difference is, that the user's address
+is removed from the mailing list rather than added to it.
+
+B<delete> and B<remove> can be used synonymously to B<unsubscribe>.
+
+=head2 Index
+
+The B<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 B<lists> and B<longindex> are synonyms to B<index>.
+
+
+=head2 Help
+
+If the server receives the command b<help>, it will send the help
+file back. If b<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.
+
+
+=head2 Members
+
+The B<members> command will return the addresses of all subscribers
+of the mailing list, if the administrator chose to allow this command.
+When B<members> is sent to the B<listname-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:
+
+=over 4
+
+=over 4
+
+B<members politics>
+
+=back
+
+=back
+
+The command B<who> can be used as a synomym to B<members>.
+
+
+=head1 FILES
+
+=over 4
+
+=over 4
+
+=item B<@PREFIX@/etc/petidomo/petidomo.conf>
+
+=item B<@PREFIX@/etc/petidomo/petidomo.hdr>
+
+=item B<@PREFIX@/etc/petidomo/petidomo.help>
+
+=item B<@PREFIX@/etc/petidomo/petidomo.index>
+
+=item B<@PREFIX@/etc/petidomo/petidomo.acl-pre>
+
+=item B<@PREFIX@/etc/petidomo/petidomo.acl-post>
+
+=item B<@PREFIX@/etc/petidomo/listname.conf>
+
+=item B<@PREFIX@/etc/petidomo/listname.desc>
+
+=item B<@PREFIX@/etc/petidomo/listname.intro>
+
+=item B<@PREFIX@/etc/petidomo/listname.hdr>
+
+=item B<@PREFIX@/etc/petidomo/listname.sig>
+
+=item B<@PREFIX@/etc/petidomo/listname.list>
+
+=item B<@PREFIX@/etc/petidomo/listname.ack>
+
+=item B<@PREFIX@/etc/petidomo/listname.acl-pre>
+
+=item B<@PREFIX@/etc/petidomo/listname.acl-post>
+
+=back
+
+=back
+
+=head1 SEE ALSO
+
+=head2 Allman Sendmail
+
+=over 4
+
+=over 4
+
+B<sendmail(8)>
+
+=back
+
+=back
+
+=head2 Postfix
+
+=over 4
+
+=over 4
+
+B<bounce(8)>, B<cleanup(8)>, B<defer(8)>, B<error(8)>, B<flush(8)>, B<lmtp(8)>,
+B<local(8)>, B<master(8)>, B<pickup(8)>, B<pipe(8)>, B<qmgr(8)>, B<showq(8)>, B<smtp(8)>,
+B<smtpd(8)>, B<spawn(8)>, B<trivial-rewrite(8)>.
+
+=back
+
+=back
=head1 HISTORY
|
