"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "petidomo-4.0b6/docs/petidomo.tex" of archive petidomo-4.0b6.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 \documentclass[a4paper,10pt]{scrreprt}
2 %
3 % Petidomo Manual
4 %
5 % $Header: /e/ossp/cvs/ossp-pkg/petidomo/docs/petidomo.tex,v 1.8 2001/02/18 01:02:08 simons Exp $
6 %
7 \typearea[2cm]{12}
8 \usepackage{lastpage}
9 \usepackage{fancyhdr}
10 \pagestyle{fancy}
11 \lhead{\sl The Petidomo Mailing List Manager}
12 \chead{}
13 \rhead{Page \thepage\ of \pageref{LastPage}}
14 \lfoot{}
15 \cfoot{}
16 \rfoot{}
17 \fancypagestyle{plain}{}
18 \fussy
19
20 \newcommand{\Def}[1]{{\sl #1}}
21 \newcommand{\file}[1]{{\sf #1}}
22
23 \begin{document}
24
25 \title{The Petidomo Mailing List Manager}
26 \author{Peter Simons $<$simons@computer.org$>$}
27 \date{February 2001}
28 \maketitle
29 \tableofcontents
30 \clearpage
31
32 \chapter{Installing Petidomo}
33
34 The installation of the Petidomo Mailing List Manager is simple and
35 straight forward; do not be scared by the length of this chapter.
36 There are many different ways and options how to install it and I have
37 tried my best to cover \emph{all} of them. If you are not interested
38 in every little detail, you will be able to skim over most of the text
39 here.
40
41 \section{Getting it}
42
43 {\sf This section has not been written yet, because the means of
44 obtaining Petidomo from the Internet are not entirely defined at
45 the moment. I put all my hope into the most kind Mister
46 Engelschall to fill in the details here. }
47
48 \section{Building the Binaries}
49
50 Untar the source archive of Petidomo in a directory of your choice
51 like \file{/usr/local/src} or your home directory. This will create a
52 directory called \file{petidomo-VERSION}, where the ``VERSION''
53 part is called exactly as in the file name of the tar archive. Change
54 into this directory.
55
56 Now you have to run the configure script
57 \begin{quote}
58 \begin{verbatim}
59 ./configure
60 \end{verbatim}
61 \end{quote}
62 which will determine the characteristics of your system and create the
63 files required to actually build Petidomo. You may provide several
64 parameters to the script. The interesting ones, including the default
65 values if unspecified, are:
66 \begin{description}
67
68 \item[{-}{-}help] Display the complete list of command line options.
69
70 \item[{-}{-}prefix] The the \file{PREFIX} for all following paths. The
71 default is \file{/usr/local}.
72
73 \item[{-}{-}exec-prefix] Set the \file{EPREFIX} for all following
74 paths. This is useful in case you want to install binaries into a
75 different directory hierarchy than normal text files, but usually the
76 \file{EPREFIX} is identical to \file{PREFIX}. The default is
77 \file{PREFIX}.
78
79 \item[{-}{-}bindir] Set the directory where the binaries should be
80 installed. The default is \file{EPREFIX/bin}.
81
82 \item[{-}{-}libexecdir] Set the directory where executables should be
83 installed that will be called by Petidomo but not by the user directly
84 (like posting filters). The default is \file{EPREFIX/libexec}.
85
86 \item[{-}{-}datadir] Set the directory where read-only
87 architecture-independent data files should be installed (like the help
88 file). The default is \file{PREFIX/share}.
89
90 \item[{-}{-}sysconfdir] Set the directory where read-only
91 configuration files should be installed. The default is
92 \file{PREFIX/etc}.
93
94 \item[{-}{-}localstatedir] Set the directory where modifiable
95 data files should be installed (like the approve-queue or the mailing
96 list config files). The default is \file{PREFIX/var}.
97
98 \item[{-}{-}mandir] Set the directory where man documentation files
99 should be installed. The default is \file{PREFIX/man}.
100
101 \end{description}
102
103 Please note that the directories you specify here are only the default
104 settings that are compiled into Petidomo. You can modify \emph{all}
105 paths at run-time via the command line and through the configuration
106 files. So don't waste to much time figuring out what you want here,
107 you can change anything later without having to recompile Petidomo.
108
109 Finally, here is an example output of the configuration script when
110 run without any parameters on a Linux machine:
111 \begin{quote}
112 \begin{verbatim}
113 simons@peti:~/projects/petidomo-4.0b1$ ./configure
114 Configuring OSSP Petidomo, Version 4.0b1 (18-Jan-2001)
115 creating cache ./config.cache
116 checking for gcc... gcc
117 checking whether the C compiler (gcc ) works... yes
118 checking whether the C compiler (gcc ) is a cross-compiler... no
119 checking whether we are using GNU C... yes
120 checking whether gcc accepts -g... yes
121 checking for ranlib... ranlib
122 checking for flex... flex
123 checking for yywrap in -lfl... yes
124 checking for bison... bison -y
125 checking size of unsigned short... 2
126 checking size of unsigned int... 4
127 checking size of unsigned long... 4
128 checking how to run the C preprocessor... gcc -E
129 checking for ANSI C header files... yes
130 checking for ssize_t... yes
131 updating cache ./config.cache
132 creating ./config.status
133 creating Makefile
134 \end{verbatim}
135 \end{quote}
136
137 Often, you may want to pass certain flags to the compiler or the
138 linker to modify the building process. To achieve this, you can set
139 certain environment variables before calling the configure script.
140 These variables are:
141 \begin{description}
142 \item[CC] The name of the C compiler to use.
143
144 \item[CPPFLAGS] Flags to pass to the preprocesser before compiling a
145 source code file.
146
147 \item[CFLAGS] Flags to pass to the compiler when compiling a C source
148 code file.
149
150 \item[LDFLAGS] Flags to pass to the linker when linking the binaries.
151
152 \end{description}
153
154 I personally find this useful to raise the level of compiler
155 optimization or to add linker flags that tell the linker to strip
156 unnecessary symbols from the binaries. To achive these effects, I call
157 the configure script like this:
158 \begin{quote}
159 \begin{verbatim}
160 CFLAGS=-O3 LDFLAGS=-s ./configure
161 \end{verbatim}
162 \end{quote}
163
164 Anyway, once the configure script has been run, just call
165 \begin{quote}
166 \begin{verbatim}
167 make
168 \end{verbatim}
169 \end{quote}
170 to start the building process. Petidomo has been tested with various
171 flavours of the make utility and all of them seem to work fine. If in
172 doubt, try GNU Make, which is available from ftp.gnu.org.
173
174 Petidomo has also been built using parallel builds. This is useful if
175 you have a multi-processer system. You can do this with most make
176 utilities by adding the flag ``-j4'' with ``4'' being the number of
177 processes you want to spawn simultaneously. Please note, though, that
178 some make utilities have problems with the rules that translate the
179 yacc-modules included in Petidomo correctly when building in parallel.
180 If you experience any trouble, just build it conventionally and you
181 should be fine.
182
183 \section{Installing the Binaries}
184
185 To install the software to your system, all you have to do is execute
186 \begin{quote}
187 \begin{verbatim}
188 make install
189 \end{verbatim}
190 \end{quote}
191 This will copy the Petidomo binary, the posting filters included in
192 the distribution, the sample config files and the manual pages into
193 the directories you chose at configure time earlier. If you're a
194 first-time user, you may also want to execute
195 \begin{quote}
196 \begin{verbatim}
197 make install-testlist
198 \end{verbatim}
199 \end{quote}
200 which will create a sample mailing list called ``testlist'' for you.
201
202 Assuming you used the default paths when running configure, the
203 install process will create the follwing directories, respectively
204 copy the following files to your system:
205 \begin{quote}
206 \begin{verbatim}
207 /usr/local/
208 /usr/local/bin/
209 /usr/local/bin/petidomo
210 /usr/local/bin/petidomo-approve
211 /usr/local/bin/petidomo-kickout
212 /usr/local/etc/
213 /usr/local/etc/petidomo.acl-sample
214 /usr/local/etc/petidomo.conf-sample
215 /usr/local/libexec/
216 /usr/local/libexec/petidomo/
217 /usr/local/libexec/petidomo/insert-name-in-subject.sh
218 /usr/local/libexec/petidomo/pgp-decrypt.sh
219 /usr/local/libexec/petidomo/pgp-encrypt.sh
220 /usr/local/libexec/petidomo/rfc2369.sh
221 /usr/local/man/
222 /usr/local/man/man1/
223 /usr/local/man/man1/petidomo.1
224 /usr/local/share/
225 /usr/local/share/petidomo/
226 /usr/local/share/petidomo/help
227 /usr/local/var/
228 /usr/local/var/petidomo/
229 /usr/local/var/petidomo/ack-queue/
230 /usr/local/var/petidomo/index
231 /usr/local/var/petidomo/lists/
232 \end{verbatim}
233 \end{quote}
234 If you run the ``install-testlist'' target, the following
235 directory/files will be created additionally:
236 \begin{quote}
237 \begin{verbatim}
238 /usr/local/var/petidomo/lists/testlist/
239 /usr/local/var/petidomo/lists/testlist/config
240 /usr/local/var/petidomo/lists/testlist/acl
241 /usr/local/var/petidomo/lists/testlist/list
242 \end{verbatim}
243 \end{quote}
244
245 \section{Configuring Sendmail}
246
247 Before you can use Petidomo, you have to configure sendmail so that it
248 knows about Petidomo --- I assume that you have sendmail installed
249 already. If you are using an MTA other than sendmail, you are on your
250 own from here on, I am afraid. Any users who have successfully
251 installed Petidomo on a qmail-, vmailer-, or postfix-based system are
252 more than welcome to contribute to this documentation to help other
253 users.
254
255 To run Petidomo via sendmail --- what is what you want to do ---, you
256 have to create apropriate aliases for it. You can do this by adding
257 the folling lines to your aliases file, which usually resides in
258 \file{/etc/aliases} or, with newer sendmail versions, in
259 \file{/etc/mail/aliases}:
260 \begin{quote}
261 \begin{verbatim}
262 petidomo-manager: postmaster
263 petidomo: "|/usr/local/bin/petidomo --mode=listserv"
264 petidomo-approve: "|/usr/local/bin/petidomo --mode=approve"
265 \end{verbatim}
266 \end{quote}
267 In case you installed the Petidomo binary to some other location, you
268 will have to change the paths here apropriately of course. You may
269 also chose that mail for the ``petidomo-manager'' should go to some
270 different address than ``postmaster'', if that suits your needs
271 better; the main point is that somebody actually \emph{reads} what
272 arrives there.
273
274 If executed the ``install-testlist'' target earlier and thus have the
275 example mailing list from the distribution installed, you may also
276 want to add the lines:
277 \begin{quote}
278 \begin{verbatim}
279 testlist: "|/usr/local/bin/petidomo --mode=deliver testlist"
280 testlist-request: "|/usr/local/bin/petidomo --mode=listserv testlist"
281 testlist-owner: petidomo-manager
282 \end{verbatim}
283 \end{quote}
284 Having done all this, execute the newaliases(1) utility to rebuild
285 sendmail's internal database. Your changes will not have any effect
286 unless you do this.
287
288 \section{Configuring the File Permissions}
289
290 The final step, before Petidomo is successfully installed, is to set
291 the right permissions to the installation directories and installed
292 files. Unfortunately, the installation process can not do this
293 automatically; you have to chose what permissions are ``right''
294 yourself. If works like this: Petidomo will be called from sendmail,
295 thanks to the aliases you just created. That means, that sendmail
296 determines under what user to start Petidomo. In 99\% of all
297 configurations I have ever seen, that user is ``daemon'', but it
298 \emph{may} be something else, so we better figure it out for sure.
299
300 Add the line
301 \begin{quote}
302 \begin{verbatim}
303 foobar: "/tmp/foobar-mail"
304 \end{verbatim}
305 \end{quote}
306 to your aliases file and execute newaliases(1). Then send an e-mail to
307 the address ``foobar''. The contents of this mail will be stored in
308 the file \file{/tmp/foobar-mail} then and we are interested in the user
309 who owns this file:
310 \begin{quote}
311 \begin{verbatim}
312 root@peti:/# sendmail -v foobar </dev/null
313 foobar... aliased to "/tmp/foobar-mail"
314 "/tmp/foobar-mail"... Sent
315 root@peti:/# ls -l /tmp/foobar-mail
316 -rw------- 1 daemon daemon 269 Feb 12 17:57 /tmp/foobar-mail
317 \end{verbatim}
318 \end{quote}
319 See? On my system it is ``daemon'' indeed. On your system it may be
320 someone else. Now that we know, you may remove the foobar-line from
321 the aliases file again.
322
323 OK, sendmail starts Petidomo under user id ``daemon''. This means that
324 ``daemon'' must have read access to virtually any file in the Petidomo
325 installation. This is the default, because all files are installed
326 with read permisson for everybody. Also, all directories allow access
327 to anybody by default. But ``daemon'' also needs write access to the
328 ``localstatedir'' --- \file{/usr/local/var/petidomo} per default. You
329 can ensure this by executing the command:
330 \begin{quote}
331 \begin{verbatim}
332 chown -R daemon /usr/local/var/petidomo
333 \end{verbatim}
334 \end{quote}
335
336 This is a rather simplistic solution to the permisson problem; you
337 \emph{can} use much more fine-grained settings if you like to. But I
338 figured that if you are the kind of person who wants to do things like
339 this, you won't need an explanation how to do it anyway. Just that
340 much information for you: Petidomo does not actually write to the
341 ``localstatdir'', but only to the subdirectory \file{ack-queue} located
342 in it.
343
344 Of course, you do not necessarily need to have the \file{ack-queue}
345 directory owned by ``daemon'', you can also set the group permissions
346 apropriately. Furthermore, Petidomo will usually want to write to the
347 \file{lists} directory located in the ``localstatedir'', because most
348 list administrators tend to place the mailing list archives there, but
349 you can enable write access according to the list's configuration once
350 you know how you're mailing lists are configured. In case something
351 does not work as expected, check out the syslog messages for the
352 LOG\_MAIL facility --- this is where Petidomo logs its error messages.
353
354 \section{Configuring Petidomo}
355
356 The last step before we can test our installation is to configure
357 Petidomo. This is really simple. List the contents of the
358 ``sysconfdir'' you chose. If you did not change the default paths,
359 this is \file{/usr/local/etc}. There you will find two files:
360 \file{petidomo.conf-sample} and \file{petidomo.acl-sample}. Just
361 rename them to \file{petidomo.conf} and \file{petidomo.acl}
362 respectively and fire up your favorite text editor to edit the file
363 \file{petidomo.conf}.
364
365 Uncomment the options ``Hostname'', ``AdminPassword'', and ``MTA'' and
366 set the values correctly. ``Hostname'' should be the fully qualified
367 domain name of the machine running Petidomo. It is essential that this
368 name can receive e-mail, that is, that is has an MX record. (Talk to
369 the person administrating the domain name service of your organization
370 if this doesn't make any sense to you.) As ``AdminPassword'', you can
371 chose pretty much any text you like, just make sure you remember it.
372 The ``MTA'' setting will usually be alright the way it is. You may
373 want to check whether sendmail does actually live at this path; on
374 some Unixes, it is not installed at \file{/usr/sbin/sendmail}, but at
375 \file{/usr/lib/sendmail}. Change the setting if this is the case. You
376 can ignore all other settings right now. Come back and configure those
377 once you have read the apropriate sections of this manual. If you're
378 an experienced Unix wizard, the comments in the config file will
379 probably be enough for you to guess what these options do, though.
380
381 Once you have done this, your installation is ready to be tested.
382
383 \section{Testing the Installation}
384 \label{testing}
385
386 Asserting you followed all steps described above, you have a working
387 Petidomo installation now. Occasionally, some minor permisson problem
388 may still remain to be fixed, or you may want to customize some texts.
389 To figure out what is left to do (or to realize that there is nothing
390 left do to), send an e-mail to the ``petidomo'' user on your machine
391 and put the word ``help'' into the mail body --- without the quotes of
392 course.
393
394 On my system, this looks like this:
395 \begin{quote}
396 \begin{verbatim}
397 simons@peti:~/projects/petidomo$ echo help | sendmail -v petidomo
398 petidomo... aliased to "|/usr/local/bin/petidomo --mode=listserv"
399 "|/usr/local/bin/petidomo --mode=listserv"... Connecting to prog...
400 "|/usr/local/bin/petidomo --mode=listserv"... Sent
401 \end{verbatim}
402 \end{quote}
403
404 Once you sent the e-mail, sendmail will start up Petidomo and feed the
405 mail text into it for processing. If you take a look at the syslogfile
406 containing the LOG\_MAIL facility now --- this is usally
407 \file{/var/log/messages} or \file{/var/log/maillog} ---, you will find that
408 Petidomo logged entries there that look pretty much like the following
409 ones. The backslash (``\verb#\#'') characters at the end of some of
410 these lines denote that the line has been wrapped for readability. In
411 reality, this would be one single large line.
412 \begin{quote}
413 \begin{verbatim}
414 sendmail[8705]: f1CIHWJ08705: from=simons, size=5, class=0, \
415 nrcpts=1, msgid=<200102121817.f1CIHWJ08705@peti.cryp.to>, \
416 relay=simons@localhost
417 petidomo[8706]: Petidomo 4.0b1 (18-Jan-2001) starting up; \
418 mode=listserv, listname=<none>, \
419 masterconf=/usr/local/etc/petidomo.conf, \
420 approved=false, ruid=2, euid=2, gid=2, egid=2
421 petidomo[8706]: simons@peti.cryp.to: help
422 sendmail[8707]: f1CIHX508707: from=petidomo-manager@peti.cryp.to, \
423 size=2091, class=-100, nrcpts=1, \
424 msgid=<200102121817.f1CIHX508707@peti.cryp.to>, \
425 relay=daemon@localhost
426 sendmail[8705]: f1CIHWJ08705: \
427 to="|/usr/local/bin/petidomo --mode=listserv", \
428 ctladdr=petidomo (2/0), delay=00:00:01, xdelay=00:00:01, \
429 mailer=prog, pri=30005, dsn=2.0.0, stat=Sent
430 sendmail[8709]: f1CIHX508707: to=simons@peti.cryp.to, delay=00:00:00, \
431 xdelay=00:00:00, mailer=local, pri=212091, dsn=2.0.0, stat=Sent
432 \end{verbatim}
433 \end{quote}
434
435 As you can see, Petidomo logged how it was started, where it is
436 expecting its master config file and under which user- and group id it
437 is running. Then it logs that it has received a HELP request. This
438 request will be answered by sending the file
439 \file{/usr/local/share/petidomo/help} back to the person who requested
440 help, and if everthing worked, you will now find that mail in your
441 mail box.
442
443 If something went wrong, Petidomo will tell you what went wrong. So,
444 please fix the problem and try again. In 99\% of all cases, the error
445 will say something like ``opening file XYZ failed: permission
446 denied''. Then all you have to do is to make sure that the user under
447 which Petidomo has been started (you have the numeric id in the
448 logfile) has read access to that file. If the user has but Petidomo
449 keeps complaining, check, whether that user has access to the
450 directory at all!
451
452 Those of you who executed the ``install-testlist'' target earlier in
453 the ``Building the Binaries'' chapter may also want to test whether
454 this mailing list is working. To do so, send another mail to Petidomo
455 and put the command ``subscribe YOUR-ADDRESS testlist'' in the mail
456 body --- without the quotes! ``YOUR-ADDRESS'' naturally means that you
457 should insert your e-mail address here. This command will subscribe
458 your e-mail address to the ``testlist'' mailing list; you should
459 receive a confirmation about that via e-mail within moments. Once that
460 is accomplished, send another e-mail to the ``testlist'' address on
461 your system. The e-mail may look like whatever you want.
462
463 Within seconds, you should get the mail back from the mailing list
464 server --- and so will all other addresses that are subscribed to the
465 list. My personal test mail looked like this:
466
467 \begin{quote}
468 \begin{verbatim}
469 From testlist-owner@peti.cryp.to Mon Feb 12 19:43:56 2001
470 Received: (from daemon@localhost)
471 by peti.cryp.to id f1CIhuA08872 for simons@peti.cryp.to;
472 Mon, 12 Feb 2001 19:43:56 +0100
473 Received: (from simons@localhost)
474 by peti.cryp.to id f1CIhJY08853 for testlist;
475 Mon, 12 Feb 2001 19:43:19 +0100
476 Date: Mon, 12 Feb 2001 19:43:19 +0100
477 From: Peter Simons <simons@peti.cryp.to>
478 Message-Id: <200102121843.f1CIhJY08853@peti.cryp.to>
479 Subject: Petidomo absolutely rules the known earth!
480 Reply-To: testlist@peti.cryp.to
481 Sender: testlist-owner@peti.cryp.to
482 Precedence: list
483
484 It does ...
485 \end{verbatim}
486 \end{quote}
487
488 If this all worked for you, you have a your Petidomo installation up
489 and running. Men will envy you and women will desire you --- unless,
490 of course, you \emph{are} a woman, then it is vice versa. You will be
491 able to stop smoking any time you want, you may eat anything you like
492 and as much as you like, but you will never gain a single pound. Your
493 sex life will improve dramatically, your boss will like you, your hard
494 drives will never crash and your Internet connections will always be
495 fast. All this, thanks to the wonders of the {\bf Petidomo Mailing
496 List Manager!}
497
498 In case any of the benefits promised above stays away, please consult
499 paragraphs 11 and 12 of the file \file{COPYING} included in this
500 distribution.
501
502 \chapter{Configuring Petidomo}
503
504 \section{Configuration File Syntax}
505
506 All configuration files in the Petidomo-package\label{Config file
507 format}, have the following format:
508 \begin{quote}
509 \begin{verbatim}
510 keyword parameter
511 \end{verbatim}
512 \end{quote}
513
514 The ``keyword''-part must start at the first column of the line and is
515 followed by one or several blanks or tabs. The first non-blank
516 character then is interpreted as the parameter for this keyword. The
517 following line, for example:
518 \begin{quote}
519 \begin{verbatim}
520 Hostname petidomo.is.great
521 \end{verbatim}
522 \end{quote}
523 will tell Petidomo that the name of the machine it is running on is
524 called ``petidomo.is.great''. If the parameter contains any blanks,
525 what is not very likely for a hostname, but may happen with other
526 settings, you should enclose it in double quotes, like this:
527 \begin{quote}
528 \begin{verbatim}
529 AdminPassword "open sesame"
530 \end{verbatim}
531 \end{quote}
532
533 Quoting the parameter is not strictly necessary, though, Petidomo's
534 config file parser will get it right anyway. You only have to quote
535 the parameter, if it contains blanks as first or last character, what
536 is rather unlikely to happen.
537
538 Furthermore all empty lines are ignored. So are lines that start with
539 a `\#' sign. You can use this for writing comments for the reader into
540 the config file.
541
542 \section{The Master Configuration File}
543 \label{master config file}
544
545 The following keywords are recognized in the master config file.
546
547 \begin{description}
548
549 \item[Hostname] \hfill ``hostname.domain.name''
550
551 This entry specifies the fully qualified domain name of the machine,
552 Petidomo is running on. A fully qualified domain name is the
553 hostname of the machine with the domain name appended with a dot. The
554 following, for example:
555 \begin{quote}
556 \begin{verbatim}
557 HostName listserver.foo.bar
558 \end{verbatim}
559 \end{quote}
560 would be a valid statement. Normally this option has been set by the
561 install script correctly already.
562
563 The name you set here is not necessarily the name, Petidomo will use
564 when delivering mailing list-postings to the subscribers, or when
565 answering requests, because you can specify a different fully
566 qualified domain name for every mailing list you host. This is known
567 as \Def{virtual hosting}.
568
569 This option is \emph{required}. Petidomo will abort with an error,
570 if the master config file doesn't set it.
571
572 \item[AdminPassword] \hfill ``password''
573
574 This tag sets the master password, which authenticiates the Petidmo
575 administrator. Here is an example:
576 \begin{quote}
577 \begin{verbatim}
578 AdminPassword "open sesame"
579 \end{verbatim}
580 \end{quote}
581 Normally this option has been set by the install script already.
582
583 Please chose this password carefully. Knowledge of the master password
584 will enable you to access \emph{all} mailing lists running on this
585 system.
586
587 Passwords are compared case-insensitively. That means, that the
588 passwords ``Open SESAME'', ``open sesame'' and ``OPEN seSAme'' are all
589 the same.
590
591 This option is \emph{required}. Petidomo will abort with an error,
592 if the master config file doesn't set it.
593
594
595 \item[MTA] \hfill ``/path/to/executable''
596
597 The MTA tag tells Petidomo which mail transport agent should be used
598 to deliver outgoing emails. Normally this option has been set by the
599 install script already, so you don't need to worry about this anymore.
600
601 An example setting is:
602 \begin{quote}
603 \begin{verbatim}
604 MTA "/usr/sbin/sendmail"
605 \end{verbatim}
606 \end{quote}
607 but Petidomo will run fine with other mail transport agents, too. So
608 far, the system has been tested with the Allman sendmail, SMail and
609 qmail without any problems.
610
611 This option is \emph{required}. Petidomo will abort with an error,
612 if the master config file doesn't set it.
613
614
615 \item[MTAOptions] \hfill ``string''
616
617 This tag is a bit tricky and in ninety-nine out of hundred cases you
618 should simply leave this option undefined as it is rarely required
619 anyway.
620
621 This entry sets the options which will be handed over to the MTA
622 when it is called. The following example
623 \begin{quote}
624 \begin{verbatim}
625 MTAOptions "-odq -i -f%s"
626 \end{verbatim}
627 \end{quote}
628 will yield a call ``$<$MTA$>$ -odq -i -f$<$envelope$>$''. The `\%s' is
629 replaced with the envelope the mail should be sent under.
630
631 Adding options to the execution call of the mail transport agent can
632 be useful to enable or disable certain features for mailing lists
633 only, while leaving them on for all other mail. The `-odq' setting is
634 a fine example. This parameter will tell the Allmann sendmail to queue
635 all mail, instead of trying to deliver it immediately.
636
637
638 \item[ListDirectory] \hfill ``/path/to/directory''
639
640 Here you can tell Petidomo the path to the directory where the mailing
641 list config file reside. The compiled-in default is
642 ``LOCALSTATEDIR/petidomo/lists'' --- in most cases that resolves to
643 \file{/usr/local/var/petidomo/lists}. When Petidomo tries to find the
644 configuration of list, say, ``foobar'', it will look for any of the
645 following files in this directory: \file{foobar.conf},
646 \file{foobar.config}, \file{foobar/conf}, or \file{foobar/config}.
647
648 \item[AckQueueDirectory] \hfill ``/path/to/directory''
649
650 This tag will tell Petidomo where to store files that need to be
651 queued for later processing --- for example subscribe requests that
652 need to be acknowledged by the user before they'll be carried out. The
653 default location is ``LOCALSTATEDIR/petidomo/ack-queue''; unless you
654 changed the default path at compile time, this will resolve to
655 \file{/usr/local/var/petidomo/ack-queue}. Please note that Petidomo
656 will need permission to write to that directory in order for things to
657 work.
658
659 \item[HelpFile] \hfill ``/path/to/file''
660
661 This tag will tell Petidomo where to find the text file that will be
662 sent back to a user sending in a ``help'' command. The default
663 location is ``DATADIR/petidomo/help"'', what is usually the file
664 \file{/usr/local/share/petidomo/help}.
665
666
667 \item[ACLFile] \hfill ``/path/to/file''
668
669 This tag tells Petidomo the path to the system-wide ACL file. The
670 default location is ``SYSCONFDIR/petidomo.acl'', what usually resolves
671 to \file{/usr/local/etc/petidomo.acl}.
672
673 \item[IndexFile] \hfill ``/path/to/file''
674
675 Similarly to ``HelpFile'', this tag will tell Petidomo where to find
676 the text file that will be sent back to a user requesting the server's
677 ``index''. The default location is ``LOCALSTATEDIR/petidomo/index'';
678 unless you changed the default path at compile time, this will resolve
679 to \file{/usr/local/var/petidomo/index}.
680
681 \end{description}
682
683 \section{List Configuration Files}
684 \label{list config file}
685
686 While the master config file sets options which are relevant for the
687 Petidomo package as a whole, the list config file sets options which
688 are valid only locally for the mailing list. The supported keywords
689 are as follows.
690
691 \begin{description}
692
693 \item[ListType] \hfill ``open'', ``closed'', ``moderated'',
694 ``acknowledged'', or ``acknowledged-once''
695
696 This setting tells Petidomo who is allowed to post to the mailing
697 list. On an ``open'' mailing list, everybody is allowed to post,
698 whether he's subscribed or not. On a ``closed'' mailing list, only
699 subscribers are allowed to post. That means that only mails coming
700 from an address found on the list's address database will go through.
701 All other mails will be sent back to the person trying to post with
702 the comment that he should subscribe first.
703
704 Please note that a closed list may not do exactly what you want,
705 because when a person is subscribed to a list as
706 ``example@address.net'', but tries to post from a different account
707 than that one, Petidomo will not let him post. It tries to recognize
708 this case as far as possible: For example, it doesn't matter whether
709 you are posting from ``address@host1.address.net'' or
710 ``address@host2.address.net'', Petidomo will handle that. But if the
711 article comes from ``example@private.account'', it will be rejected,
712 even though the sender might be a valid subscriber. It depends on the
713 subscribers of the mailing list, whether this is a problem or not.
714
715 A better way to keep spam off your lists may be the ``acknowledged''
716 or ``acknowledged-once'' type of list. The former list mode means that
717 every time someone tries to post, he will get a short reply back which
718 contains some cryptographic cookie. Furthermore the mail will tell
719 him to please reply to that mail and send the cookie back to Petidomo.
720 Once that is accomplished, Petidomo will let the posting pass.
721
722 This means that only people will be able to post that have a valid
723 envelope or from address --- something spammers usually do not. Since
724 the request for confirmation never reaches them, their postings will
725 not go through. Everybody else can acknoledge the posting by sending
726 the cookie back and thus get by that hurdle.
727
728 The difference between the ``acknowledged'' and ``acknowledged-once''
729 mode finally is that in the latter mode, people have to send that
730 confirmation back only \emph{once}, while in the first mode, they have
731 to send it in every time they're trying to post. Petidomo will keep a
732 database of addresses that have been confirmed by that mechanism and
733 these addresses are allowed to post from now on without having to
734 confirm their posting again. Please note that this list of addresses
735 is not related to the list of subscribers!
736
737 Last but not least, there is a mode called ``moderated''; in this
738 mode, nobody is allowed to post unless he can provide the correct
739 posting- or administrator password for the list.
740
741 If this option is unset, the default is to run an open list.
742
743 \item[SubscriptionType] \hfill ``public'', ``admin'', or ``acknowledged''
744
745 This option specifies who may subscribe to a mailing list. On an
746 ``open''-subscription list, anybody may subscribe any address to the
747 list. If the subscription type is ``admin'', only the person knowing
748 the admin password of the mailing list is allowed to subscribe or
749 unsubscribe addresses. All other requests that aren't properly
750 authenticated will be forwarded to the list owner for approval.
751
752 If the subscription type is set to ``acknowledged'', anybody can issue
753 a subscribe command, but the address will not be added to the list (or
754 removed from the list in case of an ``unsubscribe'') unless the
755 request has been confirmed: Petidomo will send a random cookie to the
756 address in questing and ask to send the cookie back to acknowledge the
757 request. Once the cookie has been send back, the request is carried
758 out.
759
760 This mode is useful to prevent people from adding random addresses to
761 the list or to prevent them from removing other people from the list
762 without their consesus.
763
764 If this option is unset, the default to allow public subscription.
765
766 \item[AllowMembersCommand] \hfill ``yes'' or ``no''
767
768 Petidomo knows a command ``members'' or ``who'', which can be sent
769 to the server and it will reply with the complete list of subscribed
770 addresses for the mailing list. This may be useful for list
771 administrators, but it can be abused easily by spammers, to collect
772 addresses where to send their unsolicted commercial e-mail to.
773
774 Furthermore, with certain mailing lists it may be undesirable that one
775 can see ``who else'' is subscribed to that list. That's why this
776 option has been added. If you set it to ``no'', the
777 ``members''-command will be diabled for this list. (This is also the
778 default if the option is not specified in the config file.)
779
780 If you set it to ``yes'', the ``members''-command will work.
781
782 \item[Hostname] \hfill ``hostname.domainname''
783
784 This options tells Petidomo to use this hostname for the mailing list,
785 instead of the one configured in the master configuration file. This
786 feature is useful to do virtual hosting.
787
788 \Def{Virtual hosting} is required when several mailing lists run on
789 the same server, but they have to look like they would coming from
790 different machines. Let's use an example: The internet service
791 provider ``Inter.Net'' offers its customers to host mailing lists for
792 them. A small software house of the name ``Petiware'' wants to provide
793 a mailing list for all its customers, but they don't have a dedicated
794 Internet line.
795
796 So they use the service provided by Inter.Net and let them host the
797 mailing list on their machine. The mailing list server at Inter.Net
798 has the fully qualified domain name ``mail.inter.net''. Petiware,
799 though, wants the list to run under the name
800 ``customers@petiware.com'' and \emph{not} ``customers@inter.net'' ---
801 what would a be misleading.
802
803 So all the mailing list guru from Inter.Net has to do is to set the
804 entry
805 \begin{quote}
806 \begin{verbatim}
807 Hostname petiware.com
808 \end{verbatim}
809 \end{quote}
810 in the config file of the ``customers'' mailing list. Petidomo will
811 now use the hostname ``peti\-ware.com'' in all mails that are posted
812 to that list, instead of ``mail.inter.net''.
813
814 You can specify a different hostname for every mailing list, using
815 this feature. \emph{That} is ``virtual hosting''. Further details on
816 virtual hosting can be found in section~\ref{virtual hosting and
817 sendmail} of the user manual.
818
819 If this entry is unset, the name configured in the master config file
820 will be used as hostname for this mailing list.
821
822 \item[AdminPassword] \hfill ``string''
823 \label{list admin password}
824
825 This tag sets the master password, which authenticiates the
826 administrator of this mailing list. The administrator has special
827 priviledes, such as deleting other users, overriding access control
828 restrictions or un-/subscribing users to closed mailing lists. This is
829 described briefly in section~\ref{petidomo as admin} of the user manual.
830
831 Please note that passwords are always case-insensitive. It is also
832 worth noting that the master password is always valid as administrator
833 password for the list, also.
834
835 Leave this entry blank, if you don't want to enable remote
836 administration of the mailing list.
837
838 \item[PostingPassword] \hfill ``string''
839 \label{posting password}
840
841 This tag sets the ``posting password''. The posting password allows to
842 post an article to a moderated mailing list, but it does not allow any
843 administration of the list itself. On lists that are of a different
844 type than moderated, setting a posting password does usually not make
845 any sense and you can leave this entry unset.
846
847 \item[ReplyTo] \hfill ``email@address.net'' or ``none''
848
849 This tag controls the `Reply-To:' field, which Petidomo adds to
850 posted articles before it is delivered to the recipients. Using this
851 option, you can force Petidomo to insert a `Reply-To:' which points
852 to a certain address. On a moderated list, for example, you can set
853 this as follows:
854 \begin{quote}
855 \begin{verbatim}
856 ReplyTo moderator@address.net
857 \end{verbatim}
858 \end{quote}
859 to direct all replies to the posting to the moderator again,
860 regardless of what address is noted in the `From:' line of the mail.
861
862 If you set ``none'', Petidomo will not add a `Reply-To:' header at
863 all.
864
865 If this option is unset, Petidomo will to insert a `Reply-To:'
866 header that directs replies back to the mailing list, so that
867 subscribers can conveniently post simply by hitting the `reply'
868 function in their mail reader.
869
870 \item[PostingFilter] \hfill ``bourne shell command''
871
872 If you specify a posting filter, this program or script will be
873 started by Petidomo before it sends a posting out to the
874 subscribers. The programm will receive the article, as it has been
875 prepared by Petidomo, on standard input and is expected to write the
876 final version of the mail to standard output. The posting filter can
877 be used to manipulate the headers for special purposes.
878
879 An example for a postin filter that wouldn't modify the mail at all is
880 the following:
881 \begin{quote}
882 \begin{verbatim}
883 PostingFilter /bin/cat
884 \end{verbatim}
885 \end{quote}
886
887 A detailed discussion of posting filters can be found in
888 section~\ref{using posting filters} of the manual.
889
890 If the filter program exits with a returncode not equal to 0 (zero),
891 Petidomo will not post the article and terminate.
892
893
894 \item[Archive] \hfill ``/path/of/archive''
895
896 If this option is set, Petidomo will archive all articles that have
897 been posted on that mailing list. The parameter for this tag may
898 either be the name and path of a file or of a directory. The path may
899 either be absolute (\file{/var/archive/list}) or relative
900 (\file{archive}). For relative paths, the directory where the list's
901 config file resides will be used as starting point. If the
902 ``Archive''-tag points to a file, Petidomo will append every posted
903 article to that file. If points to a directory, each posting will be
904 stored in that directory in a separate file.
905
906 If this option is unset, posted articles will not be archived at all.
907
908 For further information an creating mailing list archives, please
909 refer to section~\ref{mailing list archives} of the user manual.
910
911
912 \item[IntroductionFile] \hfill ``/path/to/file''
913
914 This tag specifies the path to the so called ``introduction'' file.
915 Every time an address is added to the mailing list, Petidomo will send
916 the contents of this file to the new subscriber. This is meant to be
917 used to inform the new subscriber about the list's topic, habits he
918 should know, etc. If the file does not exist, no mail is sent out.
919
920 If the path specified here is relative --- not starting with a ``/''
921 character that is ---, it is interpreted to be relative to the
922 directory where the list's config file has been found. The default
923 path is \file{introduction}.
924
925
926 \item[DescriptionFile] \hfill ``/path/to/file''
927
928 This tag specifies the path to the so called ``description'' file.
929 This file is supposed to contain a short description of the mailing
930 list's topic and purpose. It's contents will be sent back if a user
931 requests the command ``help listname''.
932
933 If the path specified here is relative --- not starting with a ``/''
934 character that is ---, it is interpreted to be relative to the
935 directory where the list's config file has been found. The default
936 path is \file{description}.
937
938
939 \item[ACLFile] \hfill ``/path/to/file''
940
941 This tag specifies the path to the list-specific ACL file. Please
942 refer to section~\ref{acl} for more information about the access
943 control language of Petidomo.
944
945 If the path specified here is relative --- not starting with a ``/''
946 character that is ---, it is interpreted to be relative to the
947 directory where the list's config file has been found. The default
948 path is \file{acl}.
949
950
951 \item[HeaderFile] \hfill ``/path/to/file''
952
953 The contents of this file this tag points to will be added to the
954 header of \emph{every} posting on this list. This may be used to add
955 custom headers like:
956 \begin{quote}
957 \begin{verbatim}
958 X-List-Archive-is-at: http://list-archive.example.org/
959 \end{verbatim}
960 \end{quote}
961
962 Please note that the contents of this file will be added
963 \emph{verbatim}! So don't include any empty lines in here as empty
964 lines mark the end of the mail headers! Generally, please use this
965 feature with care; most mailing list administrators tend to
966 overestimate the importance of custom headers on their mailing list.
967
968 If the path specified here is relative --- not starting with a ``/''
969 character that is ---, it is interpreted to be relative to the
970 directory where the list's config file has been found. The default
971 path is \file{header}.
972
973
974 \item[SignatureFile] \hfill ``/path/to/file''
975
976 The contents of this file this tag points to will be appended to
977 \emph{every} posting on this list. This may be used to add a
978 list-specific signature, like:
979 \begin{quote}
980 \begin{verbatim}
981 --
982 Useful comment here.
983 \end{verbatim}
984 \end{quote}
985
986 If the path specified here is relative --- not starting with a ``/''
987 character that is ---, it is interpreted to be relative to the
988 directory where the list's config file has been found. The default
989 path is \file{signature}.
990
991
992 \item[AddressFile] \hfill ``/path/to/file''
993
994 This tag specifies the path to the path of the file Petidomo uses to
995 store the list of subscribed addresses. If the path specified here is
996 relative --- not starting with a ``/'' character that is ---, it is
997 interpreted to be relative to the directory where the list's config
998 file has been found. The default path is \file{list}.
999
1000
1001 \item[AcknowledgementFile] \hfill ``/path/to/file''
1002
1003 This tag specifies the path to the path of the file Petidomo uses to
1004 store the list of addresses that have been verified by the
1005 acknowledgement mechanism and may furtheron post without having to
1006 acknowledge their posting again. This is only used if the list is set
1007 to ``acknowledge-once'' mode.
1008
1009 If the path specified here is relative --- not starting with a ``/''
1010 character that is ---, it is interpreted to be relative to the
1011 directory where the list's config file has been found. The default
1012 path is \file{ack}.
1013
1014 \end{description}
1015
1016 \section{Command Line Syntax}
1017
1018 Petidomo understans several command line parameters. Here is the
1019 complete list:
1020
1021 \begin{description}
1022
1023 \item[{-}-mode={\sf mode}] \hfill ``listserv'', ``deliver'', ``approve'', or ``dump''
1024
1025 The mode parameter is the only mandatory parameter and it will
1026 determine what mode Petidomo runs in. Anyway, if Petidomo is started
1027 in ``listserv'' mode, it will expect to read an e-mail from standard
1028 input, which contains commands like ``subscribe'', ``index'' or
1029 ``help''. These commands will be carried out and notifications be sent
1030 back to the mail's originator if apropriate.
1031
1032 In ``deliver'' mode, Petidomo will read the incoming e-mail from
1033 standard input and post it to the mailing list, which's name has been
1034 provided via the ``listname'' option. When running in ``approve''
1035 mode, Petidomo will read the incoming mail from standard input and
1036 search for any cookies that mail might contain. If it does, it checks
1037 the ack-queue for a mail that has been deferred until confirmation
1038 that matches that cookie and processes the mail.
1039
1040 In ``dump'' mode, Petidomo will expect the name of a mailing list on
1041 the command line --- the ``listname'' option --- and dump the list of
1042 subscribed addresses on that list to standart output.
1043
1044 \item[{-}-listname={\sf list name}]
1045
1046 This parameter may contain any valid mailing list name. Depending on
1047 the mode, it this list name will be used as follows. In ``listserv''
1048 mode, that list will be used as default list name for any command
1049 where no list name has been specified. A ``subscribe'', for example''
1050 will subscribe the user to the list given here; a ``subscribe
1051 some-other-name'' will still subscribe the user to that other list,
1052 though.
1053
1054 When running in ``deliver'' mode, this is the name of the list the
1055 posting is supposed to be posted to. In ``dump'' mode, this is the
1056 name of the list, which's subscriber list should be dumped. In
1057 ``approve'' mode, this parameter is ignored.
1058
1059 \item[{-}-masterconf=\file{/path/to/petidomo.conf}]
1060
1061 Using this parameter you can tell Petidomo to use a different location
1062 for the master config file than the one that has been compiled in.
1063
1064 \item[{-}-approved]
1065
1066 This flag is for internal purposes and should not be specified by the
1067 administrator. It will tell Petidomo that, whatever it is supposed to
1068 do now, is the result of a received confirmation cookie. This will
1069 effectively tell the checks for posting (in ListType ``acknowledged''
1070 and ``acknowledged-once'' mode) and un-/subscription (in
1071 SubscriptionType ``acknowledged'' mode) that everything is fine and
1072 that the request should be carried out.
1073
1074 \end{description}
1075
1076
1077 \section{Aliases}
1078 \label{aliases}
1079
1080 The Petidomo binary will usually not be called manually from the
1081 shell, but by the mail transport agent. This works as follows: You
1082 create an e-mail account, which serves the purpose of accepting the
1083 incoming e-mail and piping it into the Petidomo binary.
1084
1085 This is archieved with the ``alias''-function of your mail transport
1086 agent. Most MTAs, like sendmail, have a file where a list of special
1087 account names is given together with the instructions what to do with
1088 any mail received for that account. This file is usually located at
1089 \file{/etc/aliases} or \file{/etc/mail/aliases}.
1090
1091 One thing, aliases can do is pipe the mail into a program for
1092 processing. This is the mechanism Petidomo uses. Petidomo requires you
1093 to add the following aliases to your system:
1094 \begin{quote}
1095 \begin{verbatim}
1096 #
1097 # Mailing List Stuff
1098 #
1099 petidomo-manager: postmaster
1100 petidomo: "|/usr/local/bin/petidomo --mode=listserv"
1101 petidomo-approve: "|/usr/local/bin/petidomo --mode=approve"
1102 \end{verbatim}
1103 \end{quote}
1104
1105 The lines starting with the `\#' character are only comments and are
1106 ignored by the mail transport agent. The fourth line, though, is the
1107 first command. It tells the MTA to accept mail for an user of the name
1108 ``petidomo-manager'' and to re-direct the e-mail to the address
1109 ``postmaster'' --- the mail system administrator.
1110
1111 Petidomo will send error notifications and things like that to the
1112 address ``petidomo-manager''. By setting this alias to a certain user
1113 name, you can control who will receive those mails.
1114
1115 The next line tells the MTA to pipe any incoming mail for the user
1116 ``petidomo'' into the ``petidomo'' program, instead of delivering it
1117 into a mailbox. ``petidomo'' (in listserv mode) will then parse the
1118 mail for commands and react accordingly. Hence, the address people can
1119 send their subscription requests to is ``petidomo@your.host.name''.
1120
1121 Similarly, the address ``petidomo-approve'' will be used to receive
1122 any acknowledges user send back after Petidomo requested them. Only
1123 now, Petidomo is started in ``approve'' mode.
1124
1125 Furthermore, each mailing list on your server \emph{requires} three
1126 aliases, as shown in the example below, which is written for the
1127 ``testlist'' mailing list that comes with the distribution:
1128 \begin{quote}
1129 \begin{verbatim}
1130 testlist: "|/usr/local/bin/petidomo --mode=deliver testlist"
1131 testlist-request: "|/usr/local/bin/petidomo --mode=listserv testlist"
1132 testlist-owner: petidomo-manager
1133 \end{verbatim}
1134 \end{quote}
1135
1136 The first alias, ``testlist'' is the address to which people can send
1137 their mail in order to post to the mailing list. Any incoming mail for
1138 that account will be piped into the ``petidomo'' binary in ``deliver''
1139 mode, which will process the mail and then re-send it to all
1140 subscribers of the mailing list. In order to let Petidomo know, for
1141 which mailing list the posting was meant, the parameter ``testlist''
1142 has to be specified on the command line. If the name of the mailing
1143 list was ``foobar'', the line would look like this:
1144 \begin{quote}
1145 \begin{verbatim}
1146 foobar: "|/usr/local/bin/petidomo --mode=deliver foobar"
1147 \end{verbatim}
1148 \end{quote}
1149
1150 The second alias is a special request address, to which users can send
1151 their commands. The difference between this address and the
1152 ``petidomo'' alias described above is that here Petidomo is being
1153 given a default listname on the command line. The difference is this:
1154 If Petidomo receives a mail, which has the command ``subscribe'' in
1155 it, without any further parameters, it will reject the command with an
1156 error, because it doesn't know to which list the sender wants to be
1157 added.
1158
1159 If the command ``subscribe'' is sent to the ``testlist-request''
1160 address, though, it will assume that the user wants to be subscribed
1161 to the ``testlist'' mailing list, as this is the default list for this
1162 address.
1163
1164 The name of this alias should always be the name of the mailing list
1165 with the string ``-request'' appended. Theoretically you could choose
1166 a different name, but this unwritten standard has been widely accepted
1167 in the Internet for several years now.
1168
1169 The last alias is the name of the mailing list with the string
1170 ``-owner'' appended. This alias points to the person who is
1171 responsible for managing the ``testlist'' mailing list. Petidomo
1172 will send all e-mail concerning the administration of the mailing list
1173 to the address ``listname-owner''. Usually this will ultimately be the
1174 same person as the ``petidomo-manager'', but you are free to direct
1175 mail for this account to somebody else, or to several persons.
1176
1177 \chapter{Petidomo for Mailing List Users}
1178 \label{petidomo as user}
1179
1180 In this chapter, we will describe the commands, that are understood in
1181 ``listserv'' mode. This is the interface for the users of the mailing
1182 lists, where they can send their requests to in order to be subscribed
1183 to a mailing list, be unsubscribed again and similar things. The text
1184 here is mostly identical with the default help text that is sent to
1185 the user whenever he or she issues a command that is syntactically
1186 incorrect.
1187
1188 User commands always have to be sent to the request address of
1189 the mailing list --- \emph{not} to the mailing list itself!
1190
1191 Alternatively, commands can always be sent to the address
1192 ``peti\-do\-mo@your.ad\-dress'', but the ``-request''-address is
1193 preferable, for the fact that the Petidomo will have a default
1194 listname for this address and thus understand a simpler command
1195 syntax.
1196
1197 \section{SUBSCRIBE}
1198
1199 The ``subscribe'' command will add the address of the user to a
1200 mailing list. When using the ``-request''-address, only the word
1201 ``subscribe'' is required for the request to suceed. If the command is
1202 sent to the ``petidomo'' address, the user will have to specify an
1203 additional parameter: The name of the mailing list he or she wants to
1204 be added to, like in the following example:
1205 \begin{quote}
1206 \begin{verbatim}
1207 subscribe politics
1208 \end{verbatim}
1209 \end{quote}
1210
1211 If the user wants to add an address that is not equal to the one he or
1212 she is sending the e-mail from, the e-mail address will have to be
1213 specified, too:
1214 \begin{quote}
1215 \begin{verbatim}
1216 subscribe politics joe@foo.bar
1217 \end{verbatim}
1218 \end{quote}
1219
1220 The order in which the e-mail address and the mailing list name are
1221 provided does not matter. Please note that the administrator can
1222 configure Petidomo to disallow un-/subscring other addresses than
1223 the one, the request is sent from, using the
1224 ``AllowAlienSubscription'' option in the list's config file.
1225
1226 The command ``add'' is synonymous to ``subscribe''.
1227
1228 \section{UNSUBSCRIBE}
1229
1230 The syntax and usage of the ``unsubscribe`` command are the same as the
1231 ``subscribe'' command. The difference is, though, the the user's address
1232 is removed from the mailing list rather than added to it.
1233
1234 ``delete'' and ``remove'' can be used synonymously to ``unsubscribe''.
1235
1236 \section{INDEX}
1237
1238 The ``index'' command does not need any parameters. Sending it to the
1239 server will return a list of available mailing lists on this server.
1240 This is useful in case you want to subscribe to a list but can't
1241 remember the exact name anymore.
1242
1243 The commands ``lists'' and ``longindex'' are synonyms to ``index''.
1244
1245 \section{HELP}
1246
1247 If the server receives the command ``help'', it will send the help
1248 file back. If ``help'' has a parameter, Petidomo will check whether
1249 this is a valid name of an existing mailing list, and if it is, it
1250 will return the description file for this mailing list, rather than
1251 the help file.
1252
1253 \section{MEMBERS}
1254
1255 The ``members'' command will return the addresses of all subscribers
1256 of the mailing list, if the administrator chose to allow this command.
1257 When ``members' is sent to the ``-request''-address, the default list
1258 will be used by Petidomo. Otherwise, the name of the mailing list
1259 which's subscribers should be listed, has to be specified as an option
1260 like in the following example:
1261 \begin{quote}
1262 \begin{verbatim}
1263 members politics
1264 \end{verbatim}
1265 \end{quote}
1266
1267 The command ``who'' can be used synonymously to ``members''.
1268
1269 \chapter{Petidomo for Administrators}
1270 \label{petidomo as admin}
1271
1272 On the ``other side'' of Petidomo, from the user's
1273 perspective, is the administrator of the mailing list --- also called
1274 the \Def{mailing list owner}). Each mailing list has an
1275 alias ``listname-owner'' (see section~\ref{aliases}), where the mail
1276 address of the person who is responsible for this mailing list should
1277 be specified. Per default, this is the user who is known as
1278 ``petidomo-manager''. But you are free to direct mail for this accoun
1279 to any other person --- or several persons.
1280
1281 The list owner will receive administrative e-mail from Petidomo in
1282 the following cases:
1283
1284 \begin{itemize}
1285
1286 \item When a new user subscribes, or a subscriber removes himself from
1287 the list, a carbon copy of the recipt will be sent to the owner. By
1288 looking at these mails, the owner can check whether a ``subscribe'' or
1289 ``unsubscribe'' command looks bogus. He or she can also keep track of
1290 who is on the list and who is not.
1291
1292 \item If a ``members'' command is received for a mailing list where
1293 this command has been disabled, this will also be forwarded to the
1294 owner.
1295
1296 \end{itemize}
1297
1298 These mails are merely for information purposes and do not necessarily
1299 require an action from the admin. There are cases, where the list
1300 owner will receive mails from Petidomo, though, that require some
1301 kind of reaction.
1302
1303 \section{Bounces}
1304
1305 While maintaining mailing list with a larger number of subscribers, it
1306 happens regularly that subscribed addresses become invalid or are
1307 temporarily not reachable. In this case postings will \Def{bounce}.
1308 You will then receive a mail from a mail server telling you, that the
1309 delivery of the mail failed.
1310
1311 Often, addresses become unreachable due to a misconfiguration of a
1312 machine, so it is not always necessary to remove that address from the
1313 list immediately, but when an addresses bounces for several days in a
1314 row, it is a good idea to delete that address from the mailing list.
1315 You should do that by sending an ``unsubscribe'' command for that
1316 address to the ``-request''-address of the mailing list.
1317
1318 If you have configured Petidomo to disallow the unsubscription of
1319 addresses not equal to the address the mail is sent from, you will
1320 have to specify your admin password in the mail, to override the
1321 barrier. How this is done is described in section~\ref{approve} later.
1322
1323 \section{Closed and moderated lists}
1324
1325 If you have configured a mailing list to reject postings under certain
1326 circumstances, such as a closed or moderated mailing list, these
1327 rejected articles will be forwarded to you for approval. When you
1328 receive such a rejected article, you can either silently
1329 discard it, contact the author or post it to the mailing list with
1330 your approval.
1331
1332 You can approve an article with the master password for Petidomo, the
1333 admin password of the mailing list in question or the posting password
1334 (see section~\ref{posting password} of that list.
1335
1336 \section{Approving requests}
1337 \label{approve}
1338
1339 To approve an article, you have several ways of specifying the
1340 appropriate password. They are all the same for Petidomo and it is
1341 only a matter of taste, which scheme you use.
1342
1343 When sending a command to Petidomo in ``listserv'' mode through the
1344 ``-request'' or ``petidomo''-address, it is easy: Just preface your
1345 commands with a ``password'' command, like in the following example.
1346 \begin{quote}
1347 \begin{verbatim}
1348 To: testlist-request@foo.bar
1349 Subject:
1350
1351 password open sesame
1352 subscribe some@one.else
1353 subscribe someone@even.elser
1354 \end{verbatim}
1355 \end{quote}
1356
1357 One ``password'' command sets your password for all the commands to
1358 follow. If you want to use one mail to send requests for several
1359 mailing lists with different passwords, just give a ``password''
1360 command again:
1361 \begin{quote}
1362 \begin{verbatim}
1363 To: petidomo@foo.bar
1364 Subject:
1365
1366 password open sesame
1367 subscribe user@inter.net testlist1
1368 password let me in
1369 subscribe user@inter.net testlist2
1370 \end{verbatim}
1371 \end{quote}
1372
1373 Instead of ``password'', you can also use the commands ``passwd'', or
1374 ``approve'', they are all synonymous.
1375
1376 \section{Approving postings}
1377
1378 If you want to approve a posting for a mailing list, just send the
1379 article to the mailing list and specify your password either in the
1380 header or in the body of the mail.
1381
1382 If you choose to approve the mail in the body, add line with the
1383 command ``approve'' to the mail as first line of the body. Petidomo
1384 will strip that line before actually posting the article then. You can
1385 also use the synonyms ``approved'', ``password'' or ``passwd''
1386 instead. Here is an example:
1387 \begin{quote}
1388 \begin{verbatim}
1389 From: simons@computer.org (Peter Simons)
1390 Subject: Cats are the most beautiful animals in the world.
1391
1392 approve let me post
1393 It's not that I wouldn't like animals like dogs, birds
1394 or fishes, but for me, a cat is *the* animal to have.
1395 [...]
1396 \end{verbatim}
1397 \end{quote}
1398
1399 The line ``approve let me post'' will be stripped by Petidomo and
1400 then the article will be sent out.
1401
1402 If you want to specify the password in the headers, just add an header
1403 of the name ``Approved'' or ``Approve'' to the headers of the mail.
1404 (Unfortunately, many mail readers do not allow you to modify the
1405 headers of outgoing mail. That is why the body-approval has been
1406 added.) Here is the same example as above now using the headers:
1407 \begin{quote}
1408 \begin{verbatim}
1409 From: simons@computer.org (Peter Simons)
1410 Subject: Cats are the most beautiful animals in the world.
1411 Approve: let me post
1412
1413 It's not that I wouldn't like animals like dogs, birds
1414 or fishes, but for me, a cat is *the* animal to have.
1415 [...]
1416 \end{verbatim}
1417 \end{quote}
1418
1419 Please note that you have to add a colon to the keyword to make a
1420 valid RFC mail-header.
1421
1422
1423 \section{The Access Control Language}
1424 \label{acl}
1425
1426 Unfortunately, we live in a world where some people are trying to
1427 abuse services like mailing lists for their entertainment or for
1428 commercial purposes. It is also not uncommon that among thousands of
1429 mailing list subscribers, there is one particular moron who simply
1430 can't behave. That is why access control is a useful feature, even
1431 though it contradicts the idea of a mailing list: To be a media for
1432 communication.
1433
1434 Writing and understanding ACL files is, to be honest, not very easy
1435 and the novice mailing list administrator should better be careful
1436 when using them, because a wrong access control rule might cause more
1437 trouble than it is worth, but the experienced administrator will
1438 certainly appreciate their power. Understanding how ACL files work
1439 will also require you to know a bit about the syntax of an RFC format
1440 e-mail. A good place to start is to take a look at RFC822 and its
1441 sons.
1442
1443 In Petidomo, two places exist to control who is allowed to do what:
1444 The global acl file and the acl file that is local to the mailing
1445 list. While the latter is valid only for the list in which's home
1446 directory it is stored, the globl acl file will be parsed for
1447 \emph{all} your mailing lists. ACL files are only relevant for mailing
1448 list postings, Petidomo does not use them in ``listserv'' mode.
1449
1450 The syntax of an ACL file is similar to the C programming
1451 language, as you can see in the following example:
1452 \begin{quote}
1453 \begin{verbatim}
1454 if (envelope matches "mailer-daemon@") then
1455 forward "petidomo-manager";
1456 \end{verbatim}
1457 \end{quote}
1458
1459 This is a simple version of the default ACL file which comes with the
1460 Petidomo distribution. It tells Petidomo to forward all postings to a
1461 mailing list, where the envelope of the mail matches the regular
1462 expression ``mailer-daemon@''. This rule is included in the default
1463 distribution to make sure that bounces of articles will not be posted
1464 to the list again, thus causing an infinite mail loop. The syntax of
1465 an ACL statement is shown in figure~\ref{acl syntax}.
1466
1467 \begin{figure}[bth]
1468 \begin{center}
1469 \begin{tabular}{cccccccccc}
1470 IF & ( & from & match & {\tt "}regexp{\tt "} & ) & THEN & pass & & ; \\
1471 & & subject & matches & & & & drop & & \\
1472 & & envelope & == & {\tt "}string{\tt "} & & & reject & & \\
1473 & & header & = & & & & rejectwith & {\tt "}file{\tt "} & \\
1474 & & body & & & & & redirect & {\tt "}address{\tt "} & \\
1475 & & & & & & & forward & {\tt "}address{\tt "} & \\
1476 & & & & & & & filter & {\tt "}script{\tt "} & \\
1477 & & & & & & & approve & & \\
1478 IF & ( & & {\tt "}filter{\tt "} & & ) & THEN & & & ; \\
1479 \end{tabular}
1480 \caption{Access Control Language syntax}
1481 \label{acl syntax}
1482 \end{center}
1483 \end{figure}
1484
1485 Admittedly, the figure is rather impossible to understand without
1486 further explaination, don't worry if things are still a bit unclear
1487 after looking at it. There is also an EBNF grammar of the ACL to be
1488 found in figure~\ref{ebnf}, which might help those who can read BNF
1489 much more than the other figure.
1490
1491 \begin{figure}[bth]
1492 \begin{quote}
1493 \begin{verbatim}
1494 input: /* empty */
1495 | input statmt
1496 ;
1497
1498 statmt: `;'
1499 | `if' exp `then' action `;'
1500 ;
1501
1502 exp: qualifier `=' string
1503 | qualifier `match' string
1504 | string
1505 | exp `or' exp
1506 | exp `and' exp
1507 | `!' exp
1508 | `(' exp `)'
1509 ;
1510
1511 qualifier: `from'
1512 | `subject'
1513 | `envelope'
1514 | `header'
1515 | `body'
1516 ;
1517
1518 action: `pass'
1519 | `drop'
1520 | `approve'
1521 | `reject'
1522 | `rejectwith' string
1523 | `redirect' string
1524 | `forward' string
1525 | `filter' string
1526 ;
1527
1528 string: `"' [^"]* `"'
1529 \end{verbatim}
1530 \end{quote}
1531 \caption{EBNF of the Access Control Language}
1532 \label{ebnf}
1533 \end{figure}
1534
1535 Every ACL statement looks like this: ``IF condition THEN action ;''.
1536 The condition may or may not be enclosed in brackets. Several
1537 conditions can be combined with the keywords ``OR'' and ``AND''.
1538 Furthermore every condition can prefaced with a ``NOT'', which will
1539 reverse the outcome of the condition.
1540
1541 Let's explain this all at a concrete example: You want to reject all
1542 postings which come from the addresses ``moron@moron.net'' and
1543 ``spam@spam.net'', because these people have constantly been abusing
1544 your mailing list service. This can be done with the following two
1545 statements:
1546 \begin{quote}
1547 \begin{verbatim}
1548 IF from == "moron@moron.net" THEN reject;
1549 IF from == "spam@spam.net" THEN reject;
1550 \end{verbatim}
1551 \end{quote}
1552
1553 Using the ``OR'' statement you can combine this into one statement:
1554 \begin{quote}
1555 \begin{verbatim}
1556 IF from == "moron@moron.net" OR
1557 from == "spam@spam.net" THEN
1558 reject;
1559 \end{verbatim}
1560 \end{quote}
1561
1562 And now we include brackets for readability:
1563 \begin{quote}
1564 \begin{verbatim}
1565 IF (from == "moron@moron.net") OR
1566 (from == "spam@spam.net") THEN
1567 reject;
1568 \end{verbatim}
1569 \end{quote}
1570
1571 The keyword ``from'' stands for the address, noted in the ``From:''
1572 header line of the mail and, the ``== {\tt "}address{\tt "}'' means
1573 that the condition if this address is equal to the one written in
1574 quotes thereafter. (You can also use a single `=' character, if you
1575 prefer that over two equal-characters.) This is a verbatim match. If
1576 we'd use the ``match'' or ``matches'' keyword instead of the ``=='',
1577 the parameter would be interpreted as an extended regular expression
1578 and the condition would be true if the addresses matched this pattern.
1579 (Regular expressions are described in the re\_format(7) man page, or
1580 in the manpages of sed(1), grep(1) or egrep(1).)
1581
1582 Other keywords than ``from'' for the first part of the conditional are
1583 ``subject'' (the contents of the ``Subject:'' header), ``envelope''
1584 (the envelope of the mail), header and body. The latter two represent
1585 the whole header or body of the mail and should be used only for
1586 regular expression matches and not for verbatim matches.
1587
1588 A short comment on the difference between ``redirect'' and
1589 ``forward'': The ``redirect'' action will send the mail to the
1590 specified address without changing anythin in the mail. All the
1591 headers are left untouched and thus the mail will look as if it has
1592 been sent by the person to that address right away. This is useful for
1593 redirecting mails to daemons or programs, but it will usually confuse
1594 a human recipient
1595
1596 The ``forward'' action, though, will send a mail to the specified
1597 address with a new set of headers, which identify the Petidomo Mailing List Manager as
1598 originator and then it will quote the mail that has been forwarded in
1599 the mail body.
1600
1601 Valid actions are ``pass'' (post the mail immediately), ``drop''
1602 (discard the mail without further notice), ``reject'' (send a mail to
1603 the poster, telling him his posting was rejected), ``rejectwith''
1604 (sending mail to the poster, too, but with the contents of a specified
1605 file), ``redirect'' (redirect the mail to a specified address),
1606 ``forward'' (like ``redirect'' but preface the mail with a note
1607 telling why the mail was re-sent) or ``filter'' (pipe the mail into
1608 the specified filter script and post the mail as the filter writes it
1609 to the standard output). Furthermore, there is the ``approve'' action
1610 that allows you to approve the posting, thus bypassing all other
1611 checks.
1612
1613 Here are a few more examples in the hope that they make this all
1614 easier to understand: Let's assume you would like to catch all
1615 postings to your mailing lists, that contain the words ``MAKE MONEY
1616 FAST'' in the subject. Then one way of doing this is the following
1617 statement:
1618 \begin{quote}
1619 \begin{verbatim}
1620 IF (subejct matches "make money fast") THEN
1621 rejectwith "/usr/local/share/petidomo/make-money-fast.txt";
1622 \end{verbatim}
1623 \end{quote}
1624 The file \file{make-money-fast.txt} could, for example, contain the
1625 following text:
1626 \begin{quote}
1627 \begin{verbatim}
1628 Dear poster,
1629
1630 your mail has been rejected. Please note that chain letters
1631 like the "make money fast" text you tried to post are
1632 illegal throughout the world and your are likely to get in
1633 trouble if you continue to spread them.
1634 \end{verbatim}
1635 \end{quote}
1636
1637 If someone tried to post the chain letter to your mailing lists now,
1638 he would receive a mail like that:
1639 \begin{quote}
1640 \begin{verbatim}
1641 Date: Sat, 28 Jun 1997 19:59:18 +0200 (MET DST)
1642 From: testlist-owner@example.org (Petidomo Mailing List Server)
1643 To: simons@example.org
1644 Cc: testlist-owner@example.org
1645 Subject: Your posting to list "testlist" was rejected
1646 Precedence: junk
1647 Sender: testlist-owner@example.org
1648
1649 Dear poster,
1650
1651 your mail has been rejected. Please note that chain letters
1652 like the ``make money fast'' text you tried to post are
1653 illegal throughout the world and your are likely to get in
1654 trouble if you continue to spread them.
1655
1656 >From simons Sat Jun 28 19:59:17 1997
1657 Received: from [[UNIX: localhost]]
1658 by example.org (8.8.5/8.8.4) id TAA16959
1659 Date: Sat, 28 Jun 1997 19:59:17 +0200 (MET DST)
1660 Message-Id: <199706281759.TAA16959@example.org>
1661 From: Peter Simons <simons@example.org>
1662 To: testlist
1663 Subject: MAKE MONEY FAST
1664 Mime-Version: 1.0 (generated by tm-edit 7.92)
1665 Content-Type: text/plain; charset=US-ASCII
1666
1667 Hi, my name is David Rodes...
1668 \end{verbatim}
1669 \end{quote}
1670
1671 A few more words about how the ACL files are parsed:
1672 \begin{itemize}
1673
1674 \item All comparisons are done case insensitive. ``MAKE MONEY FAST''
1675 matches ``make money fast'' in both the verbatim and the regular
1676 expression match just fine.
1677
1678 \item Any whitespace in the ACL file is ignored. The statements
1679 \begin{quote}
1680 \begin{verbatim}
1681 if (envelope matches "mailer-daemon@") then drop;
1682 \end{verbatim}
1683 \end{quote}
1684 and
1685 \begin{quote}
1686 \begin{verbatim}
1687 if
1688 (envelope matches
1689 "mailer-daemon@")
1690 then
1691 drop
1692 ;
1693 \end{verbatim}
1694 \end{quote}
1695 are the same to Petidomo.
1696
1697 \item The argument after the ``=='' or ``matches'' keyword \emph{has}
1698 to be included in quotes. An ACL statement like this:
1699 \begin{quote}
1700 \begin{verbatim}
1701 if from == simons@computer.org then drop;
1702 \end{verbatim}
1703 \end{quote}
1704 will cause Petidomo to abort with an error, because it can't parse
1705 this.
1706
1707 \item If you use an action that requires a parameter, like
1708 ``rejectwith'' or ``forward'', this parameter has to be enclosed in
1709 quotes, too. A statement like this can also not be parsed by
1710 Petidomo:
1711 \begin{quote}
1712 \begin{verbatim}
1713 if from == "simons@computer.org" then
1714 forward postmaster@example.org;
1715 \end{verbatim}
1716 \end{quote}
1717
1718 \item Petidomo stops parsing the ACL file after the first statement
1719 has matched. If you want to reject all mails from an address that
1720 matches ``simons@.*\.de'', but you want mails from the address
1721 ``simons@rhein.de'' to pass nonetheless, the following two statements
1722 will not work as expected:
1723 \begin{quote}
1724 \begin{verbatim}
1725 if from matches "simons@.*\.de" then reject;
1726 if from == "simons@rhein.de" then pass;
1727 \end{verbatim}
1728 \end{quote}
1729
1730 Instead you should use
1731 \begin{quote}
1732 \begin{verbatim}
1733 if from == "simons@rhein.de" then pass;
1734 if from matches "simons@.*\.de" then reject;
1735 \end{verbatim}
1736 \end{quote}
1737 or
1738 \begin{quote}
1739 \begin{verbatim}
1740 if (from matches "simons@.*\.de") and
1741 (not (from == "simons@rhein.de")) then
1742 reject;
1743 \end{verbatim}
1744 \end{quote}
1745
1746 \item Currently you can't match for the double quote character ({\tt
1747 "}), we're afraid. The escape sequence {\tt \verb+\+"} is not
1748 supported yet.
1749
1750 \end{itemize}
1751
1752 One last example and then we'll come to the filters. The following
1753 statement rejectes a mail based on a match in the headers. This is
1754 very useful for rejecting mail from known spam domains. You usually
1755 can't rely on the spammer to use a valid ``From:'' header and hence
1756 the ``from''-match is useless to catch them. But the following
1757 statement will usually get them nonetheless:
1758 \begin{quote}
1759 \begin{verbatim}
1760 if (header matches "^Received:.*from spam.domain") then
1761 forward "petidomo-manager";
1762 \end{verbatim}
1763 \end{quote}
1764
1765 If you thought, the Access Control Language is powerful so far, take a
1766 look at the things you can do using filters. Rather than the examples
1767 described above, you could use the following statement:
1768 \begin{quote}
1769 \begin{verbatim}
1770 if ("/usr/local/libexec/petidomo/CheckPosting") then reject;
1771 \end{verbatim}
1772 \end{quote}
1773
1774 This is a special form of the usual ACL statements and it means the
1775 following: The mail in question is piped into the ``CheckPosting''
1776 script. The script or program can perform various tests and when it
1777 exists, the action part is executed depending on the return code the
1778 script exited with. A return code of zero (0) means ``true'' and the
1779 action will be executed. A return code of one (1) ``false'' and the
1780 action will not be executed.
1781
1782 Any other return code will cause Petidomo to abort with an error and
1783 to save the mail. By using this mechanism, you can program even the
1784 most sophisticated tests and hook them into the access control
1785 mechanism.
1786
1787 Another feature that hasn't been described yet is the action
1788 ``filter''. The filter-action is pretty much the same as the posting
1789 filter, but it allows you to re-write the posting depending on who
1790 posted it or other criteria. Please note that this filter is executed
1791 additionally to a regular posting filter you might have configured.
1792
1793 A nice example for what this feature can be used is the following:
1794 \begin{quote}
1795 \begin{verbatim}
1796 if (address == "simons@computer.org") then
1797 filter "/usr/local/libexec/petidomo/simons.filter";
1798 \end{verbatim}
1799 \end{quote}
1800
1801 The script \file{simons.filter} would then look like this:
1802 \begin{quote}
1803 \begin{verbatim}
1804 #! /bin/sh
1805
1806 cat
1807 echo
1808 echo "-- "
1809 echo " Hold your breath -- this is *the* Peter Simons!"
1810 \end{verbatim}
1811 \end{quote}
1812
1813 We resisted the temptation of adding this ACL statement into the
1814 default configuration of Petidomo.
1815
1816 % \chapter{Administrating Mailing Lists}
1817 %
1818 \chapter{Miscellaneous Topics}
1819 \section{Using posting filters}
1820 \label{using posting filters}
1821
1822 The posting filter functionality of Petidomo is a very useful
1823 mechanism for you, if you run mailing lists where you want to
1824 guarantee certain formal criteria, because you can hook a script or
1825 program of your into the posting process and use it to re-format or
1826 re-write the article that is going to be posted.
1827
1828 We have included one script into the distribution,
1829 \file{Insert\-Name\-In\-Sub\-ject.sh}, which adds a string into the
1830 subject line of every posting. The script is pretty short and used
1831 sed(1) to perform its function.
1832
1833 To use it, just add the line
1834 \begin{quote}
1835 \begin{verbatim}
1836 PostingFilter ~petidomo/bin/InsertNameInSubject.sh listname
1837 \end{verbatim}
1838 \end{quote}
1839 with ``listname'' being the name of the mailing list.
1840
1841 If the mailing list name was ``testlist'', for example, then this
1842 posting filter would re-write the subject line
1843 \begin{quote}
1844 \begin{verbatim}
1845 Subject: Hi everbody
1846 \end{verbatim}
1847 \end{quote}
1848 to
1849 \begin{quote}
1850 \begin{verbatim}
1851 Subject: [testlist] Hi everbody
1852 \end{verbatim}
1853 \end{quote}
1854
1855 It is recommended to take a look at the script itself to understand
1856 how this works. You will need a bit of knowledge of the Unix scripting
1857 language and tools like sed(1) to program more complex posting filter,
1858 we're afraid.
1859
1860 As the last point it should be made clear, that the string you specify
1861 as a filter is interpreted by the bourne shell for execution. It is
1862 thus absolutely possible, to use a posting filter like that
1863 \begin{quote}
1864 \begin{verbatim}
1865 PostingFilter "/bin/cat | /bin/cat ; echo ; echo testing"
1866 \end{verbatim}
1867 \end{quote}
1868 even though one might argue whether this particular example is a
1869 useful thing. Anyway, you know what we wanted to demonstrate.
1870
1871 \section{PGP-encrypted mailing lists}
1872
1873 Another very useful feature of the posting filter and the access
1874 control languange is the ability to maintain \Def{encrypted mailing
1875 lists}. The idea is very simple: You create a PGP key pair for your
1876 mailing list and spread the public key among the subscribers of your
1877 mailing list. In turn you collect their public keys and store them on
1878 the mailing list server.
1879
1880 Whenever a subscriber wants to post an article to the mailing list, he
1881 will encrypt it with the public key of the list server before
1882 transferring it through the Internet. Petidomo will then receive the
1883 mail, decrypt and process it and encrypt it again, with the public
1884 keys of the subscribers. Once encrypted again, the mail is distributed
1885 to the readers.
1886
1887 Please note that at no time the mail was sent through the Internet in
1888 clear text. Hence this mode is well-suited for maintaining internal
1889 discussion lists for, say, software development among a few people who
1890 know each other but live spread throughout the world. Included in the
1891 distribution are two scripts, \file{pgp-encrypt.sh} and
1892 \file{pgp-decrypt.sh}, which realize this. The setup needs a bit of
1893 work, but once you understand the principle, it is rather easy. Just
1894 follow the steps described below.
1895
1896 \begin{enumerate}
1897
1898 \item Get the PGP software package from `http://www.pgpi.com/', you
1899 will need the PGP 2.6.2 version or later --- 5.x won't work, as far as
1900 I know, maybe someone wants to adapt the PGP-mechanism to PGP 5.x, any
1901 volunteers are welcome, and install it.
1902
1903 \item Log in as user ``petidomo''.
1904
1905 \item Create a directory \file{.pgp} in the home directory of the
1906 users Petidomo runs under and set the {\tt \$PGPPATH} variable to it.
1907
1908 \item Create a PGP key pair by calling `pgp -kg''. As user-id enter
1909 the address of the mailing list itself, for example: ``The secret
1910 mailing list $<$secretlist@example.org$>$''.
1911
1912 \item Create a \file{config.txt} file for PGP in the \file{.pgp}
1913 directory and insert the appropriate user id there.
1914
1915 \item Distribute the newly created PGP key of the mailing list among
1916 the subscribers.
1917
1918 \item Add the PGP keys of the subscribers to Petidomo's keyring.
1919
1920 \item Edit the following definitions in \file{pgp-encrypt.sh}:
1921
1922 \begin{quote}
1923 \begin{verbatim}
1924 #
1925 # Please customize these things for your system.
1926 #
1927 PGP=/usr/local/bin/pgp
1928 PASSWORD="DecryptMe"
1929 PGPPATH=$PDHOME/.pgp
1930 \end{verbatim}
1931 \end{quote}
1932
1933 You will need to change the location of the PGP binary and insert the
1934 password you chose for the secret key. For security reasons, the
1935 script itself should be owned by ``petidomo'' as user- and group id,
1936 and it should have the permission ``110'', so that only Petidomo can
1937 execute it.
1938
1939 \item Edit the equivalent definitions in \file{pgp-encrypt.sh}.
1940
1941 \item Now create the mailing list in question. In our example that
1942 would be ``secretlist''. Naturally the mailing list should not be open
1943 for public subscription.
1944
1945 \item Edit the ACL file of the ``secretlist'' to contain the following
1946 line:
1947
1948 \begin{quote}
1949 \begin{verbatim}
1950 if (body matches "^-----BEGIN PGP MESSAGE-----$") then
1951 filter "~petidomo/bin/pgp-decrypt.sh";
1952 \end{verbatim}
1953 \end{quote}
1954
1955 \item Edit the config file to have the following posting filter:
1956
1957 \begin{quote}
1958 \begin{verbatim}
1959 PostingFilter "~petidomo/bin/pgp-encrypt.sh secretlist"
1960 \end{verbatim}
1961 \end{quote}
1962
1963 Please note that you must provide the name of the mailing list on the
1964 command line as parameter to \file{pgp-encrypt.sh}, so that it know
1965 which list file it should take the subscriber addresses from.
1966
1967 \item Do a test posting and that's it.
1968
1969 \end{enumerate}
1970
1971 There are a few things you should take care of: First of all, you must
1972 make sure that you have the PGP public keys of all subscribers in the
1973 keyring belonging to the ``petidomo'' user, or some of them won't be
1974 able to decipher the mail posted via the list. You must also take care
1975 that the addresses these people are subscribed under, are actually
1976 listed in their public key, or PGP won't be able to recognize who is
1977 who, when being called by \file{pgp-encrypt.sh}.
1978
1979 Finally, make sure that you do this only with the correct versions of
1980 the software. Petidomo needs to be version 2.1 or later, earlier
1981 versions won't work. The PGP binary needs to understand the {\tt -@}
1982 operator on the command line, which has been added in PGP 2.6i at some
1983 time.
1984
1985 One last hint: If PGP-encryption or decryption doesn't work, it will
1986 usually help to remove the {\tt \$LOGFILE} parameter from the {\tt
1987 trap} command in the scripts:
1988
1989 \begin{quote}
1990 \begin{verbatim}
1991 trap 'rm -f $TMPFILE $HEADER $BODY $NEWBODY $LOGFILE; exit'...
1992 ^^^^^^^^
1993 \end{verbatim}
1994 \end{quote}
1995
1996 As a result, the script won't delete the output PGP issued when called
1997 after exiting. Thus you will find the file still lying in \file{/tmp}
1998 and can easily investigate what's wrong.
1999
2000 \section{Virtual hosting and sendmail}
2001 \label{virtual hosting and sendmail}
2002
2003 A very useful things is Petidomo's virtual hosting feature.
2004 Unfortunately, there are a few traps into which you might run when you
2005 are trying to use it together with the Allmann sendmail. But we'll
2006 start at the beginning.
2007
2008 If you host mailing lists for domains other than your own, you can
2009 tell Petidomo to use this name instead of the local one for certain
2010 mailing lists in the list config file by setting the appropriate
2011 ``HostName''. Now all mail posted to this list, or sent to the
2012 ``-request'' address of the list, will appear to be coming from the
2013 domain name you configured, rather than your own.
2014
2015 When you are using sendmail v8, you will have to write these names to
2016 the \$w\$ class in your sendmail.cf file, or the corresponfing M4
2017 config. This is done by adding the line
2018 \begin{quote}
2019 \begin{verbatim}
2020 Cwdomain.name1 domain.name2 ...
2021 \end{verbatim}
2022 \end{quote}
2023 to the file.
2024
2025 This will tell sendmail that these names are to be accepted and
2026 delivered locally rather than to the MX of these entries.
2027
2028 Doing this might deliver a surprise, though, if you are using
2029 sendmail's masquerading abilities to hide the various hostname of your
2030 domain. Per default, sendmail masquerades not only the domain names
2031 you told him with the MASQUERADE\_DOMAIN() command, it automatically
2032 masquerades all domain names of the \$w\$ class, too.
2033
2034 The result is that Petidomo's fine virtual hosting is gone
2035 immediately, because sendmail will re-write the name to your own
2036 domain name. The fix for this is rather easy: Add the command
2037 ``FEATURE(limited\_masquerade)'' to your M4 file and sendmail won't
2038 touch the names that are stated only in the \$w\$ class.
2039
2040 \section{Mailing list archives}
2041 \label{mailing list archives}
2042
2043 If your are hosting a public mailing list, you might want to offer a
2044 mailing list archive, that is accessible through the WWW and has all
2045 the postings available for immediate access. We were in the midst of
2046 developing a tool that does this for you when we came accross a
2047 brilliant tool named ``MHonArc''. We installed it, tested it, and
2048 deleted all attempts of writing something like that ourselves
2049 immediately.
2050
2051 We strongly recommend looking at MHonArc, if you want to offer a WWW
2052 archive of your mailing lists. You can find more information about
2053 MHonArc at the following location:
2054 `http://www.oac.uci.edu/indiv/ehood/mhonarc.html'
2055
2056 The installation of the tool itself is very easy. Once you have
2057 MHonArc running, just enable the archiving feature in Petidomo and
2058 feed the archives into MHonArc. That's it.
2059
2060 \section{Verifying the address lists}
2061
2062 Petidomo tries its best to make sure that only syntactically correct
2063 addresses are subscribed to mailing lists, and if you stick to the
2064 correct mail interface, there's very little chance, an incorrect
2065 address will make it into the \file{list} file.
2066
2067 Sometimes, it is necessary to edit these files manually, though, or
2068 Petidomo's address validation algorithm fails. Once you have an
2069 incorrect address in your list file, sendmail will abort with an
2070 error, without trying to deliver the mail at all.
2071
2072 To clarify, this does not happen when an address is not reachable,
2073 this happens only when you subscribe something like {\tt
2074 hey@this@is@wrong....}. Once you suspect that your address list has
2075 been corrupted, there's an easy way to find out, which addresses are
2076 wrong. Simply use sendmail's address verification mode like this:
2077
2078 \begin{quote}
2079 \begin{verbatim}
2080 $ xargs <list sendmail -bv | sed -e '/deliverable/d'
2081 > @bogus.address.here... user address required
2082 \end{verbatim}
2083 \end{quote}
2084
2085 This call will find all incorrect address and notify you. The 'sed'
2086 call will filter out all correct addresses for your convenience.
2087
2088 \end{document}