ossp-pkg/petidomo/petidomo.pod
##
## petidomo.pod -- Petidomo Unix Manual Page
## Copyright (c) 2001 Ralf S. Engelschall <rse@engelschall.com>
##
## This file is part of Petidomo.
##
## Petidomo is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2, or (at your option)
## any later version.
##
## Petidomo is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
=pod
=head1 NAME
B<petidomo> -- Mailing List Manager
=head1 VERSION
OSSP Petidomo @V@
=head1 SYNOPSIS
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
B<Petidomo> is a mailing list manager very similar to the popular
package B<Majordomo>. It handles both list un-/subscription and the
address expansion of list postings. The actual delivery of postings is
still performed by an MTA like B<Sendmail>.
B<Petidomo> provides only the most important features of B<Majordomo>, but
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 B<Petidomo> program provides the following command line options:
=over 4
=item B<--mode>=I<MODE>
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>.
=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 Petidomo Global Configuration
The global B<Petidomo> configuration is stored in
B<@PREFIX@/etc/petidomo/petidomo.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 following directives are supported:
=over 4
=item B<Hostname> I<string>
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: B<Hostname petidomo.example.org>
=item B<AdminPassword> I<string>
This tag sets the master password, which authenticiates the
administrator of the package. Please chose this password carefully.
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: 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.
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
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)
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.
The syntax of an ACL file is similar to the C programming
language, as you can see in the following example:
=over 4
B<if (envelope matches "mailer-daemon@") then
forward "petidomo-manager";>
=back
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.
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.>
=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
=head1 AUTHOR
Peter Simons
<simons@computer.org>
=cut
