1 .TH 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.
14 Enemies of Carlotta keeps all data about the lists in the
15 .I ~/.enemies\-of\-carlotta
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
20 The details differ from mail system to another.
21 For QMail and Postfix, see below.
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.
31 messages from subscribers are sent automatically to the list, and the
32 moderators have to approve the rest.
35 .BR \-\-name= foo@example.com
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
39 With the \-\-edit, \-\-subscribe, \-\-unsubscribe, and \-\-list options,
40 the name can be abbreviated to by leaving out the @ sign and domain.
44 You must specify at least one owner with
47 .BI \-\-owner= address
48 Specify a list owner when creating or editing a list.
50 .BI \-\-moderator= address
51 Specificy a list moderator when creating or editing a list.
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
61 .B \-\-cleaning\-woman
62 Deal with bouncing addresses and do other cleanup.
64 .B "enemies\-of\-carlotta \-\-cleaning\-woman"
65 periodically, such as once per hour.
66 It will clean up all your lists.
72 Modify the list configuration.
74 .BI \-\-subscription= type
75 When creating a list, set its subscription mode to
85 When creating a list, set its posting mode to
95 .BI \-\-archived= yes\-or\-no
96 Should list messages be archived to the
98 directory in the list directory under the
99 .B "~/.enemies\-of\-carlotta"
106 .BI \-\-mail\-on\-subscription\-changes= yes\-or\-no
107 Should the list owners be notified when someone subscribes to or
108 unsubscribes from the list?
115 .BI \-\-mail\-on\-forced\-unsubscription= yes\-or\-no
116 Should list owners be notified when someone is forcibly dropped from
117 the list due to too much bouncing?
124 .BI \-\-ignore\-bounce= yes\-or\-no
125 Should bounces be ignored?
133 List the subscribers of a list.
136 Add subscribers to a list.
137 The non\-option arguments are the addresses to be subscribed.
138 Note that addresses added this way won't be sent confirmation requests.
141 Remove subscribers from a list.
142 The non\-option arguments are the addresses to be unsubscribed.
143 Note that addresses removed this way won't be sent confirmation requests.
146 Deal with an incoming message in the standard input.
147 The SMTP envelope sender address must be given in the
149 environment variable, and the SMTP envelope recipient address in the
151 environment variable.
152 (QMail and Postfix do this automatically.)
154 .BI \-\-skip\-prefix= string
155 Before analyzing the recipient address to see which list it refers, remove
158 This helps deal with QMail and Postfix virtual domains, see above.
160 .BI \-\-domain= domain.name
161 Before analyzing the recipient address to see which list it refers, replace
162 the domain name part with
164 This helps deal with Postfix virtual domains.
167 Does the address specified with
169 refer to a valid list?
170 This sets the exit code to zero (success) if it does, or one (failure)
173 .BI \-\-sendmail= pathname
177 .B /usr/sbin/sendmail
178 for sending mail via a command line interface.
179 Note that the command must obey the sendmail command line interface.
181 .BI \-\-smtp\-server= hostname
182 Send mail using the SMTP server at
185 The server must be configured to allow the list host to relay mail
187 Note that a command line interface is used by default;
188 SMTP sending is used only if you use this option.
190 .BI \-\-qmqp\-server= hostname
191 Send mail using the QMQP server at
194 The server must be configured to allow the list host to relay mail
196 Note that a command line interface is used by default;
197 QMQP sending is used only if you use this option.
200 Force an incoming message to be moderated, even if it is going to a list
201 where posting is free.
202 This can be used for spam filtering:
203 you pipe incoming messages through whatever spam filter you choose to use
204 and if the mssage looks like spam, you ask it to be moderated by a human.
207 Force an incoming message to be posted, even if it is going to a list
208 where posting is moderated.
209 This can be used when there is an external check for whether a mail
210 is acceptable to the list, e.g., by checking digital signatures.
213 By default, debugging log messages are sent to the standard error output
215 With this option, they aren't.
217 .BI \-\-sender= foo@example.com
219 .BI \-\-recipient= foo@example.com
220 These two options are used with
224 to override the environment variables
231 Get the values of one or more configuration variables.
232 The name of the variables are given on the command line after the options.
233 Each value is printed on a separate line.
236 Set the values of one or more configuration variables.
237 The names and values are given on the command line after the options
238 and separated by an equals sign ("=").
239 For example, the following would set the language of a list to Finnish:
240 .B "enemies\-of\-carlotta \-\-name=foo@bar \-\-set language=fi"
243 Print out the version of the program.
246 List the lists enemies\-of\-carlotta knows about.
248 Each list is represented by a directory, named after the list, in
249 .IR ~/.enemies\-of\-carlotta .
250 That directory contains several files and directories, described below.
251 In general, it is not necessary to touch these at all.
252 However, some esoteric configuration can only be done by hand editing
253 of the list configuration file.
256 The list configuration file.
257 Contents are described below.
261 Each line contains a subscriber group, with the first five space
262 delimited fields being group identifier, status, timestamp for when
263 the group was created, timestamp for the bounce that made it switch
264 from status 'ok' to 'bounced', and the bounce identifier.
270 Bounce messages groups not in state 'ok'.
273 These headers are added to the mails sent to the list.
274 They are copied to the beginning of the existing headers exactly as they
275 are in the file, after list headers ("List\-ID" and such) have been added
276 and those mentioned in
277 .B headers\-to\-remove
280 .B headers\-to\-remove
281 These headers are removed from mails sent to the list.
284 Messages waiting for moderator approval.
287 Subscription and unsubscription requests waiting to be confirmed by the user.
290 Directory containing list spesific templates (optional). If this
291 directory exists, templates are searched from it before going for
292 system wide templates. An empty file here means the corresponding
293 corresponding message is not sent at all. This can, for example, to
294 be used to turn off the "please wait for moderator" mails on a per\-list
298 Directory containing plugins, Python source files that are loaded
299 automatically by EoC upon startup.
300 The plugins may change how EoC operates.
311 owners = liw@liw.iki.fi
315 mail\-on\-subscription\-changes = yes
316 mail\-on\-forced\-unsubscribe = yes
326 correspond to the options with the same names.
330 List of addresses for the owners. Set with the
335 List of addresses for the moderators. Set with the
339 .B mail\-on\-subscription\-changes
340 Should the owners be mailed when users subscribe or unsubscribe?
342 .B mail\-on\-forced\-unsubscribe
343 Should the owners be mailed when people are removed from the list due to
347 Bounce messages are ignored on this list. Useful for example if
348 list should have static subscriber list.
351 Suffix for templates, to allow support for multiple languages.
354 is set to "fi", then the template named "foo" is first searched as
358 Do not MIME encode the headers. Set to "yes" to not encode, anything
359 else (including empty or unset) means encoding will happen.
361 To create a list called
362 .IR moviefans@example.com ,
364 .IR ding@example.com ,
365 use the following command (all on one line):
369 enemies\-of\-carlotta \-\-name=moviefans@example.com
370 \-\-owner=ding@example.com \-\-create
373 Note that you need to arrange mail to arrive at the list (and its
374 command addresses) by configuring your mail system.
375 For Qmail and Postfix, see below.
377 To see the subscribers on that list:
380 enemies\-of\-carlotta \-\-name=moviefans@example.com \-\-list
383 People wanting to subscribe to the list should mail
386 moviefans\-subscribe@example.com
389 With QMail, to arrange for incoming mail to be processed by Enemies of
390 Carlotta, you need to create a couple of
393 For example, if your username is joe and you wish to run the
394 joe\-fans mailing list, you need to create two files,
397 .IR .qmail\-fans\-default ,
401 |enemies\-of\-carlotta \-\-incoming
404 If you're running a virtual domain, example.com, and the mails are
405 being delivered to via
406 .I /var/qmail/control/virtualdomains to joe\-exampledotcom, the
407 files would be called
408 .I .qmail\-exampledotcom\-fans
410 .I .qmail\-exampledotcom\-fans\-default
414 |enemies\-of\-carlotta \-\-incoming \-\-skip\-prefix=joe\-exampledotcom\-
417 (all on one line, of course, in case the manual page formatter breaks it
420 With Postfix, you need to set up a
435 * ? enemies\-of\-carlotta \-\-name=$RECIPIENT \-\-is\-list
437 | enemies\-of\-carlotta \-\-incoming
440 To use Enemies of Carlotta with a Postfix virtual domain, you need to
442 .I "virtual regular expression map,"
444 .I /etc/postfix/virtual_regexp
446 .I "virtual_maps = regexp:/etc/postfix/virtual_regexp"
448 .I /etc/postfix/main.cf
450 The regexp file needs to do ugly things to preserve the recipient
452 Add the following to the regexp file:
455 /^your\.virtual\.domain$/ dummy
457 /^(yourlist|yourlist\-.*)@(your\.virtual\.domain)$/ joe+virtual\-$1
460 That's two lines. Use
463 .I recipient_delimiter
464 for your Postfix is configured to a minus instead of a plus..
468 .I "\-\-skip\-prefix=joe\-virtual\-"
470 .I \-\-domain=your.virtual.domain
471 options to both calls to
472 .BR enemies\-of\-carlotta .
474 (Yes, I think these things are much too complicated, too.)
476 Users and list owners use Enemies of Carlotta via e\-mail using
477 command addresses such as
478 .BR foo\-subscribe@example.com .
479 Here is a list of all command addresses list users and owners can give.
480 In all these examples, the name of the mailing list is
481 .BR foo@example.com .
482 .SS "Mail commands anyone can use"
483 These commands are meant for everyone's use.
484 They don't require any special priviledges.
487 Send mail to all list subscribers.
488 The message may have to be manually approved by the list moderators first,
489 and they have the power to reject a message.
491 .BR foo\-owner@example.com
492 Send mail to the list owner or owners instead.
494 .BR foo\-help@example.com
495 Sending mail to this address makes the list manager reply with
496 the help message for the list.
498 .BR foo\-subscribe@example.com
499 Send mail to this address to subscribe to a list.
500 The list manager will respond with a confirmation request.
501 You won't be subscribed unless you reply to the confirmation request.
502 This way, malicious people can't put your address on a mailing list,
503 or many mailing lists.
505 .BR foo\-subscribe\-joe=example.com@example.com
506 This is a second form of the subscription address.
507 If you want to subscribe to the list with another address than the
508 one you're sending mail from, use this one.
509 In this case, the address to be subscribed is joe@example.com.
510 Note that the confirmation request is sent to Joe, since it is
511 his address that is to be added to the list.
513 .BR foo\-unsubscribe@example.com
514 To unsubscribe from a list, send mail to this address from the address
515 that is subscribed to the list.
516 Again, you will receive a confirmation request, to prevent malicious
517 people from unsubscribing you against your will.
519 .BR foo\-unsubscribe\-joe=example.com@example.com
520 To unsubscribe Joe, use this address.
521 Again, it is Joe who gets to confirm.
522 .SS "Mail commands for the list owners"
523 These are commands that list owners can use to administer their list.
525 .BR foo\-subscribe\-joe=example.com@example.com
526 If a list owner sends mail like this, it is they who get the confirmation
528 It is generally better for people to subscribe themselves, but sometimes
529 list owners want to do it, when they have permission from the person
532 .BR foo\-unsubscribe\-joe=example.com@example.com
533 List owners can also unsubscribe other people.
535 .BR foo\-list@example.com
536 To see who are on the list, this is the address to use.
537 It only works if the sender address is one of the list owners.
538 The sender address is the one used on the SMTP level,
539 not the one in the From: header.
541 .BR foo\-setlist@example.com
542 This lets a list owner set the whole subscriber list at once.
543 This is similar to using lots and lots and lots of \-subscribe and
544 \-unsubscribe commands, only less painful.
545 Everyone who is added to the list gets a welcome message, and
546 everyone who is removed from the list gets a goodbye message.
548 .BR foo\-setlistsilently@example.com
549 This is similar to \-setlist, but no welcome and goodbye messages are sent.
551 Enemies of Carlotta supports plugins.
552 If you don't know what Python programming is, you may want to skip this
555 A plugin is a Python module (file named with a
557 suffix), placed in the
558 .B ~/.enemies\-of\-carlotta/plugins
560 The plugins are loaded automatically upon startup, if their declared
561 interface version matches the one implemented by Enemies of Carlotta.
562 The interface version is declared by the module global variable
563 .BR PLUGIN_INTERFACE_VERSION .
565 Plugins can define hook functions that are called by appropriate places in
567 At the moment, the only hook function is
568 .BR send_mail_to_subscribers_hook ,
569 which can manipulate a mail message before it is sent to the subscribers.
570 The function must look like this:
573 def send_mail_to_subscribers_hook(list, text):
577 argument is a reference to the
579 object that corresponds to the list in question, and
581 is the complete text of the mail message as it exists.
582 The function must return the new contents of the mail message.
585 .I ~/.enemies\-of\-carlotta
586 All files related to your mailing lists.
588 .I ~/.enemies\-of\-carlotta/secret
589 Secret password used to generate signed addresses for bounce checking
590 and subscription verification.
592 .I ~/.enemies\-of\-carlotta/foo@example.com
593 Directory containing data pertaining to the foo@example.com list.
596 file in this directory, you shouldn't edit anything by hand.
598 .I ~/.enemies\-of\-carlotta/foo@example.com/config
599 Configuration file for the mailing list.
600 You may need to edit this file by hand if you wish to change moderation
601 status or list owners.
603 You may want to visit the
604 .I "Enemies of Carlotta"
606 .IR http://www.iki.fi/liw/eoc/ .
projects / eoc.git / blob