ezmlm(5) ezmlm(5)
NAME
ezmlm - format of ezmlm directory
OVERVIEW
An ezmlm directory, dir, stores information about an ezmlm
mailing list. ezmlm-make creates dir; ezmlm-sub and
ezmlm-unsub manipulate the subscriber list stored under
dir; ezmlm-manage handles administrative requests automat-
ically; ezmlm-send sends a message to all subscribers
listed in dir and also maintains a message archive and
message subject index if the list is configured to do so.
ezmlm-reject rejects messages that have an empty subject,
or a subject consisting of only a command word; ezmlm-
return handles bounces; ezmlm-warn warns users for which
messages bounce and eventually removes them from the sub-
scriber list. ezmlm-idx can create a subject index from
an existing list archive. ezmlm-get manages message,
index, and thread retrieval from the archive, as well as
the generation of message digests; ezmlm-cron provides a
restricted interface to cron for the generation of digest
generation trigger messages; ezmlm-store queues messages
of moderated lists and sends a moderation request to the
moderator(s); ezmlm-moderate processes moderation requests
to accept the queued message to the list via ezmlm-send,
or to return the message to the sender; ezmlm-clean cleans
up the moderation queue and returns to the sender any mes-
sages that have timed-out; ezmlm-gate posts messages that
come from a SENDER in an address database, and sends
remaining messages out for moderation; ezmlm-check is used
to diagnose problems with ezmlm mailing list configura-
tion; ezmlm-issub and ezmlm-issubn determine if a SENDER
is a subscriber or a member of a collection of addresses;
ezmlm-tstdig determines if it is time to create a new
digest based on the number and volume of messages and the
amount of time that has passed since the last digest was
issued; ezmlm-request can be used to answer ezmlm commands
in the subject line easing migration from other mailing
list managers. It can also function as a global interface
mimicking the interface of other mailing list manager.
ezmlm-glmake can set up the global interface, and ezmlm-
glconf can create a configuration file for the global
interface from your lists.
SUBSCRIBERS
dir/subscribers is a directory containing the subscriber
list. ezmlm-manage allows automatic subscription if
dir/public exists.
The list is hashed into 53 files, named @ through t in
ASCII. A nonexistent file is treated as an empty file.
Each file contains a series of addresses. An address can
be any string of non-NUL characters up to 400 bytes long.
Each address is preceded by the letter T and followed by a
1
ezmlm(5) ezmlm(5)
NUL.
For reliability, when an address is added to or removed
from the mailing list, the relevant file is recreated
under a temporary name inside dir/subscribers and then
moved into place.
dir/key is a binary file. ezmlm-manage uses dir/key to
create confirmation numbers. Anyone who can guess the
contents of dir/key can forge subscription requests.
ezmlm-make does not put much effort into making dir/key
difficult to guess; for better security, you should add
some random garbage to dir/key.
ARCHIVE
dir/archive is a directory containing messages previously
sent to subscribers. ezmlm-send archives all new messages
if dir/archived exists. If dir/indexed exists, ezmlm-send
also maintains a message subject and author index.
Messages sent to the mailing list are numbered from 1
upwards, whether or not they are archived. dir/num is the
number of messages sent so far followed by ':', followed
by the cumulative amount of message body that has passed
ezmlm-send stored as kbytes * 4 (4 corresponds to 1kb).
dir/archive has subdirectories, each subdirectory storing
up to 100 messages. Message number 100m+n, with n between
0 and 99, is stored in dir/archive/m/n. For example, mes-
sage number 15307 is stored in dir/archive/153/07. The
message index is stored in the file index in the same sub-
directory of dir/archive holding the corresponding mes-
sages. Thus, the subject index contains up to 100
entries.
The subject index contains message subjects that are nor-
malized so that the original message and all replies have
the same entry. The subject index is used for advanced
message retrieval functions. For safety, the subject index
is created under a temporary name inside dir/archive and
then moved into place.
ezmlm-manage will ignore message files without the owner-
execute bit set. ezmlm-send turns on the owner-execute
bit after safely writing the message to disk.
ezmlm-make by default adds ezmlm-get to dir/manager to
handle -get, -index, and -thread requests. If ezmlm-make
is invoked with a digcode command line argument, digest
creation is enabled by putting this argument on the ezmlm-
get command line.
BOUNCES
dir/bounce is a directory containing bounce messages.
2
ezmlm(5) ezmlm(5)
ezmlm-return stores several types of files here.
DELIVERY INSTRUCTIONS
ezmlm-make sets up four files to control mailing list
deliveries. Each file is a series of delivery instruc-
tions in dot-qmail format.
dir/editor handles incoming mailing list submissions.
ezmlm-make sets up dir/editor to invoke ezmlm-send to
immediately forward each message to all subscribers and
then to run ezmlm-warn.
dir/owner handles incoming messages for the mailing list's
owner. ezmlm-make sets up dir/owner to store messages in
dir/Mailbox and then to run ezmlm-warn.
dir/bouncer handles incoming bounce messages. ezmlm-make
sets up dir/bouncer to invoke ezmlm-return. ezmlm-warn is
no longer invoked here due to the load it places on sys-
tems with many large lists with many bounces.
dir/manager handles incoming administrative requests.
ezmlm-make sets up dir/manager to invoke ezmlm-get, ezmlm-
manage, and then ezmlm-warn.
dir/moderator handles incoming message accept and reject
requests for moderated lists. ezmlm-make sets up dir/mod-
erator to invoke ezmlm-moderate, and .BR ezmlm-clean .
DIGESTS
ezmlm-get can create digests if it is invoked from the
command line, from dir/editor, or from dir/manager. The
program functions in slightly different ways in these 3
settings (see ezmlm-get(1)).
To enable automatic digests for a mailing list, use the
ezmlm-make -d switch. To also enable the generation of
digests at specific times dictated by mailed trigger mes-
sages, a digcode should be specified on the ezmlm-get com-
mand line. This can be done by specifying digcode as a
fifth argument to ezmlm-make when setting up the list.
digcode must be alphanumeric and is case-insensitive.
To generate trigger messages, use ezmlm-cron(1) as an
interface to crond(8) or use crond directly.
dir/num contains the number of the last message processed,
followed by ':' and a number that is increased by 1 for
each 256 bytes of message body text processed. The latter
number is used by ezmlm-tstdig to determine if a new
digest is due.
dir/dignum contains the contents of dir/num at the time of
the last regular digest creation, followed by a ':',
3
ezmlm(5) ezmlm(5)
followed by a timestamp. It is updated after each regular
digest is sent.
dir/digissue contains the issue number of the last regular
digest. It is incremented for each regular digest sent.
The following user crontab entry (all on one line) gener-
ates a digest of the list list@host.domain at 1600 every
day:
00 16 * * * /var/qmail/bin/qmail-inject list-dig.digcode
Alternatively, ezmlm-cron can be used:
% ezmlm-cron -t 16:00 list@host digcode
ezmlm-get can also be run from the shell: To generate a
digest to list-digest@host from the list housed in
~joe/list:
% ezmlm-get ~joe/list
Like other ezmlm-get replies, digest can be sent in sev-
eral formats. See ezmlm-get(1) for more info.
MODERATION
There are three aspects of moderation: moderation of
posts, moderation of subscriptions, and "remote adminis-
tration", i.e. giving the moderator the right to (un)sub-
scribe any user. ezmlm handles these three aspects sepa-
rately. The two first aspects enhance security, while the
third decreases security, but makes list administration
considerably easier. By default, the moderator database is
the same for all three functions. While "remote adminis-
tration" and subscription moderation always use the same
database, the moderators for message moderation can be
different.
Even with subscription moderation, the user has to verify
the request. This is to ensure that the user initiating
the request really controls the address. ezmlm-manage
options exist to disable the user handshake, which may be
useful in some circumstances.
For moderation options, the moderators are by stored in a
subscriber list in moddir/subscribers. By default moddir
is dir/mod.
Moderators can be added and removed with:
ezmlm-sub moddir moderator@host
ezmlm-unsub moddir moderator@host
4
ezmlm(5) ezmlm(5)
For subscription moderation, touch dir/modsub after adding
moderator(s). For remote administration, touch
dir/remote. If the contents of these files start with a
leading forward slash, it is assumed to be the name of
moddir subscription moderation. If both files exist and
start with a forward slash, the dir/remote contents are
ignored. Moderators are stored in a subscriber list in the
subscribers subdirectory of moddir. If no directory names
are specified, the default, dir/mod, is used. In all
cases, the subscribers subdirectory of the base directory
must exists/be created.
Moderation of messages is achieved by creating dir/modpost
and modifying dir/editor to invoke ezmlm-store. ezmlm-
store stores the message in dir/mod/pending and sends a
moderation request to all moderators stored in moddir.
If dir/modpost does not exist, ezmlm-store posts messages
directly, and ezmlm-clean does nothing.
If dir/modpost contains a directory name starting with a
forward slash, this directory is used as moddir for mes-
sage moderation. Moderators are stored in a subscriber
list in the subscribers subdirectory of moddir. If no
directory names are specified, the default, dir/mod, is
used.
dir/moderator is linked to dot-accept-default and
dot-reject-default. It handles replies from the modera-
tors.
In addition to a moderator list, the directories
dir/mod/pending, dir/mod/accepted, and dir/mod/rejected
must exist. These directories contain the message modera-
tion queue.
If dir/mod/modtime it determines the minimal time in hours
that messages wait in the moderation queue, before they
are returned to sender with the message in dir/text/mod-
timeout.
If a -help command is send for a moderator and dir/modsub
or dir/remote exist, a more detailed help message stored
in dir/text/mod-help will be sent together with the regu-
lar help. This text should not contain secrets. If
dir/text/mod-help does not exist, dir/text/help will be
sent.
If a -list command is sent for a moderator and dir/modsub
or dir/remote exist, and the ezmlm-manage -l command line
switch is specified, a subscriber list will be returned.
If an -edit.file command is sent for a moderator and
dir/remote exist, and the ezmlm-manage -d command line
5
ezmlm(5) ezmlm(5)
switch is specified, text/file is returned together with
an ezmlm cookie. The remote administrator may return an
edited version of the file, which will be stored, provided
that the cookie is valid. See ezmlm-manage(1) for more
info.
TEXT
dir/text is a directory containing files sent out by
ezmlm-manage in response to administrative requests:
top Introducing ezmlm. This is placed at the
top of each response.
bottom Explaining how to use ezmlm. This is
placed at the bottom of each response.
sub-confirm Explaining how to confirm a subscription
request.
sub-ok Acknowledging successful subscription.
sub-nop Acknowledging a subscription request for an
address already on the mailing list.
sub-bad Rejecting a bad subscription confirmation
number.
unsub-confirm Explaining how to confirm an unsubscription
request, and explaining how to figure out
the subscription address.
unsub-ok Acknowledging successful unsubscription.
unsub-nop Acknowledging an unsubscription request for
an address not on the mailing list.
unsub-bad Rejecting a bad unsubscription confirmation
number.
get-bad Rejecting a bad archive retrieval request.
digest Text copied into the Administrativia sec-
tion of the digest. Usually, this will con-
tain subscription info for the digest, as
well as information on how to post to the
list.
trailer If this files exists, it is copied to the
end of all messages to the list.
faq Sent in response to the faq command. Usu-
ally contains frequently asked questions
and answers specific for the mailing list.
6
ezmlm(5) ezmlm(5)
info Sent in response to the info command. Usu-
ally contains a descripition, policy, etc,
for the list. The first line should in
itself be a very brief description of the
list.
bounce-warn Pointing out that messages have bounced.
bounce-probe Pointing out that a warning message has
bounced.
bounce-num Explaining that ezmlm-return has kept a
list of bounced message numbers.
dig-bounce-num Explaining that digest messages have
bounced. All other text files are used for
both the main list and the digest list.
bounce-bottom Separating the bounce message.
mod-help is set to list moderators issuing a -help
command. It contains instructions for mod-
erators, but it is relatively trivial for a
non-moderator to read it. Don't put secrets
here.
mod-reject is the returned to the sender of a rejected
post.
mod-timeout is returned if the message timed-out with-
out moderator action.
mod-sub is added to the text confirming subscrip-
tion and unsubscription instead of bottom
and the requesting message, for actions
that were approved by a moderator. Not
copying the requesting message hides the
moderator identity from the subscriber.
mod-request is the text sent to the moderators to
request moderator action on a posted mes-
sage.
mod-unsub-confirm
Requesting that the moderator confirm a
request to subscribe. If this file does
not exist, sub-confirm will be used.
mod-unsub-confirm
Requesting that the moderator confirm a
request to unsubscribe. If this file does
not exist, unsub-confirm will be used.
edit-do Instructions sent to the remote
7
ezmlm(5) ezmlm(5)
administrator together with a copy of a
dir/text file and editing instructions.
edit-list A list of editable files in dir/text with a
one-line description send to a remote
administrator in response to a -edit com-
mand.
edit-done Sent to the remote administrator after an
edited dir/text file has been successfully
saved.
Several tags in the text files are replaced by ezmlm pro-
grams. All programs replace the tag <#l#> with the name
of the list or the list-digest, as appropriate for the
request, and <#h#> with the hostname for the list. ezmlm-
send and ezmlm-get replace <#n#> with the current message
number in added headers from dir/headeradd and text files.
ezmlm-get does this for digest messages, where the current
message is the number of the first message in the digest.
ezmlm-manage replaces the tag <#A#> anywhere on a line
with the subscription address, and <#R#> anywhere on a
line with the address the subscriber must reply to. Only
the first tag on any line is processed.
For backwards compatibility, ezmlm-manage replaces the
line !A in any of these files with the name of the sub-
scription address. It replaces the line !R in sub-confirm
and unsub-confirm with the address that the subscriber
must reply to.
ezmlm-store replaces the tag <#A#> anywhere on a line with
the address for accepting the message, and <#R#> anywhere
on a line with the address for rejecting the message.
Only the first tag on any line is processed.
For backwards compatibility, ezmlm-store also replaces the
line !A with the address for accepting the message and the
line !R with the address for rejecting the message.
OUTGOING MESSAGE EDITING
dir/headerremove is a list of bad header field names, one
per line. ezmlm-send removes these header fields from all
outgoing messages. ezmlm-make sets up dir/headerremove to
remove Return-Path, Return-Receipt-To, and Return-Path
fields.
dir/headeradd is a list of new header fields. ezmlm-send
adds these fields to every outgoing message. ezmlm-send
sets up dir/headeradd to add X-No-Archive: yes and Prece-
dence:bulk.
If dir/mimeremove exists, ezmlm-send removed parts with
the corresponding content-types from composite MIME
8
ezmlm(5) ezmlm(5)
messages. If the ezmlm-reject dir argument is specified,
simple MIME messages of these content-types are rejected.
If dir/mimereject exists, and the ezmlm-reject dir argu-
ment is specified, simple MIME messages of these content-
types, or composite MIME messages with any body part of
these content-types are rejected.
If dir/sequence exists, the first line is added as a
header to all outgoing messages, followed by a space and
the message number. The message number is useful for
archive retrievals, since some mail systems do not reveal
the return-path to the user. NOTE: Sublists have their
own message counter. Adding a sequence header from a sub-
lists will give you the sublist message number which is
different from the main list message number.
dir/prefix is a subject prefix. If this file exists, its
contents are prefixed to the subject of the post in the
outgoing message. The archived message is not processed.
Attempts are made to not duplicate an existing prefix in
replies. Think twice before using this option. A prefix
takes unnecessary space on the subject line and most mail
clients can easily filter on other headers, such as 'Mail-
ing-List:'. If dir/prefix contains a single '#', this will
be replaced by the message number. The use of this feature
is inadvisable and violates internet mail standards. How-
ever, it is very popular in e.g. Japan. If you must use
this feature, make sure you are aware that you may be
causing problems to users, sublists, etc.
dir/text/trailer is a message trailer. If this file
exists, it's contents are copied to the end of outgoing
messages. Only lines terminated with new-line are copied.
No trailer is copied to the archived version of the mes-
sage.
MISCELLANY
The first line of dir/mailinglist is a line of text.
ezmlm-send creates a new Mailing-List field, showing the
contents of dir/mailinglist, in every outgoing message.
The first lines of dir/outlocal and dir/outhost give the
outgoing name of the mailing list. These are used by
ezmlm-manage and ezmlm-send to construct sender addresses
for outgoing messages.
The first lines of dir/inlocal and dir/inhost give the
incoming name of the mailing list. These are used by
ezmlm-manage to parse incoming envelopes. Normally inlo-
cal and inhost are the same as outlocal and outhost, but
sometimes they are different, with outlocal@outhost for-
warded to inlocal@inhost.
9
ezmlm(5) ezmlm(5)
If dir/sublist exists, this mailing list is a sublist,
redistributing messages from a parent mailing list. The
first line of dir/sublist is the name of the parent list.
This affects the behavior of ezmlm-send.
If dir/msgsize exists, it is assumed to contain
``max:min'', where ``max'' is the maximum size in bytes of
an acceptable message body, and ``min'' the corresponding
minimal size. Either will be ignored if zero or omitted.
If the ezmlm-reject command line specifies the list direc-
tory, messages not meeting the size criteria are rejected.
If dir/charset exists, the first line is assumed to repre-
sent a valid MIME character set, which is used for all
outgoing MIME messages sent by ezmlm-get and the message
moderation programs. The character set string may be suf-
fixed with ':' and 'Q' or 'B' to send all outgoing text
(ezmlm messages, digest table-of-contents, moderation
requests, etc) encoded in ``Quoted-Printable'' or
``base64'' encoding. By default, no encoding is done,
which may result in the transmission of characters with
the high bit set. When encoding is specified, trigger mes-
sages and other parts of the reply that should not be
encoded are sent as separate MIME parts.
dir/lock is an empty file. Any program that reads or
writes the subscriber list, or adds messages to the
archive, locks dir/lock.
dir/Log is an advisory log of subscription and unsubscrip-
tion actions. WARNING: Log is not protected against sys-
tem crashes. Log entries may be missing or corrupted if
the system goes down. There is Log for each of the acces-
sory address databases as well. Thus, the log for digest
subscribers is dir/digest/Log. If enabled, these logs can
be retrieved by remote administrators (see ezmlm-man-
age(1)).
dir/digest contains items specific for the digest list.
dir/digest/subscribers contains hash files of digest sub-
scriber addresses.
dir/digest/Log, dir/digest/bounce, dir/digest/lockbounce,
and dir/digest/lock have functions for the digest list
that mirror that of the corresponding files in dir.
dir/sql contains SQL server access information for list
that are configured to use an SQL database for storage.
dir/tstdig is a timestamp used temporarily by ezmlm-tst-
dig(1) to coordinate digesting.
10
ezmlm(5) ezmlm(5)
SEE ALSO
ezmlm-check(1), ezmlm-clean(1), ezmlm-gate(1), ezmlmget(1)
, ezmlm-idx(1), ezmlm-issub(1), ezmlm-issubn(1),
ezmlm-list(1), ezmlm-make(1), ezmlm-manage(1), ezmlm-moderate(1)
, ezmlm-request(1), ezmlm-return(1), ezmlmsend(1)
, ezmlm-store(1), ezmlm-sub(1), ezmlm-tstdig(1),
ezmlm-unsub(1), ezmlm-warn(1), dot-qmail(5)
11
© 1994 Man-cgi 1.15, Panagiotis Christias <christia@theseas.ntua.gr>