Pantherlist - Advanced Settings Manual
- Introduction to GNU Mailman
- PantherList Email Addresses
- Administrative Roles
- PantherList Web Pages
- Basic Architectural Overview
- PantherList Configuration Pages
- General Options
- Language Options
- Membership Management
- Non-digest Options
- Digest Options
- Privacy Options
- Bounce Processing
- Archiving Options
- Mail/News Gateway
Every mailing list has a set of email addresses that messages can be sent to. There's always one address for posting messages to the list, one address that bounces will be sent to, and addresses for processing email commands. For example, for a mailing list called email@example.com, you'd find these addresses:
- firstname.lastname@example.org - this is the email address people should use for new postings to the list.
- email@example.com - by sending a message to this address, a new member can request subscription to the list. Both the Subject: header and body of such a message are ignored. Note that firstname.lastname@example.org is an alias for the -join address.
- email@example.com - by sending a message to this address, a member can request unsubscription from the list. As with the -join address, the Subject: header and body of the message is ignored. Note that firstname.lastname@example.org is an alias for the -leave address.
- email@example.com - This address reaches the list owner and list moderators directly.
- firstname.lastname@example.org - This address reaches a mail robot which processes email commands that can be used to set member subscription options, as well as process other commands.
- email@example.com - This address receives bounces from members who's addresses have become either temporarily or permanently inactive. The -bounces address is also a mail robot that processes bounces and automatically disables or removes members as configured in the bounce processing settings. Any bounce messages that are either unrecognized, or do not seem to contain member addresses, are forwarded to the list administrators.
- firstname.lastname@example.org - This address is another email robot, which processes confirmation messages for subscription and unsubscription requests.
There's also an -admin address which also reaches the list administrators, but this address only exists for compatibility with older versions of Mailman.
There are two primary administrative roles for each mailing list, a list owner and a list moderator. A list owner is allowed to change various settings of the list, such as the privacy and archiving policies, the content filtering settings, etc. The list owner is also allowed to subscribe or invite members, unsubscribe members, and change any member's subscription options.
The list moderator on the other hand, is only allowed to approve or reject postings and subscription requests. The list moderator can also do things like clear a member's moderation flag, or add an address to a list of approved non-member posters.
Normally, the list owner and list moderator are the same person. In fact, the list owner can always do all the tasks a list moderator can do. Access to both the owner's configuration pages, and the moderation pages are protected by the same password. However, if the list owner wants to delegate posting and subscription approval authority to other people, a separate list moderator password can be set, giving moderators access to the approval pages, but not the configuration pages. In this setup, list owners can still moderate the list, of course.
In the sections that follow, we'll often use the terms list owner and list administrator interchangeably, meaning both roles. When necessary, we'll distinguish the list moderator explicitly.
Every mailing list is also accessible by a number of web pages. Note that the exact urls is configurable by the site administrator, so they may be different than what's described below. We'll describe the most common default configuration, but check with your site administrator or hosting service for details.
Mailman provides a set of web pages that list members use to get information about the list, or manage their membership options. There are also list archive pages, for browsing an online web-based archive of the list traffic. These are described in more detail in the GNU Mailman user's manual.
Mailman also provides a set of pages for configuring an individual list, as well as a set of pages for disposing of posting and subscription requests.
For a mailing list called mylist hosted at the domain lists.example.com, you would typically access the administrative pages by going to
http://lists.example.com/mailman/admin/mylist. The first time you visit this page, you will be presented with a login page, asking for the list owner's password. When you enter the password, Mailman will store a session cookie in your browser, so you don't have to re-authenticate for every action you want to take. This cookie is stored only until you exit your browser.
To access the administrative requests page, you'd visit
http://lists.example.com/mailman/admindb/mylist (note the admindb url as opposed to the admin url). Again, the first time you visit this page, you'll be presented with a login page, on which you can enter either the list moderator password or the list owner password. Again, a session cookie is dropped in your browser. Note also that if you've previously logged in as the list owner, you do not need to re-login to access the administrative requests page.
This section will outline the basic architecture of GNU Mailman, such as how messages are processed by the sytem. Without going into lots of detail, this information will help you understand how the configuration options control Mailman's functionality.
When mail enters the system from your mail server, it is dropped into one of several Mailman queues depending on the address the message was sent to. For example, if your system has a mailing list named mylist and your domain is example.com, people can post messages to your list by sending them to email@example.com. These messages will be dropped into the incoming queue, which is also colloquially called the moderate-and-munge queue. The incoming queue is where most of the approval process occurs, and it's also where the message is prepared for sending out to the list membership.
There are separate queues for the built-in archiver, the bounce processor, the email command processor, as well as the outgoing email and news queues. There's also a queue for messages generated by the Mailman system. Each of these queues typically has one queue runner (or ``qrunner'') that processes messages in the queue. The qrunners are idle when there are no messages to process.
Every message in the queues are represented by two files, a message file and a metadata file. Both of these files share the same base name, which is a combination of a unique hash and the Unix time that the message was received. The metadata file has a suffix of .db and the message file has a suffix of either .msg if stored in plain text, or .pck if stored in a more efficient internal representation1.
As a message moves through the incoming queue, it performs various checks on the message, such as whether it matches one of the moderation criteria, or contains disallowed MIME types. Once a message is approved for sending to the list membership, the message is prepared for sending by deleting, adding, or changing message headers, adding footers, etc. Messages in the incoming queue may also be stored for appending to digests.
After logging into the list configuration pages, you'll see the configuration options for the list, grouped in categories. All the administrative pages have some common elements. In the upper section, you'll see two columns labeled ``Configuration Categories''. Some categories have sub-categories which are only visible when you click on the category link. The first page you see after logging in will be the ``General Options'' category. The specific option settings for each category are described below.
On the right side of the top section, you'll see a column labeled ``Other Administrative Activities''. Here you'll find some other things you can do to your list, as well as convenient links to the list information page and the list archives. Note the big ``Logout'' link; use this if you're finished configuring your list and don't want to leave the session cookie active in your browser.
Below this common header, you'll find a list of this category's configuration variables, arranged in two columns. In the left column is a brief description of the option, which also contains a ``details'' link. For many of the variables, more details are available describing the semantics of the various available settings, or information on the interaction between this setting and other list options. Clicking on the details link brings up a page which contains only the information for that option, as well as a button for submitting your setting, and a link back to the category page.
On the right side of the two-column section, you'll see the variable's current value. Some variables may present a limited set of values, via radio button or check box arrays. Other variables may present text entry boxes of one or multiple lines. Most variables control settings for the operation of the list, but others perform immediate actions (these are clearly labeled).
At the bottom of the page, you'll find a ``Submit'' button and a footer with some more useful links and a few logos. Hitting the submit button commits your list settings, after they've been validated. Any invalid values will be ignored and an error message will be displayed at the top of the resulting page. The results page will always be the category page that you submitted.
The General Options category is where you can set a variety of variables that affect basic behavior and public information. In the descriptions that follow, the variable name is given first, along with an overview and a description of what that variable controls.
As mentioned above, there are two primary administrative roles for mailing lists. In this category you can specify the password for these roles.
The list owner has total control over the configuration of their mailing list (within some bounds as specified by the site administrator). Note that on this page, for historical reasons, the list owner role is described here as the list administrator. You can set the list owner's password by entering it in the password field on the left. You must type it twice for confirmation. Note that if you forget this password, the only way for you to get back into your list's administrative pages is to ask the site administrator to reset it for you (there's no password reminders for list owners).
If you want to delegate list moderation to someone else, you can enter a different moderator password in the field on the right (typed twice for confirmation). Note that if you aren't going to delegate moderation, and the same people are going to both configure the list and moderate postings to the list, don't enter anything into the moderator password fields. If you do enter a separate moderator password, be sure to fill in the
moderator variable in the General options category page.
Mailman is multilingual and internationalized, meaning you can set up your list so that members can interact with it in any of a number of natural languages. Of course, Mailman won't translate list postings. :)
However, if your site administrator has enabled its support, you can set your list up to support any of about two dozen languages, such as German, Italian, Japanese, or Spanish. Your list members can then choose any of your supported languages as their preferred language for interacting with the list. Such things as their member options page will be displayed in this language. Each mailing list also has its own preferred language which is the language the list supports if no other language context is known.
These variables control the language settings for your mailing list:
- This is the list's preferred language, which is the language that the list administrative pages will be displayed in. Also any messages sent to the list owners by Mailman will be sent in this language. This option is presented as a drop-down list containing the language enabled in the
- This set of checkboxes contains all the natural languages that your site administrator has made available to your mailing lists. Select any language that you'd either like your members to be able to view the list in, or that you'd like to be able to use in your list's
- If your mailing list's preferred language uses a non-ASCII character set and the
subject_prefixcontains non-ASCII characters, the prefix will always be encoded according to the relevant standards. However, if your subject prefix contains only ASCII characters, you may want to set this option to Never to disable prefix encoding. This can make the subject headers slightly more readable for users with mail readers that don't properly handle non-ASCII encodings.
Note however, that if your mailing list receives both encoded and unencoded subject headers, you might want to choose As needed. Using this setting, Mailman will not encode ASCII prefixes when the rest of the header contains only ASCII characters, but if the original header contains non-ASCII characters, it will encode the prefix. This avoids an ambiguity in the standards which could cause some mail readers to display extra, or missing spaces between the prefix and the original header.
The Membership Management category is unlike the other administrative categories. It doesn't contain configuration variables or list settings. Instead, it presents a number of pages that allow you to manage the membership of you list. This includes pages for subscribing and unsubscribing members, and for searching for members, and for changing various member-specific settings.
More details on membership management are described in the Membership Management section.
Mailman delivers messages to users via two modes. List members can elect to receive postings in bundles call digests one or a few times a day, or they can receive messages immediately whenever the message is posted to the list. This latter delivery mode is also called non-digest delivery. There are two administrative categories available for separately controlling digest and non-digest delivery. You can even disable one or the other forms of delivery (but not both).
Both kinds of delivery can have list-specific headers and footers added to them which can contain other useful information you want your list members to see. For example, you can include instructions for unsubscribing, or a url to the lists digest, or any other information.
Non-digest deliveries can also be personalized which means certain parts of the message can contain information tailored to the member receiving the message. For example, the To: header will contain the address of the member when deliveries are personalized. Footers and headers can contain personalized information as well, such as a link to the individual user's options page.
In addition, personalized messages will contain extra information that Mailman can use to unambiguously track bounces from members. Ordinarily, Mailman does some pattern recognition on bounce messages to determine list members whose addresses are no longer valid, but because of the vagaries of mail systems, and the countless forwards people can put in place, it's often the case that bounce messages don't contain any useful information in them. Personalized messages avoid this problem by encoding information in certain headers that unambiguously identify the recipient of a message. If that message bounces, Mailman will know exactly which member it was intended for.
Note that because personalization requires extra system resources, it must be enabled by the site administrator before you can choose it.
Here are the variables which control non-digest delivery:
- This option controls whether members can receive immediate delivery or not. If not, they will be forced to receive messages in digests. You can't disable non-digest delivery if digests are already disabled.
- This option turns on message personalization.
- This text box lets you enter information that will be included in the header of every non-digest message sent through the list.
See below for more information on what can go in the headers and footers. If you leave this text box empty, no header will be added.
- Just like with the header, you can add a footer to every message. The same rules apply to footers as apply to headers.
Headers and footers can contain any text you want. For non-English lists, the headers and footers can contain any character in the character set of the list's preferred language. The headers and footers can also contain substitution variables which Mailman will fill in with information taken from the mailing list. These substitutions are in Python string interpolation format, where something like
%(list_name)s is substituted with he name of the mailing list. Note that the trailing "s" is required2.
For example, a footer containing the following text:
This is the \%(list_name)s mailing list Description: \%(description)s
might get attached to postings like so:
This is the Example mailing list Description: An example of Mailman mailing lists
Here is the list of substitution variables available for your headers and footers:
- This is the value of the
real_nameconfiguration variable in the General options category.
- This is the canonical name of the mailing list. In other words it's the posting address of the list3.
- This is the domain name part of the email address for this list.
- This is the base url for contacting the list via the web. It can be appended with
listinfo/%(list_name)sto yield the general list information page for the mailing list.
- The brief description of the mailing list.
- This is the full description of the mailing list.
- This is the extension added to CGI scripts. It might be the empty string,
.cgi, or something else depending on how your site is configured.
info substitution variables take their values from the list configuration variables of the same name.
When personalization is enabled, the following substitution variables are also available:
- The address of the recipient of the message, coerced to lower case.
- The case-preserved address that the user subscribed to the mailing list with4.
- The user's password, in clear text.
- The user's full name.
- The url to the user's personal options page.
Digest delivery is a way to bundle many articles together into one package, which can be delivered once per day (if there were any posted articles), or whenever the package is bigger than a specified limit. Some users may prefer this style of delivery for higher traffic lists since they will receive fewer messages.
Mailman supports two standard digest formats, and if digests are enabled, users can select which of the two formats they receive. One is MIME digests, where each message is an attachment inside a multipart/digest. This format also contains a summary table of contents, and of course the an optional header and footer, and it retains most of the headers of the original messages.
The second type is called ``plaintext'' digests because they are readable in mail readers that don't support MIME. Actually, they adhere to the RFC 1153 digest standard. The retain some, but not all of the original messages, but can also include a summary and headers and footers.
Like non-digest delivery, you can enable or disable digest delivery, but you cannot disable both types of delivery. You can specify different headers and footers for digest and non-digest deliveries. You cannot personalize digest deliveries.
As list administrator, you may want to send an urgent message to all list members, bypassing the normal digest bundling. To do this, send the message with a Urgent: header, where the value of the header is the list administrator's password. Non-digest members will receive the message like normal, but digest members will receive the message immediately5.
Here are the variables which control digest delivery:
- The option controls whether members can receive digest deliveries or not. If not, they will be forced to receive immediate deliveries. You can't disable digests if non-digests are already disabled.
- Controls which style of delivery is the default for new members. You can choose Regular (non-digest) or Digest delivery.
- If a member is allowed to choose digests, this variable controls which is the default digest style they will receive. Plain digests are RFC 1153 format as described above.
- Normally, digest members get at least one message per day, if there have been any messages posted to the list. However, for high volume lists, you may want to send out digests when the size has reached a certain threshold, otherwise, the one digest they receive could be huge. This variable controls the size threshold by specifying the maximum digest size in kilobytes. Note that this threshold isn't exact. Set this variable to zero to specify that there is no size threshold, in which case no more than one digest will be sent out per day.
- This variable actually controls whether or not a digest is sent daily when the size threshold has not yet been met. If set to No, then digests will only be sent when they are bigger than
- This text box lets you enter information that will be included in the header of every digest message sent through the list. The same information can go in this header as can go in the
msg_header, except for the personalization variables.
- Just like with the header, you can add a footer to every message. The same rules apply to digest footers as apply to digest headers.
- Each digest is numbered with a volume and an issue. This variable controls how often a new digest volume is sent. When the digest volume number is incremented, the issue number is reset to 1.
- This is an action variable, which forces an increment of the volume number as soon as you submit the form.
- This is another action variable. Select Yes, submit the form, and the current digest is packaged up and sent to digest members, regardless of size (well, there has to be at least one message in the digest).
The Privacy category lets you control how much of the list's information is public, as well as who can send messages to your list. It also contains some spam detection filters. Note that this section is not used to control whether your list's archives are public or private; for that, use the category.
There are four sub-categories:
- Subscription rules - i.e. the rules for joining and leaving your mailing list
- Sender filters - the rules for who may post messages to your list
- Recipient filters - moderation rules based on the recipient of the message
- Spam filters - some regular expression based rules for header matching
The sender, recipient, and spam filtering rules are part of the general list moderation features of Mailman. When a message is posted to the list, it is matched against a number of criteria, the outcome of which determines whether the message is reflected to the membership or not. In general, the outcome is one of four states:
- Approved or Accepted - the message may be sent on to the members of the mailing list.
- Hold - the message will be held for moderator approval. The list owners and moderators will then have to explicitly approve the message before the list members will see it.
- Reject - the message is bounced back to the original sender, often with a notice containing the reason the message was rejected. The list members never see rejected messages.
- Discard - the message is simply thrown away without further processing.
Many of the fields in this section are text boxes accepting addresses, one per line. Unless otherwise noted, these also accept regular expressions which will be matched against an address, if the line begins with a (caret) character.
These policies control the automatic bounce processing system in Mailman. Here's an overview of how it works:
When a bounce is received, Mailman tries to extract two pieces of information from the message: the address of the member the message was intended for, and the severity of the problem causing the bounce. The severity can be either hard for fatal errors, or soft for transient errors. When in doubt, a hard severity is used.
If no member address can be extracted from the bounce, then the bounce message is usually discarded. Every member has a bounce score, initialized at zero, and every time we encounter a bounce from a member we increment that member's score. Hard bounces increment by 1 while soft bounces increment by 0.5. We only increment the bounce score once per day, so even if we receive ten hard bounces from a member per day, their score will increase by only 1 for that day.
When a member's bounce score is greater than the bounce score threshold (see below), the member's subscription is disabled. Once disabled, the member will not receive any postings from the list until their membership is explicitly re-enabled, either by the list administrator or the user. However, they will receive occasional reminders that their membership has been disabled, and these reminders will include information about how to re-enable their membership. You can control both the number of reminders the member will receive and the frequency with which these reminders are sent.
There is one other important configuration variable; after a certain period of time - during which no bounces from the member are received - the bounce information is considered stale and discarded. Thus by adjusting this value, and the score threshold, you can control how quickly bouncing members are disabled. You should tune both of these to the frequency and traffic volume of your list.
- Specifies whether or not this list should do automatic bounce processing.
- This is the bounce score above which a member's subscription will be automatically disabled. When the subscription is re-enabled, their bounce score will be reset to zero. This value can be a floating point number.
- Thenumber of days after which a member's bounce information is considered stale. If no new bounces have been received in the interrim, the bounce score is reset to zero. This value must be an integer.
- The number of notices a disabled member will receive before their address is removed from the mailing list's roster. Set this to 0 to immediately remove an address from the list once their bounce score exceeds the threshold. This value must be an integer.
- The number of days between each disabled notification.
- This variable controls whether unrecognized bounces are discarded, or forwarded on the list administrator. The bounce detector isn't perfect, although personalization can make it much more accurate. The list owner may want to receive unrecognized bounces so that they can manually disable or remove such members.
- This option controls whether or not the list owner is notified when a member's subscription is automatically disabled due to their bounce threshold being reached.
- This option controls whether or not the list owner is notified when a member is removed from the list after their disabled notifications have been exhausted.
Mailman comes with a built-in web-based archiver called Pipermail, although it can be configured to use external, third party archivers.
- This option tells Mailman whether to archive messages it receives or not, regardless of whether Pipermail or a third party archiver is used. Turn this off if you don't want to archive messages.
Note that senders can control whether their own posts are archived, on an individual per-message basis. If the posted message has a X-No-Archive: header (regardless of value), or a X-Archive: header with a value of
No(case insensitive), then the message will not be archived, although it will be treated as normal in all other ways.
- Controls whether Pipermail archives are private or public. Private archives require a valid member address and password, or a list administrator password in order to access them. This option has no effect when a third party archiver is used.
- Controls how Pipermail splits messages in the archive. The most common option is Monthly meaning a new archive volume is started every month. Very high volume lists may want a shorter frequency (e.g. Weekly or Daily) where as lower volume lists may want a longer frequency (e.g. Yearly). This option has no effect when a third party archiver is used.
Mailman has a sophisticated mail-to-news gateway feature. It can independently gate messages from news to mail and vice versa, and can even be used to manage moderated newsgroups.