1ENEMIES-OF-CARLOTTA(1) General Commands Manual ENEMIES-OF-CARLOTTA(1)
2
6 enemies-of-carlotta - a simple mailing list manager
7
9 enemies-of-carlotta [options] [addresses]
10
12 enemies-of-carlotta is a simple mailing list manager. If you don't
13 know what a mailing list manager is, you should learn what they are
14 before trying to use one. A manual page is unfortunately too short to
15 explain it.
16 Enemies of Carlotta keeps all data about the lists in the ~/.ene‐
18 mies-of-carlotta directory. It will be created automatically when you
19 create your first list. You need to arrange manually for the mails to
20 be processed by the list manager. The details differ from mail system
21 to another. For QMail and Postfix, see below.
22 Each list has one or more owners, who also moderate subscriptions or
24 moderate some or all postings. On completely unmoderated lists the
25 list owners are responsible for answering questions about the list. On
26 completely moderated lists, they have to approve each message before it
27 is sent to the list. On lists with posting=auto, messages from sub‐
28 scribers are sent automatically to the list, and the moderators have to
29 approve the rest.
30
32 --name=foo@example.com
33 Specify the list the command is to operate on. Most of the
34 remaining options require you to set the list name with this
35 option. With the --edit, --subscribe, --unsubscribe, and --list
36 options, the name can be abbreviated to by leaving out the @
37 sign and domain.
38 --create
40 Create a new list. You must specify at least one owner with
41 --owner.
42 --owner=address
44 Specify a list owner when creating or editing a list.
45 --moderator=address
47 Specificy a list moderator when creating or editing a list.
48 --language=language-code
50 Set the language code used for looking up template files. The
51 code should be empty (the default, meaning English), or a
52 two-letter code such as fi or es.
53 --cleaning-woman
55 Deal with bouncing addresses and do other cleanup. You must run
56 enemies-of-carlotta --cleaning-woman periodically, such as once
57 per hour. It will clean up all your lists.
58 --destroy
60 Destroy the list.
61 --edit Modify the list configuration.
63 --subscription=type
65 When creating a list, set its subscription mode to free or mod‐
66 erated. Use with --edit, or --create.
67 --posting=type
69 When creating a list, set its posting mode to free (anyone can
70 post), auto (only subscribers can post, mails from others need
71 to be moderated), or moderated (all mails are moderated). Use
72 with --edit, or --create.
73 --archived=yes-or-no
75 Should list messages be archived to the archive-box directory in
76 the list directory under the ~/.enemies-of-carlotta directory.
77 Use yes or no.
78 --mail-on-subscription-changes=yes-or-no
80 Should the list owners be notified when someone subscribes to or
81 unsubscribes from the list? Use yes or no. Default is no.
82 --mail-on-forced-unsubscription=yes-or-no
84 Should list owners be notified when someone is forcibly dropped
85 from the list due to too much bouncing? Use yes or no. Default
86 is no.
87 --ignore-bounce=yes-or-no
89 Should bounces be ignored? Use yes or no. Default is no.
90 --list List the subscribers of a list.
92 --subscribe
94 Add subscribers to a list. The non-option arguments are the
95 addresses to be subscribed. Note that addresses added this way
96 won't be sent confirmation requests.
97 --unsubscribe
99 Remove subscribers from a list. The non-option arguments are
100 the addresses to be unsubscribed. Note that addresses removed
101 this way won't be sent confirmation requests.
102 --incoming
104 Deal with an incoming message in the standard input. The SMTP
105 envelope sender address must be given in the SENDER environment
106 variable, and the SMTP envelope recipient address in the RECIPI‐
107 ENT environment variable. (QMail and Postfix do this automati‐
108 cally.)
109 --skip-prefix=string
111 Before analyzing the recipient address to see which list it
112 refers, remove string from its beginning. This helps deal with
113 QMail and Postfix virtual domains, see above.
114 --domain=domain.name
116 Before analyzing the recipient address to see which list it
117 refers, replace the domain name part with domain.name. This
118 helps deal with Postfix virtual domains.
119 --is-list
121 Does the address specified with --name refer to a valid list?
122 This sets the exit code to zero (success) if it does, or one
123 (failure) if it does not.
124 --sendmail=pathname
126 Use pathname instead of /usr/sbin/sendmail for sending mail via
127 a command line interface. Note that the command must obey the
128 sendmail command line interface.
129 --smtp-server=hostname
131 Send mail using the SMTP server at hostname (port 25). The
132 server must be configured to allow the list host to relay mail
133 through it. Note that a command line interface is used by
134 default; SMTP sending is used only if you use this option.
135 --qmqp-server=hostname
137 Send mail using the QMQP server at hostname (port 628). The
138 server must be configured to allow the list host to relay mail
139 through it. Note that a command line interface is used by
140 default; QMQP sending is used only if you use this option.
141 --moderate
143 Force an incoming message to be moderated, even if it is going
144 to a list where posting is free. This can be used for spam fil‐
145 tering: you pipe incoming messages through whatever spam filter
146 you choose to use and if the mssage looks like spam, you ask it
147 to be moderated by a human.
148 --post Force an incoming message to be posted, even if it is going to a
150 list where posting is moderated. This can be used when there is
151 an external check for whether a mail is acceptable to the list,
152 e.g., by checking digital signatures.
153 --quiet
155 By default, debugging log messages are sent to the standard
156 error output stream. With this option, they aren't.
157 --sender=foo@example.com
159 --recipient=foo@example.com
161 These two options are used with --incoming and --is-list to
162 override the environment variables SENDER and RECIPIENT, respec‐
163 tively.
164 --get Get the values of one or more configuration variables. The name
166 of the variables are given on the command line after the
167 options. Each value is printed on a separate line.
168 --set Set the values of one or more configuration variables. The
170 names and values are given on the command line after the options
171 and separated by an equals sign ("="). For example, the follow‐
172 ing would set the language of a list to Finnish: enemies-of-car‐
173 lotta --name=foo@bar --set language=fi
174 --version
176 Print out the version of the program.
177 --show-lists
179 List the lists enemies-of-carlotta knows about.
180
182 Each list is represented by a directory, named after the list, in
183 ~/.enemies-of-carlotta. That directory contains several files and
184 directories, described below. In general, it is not necessary to touch
185 these at all. However, some esoteric configuration can only be done by
186 hand editing of the list configuration file.
187 config The list configuration file. Contents are described below.
189 subscribers
191 Subscriber database. Each line contains a subscriber group,
192 with the first five space delimited fields being group identi‐
193 fier, status, timestamp for when the group was created, time‐
194 stamp for the bounce that made it switch from status 'ok' to
195 'bounced', and the bounce identifier.
196 archive-box
198 Archived messages.
199 bounce-box
201 Bounce messages groups not in state 'ok'.
202 headers-to-add
204 These headers are added to the mails sent to the list. They are
205 copied to the beginning of the existing headers exactly as they
206 are in the file, after list headers ("List-ID" and such) have
207 been added and those mentioned in headers-to-remove have been
208 removed.
209 headers-to-remove
211 These headers are removed from mails sent to the list.
212 moderation-box
214 Messages waiting for moderator approval.
215 subscription-box
217 Subscription and unsubscription requests waiting to be confirmed
218 by the user.
219 templates
221 Directory containing list specific templates (optional). If this
222 directory exists, templates are searched from it before going
223 for system wide templates. An empty file here means the corre‐
224 sponding message is not sent at all. This can, for example, to
225 be used to turn off the "please wait for moderator" mails on a
226 per-list basis.
227 plugins
229 Directory containing plugins, Python source files that are
230 loaded automatically by EoC upon startup. The plugins may
231 change how EoC operates.
232 The config file has a keyword=value format:
234 [list]
236 owners = liw@liw.iki.fi
237 archived = no
238 posting = free
239 subscription = free
240 mail-on-subscription-changes = yes
241 mail-on-forced-unsubscribe = yes
242 language = fi
243 The keywords archived, posting, and subscription correspond to the
245 options with the same names. Other keywords are:
246 owners List of addresses for the owners. Set with the --owner option.
248 moderators
250 List of addresses for the moderators. Set with the --moderator
251 option.
252 mail-on-subscription-changes
254 Should the owners be mailed when users subscribe or unsubscribe?
255 mail-on-forced-unsubscribe
257 Should the owners be mailed when people are removed from the
258 list due to excessive bouncing?
259 ignore_bounce
261 Bounce messages are ignored on this list. Useful for example if
262 list should have static subscriber list.
263 language
265 Suffix for templates, to allow support for multiple languages.
266 (If language is set to "fi", then the template named "foo" is
267 first searched as "foo.fi".)
268 pristine-headers
270 Do not MIME encode the headers. Set to "yes" to not encode, any‐
271 thing else (including empty or unset) means encoding will hap‐
272 pen.
273
275 To create a list called moviefans@example.com, owned by ding@exam‐
276 ple.com, use the following command (all on one line):
277 enemies-of-carlotta --name=moviefans@example.com
279 --owner=ding@example.com --create
280 Note that you need to arrange mail to arrive at the list (and its com‐
282 mand addresses) by configuring your mail system. For Qmail and Post‐
283 fix, see below.
284 To see the subscribers on that list:
286 enemies-of-carlotta --name=moviefans@example.com --list
288 People wanting to subscribe to the list should mail
290 moviefans-subscribe@example.com
292
294 With QMail, to arrange for incoming mail to be processed by Enemies of
295 Carlotta, you need to create a couple of .qmail-extension files per
296 list. For example, if your username is joe and you wish to run the
297 joe-fans mailing list, you need to create two files, .qmail-fans and
298 .qmail-fans-default, containing
299 |enemies-of-carlotta --incoming
301 If you're running a virtual domain, example.com, and the mails are
303 being delivered to via /var/qmail/control/virtualdomains to joe-exam‐
304 pledotcom, the files would be called .qmail-exampledotcom-fans and
305 .qmail-exampledotcom-fans-default and would contain
306 |enemies-of-carlotta --incoming --skip-prefix=joe-exampledotcom-
308 (all on one line, of course, in case the manual page formatter breaks
310 it on several lines).
311
313 For Courier-MTA, the instructions are similar to the Qmail ones above.
314 If your user name is joe and you wish to run the joe-fans email list,
315 you need to create the two files .courier-fans and .courier-fans-
316 default in your home directory with the content
317 |enemies-of-carlotta --is-list --name $RECIPIENT || exit 67
319 |enemies-of-carlotta --incoming
320 (The former file needs only the second line, but the first line does no
322 harm and it is easier to keep track of things when the files have the
323 same content. Note that $RECIPIENT should be included verbatim, it is
324 not a metavariable for you to expand.)
325 If you are running a virtual domain configured so that all mail to the
327 domain @example.com is delivered to joe-exampledotcom, you need to cre‐
328 ate the files .courier-exampledotcom-fans and
329 |enemies-of-carlotta --is-list --name $RECIPIENT --skip-pre‐
331 fix=joe-exampledotcom || exit 67
332 |enemies-of-carlotta --incoming --skip-prefix=joe-exampledotcom
333 If the virtual domain is for list use only, then it is sufficient to
335 create only the file .courier-exampledotcom-default containing the lat‐
336 ter two lines.
337
339 With Postfix, you need to set up a .forward file containing
340 "|procmail -p"
342 and then a .procmailrc file containing
344 :0
346 * ? enemies-of-carlotta --name=$RECIPIENT --is-list
347 | enemies-of-carlotta --incoming
348 To use Enemies of Carlotta with a Postfix virtual domain, you need to
350 set up a virtual regular expression map, typically called /etc/post‐
351 fix/virtual_regexp (add virtual_maps = regexp:/etc/postfix/virtual_reg‐
352 exp to your /etc/postfix/main.cf file to enable it). The regexp file
353 needs to do ugly things to preserve the recipient address. Add the
354 following to the regexp file:
355 /^your.virtual.domain$/ dummy
357 /^(yourlist|yourlist-.*)@(your.virtual.domain)$/ joe+virtual-$1
358 That's two lines. Use joe-virtual instead, if recipient_delimiter for
360 your Postfix is configured to a minus instead of a plus.. Then, in
361 your .procmailrc file, add the --skip-prefix=joe-virtual- and
362 --domain=your.virtual.domain options to both calls to enemies-of-car‐
363 lotta.
364 (Yes, I think these things are much too complicated, too.)
366
368 Users and list owners use Enemies of Carlotta via e-mail using command
369 addresses such as foo-subscribe@example.com. Here is a list of all
370 command addresses list users and owners can give. In all these exam‐
371 ples, the name of the mailing list is foo@example.com.
372 Mail commands anyone can use
374 These commands are meant for everyone's use. They don't require any
375 special priviledges.
376 foo@example.com
378 Send mail to all list subscribers. The message may have to be
379 manually approved by the list moderators first, and they have
380 the power to reject a message.
381 foo-owner@example.com
383 Send mail to the list owner or owners instead.
384 foo-help@example.com
386 Sending mail to this address makes the list manager reply with
387 the help message for the list.
388 foo-subscribe@example.com
390 Send mail to this address to subscribe to a list. The list man‐
391 ager will respond with a confirmation request. You won't be
392 subscribed unless you reply to the confirmation request. This
393 way, malicious people can't put your address on a mailing list,
394 or many mailing lists.
395 foo-subscribe-joe=example.com@example.com
397 This is a second form of the subscription address. If you want
398 to subscribe to the list with another address than the one
399 you're sending mail from, use this one. In this case, the
400 address to be subscribed is joe@example.com. Note that the con‐
401 firmation request is sent to Joe, since it is his address that
402 is to be added to the list.
403 foo-unsubscribe@example.com
405 To unsubscribe from a list, send mail to this address from the
406 address that is subscribed to the list. Again, you will receive
407 a confirmation request, to prevent malicious people from unsub‐
408 scribing you against your will.
409 foo-unsubscribe-joe=example.com@example.com
411 To unsubscribe Joe, use this address. Again, it is Joe who gets
412 to confirm.
413 Mail commands for the list owners
415 These are commands that list owners can use to administer their list.
416 foo-subscribe-joe=example.com@example.com
418 If a list owner sends mail like this, it is they who get the
419 confirmation request, not Joe. It is generally better for peo‐
420 ple to subscribe themselves, but sometimes list owners want to
421 do it, when they have permission from the person and feel help‐
422 ful.
423 foo-unsubscribe-joe=example.com@example.com
425 List owners can also unsubscribe other people.
426 foo-list@example.com
428 To see who are on the list, this is the address to use. It only
429 works if the sender address is one of the list owners. The
430 sender address is the one used on the SMTP level, not the one in
431 the From: header.
432 foo-setlist@example.com
434 This lets a list owner set the whole subscriber list at once.
435 This is similar to using lots and lots and lots of -subscribe
436 and -unsubscribe commands, only less painful. Everyone who is
437 added to the list gets a welcome message, and everyone who is
438 removed from the list gets a goodbye message.
439 foo-setlistsilently@example.com
441 This is similar to -setlist, but no welcome and goodbye messages
442 are sent.
443
445 Enemies of Carlotta supports plugins. If you don't know what Python
446 programming is, you may want to skip this section.
447 A plugin is a Python module (file named with a .py suffix), placed in
449 the ~/.enemies-of-carlotta/plugins directory. The plugins are loaded
450 automatically upon startup, if their declared interface version matches
451 the one implemented by Enemies of Carlotta. The interface version is
452 declared by the module global variable PLUGIN_INTERFACE_VERSION.
453 Plugins can define hook functions that are called by appropriate places
455 in the EoC code. At the moment, the only hook function is
456 send_mail_to_subscribers_hook, which can manipulate a mail message
457 before it is sent to the subscribers. The function must look like
458 this:
459 def send_mail_to_subscribers_hook(list, text):
461 The list argument is a reference to the MailingList object that corre‐
463 sponds to the list in question, and text is the complete text of the
464 mail message as it exists. The function must return the new contents
465 of the mail message.
466
468 ~/.enemies-of-carlotta
469 All files related to your mailing lists.
470 ~/.enemies-of-carlotta/secret
472 Secret password used to generate signed addresses for bounce
473 checking and subscription verification.
474 ~/.enemies-of-carlotta/foo@example.com
476 Directory containing data pertaining to the foo@example.com
477 list. Except for the config file in this directory, you
478 shouldn't edit anything by hand.
479 ~/.enemies-of-carlotta/foo@example.com/config
481 Configuration file for the mailing list. You may need to edit
482 this file by hand if you wish to change moderation status or
483 list owners.
484
486 You may want to visit the Enemies of Carlotta home page at
487 http://www.iki.fi/liw/eoc/.
488 ENEMIES-OF-CARLOTTA(1)