Merged subject prefix patch from Christine Spang.
[eoc.git] / enemies-of-carlotta.1
3 enemies\-of\-carlotta \- a simple mailing list manager
5 .B enemies\-of\-carlotta 
6 .IR "" [ options "] [" addresses ]
8 .B enemies\-of\-carlotta
9 is a simple mailing list manager.
10 If you don't know what a mailing list manager is, you should learn
11 what they are before trying to use one.
12 A manual page is unfortunately too short to explain it.
13 .PP
14 Enemies of Carlotta keeps all data about the lists in the
15 .I ~/.enemies\-of\-carlotta
16 directory.
17 It will be created automatically when you create your first list.
18 You need to arrange manually for the mails to be processed by the
19 list manager.
20 The details differ from mail system to another.
21 For QMail and Postfix, see below.
22 .PP
23 Each list has one or more owners, who also moderate subscriptions or
24 moderate some or all postings.
25 On completely unmoderated lists the list owners are responsible for
26 answering questions about the list.
27 On completely moderated lists, they have to approve each message before
28 it is sent to the list.
29 On lists with 
30 .IR posting=auto ,
31 messages from subscribers are sent automatically to the list, and the
32 moderators have to approve the rest.
34 .TP
35 .BR \-\-name=
36 Specify the list the command is to operate on.
37 Most of the remaining options require you to set the list name with this
38 option.
39 With the \-\-edit, \-\-subscribe, \-\-unsubscribe, and \-\-list options,
40 the name can be abbreviated to by leaving out the @ sign and domain.
41 .TP
42 .BI \-\-create
43 Create a new list.
44 You must specify at least one owner with
45 .BR \-\-owner .
46 .TP
47 .BI \-\-owner= address
48 Specify a list owner when creating or editing a list.
49 .TP
50 .BI \-\-moderator= address
51 Specificy a list moderator when creating or editing a list.
52 .TP
53 .BI \-\-language= language\-code
54 Set the language code used for looking up template files.
55 The code should be empty (the default, meaning English), or a two\-letter
56 code such as 
57 .B fi
58 or
59 .BR es .
60 .TP
61 .B \-\-cleaning\-woman
62 Deal with bouncing addresses and do other cleanup.
63 You must run
64 .B "enemies\-of\-carlotta \-\-cleaning\-woman"
65 periodically, such as once per hour.
66 It will clean up all your lists.
67 .TP
68 .BI \-\-destroy
69 Destroy the list.
70 .TP
71 .BI \-\-edit
72 Modify the list configuration.
73 .TP
74 .BI \-\-subscription= type
75 When creating a list, set its subscription mode to
76 .I free
77 or
78 .IR moderated .
79 Use with
80 .BR \-\-edit ,
81 or
82 .BR \-\-create .
83 .TP
84 .BI \-\-posting= type
85 When creating a list, set its posting mode to
86 .IR free 
87 (anyone can post),
88 .IR auto
89 (only subscribers can post, mails from others need to be moderated),
90 or
91 .IR moderated 
92 (all mails are moderated).
93 Use with
94 .BR \-\-edit ,
95 or
96 .BR \-\-create .
97 .TP
98 .BI \-\-archived= yes\-or\-no
99 Should list messages be archived to the
100 .B archive\-box
101 directory in the list directory under the
102 .B "~/.enemies\-of\-carlotta"
103 directory.
104 Use
105 .I yes
106 or
107 .IR no .
108 .TP
109 .BI \-\-mail\-on\-subscription\-changes= yes\-or\-no
110 Should the list owners be notified when someone subscribes to or
111 unsubscribes from the list?
112 Use
113 .I yes
114 or
115 .IR no .
116 Default is no.
117 .TP
118 .BI \-\-mail\-on\-forced\-unsubscription= yes\-or\-no
119 Should list owners be notified when someone is forcibly dropped from
120 the list due to too much bouncing?
121 Use
122 .I yes
123 or
124 .IR no .
125 Default is no.
126 .TP
127 .BI \-\-ignore\-bounce= yes\-or\-no
128 Should bounces be ignored?
129 Use
130 .I yes
131 or
132 .IR no .
133 Default is no.
134 .TP
135 .BI \-\-list
136 List the subscribers of a list.
137 .TP
138 .BI \-\-subscribe
139 Add subscribers to a list.
140 The non\-option arguments are the addresses to be subscribed.
141 Note that addresses added this way won't be sent confirmation requests.
142 .TP
143 .BI \-\-unsubscribe
144 Remove subscribers from a list.
145 The non\-option arguments are the addresses to be unsubscribed.
146 Note that addresses removed this way won't be sent confirmation requests.
147 .TP
148 .B \-\-incoming
149 Deal with an incoming message in the standard input.
150 The SMTP envelope sender address must be given in the 
152 environment variable, and the SMTP envelope recipient address in the
154 environment variable.
155 (QMail and Postfix do this automatically.)
156 .TP
157 .BI \-\-skip\-prefix= string
158 Before analyzing the recipient address to see which list it refers, remove 
159 .I string
160 from its beginning.
161 This helps deal with QMail and Postfix virtual domains, see above.
162 .TP
163 .BI \-\-domain=
164 Before analyzing the recipient address to see which list it refers, replace
165 the domain name part with
166 .IR .
167 This helps deal with Postfix virtual domains.
168 .TP
169 .BI \-\-is\-list
170 Does the address specified with
171 .B \-\-name
172 refer to a valid list?
173 This sets the exit code to zero (success) if it does, or one (failure)
174 if it does not.
175 .TP
176 .BI \-\-sendmail= pathname
177 Use 
178 .I pathname
179 instead of
180 .B /usr/sbin/sendmail
181 for sending mail via a command line interface.
182 Note that the command must obey the sendmail command line interface.
183 .TP
184 .BI \-\-smtp\-server= hostname
185 Send mail using the SMTP server at
186 .I hostname
187 (port 25).
188 The server must be configured to allow the list host to relay mail
189 through it.
190 Note that a command line interface is used by default;
191 SMTP sending is used only if you use this option.
192 .TP
193 .BI \-\-qmqp\-server= hostname
194 Send mail using the QMQP server at
195 .I hostname
196 (port 628).
197 The server must be configured to allow the list host to relay mail
198 through it.
199 Note that a command line interface is used by default;
200 QMQP sending is used only if you use this option.
201 .TP
202 .BI \-\-moderate
203 Force an incoming message to be moderated, even if it is going to a list
204 where posting is free.
205 This can be used for spam filtering: 
206 you pipe incoming messages through whatever spam filter you choose to use
207 and if the mssage looks like spam, you ask it to be moderated by a human.
208 .TP
209 .BI \-\-post
210 Force an incoming message to be posted, even if it is going to a list
211 where posting is moderated.
212 This can be used when there is an external check for whether a mail
213 is acceptable to the list, e.g., by checking digital signatures.
214 .TP
215 .BI \-\-quiet
216 By default, debugging log messages are sent to the standard error output
217 stream.
218 With this option, they aren't.
219 .TP
220 .BI \-\-sender=
221 .TP
222 .BI \-\-recipient=
223 These two options are used with 
224 .B \-\-incoming 
225 and
226 .B \-\-is\-list
227 to override the environment variables 
229 and
231 respectively.
232 .TP
233 .BI \-\-get
234 Get the values of one or more configuration variables.
235 The name of the variables are given on the command line after the options.
236 Each value is printed on a separate line.
237 .TP
238 .BI \-\-set 
239 Set the values of one or more configuration variables.
240 The names and values are given on the command line after the options
241 and separated by an equals sign ("=").
242 For example, the following would set the language of a list to Finnish:
243 .B "enemies\-of\-carlotta \-\-name=foo@bar \-\-set language=fi"
244 .TP
245 .BI \-\-version
246 Print out the version of the program.
247 .TP
248 .BI \-\-show\-lists
249 List the lists enemies\-of\-carlotta knows about.
251 Each list is represented by a directory, named after the list, in 
252 .IR ~/.enemies\-of\-carlotta .
253 That directory contains several files and directories, described below.
254 In general, it is not necessary to touch these at all.
255 However, some esoteric configuration can only be done by hand editing
256 of the list configuration file.
257 .TP
258 .B config
259 The list configuration file.
260 Contents are described below.
261 .TP
262 .B subscribers
263 Subscriber database.
264 Each line contains a subscriber group, with the first five space 
265 delimited fields being group identifier, status, timestamp for when
266 the group was created, timestamp for the bounce that made it switch
267 from status 'ok' to 'bounced', and the bounce identifier.
268 .TP
269 .B archive\-box
270 Archived messages.
271 .TP
272 .B bounce\-box
273 Bounce messages groups not in state 'ok'.
274 .TP
275 .B headers\-to\-add
276 These headers are added to the mails sent to the list.
277 They are copied to the beginning of the existing headers exactly as they
278 are in the file, after list headers ("List\-ID" and such) have been added
279 and those mentioned in 
280 .B headers\-to\-remove
281 have been removed.
282 .TP
283 .B headers\-to\-remove
284 These headers are removed from mails sent to the list.
285 .TP
286 .B moderation\-box
287 Messages waiting for moderator approval.
288 .TP
289 .B subscription\-box
290 Subscription and unsubscription requests waiting to be confirmed by the user.
291 .TP
292 .B templates
293 Directory containing list specific templates (optional). If this
294 directory exists, templates are searched from it before going for
295 system wide templates. An empty file here means the
296 corresponding message is not sent at all. This can, for example, to
297 be used to turn off the "please wait for moderator" mails on a per\-list
298 basis.
299 .TP
300 .B plugins
301 Directory containing plugins, Python source files that are loaded 
302 automatically by EoC upon startup.
303 The plugins may change how EoC operates.
304 .PP
305 The 
306 .B config
307 file has a 
308 .IR keyword = value
309 format:
310 .PP
311 .RS
312 .nf
313 [list]
314 owners =
315 archived = no
316 posting = free
317 subscription = free
318 mail\-on\-subscription\-changes = yes
319 mail\-on\-forced\-unsubscribe = yes
320 language = fi
321 .fi
322 .RE
323 .PP
324 The keywords 
325 .BR archived , 
326 .BR posting ,
327 and
328 .B subscription 
329 correspond to the options with the same names.
330 Other keywords are:
331 .TP
332 .B owners
333 List of addresses for the owners. Set with the
334 .I \-\-owner
335 option.
336 .TP
337 .B moderators
338 List of addresses for the moderators. Set with the
339 .I \-\-moderator
340 option.
341 .TP
342 .B mail\-on\-subscription\-changes
343 Should the owners be mailed when users subscribe or unsubscribe?
344 .TP
345 .B mail\-on\-forced\-unsubscribe
346 Should the owners be mailed when people are removed from the list due to
347 excessive bouncing?
348 .TP
349 .B ignore_bounce
350 Bounce messages are ignored on this list. Useful for example if
351 list should have static subscriber list.
352 .TP
353 .B language
354 Suffix for templates, to allow support for multiple languages.
355 (If 
356 .I language
357 is set to "fi", then the template named "foo" is first searched as
358 "".)
359 .TP
360 .B pristine\-headers
361 Do not MIME encode the headers. Set to "yes" to not encode, anything
362 else (including empty or unset) means encoding will happen.
363 .TP
364 .B subject\-prefix
365 A string to prepend to the "Subject" header of mails sent to this
366 list, such as "[list\-name]". The prefix will not be added to
367 subjects which already contain the prefix string.
369 To create a list called 
370 .IR ,
371 owned by
372 .IR ,
373 use the following command (all on one line):
374 .sp 1
375 .nf
376 .RS
377 enemies\-of\-carlotta \-\
378 \-\ \-\-create
379 .RE
380 .fi
381 .PP
382 Note that you need to arrange mail to arrive at the list (and its
383 command addresses) by configuring your mail system.
384 For Qmail and Postfix, see below.
385 .PP
386 To see the subscribers on that list:
387 .sp 1
388 .nf
389 .RS
390 enemies\-of\-carlotta \-\ \-\-list
391 .RE
392 .fi
393 .PP
394 People wanting to subscribe to the list should mail
395 .sp 1
396 .nf
397 .RS
398 moviefans\
399 .RE
400 .fi
402 With QMail, to arrange for incoming mail to be processed by Enemies of
403 Carlotta, you need to create a couple of
404 .I .qmail\-extension
405 files per list.
406 For example, if your username is joe and you wish to run the
407 joe\-fans mailing list, you need to create two files,
408 .I .qmail\-fans
409 and
410 .IR .qmail\-fans\-default ,
411 containing
412 .sp 1
413 .RS
414 |enemies\-of\-carlotta \-\-incoming
415 .RE
416 .PP
417 If you're running a virtual domain,, and the mails are
418 being delivered to via 
419 .I /var/qmail/control/virtualdomains
420 to
421 .IR joe\-exampledotcom ,
422 the files would be called
423 .I .qmail\-exampledotcom\-fans
424 and
425 .I .qmail\-exampledotcom\-fans\-default
426 and would contain
427 .sp 1
428 .RS
429 |enemies\-of\-carlotta \-\-incoming \-\-skip\-prefix=joe\-exampledotcom\-
430 .RE
431 .sp 1
432 (all on one line, of course, in case the manual page formatter breaks it
433 on several lines).
435 For Courier-MTA, the instructions are similar to the Qmail ones above.
436 If your user name is joe and you wish to run the joe-fans email list,
437 you need to create the two files .courier-fans and .courier-fans-default
438 in your home directory with the content
439 .sp 1
440 .RS
441 |enemies-of-carlotta --is-list --name $RECIPIENT || exit 67
442 .br
443 |enemies-of-carlotta --incoming
444 .RE
445 .sp 1
446 (The former file needs only the second line, but the first line does no
447 harm and it is easier to keep track of things when the files have the
448 same content.  Note that $RECIPIENT should be included verbatim, it is
449 not a metavariable for you to expand.)
450 .PP
451 If you are running a virtual domain configured so that all mail to the
452 domain is delivered to joe-exampledotcom, you need to
453 create the files .courier-exampledotcom-fans and
454 .courier-exampledotcom-fans-default containing the two following lines:
455 .sp 1
456 .RS
457 |enemies-of-carlotta --is-list --name $RECIPIENT --skip-prefix=joe-exampledotcom || exit 67
458 .br
459 |enemies-of-carlotta --incoming --skip-prefix=joe-exampledotcom
460 .RE
461 .sp 1
462 If the virtual domain is for list use only, then it is sufficient to
463 create only the file .courier-exampledotcom-default containing the
464 latter two lines.
466 With Postfix, you need to set up a
467 .I .forward
468 file containing
469 .sp 1
470 .RS
471 "|procmail \-p"
472 .RE
473 .sp 1
474 and then a
475 .I .procmailrc
476 file containing
477 .sp 1
478 .RS
479 :0
480 .br
481 * ? enemies\-of\-carlotta \-\-name=$RECIPIENT \-\-is\-list
482 .br
483 | enemies\-of\-carlotta \-\-incoming
484 .RE
485 .PP
486 To use Enemies of Carlotta with a Postfix virtual domain, you need to
487 set up a 
488 .IR "virtual regular expression map" ,
489 typically called
490 .I /etc/postfix/virtual_regexp
491 (add 
492 .I "virtual_maps = regexp:/etc/postfix/virtual_regexp"
493 to your 
494 .I /etc/postfix/
495 file to enable it).
496 The regexp file needs to do ugly things to preserve the recipient
497 address.
498 Add the following to the regexp file:
499 .sp 1
500 .RS
501 /^your\.virtual\.domain$/ dummy
502 .br
503 /^(yourlist|yourlist\-.*)@(your\.virtual\.domain)$/ joe+virtual\-$1
504 .RE
505 .sp 1
506 That's two lines. Use
507 .B joe-virtual
508 instead, if
509 .I recipient_delimiter
510 for your Postfix is configured to a minus instead of a plus..
511 Then, in your
512 .I .procmailrc
513 file, add the
514 .I "\-\-skip\-prefix=joe\-virtual\-"
515 and 
516 .I \-\-domain=your.virtual.domain
517 options to both calls to 
518 .BR enemies\-of\-carlotta .
519 .PP
520 (Yes, I think these things are much too complicated, too.)
522 Users and list owners use Enemies of Carlotta via e\-mail using
523 command addresses such as
524 .BR foo\ .
525 Here is a list of all command addresses list users and owners can give.
526 In all these examples, the name of the mailing list is
527 .BR .
528 .SS "Mail commands anyone can use"
529 These commands are meant for everyone's use.
530 They don't require any special priviledges.
531 .TP
532 .BR
533 Send mail to all list subscribers.
534 The message may have to be manually approved by the list moderators first,
535 and they have the power to reject a message.
536 .TP
537 .BR foo\
538 Send mail to the list owner or owners instead.
539 .TP
540 .BR foo\
541 Sending mail to this address makes the list manager reply with
542 the help message for the list.
543 .TP
544 .BR foo\
545 Send mail to this address to subscribe to a list.
546 The list manager will respond with a confirmation request.
547 You won't be subscribed unless you reply to the confirmation request.
548 This way, malicious people can't put your address on a mailing list,
549 or many mailing lists.
550 .TP
551 .BR foo\-subscribe\
552 This is a second form of the subscription address.
553 If you want to subscribe to the list with another address than the
554 one you're sending mail from, use this one.
555 In this case, the address to be subscribed is
556 Note that the confirmation request is sent to Joe, since it is
557 his address that is to be added to the list.
558 .TP
559 .BR foo\
560 To unsubscribe from a list, send mail to this address from the address
561 that is subscribed to the list.
562 Again, you will receive a confirmation request, to prevent malicious
563 people from unsubscribing you against your will.
564 .TP
565 .BR foo\-unsubscribe\
566 To unsubscribe Joe, use this address.
567 Again, it is Joe who gets to confirm.
568 .SS "Mail commands for the list owners"
569 These are commands that list owners can use to administer their list.
570 .TP
571 .BR foo\-subscribe\
572 If a list owner sends mail like this, it is they who get the confirmation
573 request, not Joe.
574 It is generally better for people to subscribe themselves, but sometimes
575 list owners want to do it, when they have permission from the person
576 and feel helpful.
577 .TP
578 .BR foo\-unsubscribe\
579 List owners can also unsubscribe other people.
580 .TP
581 .BR foo\
582 To see who are on the list, this is the address to use.
583 It only works if the sender address is one of the list owners.
584 The sender address is the one used on the SMTP level,
585 not the one in the From: header.
586 .TP
587 .BR foo\
588 This lets a list owner set the whole subscriber list at once.
589 This is similar to using lots and lots and lots of \-subscribe and
590 \-unsubscribe commands, only less painful.
591 Everyone who is added to the list gets a welcome message, and
592 everyone who is removed from the list gets a goodbye message.
593 .TP
594 .BR foo\
595 This is similar to \-setlist, but no welcome and goodbye messages are sent.
597 Enemies of Carlotta supports plugins.
598 If you don't know what Python programming is, you may want to skip this
599 section.
600 .PP
601 A plugin is a Python module (file named with a 
602 .B .py
603 suffix), placed in the
604 .B ~/.enemies\-of\-carlotta/plugins
605 directory.
606 The plugins are loaded automatically upon startup, if their declared
607 interface version matches the one implemented by Enemies of Carlotta.
608 The interface version is declared by the module global variable
610 .PP
611 Plugins can define hook functions that are called by appropriate places in
612 the EoC code.
613 At the moment, the only hook function is 
614 .BR send_mail_to_subscribers_hook ,
615 which can manipulate a mail message before it is sent to the subscribers.
616 The function must look like this:
617 .PP
618 .ti +5
619 def send_mail_to_subscribers_hook(list, text):
620 .PP
621 The
622 .I list
623 argument is a reference to the
624 .I MailingList
625 object that corresponds to the list in question, and 
626 .I text
627 is the complete text of the mail message as it exists.
628 The function must return the new contents of the mail message.
630 .TP
631 .I ~/.enemies\-of\-carlotta
632 All files related to your mailing lists.
633 .TP
634 .I ~/.enemies\-of\-carlotta/secret
635 Secret password used to generate signed addresses for bounce checking
636 and subscription verification.
637 .TP
638 .I ~/.enemies\-of\-carlotta/
639 Directory containing data pertaining to the list.
640 Except for the 
641 .I config
642 file in this directory, you shouldn't edit anything by hand.
643 .TP
644 .I ~/.enemies\-of\-carlotta/
645 Configuration file for the mailing list.
646 You may need to edit this file by hand if you wish to change moderation
647 status or list owners.
648 .SH "SEE ALSO"
649 You may want to visit the 
650 .I "Enemies of Carlotta"
651 home page at
652 .IR .