README mlmmj-1.3.0                                                 May 25, 2017

This is an attempt at implementing a mailing list manager with the same
functionality as the brilliant ezmlm, but with a decent license and mail server
independence.

The functionality:

 · Archive
 · Custom headers / footer
 · Fully automated bounce handling (similar to ezmlm)
 · Complete requeueing functionality
 · Moderation functionality
 · Subject prefix
 · Subscribers only posting
 · Regular expression access control
 · Functionality to retrieve old posts
 · Web interface
 · Digests
 · No-mail subscription
 · VERP support
 · Delivery Status Notification (RFC1891) support
 · Rich, customisable texts for automated operations

To use mlmmj, do the following:

 0) Compile it if you're not using a binary package such as dpkg, rpm or
    a ports collection from a BSD or Gentoo. To compile, untar the tar-ball
    and do:

    $ ./configure && make && make install

		If you want to filter multipart/mime messages, pass the option
		--enable-receive-strip to configure, and take a look at
		contrib/receivestrip/README.

 1) Configure a recipient delimiter. The default is to use '+', and in
    Postfix it's done by adding

        recipient_delimiter = +

    to /etc/postfix/main.cf. In Exim it can be done by adding

        local_part_suffix = +*
	local_part_suffix_optional

    to the "userforward:" and the "localuser:" router in /etc/exim/exim.conf,
    and also add "local_part_suffix = +*" to the system_aliases function. Also
    make sure that exim will add the envelope from in the Return-Path: header.

    There is a nice FAQ explaining recipient delimiter configuration here:

    http://faqs.org/faqs/mail/addressing/

    The mlmmj TUNABLE "delimiter" configures this on a per list basis

    NOTE: Using '-' as a delimiter is unlikely to work. Mlmmj uses '-' as its
    own kind of minor delimiter. Of course, you also cannot use the delimiter
    in your list names or you will encounter problems.

 2) Create the mailinglist.  There's a script, mlmmj-make-ml, that will make
    a mailinglist for mlmmj. It is highly recommended to use this script to make
    the lists! What is does is described here:

    In the case of a list called mlmmj-test below /var/spool/mlmmj it makes the
    following directories:

    /var/spool/mlmmj/mlmmj-test/incoming
    /var/spool/mlmmj/mlmmj-test/queue
    /var/spool/mlmmj/mlmmj-test/queue/discarded
    /var/spool/mlmmj/mlmmj-test/archive
    /var/spool/mlmmj/mlmmj-test/text
    /var/spool/mlmmj/mlmmj-test/subconf
    /var/spool/mlmmj/mlmmj-test/unsubconf
    /var/spool/mlmmj/mlmmj-test/bounce
    /var/spool/mlmmj/mlmmj-test/control
    /var/spool/mlmmj/mlmmj-test/moderation
    /var/spool/mlmmj/mlmmj-test/subscribers.d
    /var/spool/mlmmj/mlmmj-test/digesters.d
    /var/spool/mlmmj/mlmmj-test/nomailsubs.d
    /var/spool/mlmmj/mlmmj-test/requeue

    NOTE: The mailinglist directory (/var/spool/mlmmj/mlmmj-test in our
    example) have to be owned by the user the mailserver writes as. On some
    Postfix installations Postfix is run by the user postfix, but still writes
    files as nobody:nogroup or nobody:nobody

 3) Make the changes to your mailserver aliases that came as output from
    mlmmj-make-ml. Following the example above they will look like this:

    mlmmj-test:     "|/usr/bin/mlmmj-receive -L /var/spool/mlmmj/mlmmj-test"

    NOTE: Don't forget newaliases.

 4) Start mlmmj-maintd (remember full path when starting it!) or add it to
    crontab with -F switch. The recommended way for now is to run it via cron:

    "0 */2 * * *  /usr/bin/mlmmj-maintd -F -L /var/spool/mlmmj/mlmmj-test"

    It should be started as root, as mlmmj-maintd will become the user owning
    the listdir (/var/spool/mlmmj/mlmmj-test), and log it's last maintenance
    run to listdir/mlmmj-maintd.lastrun.log.

    If you have several lists below /var/spool/mlmmj you can use -d:
    /usr/bin/mlmmj-maintd -F -d /var/spool/mlmmj

    If you have lists more deeply nested below /var/spool/mlmmj, use
    something like:
    find /var/spool/mlmmj -mindepth 1 -maxdepth 1 -type d \
        -exec /usr/bin/mlmmj-maintd -F -d {} \;

That's it! You probably want to go through the next steps too.

 5) Subscribe some people

    /usr/bin/mlmmj-sub -L /var/spool/mlmmj/mlmmj-test/ -a joe@domain.tld

    etc.

 6) If you want custom headers like X-Mailinglist, Reply-To: etc. just add a
    file called 'customheaders' in the list control/ directory like this:
    $ cat /var/spool/mlmmj/mlmmj-test/control/customheaders
    X-Mailinglist: mlmmj-test
    Reply-To: mlmmj-test@domain.tld

 7) If you want every mail to have something like:
    --
    To unsubscribe send a mail to coollist+unsubscribe@lists.domain.net

    Just add what you want to a file named "footer" in the same dir as
    "customheaders" (listdir/control/).

 8) If you want a prefix on the subject, to make it look like this:
    Subject: [mlmmj-test] how are we doing?
    Simply do 'echo "[mlmmj-test]" > control/prefix

 9) For having a moderated list, simply create a file called 'moderated' in the
    control/ directory. Moderators are added to a file called 'moderators' in
    the control/ dir as well.

10) Have a look at the file TUNABLES for runtime configurable things.

Tunables in include/mlmmj.h:
 · There's some time intervals for how mlmmj-maintd operates. I've chosen
   non-strict defaults, so depending on your BOFH rate you might want to tweak.
   The defaults should be good for most people though.

Have fun!

	Mads Martin Joergensen <mmj at mmj dot dk>
	Morten K. Poulsen <morten at afdelingp dot dk>
	Ben Schmidt <mail_ben_schmidt at yahoo dot com dot au>

README.access                           present in mlmmj versions >= 0.8.0
                                        (moderate tag since 1.1.0-RC3)
Access control in mlmmj
=======================

If the file listdir/control/access is present, access control is enabled.

NOTE: the default action is to deny access (reject the mail), so an empty
access control file will cause mlmmj to reject all posts, whereas a non-
existant file will change nothing, and mlmmj will behave as usual.

Each header in the mail is tested against each rule, rule by rule. That is,
all headers are first tested against the first rule, then all headers are
tested against the second rule, and so on.

The first rule to match a header decides which action to take - allow, deny,
discard or moderate the post.

The syntax is quite simple: action[ [!]regexp]
- "Action" can be "allow", "send", "deny", "discard" or "moderate".
- The optional "!" makes the rule a match, if NO header matches the regular
  expression.
- "Regexp" is a POSIX.2 extended regular expression. Matching is done case
  insensitive.

The action "allow" will pass the mail on to the next step in processing. The
mail may still be held for moderation, if it would have been so without access
rules.

The action "send" will send the mail unconditionally. It will not be
moderated, nor subject to subonlypost, nor modnonsubposts.

The action "deny" will not send the mail to the mailing list, but will send a
rejection mail to the sender.

The action "discard" will not send the mail to the list, and will not send a
rejection mail.

The action "moderate" will hold the mail for moderation.

IMPORTANT: if "moderate" is used then don't forget to add people who should
           function as moderators in listdir/control/moderators


The flow through the access system is something like this:

               deny       +------+
       +----------------->| deny |
       |                  +------+
       |
       |       discard    +---------+
       |  +-------------->| discard |
       |  |               +---------+
       |  |                   ^
       |  |                   | expire
    +--------+ moderate   +------+           +------+
--->| access |----------->| hold |---------->| send |--->
    +--------+            +------+ confirm   +------+
       |  |                   ^                ^  ^
       |  |                   | yes            |  |
       |  |    allow      +--------------+ no  |  |
       |  +-------------->| moderation * |-----+  |
       |                  +--------------+        |
       |       send                               |
       +------------------------------------------+

* modnonsubposts is also processed here, and subonlypost (the flow
  may be to deny or discard for subonlypost without modnonsubposts).


First a simple example. This rule set will reject any mail that is NOT plain
text, or has a subject that contains "BayStar", and allow anything else:

 deny !^Content-Type: text/plain
 deny ^Subject:.*BayStar
 allow

To allow only text mails, but have the moderators moderate every html mail one
would use this:

 allow ^Content-Type: text/plain
 moderate ^Content-Type: text/html
 deny

Now on to a more advanced example. Morten can post anything, Mads Martin can
post if the subject does not contain "SCO". Everything else is denied:

 allow ^From: Morten
 deny ^Subject:.*SCO
 allow ^From: Mads Martin
 deny

The last rule (deny) can be left out, as deny is the default action.

A third example. Deny any mails with "discount", "weightloss", or "bonus" in
the subject. Allow PGP signed and plain text mails. Anything else is denied:

 deny ^Subject:.*discount
 deny ^Subject:.*weightloss
 deny ^Subject:.*bonus
 allow ^Content-Type: multipart/signed
 allow ^Content-Type: text/plain

README.archives

Generating web-browseable archives of Mlmmj lists
=================================================

There are a couple of options for making web-browseable archives of Mlmmj
lists.

mlmmj-webarchiver (mhonarc)
---------------------------

Andreas Schneider has created mlmmj-webarchiver, based on mhonarc and perl.

You can get it here:

http://git.cryptomilk.org/projects/mlmmj-webarchiver.git/

And see the kind of output it gives here:

http://www.libssh.org/archive/

hypermail
---------

Wolf Bergenheim has written some scripts which use hypermail to create
web-browseable archives.

The scripts and details can be found here:

http://mlmmj.org/archive/mlmmj/2010-08/1710.html

README.exim4                                                      May 7th 2005


This is a step-by-step guide to run mlmmj with Exim4. The most current version
of this can be found on http://plonk.de/sw/mlmmj/README.exim4.



Notes:
- We assume that you have a user and group called mlmmj to use with mlmmj
- The exim user needs rx access rights to mlmmj's spool directory. (If you
  don't want that, see below.) The easiest way is
  "chmod 755 /path/to/mlmmj/spool", if it's ok that local users can see which
  lists there are.
  Note that the owner of the mlmmj spool must still be the mlmmj user (and
  this user must have at least x rights to the directories below).
- Existence of mailing lists is automatically checked ($listdir) and you
  don't need to put anything into your aliases file
- If you want VERP to be done by your MTA, follow the instructions below and
  put an empty file named verp into the control directory of your lists


1. In the main configuration section:

MLMMJ_HOME=/var/spool/mlmmj
domainlist mlmmj_domains = list.example.net


2. Add +mlmmj_domains to relay_to_domains:

domainlist relay_to_domains = other.domain : +mlmmj_domains


3. mlmmj is barely interested in delay warnings, so add this in the main
configuration:

delay_warning_condition = ${if match_domain{$domain}{+mlmmj_domains}{no}{yes}}


4. In the routers section (before the dnslookup router, preferably at the
beginning):

mlmmj_router:
  driver = accept
  domains = +mlmmj_domains
  require_files = MLMMJ_HOME/${lc::$local_part}
  # Use this instead, if you don't want to give Exim rx rights to mlmmj spool.
  # Exim will then spawn a new process running under the UID of "mlmmj".
  #require_files = mlmmj:MLMMJ_HOME/${lc::$local_part}
  local_part_suffix = +*
  local_part_suffix_optional
  headers_remove = Delivered-To
  headers_add = Delivered-To: $local_part$local_part_suffix@$domain
  transport = mlmmj_transport


If you want VERP to be done by your MTA, also add this:

verp_router:
  driver = dnslookup
  domains = !+mlmmj_domains
  # we only consider messages sent in through loopback
  condition = ${if eq{$sender_host_address}{127.0.0.1}{yes}{no}}
  ignore_target_hosts = <; 0.0.0.0; 127.0.0.0/8; ::1/128; fe80::/10; ff00::/8
  # only the un-VERPed bounce addresses are handled
  senders = \N^.+\+bounces-\d+@.+\N
  transport = verp_smtp


To prevent temporary errors for not-existing lists, add !+mlmmj_domains to the
domains condition of the dnslookup router:

dnslookup:
  driver = dnslookup
  domains = !+mlmmj_domains : !+local_domains
[...]

5. Somewhere in the transports section. (Change the path of mlmmj-receive if you
don't use the default location!):

mlmmj_transport:
  driver = pipe
  return_path_add
  user = mlmmj
  group = mlmmj
  home_directory = MLMMJ_HOME
  current_directory = MLMMJ_HOME
  command = /usr/local/bin/mlmmj-receive -F -L MLMMJ_HOME/${lc:$local_part}

If you want VERP to be done by your MTA, also add this:

verp_smtp:
  driver = smtp
  # put recipient address into return_path
  return_path = ${quote_local_part:${local_part:$return_path}}-\
                ${original_local_part}=${original_domain}@\
                ${domain:$return_path}
  # must restrict to one recipient at a time
  max_rcpt = 1
  # Errors-To: may carry old return_path
  headers_remove = Errors-To
  headers_add = Errors-To: $return_path


6. Test your setup with

$ exim -bt mlmmj-test@your.list.domain
mlmmj-test@your.list.domain
  router = mlmmj_router, transport = mlmmj_transport

If you get different output, run it with -d to see what's going wrong.
If not, you're done!



	Jakob Hirsch (jh at plonk dot de)

README.footers

Footers in Mlmmj
================

Mlmmj's built-in footer support is very rudimentary. It will work for plain
text emails, and that's about it. It doesn't understand HTML or MIME or
anything like that.

There are a few solutions to this. They all involve piping incoming mail
through a filter before it reaches Mlmmj. A script to do this, called
mlmmj-amime-receive, is included in amime-receive in the contrib directory.

It can be used with a number of different pre-processors. One day we also hope
to improve the integration of these external filters with Mlmmj, e.g. so only
list posts are processed. However, the piping solution has worked for a number
of people over the years quite satisfactorily, so this is not a high priority.

Here are some pre-processors you can use.

alterMIME
---------

The mlmmj-amime-receive script is designed to work with a program called
alterMIME. The script itself (in amime-receive in the contrib directory)
contains links to that software, and instructions.

Foot Filter
-----------

alterMIME didn't allow me to reach my particular goals, so I wrote an
alternative called Foot Filter. It is a single source-file C program; the code
and a very simple Makefile can be found in foot_filter in the contrib
directory, along with an altered version of mlmmj-amime-receive, called
mlmmj-recieve-ff.

Foot Filter will output documentation if you run it without arguments, and
again, instructions for the script that handles the piping are found within it.

Py-MIME
-------

A third option is Py-MIME. It was developed for use at The Document Foundation
(LibreOffice) and is included in pymime in the contrib directory.

README.listtexts

List texts in Mlmmj
===================

List texts are stored in listdir/text and subdirectories of
prefix/share/mlmmj/text.skel. They specify the content of various automatic
emails that Mlmmj sends. They are provided in a number of different languages.
The language to use for a list is chosen when you run the mlmmj-make-ml script
and the appropriate files are copied into your listdir/text directory.

This file documents the following aspects of list texts:

- Naming scheme
- Supported list texts
- Format
- Conditionals
- Wrapping
- Formatting and comments
- Formatted substitutions
- Unformatted substitutions
- Escapes

Naming scheme
-------------

List texts are named following a scheme of:

  purpose-action-reason-type

Mlmmj will look for the full four-part name first, then for files with shorter
names obtained by dropping parts off the end, and finally for a file with a
compatibility filename. It will use the first one it finds. (Note that use of
the compatibility filename is DEPRECATED and will be removed in a future
release.)

So, the complete search order is:

- purpose-action-reason-type
- purpose-action-reason
- purpose-action
- purpose
- compatibility filename (DEPRECATED)

When using shortened names, the %ifaction%, %ifreason%, %iftype% and related
conditionals can be used to customise the list text according to the values of
the missing parts.

Mlmmj checks these three paths for each candidate filename, and then moves on
to the next candidate filename:

- listdir/text
- prefix/share/mlmmj/text.skel/default
- prefix/share/mlmmj/text.skel/en

The second path does not exist by default, but can be created by copying or
symlinking the language of your choice to that path.

Note that this search order means that if there is a more specific list text in
a system directory, it will override a less-specific or compatibility list text
in the listdir. This may be surprising, and may change in a future version, so
should not be relied upon. Best practice is to ensure each list has its own
copy of all textx present in system directories, or none of them.

Supported list texts
--------------------

The following list texts are supported. The compatibility filename (DEPRECATED)
is given in brackets. Those with asterisks (*) are not yet used.

- help (listhelp)
  sent in response to an email to listname+help@domain.tld

- faq (listfaq)
  sent in response to an email to listname+faq@domain.tld

- confirm-sub-{request|admin}-normal (sub-confirm)
- confirm-sub-{request|admin}-digest (sub-confirm-digest)
- confirm-sub-{request|admin}-nomail (sub-confirm-nomail)
- confirm-unsub-{request|admin}-normal (unsub-confirm)
- confirm-unsub-{request|admin}-digest (unsub-confirm-digest)
- confirm-unsub-{request|admin}-nomail (unsub-confirm-nomail)
  sent to a requester to allow them to confirm a (un-)subscription request

- moderate-post-{modnonsubposts|access|moderated} (moderation)
  sent to the appropriate moderators when moderation is required because a user
  has submitted a post

- gatekeep-sub-{request|admin|confirm}-{normal|digest|nomail} (submod-moderator)
  sent to the appropriate gatekeepers when gatekeeping is required because a
  subscription request has been received

- wait-post-{modnonsubposts|access|moderated} (moderation-poster)
  sent to a person submitting a post when they need to wait for moderation
  before it is released to the list

- wait-sub-{request|admin|confirm}-{normal|digest|nomail} (submod-requester)
  sent to a person requesting subscription when they need to wait for
  gatekeeping for permission to join

- deny-sub-disabled-{digest|both} (sub-deny-digest)
- deny-sub-disabled-nomail (sub-deny-nomail)
- deny-sub-subbed-{normal|digest|nomail|both} (sub-subscribed)
- deny-sub-closed *
- deny-sub-expired *
- deny-sub-obstruct *
- deny-unsub-unsubbed-{normal|digest|nomail|all} (unsub-notsubscribed)
- deny-post-subonlypost (subonlypost)
- deny-post-modonlypost
- deny-post-access (access)
- deny-post-maxmailsize (maxmailsize)
- deny-post-tocc (notintocc)
- deny-post-expired *
- deny-post-reject *
- deny-release-notfound *
- deny-release-moderators *
- deny-reject-notfound *
- deny-reject-moderators *
- deny-permit-notfound *
- deny-permit-gatekeepers *
- deny-obstruct-notfound *
- deny-obstruct-gatekeepers *
  sent to the requestor when an action is denied or fails for some reason
  ('requestor' here means the person who requested the action, so e.g. for a
  reject action, deny-reject will go to the moderator requesting the rejection
  if the rejection fails; but deny-post-reject will go to the person requesting
  the post if the rejection succeeds, causing the post to fail)

- finish-sub-{request|confirm|admin|permit|switch}-normal (sub-ok)
- finish-sub-{request|confirm|admin|permit|switch}-digest (sub-ok-digest)
- finish-sub-{request|confirm|admin|permit|switch}-nomail (sub-ok-nomail)
- finish-unsub-{request|confirm|admin}-normal (unsub-ok)
- finish-unsub-{request|confirm|admin}-digest (unsub-ok-digest)
- finish-unsub-{request|confirm|admin}-nomail (unsub-ok-nomail)
- finish-post-request *
- finish-post-confirm *
- finish-post-release *
- finish-release *
- finish-reject *
- finish-permit *
- finish-obstruct *
  sent to the requestor when an action completes successfully
  ('requestor' here means the person who requested the action, so e.g. for a
  release action, the moderator requesting the release will receive
  finish-release, and the person who submitted the released post will receive
  finish-post-release because the release action caused their post action to
  succeed)

- notify-sub-{request|confirm|admin|permit}-normal (notifysub)
- notify-sub-{request|confirm|admin|permit}-digest (notifysub-digest)
- notify-sub-{request|confirm|admin|permit}-nomail (notifysub-nomail)
- notify-unsub-{request|confirm|admin|bouncing}-normal (notifyunsub)
- notify-unsub-{request|confirm|admin|bouncing}-digest (notifyunsub-digest)
- notify-unsub-{request|confirm|admin|bouncing}-nomail (notifyunsub-nomail)
  sent to the list owner when somebody is (un-)subscribed

- digest
  sent at the start of a digest (NOTE: the only header supported in this list
  text so far is a single-line 'Subject:' header; however, the contents of
  control/customheaders is included when digests are sent)

- probe (bounce-probe)
  sent to a subscriber after an email to them bounced to inform them of the
  bounce and probe when the address is no longer bouncing

- list---all (listsubs)
- list---normal *
- list---digest *
- list---nomail *
  sent in response to an email to listname+list@domain.tld from the list owner
  (DEPRECATED: if none of %listsubs%, %digestsubs% and %nomailsubs% is
  encountered in the text, then they will be automatically added with some
  default formatting; this functionality is expected to be removed in the
  future)

* Not yet used.

Format
------

List texts have the following format:

- Headers
- Blank line
- Body

They are expected to be in UTF-8 encoding and have Unix line endings.

The headers should be formatted as they should appear in the mail message. They
will begin the mail message. Header continuation via lines beginning with
linear whitespace is supported.

Following the headers found in the list text, Mlmmj will output the following
default headers, unless the same header is already provided in the list text.

- From:
- To:
- Message-ID:
- Date:
- Subject: mlmmj administrivia
- MIME-Version: 1.0
- Content-Type: text/plain; charset=utf-8
- Content-Transfer-Encoding: 8bit

The Subject: header is treated specially: it may include UTF-8 characters,
which will automatically be escaped using the =?utf-8?q?...?= quoting
mechanism.

(NOTE: the 'digest' list text is a bit different. See its description above.)

Both headers and bodies of list texts may include conditionals, formatting
directives and substitutions. These are explained in the following sections.

Conditionals
------------

Conditionals allow text in list texts to be included or omitted based on
conditions. The following are available:

- %ifaction A ...%
  the action is one of those given

- %ifreason R ...%
  the reason is one of those given

- %iftype T ...%
  the type is one of those given

- %ifcontrol C ...%
  one of the given control files exists

- %ifnaction A%
  the action is not the one given

- %ifnreason R%
  the reason is not the one given

- %ifntype T%
  the type is not the one given

- %ifncontrol C ...%
  at least one of the given control files does not exist

The text after the %if...% directive is only included if the condition is
satisfied, until an %else% or %endif% is encountered. These behave as you
would expect. The %else% is optional.

If a line with any of these conditional directives (%if...%, %else% or
%endif%), after processing, contains only whitespace, the line does not appear
at all in the output (the newline and any whitespace is omitted).

Furthermore, if the preceding processed output ends with a blank line, when an
unsatisfied conditional is encountered which has no %else% part, that
preceding blank line is removed (unless it is the blank line that ends the
headers).

On the whole, this is what you would want and expect, so you probably don't
need to worry about it.

Note that when multiple parameters can be given for the directives, these have
'or' behaviour; to get 'and' behaviour, nest conditionals.

Wrapping
--------

There are various directives available to assist with wrapping and formatting.
Wrapping needs to be enabled for each paragraph with:

- %wrap%
- %wrap W%
  concatenate and rewrap lines until the next empty line, whitespace-only line,
  or %nowrap% directive to a width of W (or 76 if W is omitted); second and
  later lines are preceded with as many spaces as the width preceding the
  directive; the width is reckoned including any text preceding the directive
  and any indentation preserved from a file which included the current one, so
  it is an absolute maximum width

To turn off wrapping before the end of a paragraph, use:

- %nowrap%
  stop wrapping; usually placed at the end of a line so the following line
  break is honoured but all preceding text is properly wrapped; if you want
  wrapping to continue after the break, you need to use %wrap% to turn it on
  again on the following line

To cater for various languages, there are a number of different wrapping modes
that can be set. These can be set either before or after wrapping is specified,
and can even be changed part way through a paragraph if desired. The following
directives control them:

- %wordwrap%
- %ww%
  use word-wrapping (this is the default; good for English, French, Greek and
  other languages that use an alphabet and spaces between words); lines have
  whitespace trimmed from both ends and are joined with a single space; lines
  are broken at spaces or at points marked for breaking with \/, but not at
  spaces escaped with a backslash

- %charwrap%
- %cw%
  use character-wrapping (good for Chinese, Japanese and Korean which use
  characters without spaces between words); lines have only leading whitespace
  trimmed and are joined without inserting anything at the joint; lines are
  broken at space or any non-ASCII character except where disallowed with \=

- %userwrap%
- %uw%
  use user-wrapping (for more complex languages or wherever complete manual
  control is desired); lines have only leading whitespace trimmed and are
  joined without inserting anything at the joint; lines are broken only where
  marked for breaking with \/

- %thin%
  assume non-ASCII characters are thin (equivalent to one unit, the same as
  ASCII characters) when reckoning the width for wrapping (this is the default;
  good for languages like Greek which use a non-Latin alphabet)

- %wide%
  assume non-ASCII characters are wide (equivalent to two units, twice as wide
  as ASCII characters) when reckoning the width for wrapping (good for Chinese,
  Japanese, Korean)

- %zero ABC%
  (ABC represents a sequence of non-ASCII characters)
  treat the listed characters as having zero-width when reckoning the width for
  wrapping (useful for ignoring combining characters such as accents so they
  don't affect the width calculation); usefully, the listed characters can be
  represented as unicode escapes (\uNNNN)

If a line with any of the directives in this section, after processing,
contains only whitespace, the line does not appear at all in the output (the
newline and any whitespace is omitted).

Formatting and comments
-----------------------

The following directives are available to assist with formatting and
readability:

- %^%
  start the line here; anything preceding this directive is ignored (useful for
  using indentation for readability without ruining the formatting of the text
  when it is processed)

- %comment%
- %$%
  end the line here; anything following this directive is ignored/a comment

If a line with any of these directives, after processing, contains only
whitespace, the line does not appear at all in the output (the newline and any
whitespace is omitted).

Formatted substitutions
-----------------------

These formatted substitutions work with multiple lines, so are generally not
appropriate for use in headers. They are:

- %text T%
  text from the file named T in the listdir/text directory; the name may only
  include letters, digits, underscore, dot and hyphen, and may not start with a
  dot; note that there is an unformatted version of this directive

- %control C%
  the contents of the control file named C in listir/control; the name may only
  include letters, digits, underscore, dot and hyphen, and may not start with a
  dot; note that there is an unformatted version of this directive

- %originalmail%
- %originalmail N%
  (available only in moderate-post-*, wait-post-* and
  deny-post-{access|maxmailsize|tocc|subonlypost|modonlypost})
  the email message being processed (usually a mail being moderated); N
  represents a number, which is how many lines of the message (including
  headers) to include: if omitted, the whole message will be included

- %digestthreads%
  (available only in digest)
  the list of threads included in the digest

- %gatekeepers%
  (available only in gatekeep-sub and wait-sub)
  the list of moderators to whom the moderation request has been sent

- %listsubs%
  (available only in list---*)
  the list of normal subscribers
  DEPRECATED: use %normalsubs%

- %normalsubs%
  (available only in list---*)
  the list of normal subscribers

- %digestsubs%
  (available only in list---*)
  the list of digest subscribers

- %nomailsubs%
  (available only in list---*)
  the list of nomail subscribers

- %moderators%
  (available only in moderate-post-* and wait-post-*)
  the list of moderators to whom the moderation request has been sent

- %bouncenumbers%
  (available only in probe)
  the list of indexes of messages which may not have been received as they
  bounced

Directives which include a list of items have the behaviour that each item is
preceded and followed by the same text as preceded and followed the directive
on its line; only one such directive is supported per line. Those which include
a block of text have the behaviour that second and later lines are preceded
with as many spaces as there were bytes preceding the directive; any text
following such directives on the same line is omitted.

If a line with any of these directives, after processing, contains only
whitespace, the line does not appear at all in the output (the newline and any
whitespace is omitted).

Unformatted substitutions
-------------------------

Unformatted substitutions that are available are:

- $bouncenumbers$
  (available only in probe)
  the formatted list of indexes of messages which may not have been received as
  they bounced
  DEPRECATED: use %bouncenumbers%

- $confaddr$
- $confirmaddr$
  (available only in confirm-[un]sub-*)
  the address to which to send mail to confirm the (un-)subscription in
  question
  NOTE: the short version of this substitution is DEPRECATED

- $control C$
  the contents of the control file named C in listdir/control, with its final
  newline stripped; the name may only include letters, digits, underscore, dot
  and hyphen, and may not start with a dot; note that there is a formatted
  version of this directive

- $digestfirst$
  (available only in digest)
  index of the first message included in a digest

- $digestinterval$
  (available only in digest)
  indexes of the first and last messages included in a digest (e.g. 1-5), or
  just the index if only a single message is included

- $digestissue$
  (available only in digest)
  the issue number of the digest

- $digestlast$
  (available only in digest)
  index of the last message included in a digest

- $digestsubaddr$
  listname+subscribe-digest@domain.tld
  DEPRECATED: use $list+$subscribe-digest@$domain$ instead

- $digestthreads$
  (available only in digest)
  the formatted list of threads included in the digest
  DEPRECATED: use %digestthreads%

- $digestunsubaddr$
  listname+unsubscribe-digest@domain.tld
  DEPRECATED: use $list+$unsubscribe-digest@$domain$ instead

- $domain$
  domain.tld

- $faqaddr$
  listname+faq@domain.tld
  DEPRECATED: use $list+$faq@$domain$ instead

- $helpaddr$
  listname+help@domain.tld
  DEPRECATED: use $list+$help@$domain$ instead

- $list$
  listname

- $list+$
  listname+

- $listaddr$
  listname@domain.tld
  DEPRECATED: use $list$@$domain$ instead

- $listgetN$
  listname+get-N@domain.tld
  (the N here is nothing special, so this won't actually work, but is used to
  explain to users how to use the +get functionality)
  DEPRECATED: use $list+$get-N@$domain$ instead

- $listowner$
  listname+owner@domain.tld
  DEPRECATED: use $list+$owner@$domain$ instead

- $listsubaddr$
  listname+subscribe@domain.tld
  DEPRECATED: use $list+$subscribe@$domain$ instead

- $listunsubaddr$
  listname+unsubscribe@domain.tld
  DEPRECATED: use $list+$unsubscribe@$domain$ instead

- $maxmailsize$
  (available only in deny-post-maxmailsize)
  the maximum size of mail that Mlmmj will accept

- $moderateaddr$
  (available only in moderate-post-* and gatekeep-sub)
  the address to which to send mail to approve the post or subscription in
  question
  DEPRECATED: use $releaseaddr$ or $permitaddr$ instead

- $moderators$
  (available only in moderate-post-*, wait-post-*, gatekeep-sub and wait-sub)
  the formatted list of moderators to whom the moderation request has been sent
  DEPRECATED: use %moderators% or %gatekeepers% instead

- $newsub$
  (available only in notify-sub-*-*)
  the address that has been subscribed
  DEPRECATED: use $subaddr$ instead

- $nomailsubaddr$
  listname+subscribe-nomail@domain.tld
  DEPRECATED: use $list+$subscribe-nomail@$domain$ instead

- $nomailunsubaddr$
  listname+unsubscribe-nomail@domain.tld
  DEPRECATED: use $list+$unsubscribe-nomail@$domain$ instead

- $oldsub$
  (available only in notify-sub-*-*)
  the address that has been unsubscribed
  DEPRECATED: use $subaddr$ instead

- $originalmail$
  the same as %originalmail 100% preceded by a space
  DEPRECATED: use %originalmail%

- $permitaddr$
  (available only in gatekeep-sub)
  the address to which to send mail to permit the subscription in question

- $posteraddr$
  (available only in deny-post-{access|tocc|subonlypost|modonlypost|
  maxmailsize}, moderate-post-* and wait-post-*)
  the from address of the message that was received as determined by Mlmmj

- $random0$
- $random1$
- $random2$
- $random3$
- $random4$
- $random5$
  these are 6 distinct random strings; they allow list texts to be constructed
  that are MIME messages with attachments by creating boundaries that are
  unlikely to appear in the attached messages

- $releaseaddr$
  (available only in moderate-post-*)
  the address to which to send mail to release the post in question

- $subaddr$
  (available only in gatekeep-sub, confirm-[un]sub-*, finish-[un]sub-*,
  notify-[un]sub-* and deny-[un]sub-*)
  the address requested to be (un-)subscribed

- $subject$
  (available only in deny-post-{access|tocc|subonlypost|modonlypost|
  maxmailsize}, moderate-post-* and wait-post-*)
  the subject line of the message in question

- $text T$
  text from the file named T in the listdir/text directory, with its final
  newline stripped; the name may only include letters, digits, underscore, dot
  and hyphen, and may not start with a dot; note that there is a formatted
  version of this directive

Escapes
-------

These allow you to avoid special meanings of characters used for other purposes
in list texts, as well as control the construction of the texts at a fairly low
level.

- $$
  a single $

- %%
  a single %

- \\
  a single \

- \uNNNN
  (NNNN represents four hex digits)
  a Unicode character
  (this is not really appropriate for use in a header, except perhaps the
  Subject: header as Mlmmj does automatic quoting for that header as described
  above)

- \<space>
  a space, but don't allow the line to be broken here when wrapping

- \/
  nothing, but allow the line to be broken here when wrapping

- \=
  nothing, but don't allow the line to be broken here when wrapping

README.postfix                                                   Jan 28th 2012

The main challenge to setting up Mlmmj with Postfix is that Mlmmj must be
executed by root or the owner of the list directory, but by default Postfix
will execute Mlmmj as 'nobody'[1].

There are a number of possible ways around this:

- Making 'nobody' own your lists (insecure) [2]
- Changing the Postfix default to an 'mlmmj' user (possibly insecure or
  impractical) [3]
- .forward files (impractical) [4]
- Using an :include: file owned by an 'mlmmj' user (possibly insecure and
  suboptimal) [5]
- Adding an alias table owned by an 'mlmmj' user (suboptimal) [6]
- Using a Postfix transport to run Mlmmj as an 'mlmmj' user (recommended)

As you can see, the last option is recommended. Here is how to set it up using
Postfix virtual domains (so you can host multiple domains on the same server).
(It can also be done with regular non-virtual aliases[7].)

 1) Add an 'mlmmj' user to your system (e.g. using 'useradd'). It usually
    makes sense to make this a 'system' user, with no password and no shell
    (/usr/false for the shell), and for its home directory to be
    /var/spool/mlmmj (or wherever you want to put your Mlmmj spool directory).

 2) Create your Mlmmj spool directory (we'll assume it's /var/spool/mlmmj)
    and change its owner to the 'mlmmj' user.

 3) Add an 'mlmmj' transport which uses the pipe(8) delivery agent to execute
    mlmmj-receive as the mlmmj user by adding something like the following to
    master.cf (often in /etc/postfix)[8]:

        # mlmmj mailing lists
        mlmmj   unix  -       n       n       -       -       pipe
            flags=ORhu user=mlmmj argv=/usr/local/bin/mlmmj-receive -F -L /var/spool/mlmmj/$nexthop

    Note that $nexthop is used to specify the list directory. We will return
    to that later.

 4) Integrate some necessary options in main.cf (also often in /etc/postfix):

        # Only deliver one message to Mlmmj at a time
        mlmmj_destination_recipient_limit = 1

        # Consider the part after '+' but before '@' to be an address extension
        # i.e. addresses have the form user+extension@domain.tld
        recipient_delimiter = +

        # A map to forward mail to a dummy domain
        virtual_alias_maps = hash:/var/spool/mlmmj/virtual

	# Allow virtual alias maps to specify only the user part of the address
	# and have the +extension part preserved when forwarding, so that
	# list-name+subscribe, list-name+confsub012345678, etc. will all work
        propagate_unmatched_extensions = virtual

        # A map to forward mail for the dummy domain to the Mlmmj transport
        transport_maps = hash:/var/spool/mlmmj/transport

    Of course, you may need to merge these options with existing ones (e.g.
    you probably have existing virtual_alias_maps if you run a multi-domain
    server).

    It is probably unnecessary to change propagate_unmatched_extensions because
    it defaults to something including 'virtual'. You can check this with
    something like 'postconf | grep propagate'.

 5) (For each list) Create a mailing list (e.g. by using mlmmj-make-ml). The
    list directory should be like /var/spool/mlmmj/list-dir for a flat
    structure, or /var/spool/mlmmj/domain.tld/list-name for a hierarchical
    structure (the -s option to mlmmj-make-ml may be useful to get the list
    created where you want it). Ensure the list directory and everything in it
    is owned by the mlmmj user (except you may want control files to be owned
    by your www server user in order to use web configuration interfaces; they
    must be readable by the mlmmj user though).

 6) (For each list) Add entries to the Postfix tables to accept mail for the
    list and forward it to the Mlmmj transport:

    /var/spool/mlmmj/virtual:
        list-name@domain.tld    domain.tld--list-name@localhost.mlmmj

    /var/spool/mlmmj/transport:
        # for a flat structure
        domain.tld--list-name@localhost.mlmmj   mlmmj:list-dir
        # for a hierarchical structure
        domain.tld--list-name@localhost.mlmmj   mlmmj:domain.tld/list-name

    Note that we have used a dummy domain 'localhost.mlmmj' to connect the
    virtual alias with the Mlmmj transport. This could be anything as long as
    it isn't a real domain. The user part of the address could also be
    anything; as long as the address matches in both tables it should work.

    Also note that the text after 'mlmmj:' becomes $nexthop which was mentioned
    earlier, so it is used to specify the list directory when executing
    mlmmj-receive.

 7) Refresh your postfix tables and reload your configuration so it takes
    effect.

        postmap /var/spool/mlmmj/virtual
        postmap /var/spool/mlmmj/transport
        postfix reload

    Enjoy your new lists!



[1] Actually, the standard local(8) delivery agent will execute external
    programs (such as Mlmmj) as the 'receiving user'. However, unless you
    direct your mail to Mlmmj using a .forward file (see local(8)) or an
    :include: file (see aliases(5)), or your aliases file is not owned by root,
    there is no 'receiving user'. Without a 'receiving user', Postfix uses the
    user from the configuration option 'default_privs', which defaults to
    'nobody'.

[2] Making 'nobody' own your lists is insecure because other programs and
    daemons rely on 'nobody' not owning any files or having access to anything;
    they use 'nobody' as a way of denying access and keeping all your files and
    system secure. Most notably, some NFS implementations use 'nobody' when
    somebody connects but fails to authenticate. Your mailing lists should not
    be accessible in such situations, but they may be if they are owned by
    'nobody'.

[3] Changing 'default_privs' to an 'mlmmj' user may open other security holes,
    and may not be appropriate if Postfix is used for other external programs
    besides Mlmmj.

[4] Using .forward files is not practical, as it requires a user to be created
    for every mailing list.

[5] Using :include: files would require delivery to commands to be enabled in
    :include: files, which is not recommended for security reasons. It is also
    messy for virtual domains in the same way as an alias table owned by an
    'mlmmj' user is[6].

[6] Adding an alias table owned by an 'mlmmj' user works, and doesn't pose any
    great security risk. However, it is messy for virtual domains as you need
    to forward mail from the virtual domain to your non-virtual domain and then
    to Mlmmj. This results in each list having an additional address, which is
    not desirable. That extra intermediate address is also included in mail
    headers, which is not desirable (though it could be filtered out by Mlmmj).
    Setting up an Mlmmj transport is about the same amount of work and doesn't
    have these drawbacks. However, If you are not using virtual domains, this
    is a good and simple option; but it will not be explained in detail here.

[7] To use non-virtual alises, at step 4, you'll need to incorporate:

        alias_maps = hash:/var/spool/mlmmj/aliases
        propagate_unmatched_extensions = alias

    You probably will need to adjust propagate_unmatched_extensions in this
    case, probably by adding 'alias' to the existing value rather than using
    'alias' alone.

    If you want to use 'newaliases' to update the alias table, you should also
    incorporate:

        alias_database = hash:/var/spool/mlmmj/aliases

    At step 6, entries in /var/spool/mlmmj/aliases should look something like:

        list-name:    list-name@localhost.mlmmj

    At step 7, you'll need:

        postalias /var/spool/mlmmj/aliases

    or (if you included alias_database above)

        newaliases

    And of course you can omit the virtual stuff if you're not using it.

    Note that this has not been tested, but we believe it should work.

[8] The flags for the transport are pretty critical. In particular if the 'R'
    option is not used mlmmj-receive fails to receive the mail correctly. The
    options mean:

        D - Prepend a 'Delivered-To: recipient' header (not used)
        O - Prepend an 'X-Original-To: recipient' header
        R - Prepend a 'Return-Path:'. header
        h - fold $nexthop to lowercase
        u - fold $recipient to lowercase

|------------------------------------------------------------------------------|
|                     Using mlmmj with qmail (and vpopmail)                    |
|------------------------------------------------------------------------------|
|--------------- Fabio Busatto <fabio.busatto@programmazione.it> --------------|
|------------------------------------------------------------------------------|

This mini-HOWTO is a step-by-step guide for using mlmmj with qmail MTA
(http://www.qmail.org/), and it has been successfully tested also with vpopmail
virtual domains (http://www.inter7.com/vpopmail/).

Prerequisites:
- qmail (and vpopmail) correctly installed
- mlmmj correctly installed

Conventions:
- ${BINDIR}: directory with mlmmj binary files (/usr/local/bin/)
- ${LISTDIR}: directory with list configuration files
              (/var/spool/mlmmj/listname)
- ${DQFILE}: dot-qmail file (see below)

Configuration:
- the first thing you've to do is to create the list, using the
  mlmmj-make-ml script (follow the classic procedure to do this step)
- enter the control directory for the list (${LISTDIR}/control/), and execute
  the following command:
   # cd ${LISTDIR}/control/; echo '-' > delimiter
- chown and chmod the file according to the mlmmj configuration
- create dot-qmail files for the list to handle direct requests and extensions:
   # echo -e "|${BINDIR}/mlmmj-receive -L ${LISTDIR}" > ${DQFILE}
- chown and chmod the files according to the qmail (and vpopmail) configuration

WARNING: REMEMBER that the delimiter is -, so do not use + when composing mail
addresses for extensions!!!

WARNING: DO NOT USE 'preline' command in dot-qmail files, it will result in
mlmmj to not work properly!!!

|------------------------------------------------------------------------------|

Example:

- Configuring mlmmj to handle ml@programmazione.it mailing list using qmail as
  MTA and vpopmail for virtual domain support:

# mlmmj-make-ml -c vpopmail:vchkpw -L ml
Creating Directorys below /var/spool/mlmmj. Use '-s spooldir' to change
The Domain for the List? [] : programmazione.it
The emailaddress of the list owner? [postmaster] : postmaster@programmazione.it
The path to texts for the list? [/usr/local/share/mlmmj/text.skel] :
chown -R vpopmail:vchkpw /var/spool/mlmmj/ml? [y/n]: y

# cd /var/spool/mlmmj/ml/control/
# echo '-' > delimiter
# chown vpopmail:vchkpw delimiter
# cd /home/vpopmail/domains/programmazione.it/
# echo -e "|/usr/local/bin/mlmmj-receive -L /var/spool/mlmmj/ml/" > .qmail-ml
# cp -a .qmail-ml .qmail-ml-default
# cat *-default
# chown vpopmail:vchkpw .qmail-ml .qmail-ml-default
# chmod 600 .qmail-ml .qmail-ml-default

|------------------------------------------------------------------------------|
|--------------- Fabio Busatto <fabio.busatto@programmazione.it> --------------|
|------------------------------------------------------------------------------|

Date: Sun, 1 May 2005 12:54:41 +0200
From: Mads Martin Joergensen <mmj@mmj.dk>
To: mlmmj@mmj.dk
Subject: Security audit

Hey list,

Sebastian Krahmer (http://www.novell.com/linux/security/team.html)
recently did a security audit of mlmmj, and didn't find any issues.

That doesn't necessarily mean that there isn't any, but at least the
code have been looked by different eyes with security in mind.

--
Mads Martin Joergensen, http://mmj.dk
"Why make things difficult, when it is possible to make them cryptic
 and totally illogical, with just a little bit more effort?"
                                -- A. P. J.

Using sendmail + VERP

--------------------------------------------------------------------------------

The following configuration enables VERP (http://cr.yp.to/proto/verp.txt) which
is useful for mailing list managers that are able to take advantage of that
feature.

This configuration is currently used for using the mlmmj manager
(http://mlmmj.mmj.dk) with VERP enabled + sendmail.

The hack consists in hooking VERP rewriting in a replacement ruleset for the
existing EnvFromSMTP one (called VerpEnvFromSMTP). This is going to work *only*
if we are splitting messages with multiple recipients in separate queue files
since the macro we are using for the rewriting ($u) is not set when multiple
rcpt are present.

The first step consists in forcing envelope splitting, this is done using the
QUEUE_GROUP feature, here we are definining r=1 (max 1 rcpt per message) for the
default queue group:


QUEUE_GROUP(`mqueue', `P=/var/spool/mqueue, F=f, I=1m,  R=2, r=1')


Since we are going to split a lot it's advisable to use the FAST_SPLIT option,
additionally we need to enforce return-path inclusion in the local mailer:


define(`confFAST_SPLIT', `100')dnl
define(`LOCAL_SHELL_FLAGS', `eu9P')dnl


Then we define a regex map for matching the addresses that we are going to
rewrite, in our example we'll rewrite addresses like

<listname+bounces-123@domain.net>

with

<listname+bounces-123-user=foo.net@domain.net>

where user@foo.net is the recipient address of the message. So we need to apply
our verp ruleset *only* to those addresses. Additionally we are also adding the
Delivered-To header:


LOCAL_CONFIG
Kmatch_verp regex -m -a@VERP (listname\+bounces\-[0-9]+<@domain\.net\.?>)
H?l?Delivered-To: $u


Here's the ruleset, the first half of the ruleset is the existing EnvFromSMTP
ruleset present in default sendmail.cf, the seconf half is the VERP stuff:


SVerpEnvFromSMTP
R$+                     $: $>PseudoToReal $1            sender/recipient common
R$* :; <@>              $@                              list:; special case
R$*                     $: $>MasqSMTP $1                qualify unqual'ed names
R$+                     $: $>MasqEnv $1                 do masquerading

R $*                                    $: $(match_verp $1 $)                            match the address
R $* + $* < @ $* . > $* @VERP           $: $1 + $2 - $&u < @ $3 . > $4 VERP              rewrite it using $u macro and add VERP string for failsafe
R $* - < @ $* . > $* VERP               $: $1 < @ $2 . > $3                              if $u wasn't defined rewrite the address back
R $* - < $+ @ $+ > < @ $* . > $* VERP   $: $(dequote $1 "-" $2 "=" $3 $) < @ $4 . > $5   replace the "@" in rcpt address with "="
R $* - $+ @ $+ < @ $* . > $* VERP       $: $(dequote $1 "-" $2 "=" $3 $) < @ $4 . > $5   replace the "@" in rcpt address with "="


Finally we need to rewrite the mailer definition for the used mailer (typically
esmtp) specifying VerpEnvFromSMTP as the sender rewrite ruleset:


MAILER_DEFINITIONS
Mesmtp,		P=[IPC], F=mDFMuXa, S=VerpEnvFromSMTP/HdrFromSMTP, R=EnvToSMTP, E=\r\n, L=990,
		T=DNS/RFC822/SMTP,
		A=TCP $h



NOTE: for mailing list servers it's also a good idea keeping existing
Delivered-To headers, sendmail needs the following patch for doing this

--- sendmail/conf.c.orig	2004-07-14 21:54:23.000000000 +0000
+++ sendmail/conf.c	2004-12-06 15:22:05.000000000 +0000
@@ -117,6 +117,7 @@
 	{ "content-length",		H_ACHECK,		NULL	},
 	{ "subject",			H_ENCODABLE,		NULL	},
 	{ "x-authentication-warning",	H_FORCE,		NULL	},
+	{ "delivered-to",	    H_FORCE,		NULL	},

 	{ NULL,				0,			NULL	}
 };


Andrea Barisani <andrea@inversepath.com>