From 6a5886db2201e37a633f6898d89810b44c13b23f Mon Sep 17 00:00:00 2001 From: Peter Simons Date: Wed, 24 Feb 2010 18:55:10 +0100 Subject: [PATCH] doc/Makefile.am: enable doc building and installation --- .gitignore | 14 + doc/Makefile.am | 8 +- doc/petidomo.pod | 1473 ---------------------------------------------- 3 files changed, 20 insertions(+), 1475 deletions(-) delete mode 100644 doc/petidomo.pod diff --git a/.gitignore b/.gitignore index c76d918..56f8332 100644 --- a/.gitignore +++ b/.gitignore @@ -27,5 +27,19 @@ Makefile.in /acl-parser.c /acl-parser.h /acl-scanner.c +/doc/petidomo.1 +/doc/petidomo.4ct +/doc/petidomo.4tc +/doc/petidomo.aux +/doc/petidomo.css +/doc/petidomo.dvi +/doc/petidomo.html +/doc/petidomo.idv +/doc/petidomo.lg +/doc/petidomo.log +/doc/petidomo.pod +/doc/petidomo.tmp +/doc/petidomo.toc +/doc/petidomo.xref /petidomo lib*.a diff --git a/doc/Makefile.am b/doc/Makefile.am index 700eb90..1e860a9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -2,5 +2,9 @@ # Petidomo User Manual # -petidomo.1: petidomo.pod - pod2man --section=1 --center="Petidomo" --release="Petidomo" $< >$@ +htmldir = $(pkgdatadir)/html +dist_html_DATA = petidomo.html petidomo.css + +petidomo.html: petidomo.tex + latex $< + htlatex $< diff --git a/doc/petidomo.pod b/doc/petidomo.pod deleted file mode 100644 index 0affa72..0000000 --- a/doc/petidomo.pod +++ /dev/null @@ -1,1473 +0,0 @@ -## -## petidomo.pod -- Petidomo Unix Manual Page -## Copyright (c) 2001 Ralf S. Engelschall -## -## This program 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 3 of the License, or (at your option) any later -## version. -## -## This program 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. -## -## You should have received a copy of the GNU General Public License along with -## this program. If not, see . -## - -=pod - -=head1 NAME - -B -- Mailing List Manager - -=head1 VERSION - -OSSP Petidomo @V@ - -=head1 SYNOPSIS - -B B<--mode=>I B<--listname=>I [B<--masterconf=>I] - -B B<--mode=>I [B<--listname=>I] [B<--masterconf=>I] - -B B<--mode=>I [B<--masterconf=>I] - -B [B<--approved>] - -=head1 DESCRIPTION - -B is a mailing list manager very similar to the popular -package B. 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. - -B provides only the most important features of B, 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 program provides the following command line options: - -=over 4 - -=item B<--mode>=I - -The mode parameter is the only mandatory parameter and it will -determine what mode B runs in: -I, I, I, I. - -=over 4 - -=item I - -In this mode, B will expect to read an e-mail from standard -input, which contains commands like I, I or -I. These commands will be carried out and notifications be sent -back to the mail's originator if apropriate. - -=item I - -This mode will cause B 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 option. - -=item I - -When running in this mode, B will read the incoming mail from -standard input and search for any cookies that mail might contain. -If it does, it checks the I for a mail that has been deferred -until confirmation that matches that cookie and processes the mail. - -=item I - -In this mode, B will expect the name of a mailing list on -the command line --- the I option --- and dump the list of -subscribed addresses on that list to standart output. - -=back - -=item B<--listname>=I - -The name of the mailing list B should work on. - -=item B<--masterconf>=I - -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 I -and I mode) and un-/subscription (in B -I mode) that everything is fine and that the request should -be carried out. - -=back - -=head1 CONFIGURATION - -=head2 Petidomo Global Configuration - -The global B configuration is stored in -B<@PREFIX@/etc/petidomo/petidomo.conf>. - -=head2 Syntax - -=over 4 - -=over 4 - -B - -=back - -=back - -If the parameter contains any blank characters, it has to be quoted, ie.: - -=over 4 - -=over 4 - -B - -=back - -=back - -=head2 The following directives are supported: - -=over 4 - -=item B I - -This entry specifies the fully qualified domain name, B -should use. This will usually be the FQDN of the machine the software -is running on. This option is mandatory. B will abort with an -error, if it is unset. - -Example: B - -=item B I - -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 will abort with an error, if it is -unset. - -Example: B - -=item B I - -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 - -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 will abort with an error, -if the master config file doesn't set it. - -=item B I - -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 - -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 I - -Here you can tell B the path to the directory where the mailing -list config files reside. The compiled-in default is B<@PREFIX@/etc/petidomo>. -When B tries to find the configuration of list, say, "foobar", -it will look for any of the following files in this directory: -I. - -=item B I - -This tag will tell B 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 I - -This tag will tell B where to find the text file that will be -sent back to a user sending in a B command. The default -location is B<@PREFIX@/etc/petidomo/petidomo.help>. - -=item B I - -Similarly to "HelpFile" this tag will tell B 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 I - -=item B I - -This tags tell B 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 and I -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 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 - -=back - -=back - -If the parameter contains any blank characters, it has to be quoted, ie.: - -=over 4 - -=over 4 - -B - -=back - -=back - -=head2 The supported keywords are as follows : - -=over 4 - -=item B I - - -This option tells B 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 - -On this type mailing list, everybody is allowed to post, whether he's -subscribed or not. - -=item I - -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 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 - -=item I - -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. Once that is accomplished, B 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 and I -mode is, that in the latter mode, people have to send that -confirmation back only B, while in the first mode, they have -to send it in every time they're trying to post. B 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 - -Here nobody is allowed to post unless he can provide the correct -posting- or administrator password for the list. - -=back - -=item B I - -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 - -In this case anybody may subscribe any address to the list. - -=item I - -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 - -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) unless -the request has been confirmed. B 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 I - -B 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, the -B command will be diabled for this list. This is also the -default if the option is not specified in the config file. - -=item B I - -This options tells B 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 - -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 I - -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 - -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 I - -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 - - -=item B I<[none | address]> - -This tag controls the C<"Reply-To:"> field, which B 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 - -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 will not add a C<"Reply-To:"> header at -all. - -If this option is unset, B 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 I - -This option tells B 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 tag points to a file, B 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 I - -This tag specifies the path to the introduction file. -Every time an address is added to the mailing list, B 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 I - -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 I - -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 I - -This option specifies the path to the file, which B 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 I - -This option specifies the path to the file, which B uses to -store the list of addresses that have been verified by the -I 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 I - -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 - -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 I - -=item B I - -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 and B -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 I - -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 -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 and B expects the output -on B of the filter. - -Example: - -=over 4 - -=over 4 - -B - -=back - -=back - -Example: - -=over 4 - -=over 4 - -B - -=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 - -=item B - -=item B<'> - -=item B - -=item B - -=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 - -=item B<'> - -=item B - -=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 your mailing lists. ACL files are only relevant for mailing -list postings, Petidomo does not use them in I 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 - -=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 - -=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 - -=over 4 - -Specifies the source to match against. This can be one of the following: -I | I | I | I
| I - -=over 4 - -=item I - -References the envelope line of the message. - -=item I - -References the C<"From:"> line of the message. - -=item I - -References the C<"Subject"> line of the message. - -Example: - -=over 4 - -=over 4 - -=item B - -=item B< rejectwith "/usr/local/share/petidomo/make-money-fast.txt";> - -=back - -=back - -=item I
- -References a specific line in the message header. The line to match is also expressed -in the I. Is meant to be used with regular expression matching. - -Example: - -=over 4 - -=over 4 - -=item B - -=item B< forward "petidomo-manager";> - -=back - -=back - -=item I - -References the body of the message. Is meant to be used with -regular expression matching. - -Example: - -=over 4 - -=over 4 - -=item B - -=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 - -C<> - -=back - -=back - -=back - -=back - -=item B - -=over 4 - -Tell the ACL how to match. There are two possibilities here: -I / I | I<=> | I<==> - -=over 4 - -=item I | I - -Does an extended regular expression match using the I parameter. - -=item I<= | ==> - -Does an exact string match using the string given in the I parameter. - -=back - -=back - -=item B<"Expression"> - -=over 4 - -Depending on I 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 part is executed or not. As in the shell an exit code of B<0> -means B and of B<1> means B. The path name has to be quoted. - - -Example: B<("/usr/local/bin/very_important.filter") THEN - forward "petidomo-manager";> - -=back - -=item B - -=over 4 - - -The I part specifies what to do after a match occured. - -=over 4 - -=item I - -Just drops the message without firther notice to the sender or list manager. - -=item I - -Posts the message onto the list immediately. - -=item I - -Will flag the message as approved, bypassing all other checks for approval. - -=item I - -Rejects the message from the list, sending a status message to the sender. - -=item I - -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 - -=back - -=item I - -Forwards the message to the given I
. Originator will be the Mailing -List Manager. The original message will be quoted in the mail body. -The I
has to be quoted. - -=item I - -Just resends the message to the given I
without changing any of the headers. -The message will still look as if it has been sent by the original poster. -The I
has to be quoted. - -=item I - -This B 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 and B expects the output -on B of the filter. - -A nice example for what this feature can be used is the following: - -Example: - -=over 4 - -B - -=back - -=back - -=back - -C<> - -=head1 Administration - -Each mailing list has an alias C<"listname-owner"> (see section -B), 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 in -the following cases: - -=item B - -=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 or -B command looks bogus. He or she can also keep track of -who is on the list and who is not. - -=back - -=item B - -=over 4 - -If a B 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, 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 for B, the -B of the mailing list in question or the B. - - -=head2 Approving requests - -To approve requests, you have several ways of specifying the -appropriate password. They are all the same for B and it is -only a matter of taste, which scheme you use. - -When sending a command to Petidomo in B mode through the -B or B address, just preface your -commands with a B command, like in the following example: - -=over 4 - -=over 4 - -=item B - -=item B - -C<> - -=item B - -=item B - -=item B - -=back - -=back - -One B 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 -command again: - -=over 4 - -=over 4 - -=item B - -=item B - -C<> - -=item B - -=item B - -=item B - -=item B - -=back - -=back - -Instead of B, you can also use the commands B, or -B, 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 to the mail as first line of the body. B -will strip that line before actually posting the article . You can -also use the synonyms B, B or B -instead. Here is an example: - -=over 4 - -=over 4 - -=item B - -=item B - -C<> - -=item B - -=item B - -=item B - -=item B<[...]> - -=back - -=back - -The line B will be stripped by B 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 or B 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 - -=item B - -=item B - -C<> - -=item B - -=item B - -=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. -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 command for that -address to the B address of the mailing list. - -If you have configured B 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 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 file. - -Sometimes, it is necessary to edit these files manually, though, or -B'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. 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 - -=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. 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 - -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, 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 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 - -=item B - -=item B - -=back - -=back - -In case you installed the B 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 should go to some -different address than B, 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 - -=item B - -=item B - -=item B - -=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 and your MTA to make use of this feature. -As an example for MTA configuration, the B system is used here. - -To configure B, all you have to do is, set the B parameter in the -lists config file B to the required name (see above). -You can do this for every list you want to run. If you do not specify a B -in the lists config file, the name configured in the global config file -B 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 system, you will have to write these additional domais to -the B class in your B file, or the corresponfing M4 -config. This is done by adding the line: - -=over 4 - -=over 4 - -B - -=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'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 command, it will also -automatically masquerades all domain names configured in the B class. - -As a result the virtual hosting you configured in B will -be overwritten. -To fix for this behavior you will have to add the command -B to your M4 file and sendmail won't -touch the names that are stated only in the B class anymore. - - -=head1 USER COMMANDS - -In this chapter, we will describe the commands, that are understood in -B mode, eg. B. 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, but the B address is -preferable, since B will have a default -listname for this address and thus understand a simpler command -syntax. - - -=head2 Subscribe - -The B 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. Have a look there for -a brief explanation. - -The command B is synonymous to B. - -When using the B address, only the word -B is required for the request to suceed. If the command is -sent to the B 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 - -=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 - -=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 command is the same as the -B command. The difference is, that the user's address -is removed from the mailing list rather than added to it. - -B and B can be used synonymously to B. - -=head2 Index - -The B 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 and B are synonyms to B. - - -=head2 Help - -If the server receives the command b, it will send the help -file back. If b 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 command will return the addresses of all subscribers -of the mailing list, if the administrator chose to allow this command. -When B is sent to the B 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 - -=back - -=back - -The command B can be used as a synomym to B. - - -=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 - -=back - -=back - -=head2 Postfix - -=over 4 - -=over 4 - -B, B, B, B, B, B, -B, B, B, B, B, B, B, -B, B, B. -2 -=back - -=back - -=head1 HISTORY - -=head1 AUTHOR - -Peter Simons - - -=cut -