NAME
enemies-of-carlotta - a simple mailing list manager
SYNOPSIS
enemies-of-carlotta [options] [addresses]
DESCRIPTION
enemies-of-carlotta is a simple mailing list manager. If you don’t
know what a mailing list manager is, you should learn what they are
before trying to use one. A manual page is unfortunately too short to
explain it.
Enemies of Carlotta keeps all data about the lists in the
~/.enemies-of-carlotta directory. It will be created automatically
when you create your first list. You need to arrange manually for the
mails to be processed by the list manager. The details differ from
mail system to another. For QMail and Postfix, see below.
Each list has one or more owners, who also moderate subscriptions or
moderate some or all postings. On completely unmoderated lists the
list owners are responsible for answering questions about the list. On
completely moderated lists, they have to approve each message before it
is sent to the list. On lists with posting=auto, messages from
subscribers are sent automatically to the list, and the moderators have
to approve the rest.
OPTIONS
--name=foo@example.com
Specify the list the command is to operate on. Most of the
remaining options require you to set the list name with this
option. With the --edit, --subscribe, --unsubscribe, and --list
options, the name can be abbreviated to by leaving out the @
sign and domain.
--create
Create a new list. You must specify at least one owner with
--owner.
--owner=address
Specify a list owner when creating or editing a list.
--moderator=address
Specificy a list moderator when creating or editing a list.
--language=language-code
Set the language code used for looking up template files. The
code should be empty (the default, meaning English), or a
two-letter code such as fi or es.
--cleaning-woman
Deal with bouncing addresses and do other cleanup. You must run
enemies-of-carlotta --cleaning-woman periodically, such as once
per hour. It will clean up all your lists.
--destroy
Destroy the list.
--edit Modify the list configuration.
--subscription=type
When creating a list, set its subscription mode to free or
moderated. Use with --edit, or --create.
--posting=type
When creating a list, set its posting mode to free (anyone can
post), auto (only subscribers can post, mails from others need
to be moderated), or moderated (all mails are moderated). Use
with --edit, or --create.
--archived=yes-or-no
Should list messages be archived to the archive-box directory in
the list directory under the ~/.enemies-of-carlotta directory.
Use yes or no.
--mail-on-subscription-changes=yes-or-no
Should the list owners be notified when someone subscribes to or
unsubscribes from the list? Use yes or no. Default is no.
--mail-on-forced-unsubscription=yes-or-no
Should list owners be notified when someone is forcibly dropped
from the list due to too much bouncing? Use yes or no. Default
is no.
--ignore-bounce=yes-or-no
Should bounces be ignored? Use yes or no. Default is no.
--list List the subscribers of a list.
--subscribe
Add subscribers to a list. The non-option arguments are the
addresses to be subscribed. Note that addresses added this way
won’t be sent confirmation requests.
--unsubscribe
Remove subscribers from a list. The non-option arguments are
the addresses to be unsubscribed. Note that addresses removed
this way won’t be sent confirmation requests.
--incoming
Deal with an incoming message in the standard input. The SMTP
envelope sender address must be given in the SENDER environment
variable, and the SMTP envelope recipient address in the
RECIPIENT environment variable. (QMail and Postfix do this
automatically.)
--skip-prefix=string
Before analyzing the recipient address to see which list it
refers, remove string from its beginning. This helps deal with
QMail and Postfix virtual domains, see above.
--domain=domain.name
Before analyzing the recipient address to see which list it
refers, replace the domain name part with domain.name. This
helps deal with Postfix virtual domains.
--is-list
Does the address specified with --name refer to a valid list?
This sets the exit code to zero (success) if it does, or one
(failure) if it does not.
--sendmail=pathname
Use pathname instead of /usr/sbin/sendmail for sending mail via
a command line interface. Note that the command must obey the
sendmail command line interface.
--smtp-server=hostname
Send mail using the SMTP server at hostname (port 25). The
server must be configured to allow the list host to relay mail
through it. Note that a command line interface is used by
default; SMTP sending is used only if you use this option.
--qmqp-server=hostname
Send mail using the QMQP server at hostname (port 628). The
server must be configured to allow the list host to relay mail
through it. Note that a command line interface is used by
default; QMQP sending is used only if you use this option.
--moderate
Force an incoming message to be moderated, even if it is going
to a list where posting is free. This can be used for spam
filtering: you pipe incoming messages through whatever spam
filter you choose to use and if the mssage looks like spam, you
ask it to be moderated by a human.
--post Force an incoming message to be posted, even if it is going to a
list where posting is moderated. This can be used when there is
an external check for whether a mail is acceptable to the list,
e.g., by checking digital signatures.
--quiet
By default, debugging log messages are sent to the standard
error output stream. With this option, they aren’t.
--sender=foo@example.com
--recipient=foo@example.com
These two options are used with --incoming and --is-list to
override the environment variables SENDER and RECIPIENT,
respectively.
--get Get the values of one or more configuration variables. The name
of the variables are given on the command line after the
options. Each value is printed on a separate line.
--set Set the values of one or more configuration variables. The
names and values are given on the command line after the options
and separated by an equals sign ("="). For example, the
following would set the language of a list to Finnish:
enemies-of-carlotta --name=foo@bar --set language=fi
--version
Print out the version of the program.
--show-lists
List the lists enemies-of-carlotta knows about.
CONFIGURATION
Each list is represented by a directory, named after the list, in
~/.enemies-of-carlotta. That directory contains several files and
directories, described below. In general, it is not necessary to touch
these at all. However, some esoteric configuration can only be done by
hand editing of the list configuration file.
config The list configuration file. Contents are described below.
subscribers
Subscriber database. Each line contains a subscriber group,
with the first five space delimited fields being group
identifier, status, timestamp for when the group was created,
timestamp for the bounce that made it switch from status ’ok’ to
’bounced’, and the bounce identifier.
archive-box
Archived messages.
bounce-box
Bounce messages groups not in state ’ok’.
headers-to-add
These headers are added to the mails sent to the list. They are
copied to the beginning of the existing headers exactly as they
are in the file, after list headers ("List-ID" and such) have
been added and those mentioned in headers-to-remove have been
removed.
headers-to-remove
These headers are removed from mails sent to the list.
moderation-box
Messages waiting for moderator approval.
subscription-box
Subscription and unsubscription requests waiting to be confirmed
by the user.
templates
Directory containing list specific templates (optional). If this
directory exists, templates are searched from it before going
for system wide templates. An empty file here means the
corresponding message is not sent at all. This can, for example,
to be used to turn off the "please wait for moderator" mails on
a per-list basis.
plugins
Directory containing plugins, Python source files that are
loaded automatically by EoC upon startup. The plugins may
change how EoC operates.
The config file has a keyword=value format:
[list]
owners = liw@liw.iki.fi
archived = no
posting = free
subscription = free
mail-on-subscription-changes = yes
mail-on-forced-unsubscribe = yes
language = fi
The keywords archived, posting, and subscription correspond to the
options with the same names. Other keywords are:
owners List of addresses for the owners. Set with the --owner option.
moderators
List of addresses for the moderators. Set with the --moderator
option.
mail-on-subscription-changes
Should the owners be mailed when users subscribe or unsubscribe?
mail-on-forced-unsubscribe
Should the owners be mailed when people are removed from the
list due to excessive bouncing?
ignore_bounce
Bounce messages are ignored on this list. Useful for example if
list should have static subscriber list.
language
Suffix for templates, to allow support for multiple languages.
(If language is set to "fi", then the template named "foo" is
first searched as "foo.fi".)
pristine-headers
Do not MIME encode the headers. Set to "yes" to not encode,
anything else (including empty or unset) means encoding will
happen.
EXAMPLES
To create a list called moviefans@example.com, owned by
ding@example.com, use the following command (all on one line):
enemies-of-carlotta --name=moviefans@example.com
--owner=ding@example.com --create
Note that you need to arrange mail to arrive at the list (and its
command addresses) by configuring your mail system. For Qmail and
Postfix, see below.
To see the subscribers on that list:
enemies-of-carlotta --name=moviefans@example.com --list
People wanting to subscribe to the list should mail
moviefans-subscribe@example.com
QMAIL
With QMail, to arrange for incoming mail to be processed by Enemies of
Carlotta, you need to create a couple of .qmail-extension files per
list. For example, if your username is joe and you wish to run the
joe-fans mailing list, you need to create two files, .qmail-fans and
.qmail-fans-default, containing
|enemies-of-carlotta --incoming
If you’re running a virtual domain, example.com, and the mails are
being delivered to via /var/qmail/control/virtualdomains to
joe-exampledotcom, the files would be called .qmail-exampledotcom-fans
and .qmail-exampledotcom-fans-default and would contain
|enemies-of-carlotta --incoming --skip-prefix=joe-exampledotcom-
(all on one line, of course, in case the manual page formatter breaks
it on several lines).
COURIER-MTA
For Courier-MTA, the instructions are similar to the Qmail ones above.
If your user name is joe and you wish to run the joe-fans email list,
you need to create the two files .courier-fans and .courier-fans-
default in your home directory with the content
|enemies-of-carlotta --is-list --name $RECIPIENT || exit 67
|enemies-of-carlotta --incoming
(The former file needs only the second line, but the first line does no
harm and it is easier to keep track of things when the files have the
same content. Note that $RECIPIENT should be included verbatim, it is
not a metavariable for you to expand.)
If you are running a virtual domain configured so that all mail to the
domain @example.com is delivered to joe-exampledotcom, you need to
create the files .courier-exampledotcom-fans and .courier-
exampledotcom-fans-default containing the two following lines:
|enemies-of-carlotta --is-list --name $RECIPIENT --skip-
prefix=joe-exampledotcom || exit 67
|enemies-of-carlotta --incoming --skip-prefix=joe-exampledotcom
If the virtual domain is for list use only, then it is sufficient to
create only the file .courier-exampledotcom-default containing the
latter two lines.
POSTFIX
With Postfix, you need to set up a .forward file containing
"|procmail -p"
and then a .procmailrc file containing
:0
* ? enemies-of-carlotta --name=$RECIPIENT --is-list
| enemies-of-carlotta --incoming
To use Enemies of Carlotta with a Postfix virtual domain, you need to
set up a virtual regular expression map, typically called
/etc/postfix/virtual_regexp (add virtual_maps =
regexp:/etc/postfix/virtual_regexp to your /etc/postfix/main.cf file to
enable it). The regexp file needs to do ugly things to preserve the
recipient address. Add the following to the regexp file:
/^your.virtual.domain$/ dummy
/^(yourlist|yourlist-.*)@(your.virtual.domain)$/ joe+virtual-$1
That’s two lines. Use joe-virtual instead, if recipient_delimiter for
your Postfix is configured to a minus instead of a plus.. Then, in
your .procmailrc file, add the --skip-prefix=joe-virtual- and
--domain=your.virtual.domain options to both calls to
enemies-of-carlotta.
(Yes, I think these things are much too complicated, too.)
MAIL COMMANDS
Users and list owners use Enemies of Carlotta via e-mail using command
addresses such as foo-subscribe@example.com. Here is a list of all
command addresses list users and owners can give. In all these
examples, the name of the mailing list is foo@example.com.
Mail commands anyone can use
These commands are meant for everyone’s use. They don’t require any
special priviledges.
foo@example.com
Send mail to all list subscribers. The message may have to be
manually approved by the list moderators first, and they have
the power to reject a message.
foo-owner@example.com
Send mail to the list owner or owners instead.
foo-help@example.com
Sending mail to this address makes the list manager reply with
the help message for the list.
foo-subscribe@example.com
Send mail to this address to subscribe to a list. The list
manager will respond with a confirmation request. You won’t be
subscribed unless you reply to the confirmation request. This
way, malicious people can’t put your address on a mailing list,
or many mailing lists.
foo-subscribe-joe=example.com@example.com
This is a second form of the subscription address. If you want
to subscribe to the list with another address than the one
you’re sending mail from, use this one. In this case, the
address to be subscribed is joe@example.com. Note that the
confirmation request is sent to Joe, since it is his address
that is to be added to the list.
foo-unsubscribe@example.com
To unsubscribe from a list, send mail to this address from the
address that is subscribed to the list. Again, you will receive
a confirmation request, to prevent malicious people from
unsubscribing you against your will.
foo-unsubscribe-joe=example.com@example.com
To unsubscribe Joe, use this address. Again, it is Joe who gets
to confirm.
Mail commands for the list owners
These are commands that list owners can use to administer their list.
foo-subscribe-joe=example.com@example.com
If a list owner sends mail like this, it is they who get the
confirmation request, not Joe. It is generally better for
people to subscribe themselves, but sometimes list owners want
to do it, when they have permission from the person and feel
helpful.
foo-unsubscribe-joe=example.com@example.com
List owners can also unsubscribe other people.
foo-list@example.com
To see who are on the list, this is the address to use. It only
works if the sender address is one of the list owners. The
sender address is the one used on the SMTP level, not the one in
the From: header.
foo-setlist@example.com
This lets a list owner set the whole subscriber list at once.
This is similar to using lots and lots and lots of -subscribe
and -unsubscribe commands, only less painful. Everyone who is
added to the list gets a welcome message, and everyone who is
removed from the list gets a goodbye message.
foo-setlistsilently@example.com
This is similar to -setlist, but no welcome and goodbye messages
are sent.
PLUGINS
Enemies of Carlotta supports plugins. If you don’t know what Python
programming is, you may want to skip this section.
A plugin is a Python module (file named with a .py suffix), placed in
the ~/.enemies-of-carlotta/plugins directory. The plugins are loaded
automatically upon startup, if their declared interface version matches
the one implemented by Enemies of Carlotta. The interface version is
declared by the module global variable PLUGIN_INTERFACE_VERSION.
Plugins can define hook functions that are called by appropriate places
in the EoC code. At the moment, the only hook function is
send_mail_to_subscribers_hook, which can manipulate a mail message
before it is sent to the subscribers. The function must look like
this:
def send_mail_to_subscribers_hook(list, text):
The list argument is a reference to the MailingList object that
corresponds to the list in question, and text is the complete text of
the mail message as it exists. The function must return the new
contents of the mail message.
FILES
~/.enemies-of-carlotta
All files related to your mailing lists.
~/.enemies-of-carlotta/secret
Secret password used to generate signed addresses for bounce
checking and subscription verification.
~/.enemies-of-carlotta/foo@example.com
Directory containing data pertaining to the foo@example.com
list. Except for the config file in this directory, you
shouldn’t edit anything by hand.
~/.enemies-of-carlotta/foo@example.com/config
Configuration file for the mailing list. You may need to edit
this file by hand if you wish to change moderation status or
list owners.
SEE ALSO
You may want to visit the Enemies of Carlotta home page at
http://www.iki.fi/liw/eoc/.