  EZFAQ 0.40 - ezmlm-idx and ezmlm FAQ
  Fred Lindberg, lindberg@id.wustl.edu & Fred B. Ringel,
  fredr@rivertown.net
  22-NOV-1999

  This document is a collection of frequently asked questions about
  ezmlm-idx. Where applicable, ezmlm itself is also covered. This FAQ
  presumes familiarity with Unix, and with the basic concepts of E-mail
  and mailing lists.  This FAQ is updated for ezmlm-0.53 and ezmlm-
  idx-0.40.
  ______________________________________________________________________

  Table of Contents


  1. General Information

     1.1 Acknowledgements
     1.2 What is this document?
     1.3 Terminology
     1.4 What is the difference between ezmlm and ezmlm-idx?
     1.5 Where can I get all of the ezmlm-related programs?
     1.6 Where can I find documentation for ezmlm and patches?
     1.7 Where do I send comments on this document?
     1.8 How to experiment with new versions of ezmlm-idx.

  2. Quick start

  3. Overview of mailing list management and mailing list managers

  4. Overview of ezmlm function

     4.1 The basic setup.
     4.2 Inventions in ezmlm.
     4.3 The qmail delivery mechanism.
     4.4 What the different programs do.
     4.5 What the different files in the list directory do.
     4.6 The paper path for posts.
     4.7 The ezmlm path for moderation messages.
     4.8 The ezmlm path for administrative messages.
     4.9 The ezmlm path for bounces.
     4.10 Messages to list-owner and list-digest-owner.
     4.11 Structure of subscriber databases.
     4.12 Local case in E-mail addresses.
     4.13 Testing SENDER to allow posts only from list subscribers.
     4.14 How cookies work.
     4.15 How moderator E-mail addresses are stored.
     4.16 How subscription moderation works.
     4.17 How remote administration works.
     4.18 How message moderation works.
     4.19 How QMQP support works
     4.20 How messages are stored in the archive.
     4.21 How the message index works.
     4.22 How threading works.
     4.23 How digests work.
     4.24 How WWW archive access works.
     4.25 How ezmlm-tstdig works.
     4.26 How sublists work.
     4.27 How sublisting can be made transparent to the user.
     4.28 How to service commands in the subject line.
     4.29 How to support alternative command names.
     4.30 How to add your own commands.
     4.31 How remote administrators can retrieve a subscriber list
     4.32 How remote administrators can determine the number of subscribers
     4.33 How remote admins can see if an address is a subscriber or not
     4.34 How remote administrators can search the subscription log
     4.35 How text file editing works.
     4.36 How subject line prefixes work.
     4.37 How bounces are handled.
     4.38 How the info and faq commands work.
     4.39 How the global ezmlm list address works.
     4.40 How ezmlm-cron works.
     4.41 How ezmlm-make works.
     4.42 What names can I use for my lists?
     4.43 Lists in virtual domains
     4.44 How do I make customization simple for me/my users?

  5. ezmlm support for SQL databases.

     5.1 Why use an SQL database with ezmlm?
     5.2 Why not to use an SQL database with ezmlm.
     5.3 Tables used for (My)SQL support.
        5.3.1 Address tables.
        5.3.2 Subscriber log tables.
        5.3.3 Message logging tables.
     5.4 How to set up a simple list with SQL support.
        5.4.1 Helper programs for SQL-enabled lists.
     5.5 Manually manipulating the subscribers of a SQL-enabled list.
     5.6 Converting to and from and SQL database.
     5.7 Optimizing MySQL for ezmlm.
        5.7.1 Address SELECTs, additions, removals.
     5.8 Maintenance of the MySQL database.

  6. Possible error conditions in ezmlm lists.

     6.1 What do I do if ezmlm doesn't work?
     6.2 How do I report ezmlm bugs?
     6.3 Where do I send suggestions for ezmlm-idx improvements?
     6.4 Using ezmlm-test to check the ezmlm(-idx) programs.
     6.5 Using ezmlm-check to find setup errors.
     6.6 Posts are rejected: Sorry, no mailbox here by that name (#5.1.1).
     6.7 Post are not sent to subscribers.
     6.8 ezmlm-make fails: usage: ezmlm-make ...
     6.9 ezmlm-make fails: Unable to create ...
     6.10 ezmlm-make fails: ... ezmlmrc does not exist
     6.11 Index/get/thread requests fail quietly or with errors from ezmlm-manage.
     6.12 Digest triggering requests fail.
     6.13 Remote administration (un)subscribe confirm requests go to the user, not the moderator.
     6.14 (Un)subscribers does not receive a (un)subscribe acknowledgement
     6.15 Messages posted to a moderated list are sent out without moderation.
     6.16 Messages posted to a moderated list do not result in moderation requests.
     6.17 Moderation request replies do not result in the appropriate action.
     6.18 Moderator comments with moderation request replies are not added to the post/sent to the poster.
     6.19 Some headers are missing from messages in the digest.
     6.20 Some Received: headers are missing from messages.
     6.21 My Mutt users cannot thread their digest messages.
     6.22 Posts fail: Message already has Mailing-List (#5.7.2).
     6.23 The last line of a
     6.24 No CONFIRM requests are sent to moderators.
     6.25 Deliveries fail ``temporary qmail-queue error''
     6.26 How to deal with corrupted subscriber lists
     6.27 Vacation program replies are treated as bounces by ezmlm.
     6.28 Digests do not come at regular hours.
     6.29 Preventing loops from misconfigured subscriber addresses.
     6.30 A user can subscribe and receives warning and probe messages, but no messages from the list.

  7. Customizing ezmlm-make operation via ezmlmrc

     7.1 Using ezmlm-make to edit existing lists.
     7.2 What is ezmlmrc?
     7.3 Changing defaults for
     7.4 Changing default moderator directories.
     7.5 Adapting ezmlm-make for virtual domains.
     7.6 Setting up ezmlm-make for special situations.

  8. Restricting message posting to the list.

     8.1 Requiring the list address in To:/Cc: headers.
     8.2 Rejecting messages sent from other mailing lists.
     8.3 Restricting posts based on the Subject line.
     8.4 Restricting the size of posts.
     8.5 Restricting posts based on MIME content-type.
     8.6 Restricting posts to list subscribers.
     8.7 Restricting posts to an arbitrary set of E-mail addresses (higher security option).
     8.8 Completely restricting posts.
     8.9 A general solution to restricting posts based on SENDER.

  9. Customizing outgoing messages.

     9.1 Adding a trailer to outgoing messages.
     9.2 Adding a subject prefix to outgoing messages.
     9.3 Adding a header to outgoing messages.
     9.4 Adding a message number header.
     9.5 Removing headers from outgoing messages.
     9.6 Removing MIME parts from messages.
     9.7 Limiting ``Received:'' headers in outgoing messages.
     9.8 Setting ``Reply-To: list@host''.
     9.9 Configuring the list so posts are not copied to the original sender.
     9.10 Customizing ezmlm notification messages.
     9.11 Specifying character set and content-transfer-encoding for outgoing ezmlm messages.

  10. Customizing archive retrieval.

     10.1 Specifying the format for retrieved messages.
     10.2 Specifying the default format for digests and archive retrieval.
     10.3 Limiting the number of messages per -get/-index request.

  11. Restricting archive retrieval.

     11.1 Restricting archive access to subscribers.
     11.2 Restricting available archive retrieval commands.
     11.3 Restricting archive retrieval to moderators.
     11.4 Allowing archive retrieval from a non-public list.

  12. Customizing digests.

     12.1 Setting up a digest list.
     12.2 Generating daily digests.
     12.3 Generating the first digest.
     12.4 Adding standard administrative information to digests.
     12.5 Controlling the digest format.
     12.6 Customizing bounce handling.

  13. Remote administration.

     13.1 How can I remotely add moderators, subscriber aliases, etc?
     13.2 Moderating posts from a secondary account.
     13.3 Moderating subscription from a secondary account.
     13.4 Automatically approving posts or subscriptions.
     13.5 Allowing remote administrators to get a subscriber list.
     13.6 Allowing remote administrators to retrieve or search a subscription log.
     13.7 Allowing users to get a subscriber list.
     13.8 Changing the timeout for messages in the moderation queue.
     13.9 Finding out how many messages are waiting for moderation.
     13.10 Using the same moderators for multiple lists.
     13.11 Using different moderators for message and subscription moderation.
     13.12 Setting up moderated lists with the list owner as the ``super moderator'' able to add/remove moderators remotely.
     13.13 Customizing ezmlm administrative messages.
     13.14 Manually approving a message awaiting moderation.
     13.15 Manually rejecting a message awaiting moderation.

  14. Sublists.

     14.1 Sublists of ezmlm lists.
     14.2 Sublists of non-ezmlm lists.
     14.3 How to set up a cluster of list and sublists with standard databases.

  15. Migration to Ezmlm from other Mailing List Managers.

     15.1 Basic Concepts.
     15.2 Setting up ezmlm to respond to host-centric commands.
     15.3 Commands of other mailinglist managers recognized by ezmlm.
        15.3.1 Listproc/Listserv.
        15.3.2 Majordomo.
        15.3.3 Smartlist.

  16. Optimizing list performance.

     16.1 Crond-generated digests for better performance.
     16.2 Optimizing execution of ezmlm-warn(1).
     16.3 Decreasing ezmlm-warn time out to increase performance.
     16.4 Use ezmlm without ezmlm-idx for maximum performance.
     16.5 Not archiving to maximize performance.
     16.6 Sublists to maximize performance.

  17. Miscellaneous.

     17.1 How do I quickly change the properties of my list?
     17.2 Open archived list with daily digests.
     17.3 Variations in moderation
     17.4 Lists that allow remote admin, but not user initiated subscription or archive retrieval.
     17.5 Lists that allow remote admin, user archive retrieval, but not user-initiated subscription.
     17.6 Lists that restrict archive retrieval to subscribers.
     17.7 Lists that do not allow archive retrieval at all.
     17.8 Lists that do not allow archive retrieval and do not allow digest triggering per mail.
     17.9 Lists that allow archive retrieval only to moderators, but allow user-initiated subscription.
     17.10 Lists that do not require user confirmation for (un)subscription.
     17.11 Announcement lists for a small set of trusted posters
     17.12 Announcement lists allowing moderated posts from anyone.
     17.13 Announcement lists with less security and more convenience.

  18. Ezmlm-idx compile time options.

     18.1 Location of binaries.
     18.2 Location of man pages.
     18.3 Base directory of qmail-installation.
     18.4 Short header texts, etc.
     18.5 Arbitrary limits.
     18.6 Command names.
     18.7 Error messages.
     18.8 Paths and other odd configuration items.

  19. Multiple language support.

     19.1 Command names.
     19.2 Text files.
     19.3 Multi-byte character code support.

  20. Subscriber notification of moderation events.

     20.1 General opinions.
     20.2 Users should know that the list is subscription moderated.
     20.3 Subscribers should know that posts are moderated.
     20.4 Senders of posts should be notified of rejections.

  21. Ezmlm-idx security.

     21.1 General assumptions.
     21.2 SENDER manipulation.
     21.3 ezmlm cookies.
     21.4 Lists without remote admin/subscription moderation.
     21.5 Message moderation.
     21.6 Subscription moderation.
     21.7 Remote administration.
     21.8 Remote editing of ezmlm text files.
     21.9 Digest generation and archive retrieval.
     21.10 Convenience for security: the ezmlm-manage ``-S'' and ``-U'' switches.
     21.11 Denial of service.
     21.12 Moderator anonymity.
     21.13 Confidentiality of subscriber E-mail addresses.
     21.14 Help message for moderators.
     21.15 Sublists.
     21.16 SQL databases.
     21.17 Reporting security problems.


  ______________________________________________________________________

  11..  GGeenneerraall IInnffoorrmmaattiioonn


  11..11..  AAcckknnoowwlleeddggeemmeennttss

  Many ezmlm users have contributed to improvements in ezmlm-idx. These
  are listed in the RREEAADDMMEE..iiddxx file in the ezmlm-idx distribution.
  Others have through questions and suggestions inspired parts in this
  FAQ, or pointed out errors or omissions. Thanks! Direct contributions
  are attributed to the respective authors in the text. Thanks again!


  11..22..  WWhhaatt iiss tthhiiss ddooccuummeenntt??

  This FAQ contains answers to many questions that arise while
  installing ezmlm, ezmlm-idx, and while setting up and managing ezmlm
  mailing lists. See ``'' for a brief summary of what is ezmlm and what
  is ezmlm-idx.

  Many aspects of ezmlm are covered in several places in this FAQ. The
  early sections explain how ezmlm works. Later sections discuss how to
  deal with possible errors/problems. Subsequent sections discuss
  details of customization and list setup in a _H_O_W_T_O form. Finally,
  there are sections on information philosophy for moderated lists and
  on security aspects on ezmlm lists.

  This is an evolving document.  If you find any errors, or wish to
  comment, please do so to the authors.  This FAQ is currently aimed at
  system administrators and knowledgeable users, and heavily weighted
  towards questions specific to the ezmlm-idx add-on.

  If you have problems with the ezmlm-idx package, please start by
  reading the ``man'' pages which come with each program, then this
  document and other ezmlm documentation which is identified here. If
  you have exhausted these resources, try the ezmlm and qmail mailing
  lists and their respective mailing list archives. If you have solved a
  problem not in the documentation, write it up as a proposed section of
  a FAQ and send it to the authors. This way, it can be added to the
  next version of this FAQ.


  11..33..  TTeerrmmiinnoollooggyy

  This document uses a number of terms. Here are the meanings ascribed
  to them by the authors.

     DDIIRR
        The base directory of the list.


     SSEENNDDEERR
        The envelope sender of the message, as passed to ezmlm by qmail
        via the $SENDER environment variable.


     LLOOCCAALL
        The local part of the envelope recipient. For list-get-1@host,
        it is usually _l_i_s_t_-_g_e_t_-_1. If host is a virtual domain,
        controlled by _u_s_e_r_-_s_u_b, then local would be _u_s_e_r_-_s_u_b_-_l_i_s_t_-_g_e_t_-_1.


     mmooddddiirr
        Base directory for moderators.  Moderator E-mail addresses are
        stored in a hashed database in mmooddddiirr//ssuubbssccrriibbeerrss//. By default,
        ``moddir'' is DDIIRR//mmoodd//.

        To add or remove moderators:


          % ezmlm-sub DIR/moddir moderator@host.domain
          % ezmlm-unsub DIR/moddir moderator@host.domain


     ddoottddiirr

        The second argument of ezmlm-make is the main .qmail file for
        the list. dotdir is the directory in which this ``dot file''
        resides, i.e. the directory part of the ``dot'' argument. This
        is usually the home directory of the user controlling the list
        (but NOT necessarily of the one creating the list). Thus, _d_o_t_d_i_r
        is ~~aalliiaass// if ``root'' creates a list:


           # ezmlm-make ~alias/list ~alias/.qmail-list ...


     _d_o_t_d_i_r is where the ..eezzmmllmmrrcc file is expected when the ezmlm-
     make(1) ``-c'' switch is used (see ``Customizing ezmlm-make opera-
     tion'').


     eezzmmllmm bbiinnaarryy ddiirreeccttoorryy
        The directory where the ezmlm-binaries are normally stored, as
        defined at compile time in ccoonnff--bbiinn.  This is compiled into the
        programs and does not change just because you have moved the
        program.


     eezzmmllmm--ggeett((11))
        This is a reference to the ezmlm-get.1 man page.  Access it with
        one of the following:


          % man ezmlm-get
          % man 1 ezmlm-get


     or if you have not yet installed ezmlm-idx (replace ``xxx'' with
     the version number):


          % cd ezmlm-idx-0.xxx
          % man ./ezmlm-get.1


     bbaasseeddiirr
        The list directory when referencing the list subscriber address
        database.  For E-mail addresses stored in a set of files within
        DDIIRR//ssuubbssccrriibbeerrss//, the ``basedir'' is ``DIR''.


     aaddddrreessss ddaattaabbaassee
        A collection of E-mail addresses stored in a set of files within
        the ``subscribers'' subdirectory of the basedir,
        DDIIRR//ssuubbssccrriibbeerrss//.


     mmeessssaaggee mmooddeerraattoorr
        An address to which moderation requests for posts to the list
        are sent. The moderation requests are formatted with
        ``From:''-``reject'' and a ``To:''-``accept'' default headers
        for moderator replies. A reply to the ``reject'' address leads
        to the rejection of the post. A reply to the ``accept'' address
        leads to the acceptance of the post. Any E-mail address can be a
        moderator E-mail address. Any number of moderator E-mail
        addresses can be used. If a post is sent from a moderator E-mail
        address, the moderation request is sent to that E-mail address
        only. If a post is sent from an E-mail address that is not a
        moderator, a moderation request is sent to all moderators.

        The first reply to the moderation request determines the fate of
        the message. Further requests for the action already taken are
        silently ignored, while a request for the contrary action
        results in an error message stating the actual fate of the
        message. Thus, if you want to ``accept'' the message and it has
        already been accepted, you receive no reply, but if you attempt
        to ``reject'' it, you will receive an error message stating that
        the message already has been accepted.

        Most lists are not message moderated. If they are, the owner is
        usually a ``message moderator'', sometimes together with a few
        other trusted users.

        For an announcement list, it is common to make all the
        ``official announcers'' ``message moderators''. This way, they
        can post securely and ``accept'' their own posts, while posts
        from other users will be sent to this set of ``official
        announcers'' for approval.


     ssuubbssccrriippttiioonn mmooddeerraattoorr
        An E-mail address where subscription moderation requests are
        sent. A subscription moderation request is sent after a user has
        confirmed her intention to subscribe. The subscription
        moderation request is sent to all moderators. As soon as a reply
        to this message is received, the user is subscribed and
        notified. Any E-mail address can be a subscription moderator and
        any number of subscription moderators can be used.

        Unsubscribe requests are never moderated (except when the ezmlm-
        manage(1) ``-U'' flag is used and the sender attempts to remove
        an address other than the one s/he is sending from). It is hard
        to imagine a legitimate mailing list that would want to prevent
        unsubscriptions.


     rreemmoottee aaddmmiinniissttrraattoorr
        When a remote administrator subscribes or unsubscribes a list
        member, the ``confirm'' request is sent back to the remote
        administrator, rather than to the subscriber's E-mail address.
        This allows the remote administrator to (un)subscribe any list
        member without the cooperation of the subscriber at that
        address. Any E-mail address can be a remote administrator and
        any number of E-mail addresses can be remote administrators.

        The set of E-mail addresses that are ``remote administrators''
        and ``subscription moderators'' are always the same. This set of
        E-mail addresses can be ``remote administrators'',
        ``subscription moderators'' or both.

        For most lists, the owner would be the ``remote administrator'',
        if s/he wishes to moderate messages, the owner would be the
        ``message moderator'' and if s/he wishes to moderate
        subscriptions the owner would also be the ``subscription
        moderator''.

        The list's ``message moderator(s)'' can be the same, but can
        also be set up to be completely different.


     CChhaannggiinngg lliisstt ````oowwnneerrsshhiipp''''
        Within this FAQ there are references to the need to check or
        change the list ``ownership.'' This is not a reference to the
        individual user who is the ``list-owner'', but a reference to
        the ownership of the files by your operating system which make
        up the list and reside in DDIIRR//.

        To change the ownership of DDIIRR// and everything within:


          % chown -R user DIR
          % chgrp -R group DIR


     Depending on your system/shell, it may be possible to combine these
     commands into either:


          % chown -R user.group DIR
          % chown -R user:group DIR


  11..44..  WWhhaatt iiss tthhee ddiiffffeerreennccee bbeettwweeeenn eezzmmllmm aanndd eezzmmllmm--iiddxx??

  ezmlm-0.53 is a qmail-based mailing list manager written by Dan J.
  Bernstein.  It has all the basic functionality of a mailing list
  manager, such as subscriber address management including automated
  bounce handling as well as message distribution and archiving.

  ezmlm-idx is an add-on to ezmlm. It adds multi-message threaded
  message retrieval from the archive, digests, message and subscription
  moderation, and a number of remote administration function. It
  modifies the configuration program ezmlm-make(1) so that it uses a
  text file template rather than compiled-in texts in list creation. In
  this manner, ezmlm-idx allows easy setup of lists in different
  languages and customization of default list setup. ezmlm-idx also adds
  MIME handling, and other support to streamline use with languages
  other than English. As an ezmlm add-on, ezmlm-idx does not work
  without ezmlm and tries to be compatible with ezmlm as much as
  possible.  ezmlm-idx also modifies the ezmlm subscriber database to be
  case insensitive to avoid many unsubscribe problems.

  New in ezmlm-idx-0.40 are better support for announcement lists,
  support for QMQP to offload message distribution onto external hosts,
  simplified optional SQL database use (MySQL or PostgreSQL), more
  flexibility in determining which messages should be moderated, a WWW
  interface to the list archives, and many small improvements.

  ezmlm-idx-0.32 adds improved handling of very large lists with
  optimized bounce handling, ezmlm-split(1) for forwarding (un)subscribe
  requests to sublists to allow sublisting transparent to the
  subscriber, and SQL support to allow sublisting with improved message
  authentication and monitoring of list function, as well as dynamic
  addition/removal/reconfiguration of sublists. Also, subscriber
  ``From:'' lines are logged with support for finding a subscription
  address from a name. The qmail DEFAULT variable is used, if present.
  Together, these additions eliminate the most common problems making
  ezmlm use and administration even easier.

  This document is a FAQ for ezmlm-idx. However, many of the basic items
  that are discussed also apply to ezmlm per se. Referring to the two
  paragraphs above, it should be relatively easy to figure out which
  features require ezmlm-idx.


  11..55..  WWhheerree ccaann II ggeett aallll ooff tthhee eezzmmllmm--rreellaatteedd pprrooggrraammss??

  We have now registered ezmlm.org to make access to ezmlm-idx and
  related programs/documentation easier. www.ezmlm.org is currently an
  alias for Fred B. Ringel's www.rivertown.net/~ezmlm/ and ftp.ezmlm.org
  an alias for Fred Lindberg's ftp.id.wustl.edu.


     DDaann JJ.. BBeerrnnsstteeiinn''ss eezzmmllmm--00..5533

     +o  <ftp://cr.yp.to/pub/software/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.ezmlm.org/pub/qmail/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.ntnu.no/pub/unix/mail/qmail/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.pipex.net/mirrors/qmail/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.jp.qmail.org/qmail/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.rifkin.technion.ac.il/pub/qmail/ezmlm-0.53.tar.gz>

     +o  <ftp://ftp.mira.net.au/unix/mail/qmail/ezmlm-0.53.tar.gz>

     +o  <http://www.qmail.org/>

     TThhee llaatteesstt vveerrssiioonn ooff eezzmmllmm--iiddxx
        ezmlm-idx releases are numbered ``ezmlm-idx-0.xy[z]''.  Versions
        with the same ``x'' are backwards compatible. A change in ``x''
        signifies major changes, some of which _m_a_y require list changes
        (see UPGRADE.idx). However, backwards compatibility with
        ezmlm-0.53 list will be maintained. Thus, this is an issue only
        if you are already using an older version of ezmlm-idx.

        Addition of ``z'' are bug fixes only. Thus, ezmlm-idx-0.301 is
        ezmlm-idx-0.30 with known bugs fixed (but no other significant
        changes).  When available, patches are named
        ``filename-0.xy[z].diff'', where ``0.xy[z]'' corresponds to the
        release to which they apply.  When a number of bugs (or a
        significant bug) are found a bug-fix release is made
        incorporating all the patches for the previous version.

        To get the latest features, look for the highest number (``e.g.
        ezmlm-idx-0.40''). Any bugs in versions with new features are
        expected to be limited to the new features.

        To get the most solid version, get the highest 3-digit number,
        i.e. a bug fix. If you already run a version in that series and
        a new bug fix is released, see CHANGES.idx to determine if it is
        worthwhile to upgrade. Most bugs so far have been relevant only
        when using lists in very unusual ways or with rarely used
        options.


     +o  <ftp://ftp.ezmlm.org/pub/patches/>

     +o  <ftp://gd.tuwien.ac.at/infosys/mail/qmail/ezmlm-patches/> ftp
        mirror in Austria.

     +o  <http://gd.tuwien.ac.at/infosys/mail/qmail/ezmlm-patches/> http
        access to the same mirror.

     +o  <ftp://ftp.win.or.jp/pub/network/mail/qmail/ezmlm-idx/> ftp
        mirror in Japan.

     eezzmmllmmrrcc((55)) ffiilleess ffoorr ddiiffffeerreenntt llaanngguuaaggeess
        The latest versions at the time of release of a package are
        included in that package. Thus, this directory will have a file
        labeled with the current ezmlm-idx version number only if it has
        been updated later than the package.  ezmlmrc(5) files are
        updated and new ones are added all the time, also with bug fix
        releases. Therefore, always look at the latest package. Please
        note that ezmlmrc may change significantly between versions.
        Thus, do not expect the ezmlm-idx-0.324 ezmlmrc.es to work with
        ezmlm-idx-0.40.

        ezmlmrc(5) files contain some release-specific configurations.
        Do not use a later file (other than from bug fix releases) with
        an earlier version of the programs. It is usually OK to use a
        version from an earlier package (see UPGRADE.idx), but some new
        functionality may nor be available.

        To contribute an ezmlmrc(5) file in a new language, start with
        the en_US version from the latest package, and send the gzipped
        file to lindberg@id.wustl.edu. Please leave comments intact and
        in English and do not change the order of items in the file.
        This will facilitate maintenance.


     +o  <ftp://ftp.ezmlm.org/pub/patches/ezmlmrc/>

     +o  <ftp://gd.tuwien.ac.at/infosys/mail/qmail/ezmlm-
        patches/ezmlmrc/>

     +o  <http://gd.tuwien.ac.at/infosys/mail/qmail/ezmlm-
        patches/ezmlmrc/>

     +o  <ftp://ftp.win.or.jp/pub/network/mail/qmail/ezmlm-idx/ezmlmrc/>

     eezzmmllmm--iissssuubb--00..0055

     +o  <ftp://ftp.ezmlm.org/pub/patches/ezmlm-issub-0.05.tar.gz>.  Use
        ezmlm-issub only if you do not use ezmlm-idx. The same
        functionality is available in ezmlm-idx and the packages are not
        compatible.

     +o  Also via mirrors mentioned above.


     RRPPMMss aanndd SSRRPPMMSS ooff qqmmaaiill,, eezzmmllmm aanndd eezzmmllmm--iiddxx

     +o  <ftp://ftp.ezmlm.org/pub/patches/>

     +o  <ftp://summersoft.fay.ar.us/pub/qmail/>


  11..66..  WWhheerree ccaann II ffiinndd ddooccuummeennttaattiioonn ffoorr eezzmmllmm aanndd ppaattcchheess??


     mmaann ppaaggeess
        All ezmlm component programs come with their own man pages.
        Thus, for info on _e_z_m_l_m_-_s_e_n_d, type:


          % man ezmlm-send


     or if you have unpacked ezmlm, but not made it or installed it:


          % cd ezmlm-0.53
          % man ./ezmlm-send.1


     eezzmmllmm((55))
        General info on ezmlm and list directories is in eezzmmllmm..55:


          % man ezmlm


     or


          % cd ezmlm-0.53
          % man ./ezmlm.5


     _N_O_T_E_: Installation of the ezmlm-idx package updates some existing
     man pages to reflect changes made by the patch (e.g.  ezmlm-
     send(1), ezmlm(5)).


     TTeexxtt ffiilleess iinn tthhee ddiissttrriibbuuttiioonn
        ezmlm comes with a RREEAADDMMEE file with general instructions, an
        IINNSSTTAALLLL file with installation instructions, an UUPPGGRRAADDEE file for
        upgrading from a previous version and a CCHHAANNGGEESS file with
        information on changes from previous versions. ezmlm-idx comes
        with similar files suffixed with ``..iiddxx''. Most other patches or
        add-ons contain similar files and man pages and should contain
        identifying suffixes (.iss for ezmlm-issub, for example).  For a
        discussion of the authors' understanding of ezmlm security, see
        ``Ezmlm-idx security''.


     ````EEzzmmaann'''',, aann eezzmmllmm//iiddxx mmaannuuaall
        The ezmlm manual is a brief manual that is meant for list
        subscribers, list moderators and remote administrators, and as
        an introduction for list owners. It is useful even if you do not
        use ezmlm-idx. Features requiring ezmlm-idx are marked as such.
        The manual is available as a set of html files, as a text file,
        and in a ``letter'' and ``A4'' postscript version:

     +o  ezman for download <ftp://ftp.ezmlm.org/pub/patches/ezman/>

     +o  An on-line html version <http://www.ezmlm.org/ezman>


     TThhiiss FFAAQQ
        This FAQ is built from a sgml source. It is available in the
        following formats:

     +o  A text file <ftp://ftp.ezmlm.org/pub/patches/ezfaq.txt.gz>

     +o  An on-line html version <http://www.ezmlm.org/>

     +o  Html for download
        <ftp://ftp.ezmlm.org/pub/patches/ezfaq.html.tar.gz>

     +o  A postscript (letter) version
        <ftp://ftp.ezmlm.org/pub/patches/ezfaq.ps.gz>

     +o  A postscript (A4) version
        <ftp://ftp.ezmlm.org/pub/patches/ezfaq.ps4.gz>

     +o  Via mirrors mentioned for the ezmlm-idx package.

     +o  An up-to-date text version,FFAAQQ..iiddxx, included with the ezmlm-idx
        package.


     WWWWWW rreessoouurrcceess

        AAnn oonn--lliinnee vveerrssiioonn ooff tthhiiss FFAAQQ
           <http://www.ezmlm.org/>The main site with an up-to-date
           mirror list.  <http://www.de.ezmlm.org/>German mirror.
           <http://www.pl.ezmlm.org/www.ezmlm.org/>Polish mirror.
           <http://www.jp.ezmlm.org/>Japanese mirror.
           <http://www.pt.ezmlm.org/>Portuguese mirror.
           <http://www.at.ezmlm.org/>Austrian mirror.
           <http://www.ca.ezmlm.org/ezmlm/>Canadian mirror.

        GGeenneerraall qqmmaaiill aanndd eezzmmllmm iinnffoo

        +o  Dan J. Bernstein's qmail page
           <http://www.pobox.com/~djb/qmail.html>

        +o  Dan J. Bernstein's ezmlm page
           <http://www.pobox.com/~djb/ezmlm.html>

        +o  Russell Nelson's qmail page <http://www.qmail.org>

        +o  Mirrors of www.qmail.org <http://www.ISO.qmail.org>.
           Substitute your two-letter country abbreviation for ``ISO''.

        TThhee qqmmaaiill mmaaiilliinngg lliisstt aarrcchhiivvee


        +o  <http://www.ornl.gov/cts/archives/mailing-lists/qmail/>

        TThhee eezzmmllmm mmaaiilliinngg lliisstt aarrcchhiivvee

        +o  <http://sunsite.auc.dk/mhonarc-archives/ezmlm/>
           <http://www.ezmlm.org/archive/> This archive of the ezmlm
           list is searchable from 11/97-present. ezmlm-cgi(1) is used
           to allow direct access to the sublist archive.

     MMaaiilliinngg lliissttss
        Please read other documentation and mailing list archives before
        posting questions to the lists. It's also useful to ``lurk'' on
        the list for a few days, (i.e. to subscribe and read without
        posting) before asking your questions on the list.

        To subscribe, send mail to the E-mail addresses listed:

     +o  Dan Bernstein's ezmlm list: ezmlm-subscribe@list.cr.yp.to

     +o  A digest version of the ezmlm list fredr-ezmlm-digest-
        subscribe@rivertown.net

     +o  Dan Bernstein's qmail list: qmail-subscribe@list.cr.yp.to

     +o  The Japanese ezmlm list: ezmlm-subscribe@jp.qmail.org

     +o  The Japanese qmail list: qmail-subscribe@jp.qmail.org

     +o  A ezmlm/idx digest list of djb-qmail: qmail-digest-
        subscribe@id.wustl.edu

     +o  A ezmlm/idx sublist of djb-qmail (you can test ezmlm-idx
        commands): qmail-index@id.wustl.edu


  11..77..  WWhheerree ddoo II sseenndd ccoommmmeennttss oonn tthhiiss ddooccuummeenntt??

  To the authors via E-mail:

  +o  Fred Lindberg, lindberg@id.wustl.edu

  +o  Fred B. Ringel, fredr@rivertown.net


  11..88..  HHooww ttoo eexxppeerriimmeenntt wwiitthh nneeww vveerrssiioonnss ooff eezzmmllmm--iiddxx..

  ezmlm-idx>=0.23 writes DDIIRR//ccoonnffiigg in a standard format.  If ezmlm-
  make(1) is invoked with the ``-e'' or ``-+'' switch and the ``DIR''
  argument only, ezmlm-make(1) will read other arguments from this file.
  The difference between the switches is that with ``-e'' the options
  used are the ones specified on the command line, whereas with ``-+''
  they are the ones currently active for the list, as overridden by any
  command line options.  Thus, with just:


               % ezmlm-make -+ DIR


  you can rebuild the list, without affecting any archives, list state
  variables, etc. You will _l_o_s_e _m_a_n_u_a_l _c_u_s_t_o_m_i_z_a_t_i_o_n_s _t_o _s_o_m_e _o_f _y_o_u_r
  _f_i_l_e_s. However, text files and DDIIRR//hheeaaddeerraadddd are protected against
  being overwritten, so that your manual customizations of these files
  are retained. To override this protection, simply specify the used
  edit switch twice, e.g. ``-ee'' and ``-++'', respectively. This is a
  feature introduced in ezmlm-idx-0.40.

  To test a new version of ezmlm-idx or to run several version, make the
  new version as per IINNSSTTAALLLL..iiddxx (if you haven't used ezmlm-idx before)
  or UUPPGGRRAADDEE..iiddxx (if you've got a previous version of ezmlm-idx
  installed), setting ccoonnff--bbiinn to a new directory. You can use either
  the current directory or any other directory. If not using the current
  dir, you also have to:


               % make setup


  If you now edit the list using the new ezmlm-make program, the list
  will automatically be configured to use the new binaries. To change
  back to the ``default'' installation, just edit the list again, this
  time with the old ezmlm-make(1).

  If your system has an //eettcc//eezzmmllmmrrcc file, you may need to temporarily
  place the eezzmmllmmrrcc((55)) file for the ezmlm version you want to test in
  ddoottddiirr of the list and use the ezmlm-make(1) ``-c'' switch (see
  ``Terminology: dotdir'').

  ezmlm-idx>=0.314 comes with ezmlm-test(1), a program that tests most
  functions of ezmlm+idx and can  be used before installation.


  22..  QQuuiicckk ssttaarrtt


  1. Create a use ``eztest'' for testing. If you use another name, add
     the switch ``-u another_name'' to the ezmlm-test(1) line below.
     (The space between the switch and the argument is required.)

  2. Unpack the ezmlm-0.53 distribution.

  3. Unpack the ezmlm-idx distribution.

  4. Move the ezmlm-idx files to the ezmlm-0.53 directory.

  5. Edit ccoonnff--bbiinn and ccoonnff--mmaann to reflect the target directories.

  6. build and install:


               % cd ezmlm-0.53
               % patch < idx.patch
               % make; make man
               % su
               # su eztest
               % ./ezmlm-test
               % exit
               # make setup
               # exit


  7. Make a list and digest list


          % ezmlm-make -rdugm -5 me@host ~/list ~/.qmail-list me-list host
          % ezmlm-sub ~/list me@host
          % ezmlm-sub ~/list/digest me@host
          % ezmlm-sub ~/list/mod me@host


  where ``me'' is your user name and ``host'' the host your list is on.

  Now, you are the owner, remote administrator, and subscriber of both
  list@host and the accompanying digest list list-digest@host. Only
  subscribers are allowed to access the archive and to post. To post to
  the list, mail to list@host. For a user to subscribe, s/he should mail
  to list-subscribe@host and for help to list-help@host.

  When a non-subscriber posts, you will be asked to approve, reject, or
  ignore the request. If you want to subscriber joe@joehost.dom, mail
  list-subscribe-joe=joehost.dom@host.

  Digests are generated about every two days, when 30 messages have
  arrived since the last digest, or when more than 64 kbytes of message
  body has arrived. To manage the digest list, use the same commands as
  the main list, but replace ``list'' with ``list-digest''.

  The sender restriction on posting used in this setup works, but is not
  secure. For more info, read the man pages (start with ezmlm(5) and
  ezmlm-make(1)), this FAQ (FFAAQQ..iiddxx in the distribution),
  RREEAADDMMEE//RREEAADDMMEE..iiddxx, IINNSSTTAALLLL//IINNSSTTAALLLL..iiddxx, and UUPPGGRRAADDEE..iiddxx.


  33..  OOvveerrvviieeww ooff mmaaiilliinngg lliisstt mmaannaaggeemmeenntt aanndd mmaaiilliinngg lliisstt mmaannaaggeerrss

  (To be written. Until then, please consult the
  <http://www.ezmlm.org/ezman/> manual for ezmlm and ezmlm-idx related
  material.)


  44..  OOvveerrvviieeww ooff eezzmmllmm ffuunnccttiioonn


  44..11..  TThhee bbaassiicc sseettuupp..

  In designing ezmlm, _D_a_n _J_. _B_e_r_n_s_t_e_i_n has used the unix philosophy of
  small component programs with limited and well defined functions.
  Requests for specific functions can then be met by the addition of new
  programs.

  Thanks to the program execution mechanism Dan built into qmail, it is
  easy to execute several small programs per delivery in a defined
  sequence. It is also very easy to add shell scripts for further
  customization.


  44..22..  IInnvveennttiioonnss iinn eezzmmllmm..

  Dan J. Bernstein has written ezmlm in C. It is written for speed and
  reliability even in the face of power loss and NFS.  These features
  are augmented to a large extent by the ruggedness of the qmail (also
  by Dan) delivery mechanism (see qmail-command(8)).

  ezmlm uses some routines and techniques that still are not frequently
  seen in many mailing list managers. For example, subscriber E-mail
  addresses are stored in a hash so that searches require reading only,
  at most, 2% of the E-mail addresses.  ezmlm has a optional message
  archive, where messages are stored 100 per directory, again to allow
  more efficient storage and retrieval. Important files are written
  under a new name and, only when safely written, moved in place, to
  assure that crashes do not leave the list in an undefined state.

  In addition, ezmlm has a number of new inventions. One of these is
  bounce detection, which generates an automatic warning containing
  information identifying the messages which have bounced, followed by a
  probe message to the E-mail addresses for which mail has bounced.  If
  the probe bounces, the address is unsubscribed. Thus, the system won't
  remove E-mail addresses due to temporary bounces: it takes 12 days
  after the first bounce before a warning is sent, and another 12 days
  of bounces after the warning bounce before the probe message is set.

  Another Dan J. Bernstein invention is the use of cryptographic cookies
  based on a timestamp, address, and action. These are used to assure
  that the user sending a request to subscribe or unsubscribe really
  controls the target address.  It is also used to prevent forgery of
  warning or probe messages to make it exceedingly difficult to subvert
  the bounce detection mechanism to unsubscribe another user.


  44..33..  TThhee qqmmaaiill ddeelliivveerryy mmeecchhaanniissmm..

  See qmail(7), qmail-local(8), qmail-command(8), envelopes(5), and dot-
  qmail(5).  Briefly, qmail having resolved the delivery address
  delivers it via the ..qqmmaaiill file that most completely matches the
  address. This file may be a link to another file, as is the case in
  ezmlm lists. qmail then delivers the message according to successive
  lines in this file forwarding it to an address, storing it, or piping
  it to a program. In the latter case, the program is expected to exit 0
  leading delivery to proceed to the next line in the ..qqmmaaiill file, or 99
  leading to success without delivery to succeeding lines. An exit code
  of 100 is a permanent error leading to an error message to the SENDER.
  An exit code of 111 is used for temporary errors, leading to re-
  delivery until successful or until the queue lifetime of the message
  has been exceeded.

  Delivery granularity is the ..qqmmaaiill file and re-deliveries start at the
  top. Thus, if the message fails temporarily at a later line, the
  delivery according to an earlier line will be repeated. Similarly,
  qmail may have made deliveries successfully according to most of the
  ..qqmmaaiill file and then fail permanently. The SENDER is informed that the
  delivery failed, but not about at which point.

  ezmlm takes advantage of these basic mechanisms to build a fast,
  efficient, and very configurable mailing list manager from a set of
  small independent programs.


  44..44..  WWhhaatt tthhee ddiiffffeerreenntt pprrooggrraammss ddoo..

  See ezmlm(5) and the man pages for the different programs (listed in
  ezmlm(5)).


  44..55..  WWhhaatt tthhee ddiiffffeerreenntt ffiilleess iinn tthhee lliisstt ddiirreeccttoorryy ddoo..

  See ezmlm(5).


  44..66..  TThhee ppaappeerr ppaatthh ffoorr ppoossttss..

  Messages to the list are delivered to a ..qqmmaaiill file, usually ~~//..qqmmaaiill--
  lliissttnnaammee which is linked to DDIIRR//eeddiittoorr.  Here, the message is first
  delivered to ezmlm-reject(1) which can reject messages based on
  subject line contents, MIME content-type, and message body length. It
  also by default rejects all messages that do not have the list address
  in the ``To:'' or ``Cc:'' header. This eliminates most bulk spam. If
  the list is set up for restrictions based on envelope SENDER, the next
  delivery is to one or more instances of ezmlm-issubn(1).  If the
  messages passed this check, it is usually delivered to ezmlm-send(1)
  for distribution.  If the list is message moderated, it is instead
  delivered to ezmlm-store(1) which queues the message and sends out a
  moderation request.  ezmlm-gate(1) is used by some other setups. It
  will for message moderated lists invoke ezmlm-send(1) directly if the
  message is from a specific set of SENDERs, and in other cases ezmlm-
  store(1) to send the message out for moderation.

  You can specify a separate ..qqmmaaiill-like file for ezmlm-gate(1).  The
  lines will be executed and the return codes determine if the message
  is rejected, sent to the list, or sent to the moderator. See man page
  for details.

  If the list is configured for digests, DDIIRR//eeddiittoorr also contains an
  ezmlm-tstdig(1) line followed by an ezmlm-get(1) line. If ezmlm-
  tstdig(1) determines that the criteria are met for digest generation,
  it exits with an exit code of 0, causing the ezmlm-get(1) line to be
  executed leading to a digest mailing. Otherwise, ezmlm-tstdig(1) exits
  99, resulting in the remainder of the DDIIRR//eeddiittoorr file to be ignored
  too long. The digest is not related to the message being delivered,
  but the delivery is used to trigger execution of the relevant
  programs.


  In addition, DDIIRR//eeddiittoorr contains a number of house-keeping functions.
  These are invocations of ezmlm-warn(1) to send out bounce warnings and
  and (if the list is moderated) ezmlm-clean(1) to clean the moderation
  queue of messages that have been ignored. Again, these functions are
  not related to the specific message delivered, but the delivery itself
  is used as a convenient ``trigger'' for processing.


  44..77..  TThhee eezzmmllmm ppaatthh ffoorr mmooddeerraattiioonn mmeessssaaggeess..

  Replies to moderation requests are channeled to DDIIRR//mmooddeerraattoorr. This
  file contains an invocation of ezmlm-moderate(1) which invokes ezmlm-
  send(1) for accepted messages and sends out a rejection notice for
  rejected messages.  It also sends error messages if the message is not
  found or already accepted/rejected _c_o_n_t_r_a_r_y to the moderation message.
  Thus, if you accept a message already accepted, no error message is
  sent. ezmlm-clean(1) is also invoked from DDIIRR//mmooddeerraattoorr for house
  keeping.


  44..88..  TThhee eezzmmllmm ppaatthh ffoorr aaddmmiinniissttrraattiivvee mmeessssaaggeess..

  Administrative requests for both list and digest lists are captured by
  ~~//..qqmmaaiill--lliissttnnaammee--ddeeffaauulltt linked to DDIIRR//mmaannaaggeerr.  Here they are
  delivered first to ezmlm-get(1) which processed archive retrieval
  requests, exiting 99 after successful completion which causes the rest
  of the delivery lines to be ignored. If the request is not for ezmlm-
  get(1) it rapidly exits 0. This leads to invocation of ezmlm-manage(1)
  which handles subscriber database functions, help messages, and (if
  configured) editing of DDIIRR//tteexxtt// files. Again, ezmlm-warn(1) lines are
  included for bounce directory processing.

  If configured, an ezmlm-request(1) line is present. This program
  constructs valid ezmlm requests from command in the subject lines of
  messages sent to listname-request@host and exits 99. These requests
  are mailed and will then return to be processed by one of the other
  programs.

  44..99..  TThhee eezzmmllmm ppaatthh ffoorr bboouunncceess..

  Bounces to the list are handled by DDIIRR//bboouunncceerr. For the digest list
  this is DDIIRR//ddiiggeesstt//bboouunncceerr. The two were combined in previous
  versions, which is still supported. As this leads to problems with
  list names ending in ``digest'', the functions are separate with lists
  set up or edited with ezmlm-idx>=0.32. The bounce is first delivery is
  to ezmlm-weed(1) which removes delivery delay notification and other
  junk. The second to ezmlm-return(1) which analyzes valid bounces
  storing the information in DDIIRR//bboouunnccee// for the list and
  DDIIRR//ddiiggeesstt//bboouunnccee// for the digest.  This is the information that
  ezmlm-warn(1) (invoked from DDIIRR//eeddiittoorr and DDIIRR//mmaannaaggeerr) uses and
  processes for automatic bounce handling.  ezmlm-return(1) will also
  unsubscribe a subscriber from whom a probe message has bounced.


  44..1100..  MMeessssaaggeess ttoo lliisstt--oowwnneerr aanndd lliisstt--ddiiggeesstt--oowwnneerr..

  These are processed by DDIIRR//oowwnneerr and delivered to DDIIRR//mmaaiillbbooxx by
  default. It is better to put the real owner address in this location.
  This can be done manually, via editing of eezzmmllmmrrcc((55)), or via the
  ezmlm-make(1) -5 switch. Again, some house-keeping functions are also
  executed.


  44..1111..  SSttrruuccttuurree ooff ssuubbssccrriibbeerr ddaattaabbaasseess..

  ezmlm subscriber E-mail addresses are stored within DDIIRR//ssuubbssccrriibbeerrss//
  as a hashed set of 53 files. The hash calculated from the address
  determines which of the 53 files and address is stored in. Thus, to
  find out if an address is a subscriber, ezmlm has to read at most
  about 2% of the E-mail addresses.  The hash function insures that E-
  mail addresses are reasonably evenly distributed among the 53 files.

  Addresses in the files in DDIIRR//ssuubbssccrriibbeerrss// are stored as strings
  starting with ``T'', followed by the address, followed by a zero byte.
  This is the same format as taken by qmail-queue(8) on file descriptor
  1.  Thus, subscriber lists can be directly copied to qmail without any
  further processing.

  With ezmlm-idx>=0.32 you can use an SQL server for the subscriber
  databases.  Please see the SQL section (``ezmlm support for SQL
  datbases'').


  44..1122..  LLooccaall ccaassee iinn EE--mmaaiill aaddddrreesssseess..

  rfc822 states that the host part of an address is case insensitive,
  but that case of the local part should be respected and the
  interpretation of it is the prerogative of the machine where the
  mailbox exists.  Thus, ezmlm preserves the case of the local part, but
  converts the host part to lower case. ezmlm proper also bases the hash
  on the case of the local part, so that USER@host and user@host are not
  (usually) stored in the same file.

  Locally, deliveries are most often case insensitive, i.e. mail to
  USER@host and user@host are delivered to the same mail box. A
  consequence of this is that many users use E-mail addresses with
  different case interchangeably.  The problem is that when USER@host is
  subscribed, ezmlm will not find that address in response to an
  unsubscribe request from user@host. This is even more problematic when
  E-mail addresses have been added by hand to e.g. moderator lists.

  ezmlm-idx>=0.22 changes address storage to make comparisons case
  insensitive and store E-mail addresses based on the hash of the all
  lower case address. Case is maintained for the local part. Thus, if
  USER@host is subscribed, mail is set to USER@host, but user@host is
  recognized as a subscriber and an unsubscribe request from user@host
  will remove USER@host from the subscriber list.

  To maintain backwards compatibility with old subscriber lists, a
  second lookup is made for partially upper case E-mail addresses in
  some cases. This will find USER@host subscribed with a case sensitive
  hash as well.

  If may be useful to move all old mixed case E-mail addresses to the
  ``new'' positions.  Without this, USER@host subscribed with the old
  system will be able to unsubscribe as USER@host, but not as user@host.
  After the repositioning, s/he will be successfully able to use any
  case in an unsubscribe request, e.g. UsEr@host. To do this:


       % ezmlm-list DIR | grep -G '[A-Z]' > tmp.tmp
       % xargs ezmlm-sub DIR < tmp.tmp


  This works, because subscribing an address, even if it already exists,
  will assure that it is stored with a case insensitive hash. On some
  systems, the grep ``-G'' switch need/should not be used.


  44..1133..  TTeessttiinngg SSEENNDDEERR ttoo aallllooww ppoossttss oonnllyy ffrroomm lliisstt ssuubbssccrriibbeerrss..

  This mode of operation is automatically set up if you specify the
  ezmlm-make(1) ``-u'' switch. Since there may be some addresses that
  should be allowed to post, but are not subscribers of list or list-
  digest, ezmlm-make(1) sets up an additional address database in
  DDIIRR//aallllooww//.  Use ezmlm-sub(1), ezmlm-unsub(1), and ezmlm-list(1) to
  manipulate these addresses. If the list is configured for remote
  administration (see ``How remote administration works''), you can
  add/remove addresses from the DDIIRR//aallllooww// database by mailing list-
  allow-subscribe@listhost and list-allow-unsubscribe@listhost,
  respectively. Other commands that access subscriber databases work in
  the same manner.

  To similarly restrict archive access, use the ezmlm-make(1) ``-g''
  switch.

  Since SENDER is under the control of a potential attacker, it is not
  secure to use tests of SENDER for anything important. However, when
  replies are always sent to SENDER (such as for archive access), a
  check of SENDER can prevent the sending of information to E-mail
  addresses not in the database.

  To test sender, use the program ezmlm-issubn(1). It will return 0
  (true for the shell, success for qmail deliveries) if SENDER is in at
  least one of a set of subscriber databases. If not, it will return 99
  (false for the shell: success, but skip remainder of ..qqmmaaiill file for
  qmail deliveries). The basedirs of the subscriber lists (i.e. the
  directories in which the ``subscriber'' dirs are located) are given as
  arguments.  ezmlm-issubn(1) can take any number of arguments.

  Thus, to permit an action if SENDER is a subscriber to the list in any
  of DDIIRR//, DDIIRR//ddiiggeesstt//, or DDIIRR//aallllooww// and exit silently, put the
  following into the relevant ..qqmmaaiill file:


  |/usr/local/bin/ezmlm/ezmlm-issubn DIR DIR/digest DIR/allow [...]
  |/path/action_program


  Restricting your list to posts from your subscribers is as easy as
  that. If your ezmlm binaries are in a different directory, you may
  have to modify the ezmlm-issubn(1) path.

  ezmlm-issubn(1) has a ``-n'' switch which ``negates/reverses'' the
  exit code.  To do an action if SENDER is _N_O_T a subscriber of any of
  the lists:


       |/usr/local/bin/ezmlm/ezmlm-issubn -n DIR/deny [dir2 ...]
       |/path/other_program


  To automatically configure the list with a blacklist address database
  in DDIIRR//ddeennyy, use the ezmlm-make(1) ``-k'' switch. If the list is
  configured for remote administration (see ``How remote administration
  works'') and if you are a remote administrator, you can manipulate the
  ``deny'' database remotely by sending mail to list-deny-subscribe-
  user=userhost@listhost, etc.


  44..1144..  HHooww ccooookkiieess wwoorrkk..

  Each ezmlm list has it's own ``key'' created by ezmlm-make at setup
  time.  This key is stored in DDIIRR//kkeeyy, and you can improve it by adding
  garbage of your own to it. However, changing the key will make all
  outstanding cookies invalid, so this should be done when the list is
  established.

  When ezmlm receives an action request, such as ``subscribe'', it
  constructs a cookie as a function of:

  +o  the request,

  +o  the time,

  +o  and the target address.

     The cookie and these items are then assembled into a address that
     is sent out as the ``Reply-To:'' address in the confirmation
     request sent to the subscriber. When the subscriber replies, ezmlm
     first checks if the timestamp is more than 1,000,000 seconds old
     (approx 11.6 days) and rejects the request if it is. Next, ezmlm
     recalculates the cookie from the items.  If the cookies match, the
     request is valid and will be completed. Depending on the
     circumstances, ezmlm generates an error message or a new cookie
     based on the current time and sends the target a new confirmation
     request.

  Dan has based these cookies on cryptographic functions that make it
  very unlikely that a change in any part of the cookie or the items
  will result in a valid combination. Thus, it is virtually impossible
  to forge a request even for someone who has a number of valid requests
  to analyze. Since the algorithm ezmlm uses is available, the security
  rests on the key (and the correctness of the algorithm). Anyone who
  knows the key for your lists can easily construct valid requests.

  As ezmlm-make(1) doesn't use a truly random process to generate the
  key, it is theoretically possible that someone with sufficient
  knowledge about your system can guess your key. In practice, this is
  very unlikely, and the safety of the system is orders of magnitude
  higher than that of other mechanisms that you may rely on in your list
  management and mail transport (exclusive of strong encryption, such as
  _P_G_P).


  44..1155..  HHooww mmooddeerraattoorr EE--mmaaiill aaddddrreesssseess aarree ssttoorreedd..

  Moderator E-mail addresses are stored just like ezmlm subscriber
  addresses, in a set of up to 53 files within the ssuubbssccrriibbeerrss
  subdirectory of the list's bbaasseeddiirr//.  For subscribers, the bbaasseeddiirr// is
  the list directory itself, i.e. DDIIRR//.  For moderators, the default is
  DDIIRR//mmoodd//, which can be overridden by placing a bbaasseeddiirr name (starting
  with a ``/'') in DDIIRR//mmooddssuubb, DDIIRR//rreemmoottee, or DDIIRR//mmooddppoosstt for
  subscription moderation, remote administration, and message
  moderation, respectively. This permits the use of one moderator
  database for multiple lists. _N_o_t_e_: _S_u_b_s_c_r_i_p_t_i_o_n _m_o_d_e_r_a_t_o_r_s _a_n_d _r_e_m_o_t_e
  _a_d_m_i_n_i_s_t_r_a_t_o_r_s _a_r_e _a_l_w_a_y_s _t_h_e _s_a_m_e _a_d_d_r_e_s_s_e_s_. _I_f _b_o_t_h DDIIRR//mmooddssuubb and
  DDIIRR//rreemmoottee contain paths, only the DDIIRR//mmooddssuubb path is used.


  44..1166..  HHooww ssuubbssccrriippttiioonn mmooddeerraattiioonn wwoorrkkss..

  Subscription moderation is a simple extension of the ezmlm subscribe
  mechanism. Once the user has confirmed the subscribe request, a new
  request is constructed with a _d_i_f_f_e_r_e_n_t _a_c_t_i_o_n _c_o_d_e. This is sent out
  to the moderator(s). When a moderator replies with a valid request and
  cookie combination, the user is subscribed. The user is then also
  welcomed to the list. Other moderators won't know that the request has
  already been approved. If other moderators reply to the request, no
  notification of the duplicate action is sent to the subscriber of the
  duplicate action. Ezmlm knows that this is a repeat request since the
  target address is already a subscriber.

  The moderators are not informed about the result, unless there was an
  error (subscribing a target that is already a subscriber is not
  considered an error). This cuts down the number of messages a
  moderator receives. Any list moderator knows (or _s_h_o_u_l_d know) the
  qmail/ezmlm/unix paradigm: _i_f _y_o_u_'_r_e _n_o_t _t_o_l_d _o_t_h_e_r_w_i_s_e_, _y_o_u_r _c_o_m_m_a_n_d
  _w_a_s _c_a_r_r_i_e_d _o_u_t _s_u_c_c_e_s_s_f_u_l_l_y.  This may be counterintuitive to those
  used to some other operating systems, but in our experience it doesn't
  take long to get used to the reliability and efficiency of
  U*ix/qmail/ezmlm.

  Subscription moderation is enabled by creating DDIIRR//mmooddssuubb and adding
  the subscription moderator to DDIIRR//mmoodd//:


       % ezmlm-sub DIR/mod moderator@host


  To use an alternative basedir for subscription moderators, place that
  directory name with a leading ``/'' in DDIIRR//mmooddssuubb.


  44..1177..  HHooww rreemmoottee aaddmmiinniissttrraattiioonn wwoorrkkss..

  The term ``remote administration'' is used to denote the ability of a
  list administrator by E-mail to add or remove any E-mail address from
  the subscriber list without the cooperation of the user. Normally,
  when user@userhost sends a message to list-subscribe-
  other=otherhost@listhost to subscribe other@otherhost, the
  confirmation request goes to other@otherhost. However, if remote
  administration is enabled and user@userhost is a moderator, a
  confirmation request (with a different action code) is sent back to
  user@userhost instead. The reply from the administrator is suppressed
  in the welcome message sent to the new subscriber (other@otherhost).
  This protects the identity of the remote administrator.

  Remote administration is enabled by creating DDIIRR//rreemmoottee and adding the
  remote administrator E-mail address(es) to DDIIRR//mmoodd//:


       % ezmlm-sub DIR/mod remoteadm@host


  To use an alternative basedir for remote administrators, place that
  directory name with a leading ``/'' in DDIIRR//mmooddssuubb.  Remote administra-
  tors and subscription moderators databases always consist of the same
  E-mail addresses.  If both are enabled and one of DDIIRR//mmooddssuubb and
  DDIIRR//rreemmoottee contains an alternative basedir name, this basedir is used
  for both functions.  If both DDIIRR//mmooddssuubb and DDIIRR//rreemmoottee contain direc-
  tory names, the one in DDIIRR//mmooddssuubb is used for both functions.

  Remote administrators can add and remove addresses to the digest list,
  the ``allow'' list (user aliases for lists using SENDER restrictions
  on posting and archive access), and if used the ``deny'' list
  containing addresses that are denied posting rights to the list. The
  latter is easy to circumvent and intended to block errant mail robots,
  rather than human users.


  44..1188..  HHooww mmeessssaaggee mmooddeerraattiioonn wwoorrkkss..

  ezmlm-store(1), invoked in DDIIRR//eeddiittoorr, receives messages for message
  moderated lists. If DDIIRR//mmooddppoosstt does not exist, ezmlm-store(1) just
  calls ezmlm-send(1) and the message is posted to the list as if it
  were not moderated.  If DDIIRR//mmooddppoosstt exists, ezmlm-store(1) places the
  message in DDIIRR//mmoodd//ppeennddiinngg//.  It also sends a moderation request to
  all the moderators. Included with this request is a copy of the
  message.  The ``From:'' and ``Reply-To:'' E-mail addresses contain
  codes for ``reject'' and ``accept'', together with a unique message
  name (derived from the message timestamp and process id) and a cookie
  based on these items.  When a moderator replies, ezmlm-moderate(1) is
  invoked via DDIIRR//mmooddeerraattoorr.  ezmlm-moderate(1) validates the request,
  and if the request is valid and the message is found in
  DDIIRR//mmoodd//ppeennddiinngg//, it carries out the requested action.

  If the request is ``reject'' the post is returned to SENDER with an
  explanation and an optional moderator comment. If the request is
  ``accept'' the message is posted to the list via ezmlm-send(1). As the
  request is processed, a stub for the message is created in
  DDIIRR//mmoodd//rreejjeecctteedd// or DDIIRR//mmoodd//aacccceepptteedd// for ``reject'' and ``accept''
  requests, respectively.

  If a valid reply is received but the message is no longer in
  DDIIRR//mmoodd//ppeennddiinngg//, ezmlm-moderate(1) looks for the corresponding stub
  in DDIIRR//mmoodd//rreejjeecctteedd// and DDIIRR//mmoodd//aacccceepptteedd//.  If the stub is found and
  the fate of the message was the one dictated by the new request, no
  further action is taken. If, however, no stub is found or the request
  and the actual message fate do not match, a notification is sent to
  the moderator. This scheme was chosen to impart a maximum of
  information with a minimum of messages. Also, it is the least
  demoralizing setup for multiple moderator lists, where it is important
  not to notify subsequent moderators that their work was in vain since
  the action of the first responding moderator has already resulted in
  processing of the message.

  If a message is not ``rejected'' or ``accepted'' it remains in
  DDIIRR//mmoodd//ppeennddiinngg// until it times out. Cleanup of both messages and
  stubs is accomplished by ezmlm-clean(1) which is invoked through both
  DDIIRR//eeddiittoorr and DDIIRR//mmooddeerraattoorr for message moderated lists. ezmlm-
  clean(1) looks at the timestamp used to generate the message/stub
  name. If it is older than 120 hours (configurable in a range of 24-240
  hours, by placing the value in DDIIRR//mmooddttiimmee) it is removed.  Unless
  suppressed with the ezmlm-clean(1) ``-R'' switch, the SENDER of the
  message is notified.

  By default, the E-mail addresses of message moderators are stored as a
  subscriber list with a basedir of DDIIRR//mmoodd//.  This can be changed to
  any other bbaasseeddiirr by placing the name of that directory with a leading
  ``/'' in DDIIRR//mmooddppoosstt.  Although the default basedirs for message
  moderation and subscription moderation/remote administration are the
  same, both the functions and actors are entirely independent.


  44..1199..  HHooww QQMMQQPP ssuuppppoorrtt wwoorrkkss

  qmail processes messages on a first-come-first-served basis. This
  means that when it receives a post to 100,000 subscribers, it will try
  all the recipients before processing the next message. Often, it is
  desirable to offload this work to an external host so that the main
  list host remains responsive to e.g. ``subscribe'' and archive access
  commands, as well as to other mail is it is not a dedicated mail host.

  ezmlm-idx allows the main distribution work to be offloaded to an
  external server via the QMQP protocol. Configure qmail-qmqpc(1) on the
  list host, and qmail-qmqpd(1) on the mail host (see qmail docs for
  details), then create the file DDIIRR//qqmmqqppsseerrvveerrss//00. The list housed in
  DDIIRR will now use the QMQP server for posts, by the local qmail for
  other messages. If you apply the qmail-qmqpc.tar.gz patch (included in
  the ezmlm-idx distribution), you can specify the QMQP server IP
  addresses, one per line, in DDIIRR//qqmmqqppsseerrvveerrss//00, just as you normally
  would in //vvaarr//qqmmaaiill//ccoonnttrrooll//qqmmqqppsseerrvveerrss.  If the first server cannot
  be contacted, the installation will try the second, and so on. The
  advantage of controlling the servers locally is that you can specify
  different servers for different lists. A good idea is to set up also
  the list host as a QMQP server and use that as the last IP address.
  This way, the list host will be used if the main QMQP server cannot be
  contacted. Of course, ezmlm does not loose messages, but rather lets
  qmail redeliver the post if no QMQP server is available.


  44..2200..  HHooww mmeessssaaggeess aarree ssttoorreedd iinn tthhee aarrcchhiivvee..

  The structure of the ezmlm list archive is described in the ezmlm(5)
  manual page.  Basically, the message is stored in DDIIRR//aarrcchhiivvee//nn//mm,
  where ``n'' is the message number divided by 100 and ``m'' the
  remainder (2 digits). The first message is stored in DDIIRR//aarrcchhiivvee//00//0011.


  44..2211..  HHooww tthhee mmeessssaaggee iinnddeexx wwoorrkkss..

  The ezmlm-idx(1) adds the option (default) of a message index to
  ezmlm.  The ``From:'' line, the subject, the author's E-mail address
  and name and the time of receipt are logged for each message as it is
  received. The subject is ``normalized'' by concatenating split lines
  and removing reply-indicators such as ``Re:''. A hash of the
  normalized subject with all white space removed is also stored.  The
  hash for any message within a thread is almost always the same and is
  used together with the order of receipt to connect a set of messages
  into a ``thread''. A hash is needed due to the inconsistent handling
  by MUAs of white space in rfc2047-encoded subject headers.

  The message index is stored as DDIIRR//aarrcchhiivvee//nn//iinnddeexx, where ``n'' is the
  message number mod 100.  Thus, the directory DDIIRR//aarrcchhiivvee//5522// stores
  messages 5200 through 5299 and the file ``index'' which contains the
  index for those messages.

  The message index can be retrieved with the -index command (see ezmlm-
  get(1)). You can also retrieve a range of messages, a specific thread,
  or generate a message digest (see ezmlm-get(1)). Each of these
  commands can be disabled or restricted as desired by the list owner.

  The ezmlm-idx(1) can be used at any time to either reconstruct an
  existing index or create one an index for an existing message archive.
  without one.


  44..2222..  HHooww tthhrreeaaddiinngg wwoorrkkss..

  A ezmlm thread is just a message number-ordered set of messages with
  identical ``normalized'' subject entries. This is a very reliable
  method for threading messages. It does not rely on any variably
  present ``In-Reply-To:'' or ``References:'' headers. If the subject
  changes, the continuation becomes a separate thread very close to the
  original thread in a digest. ezmlm uses this mechanism to return
  message sets threaded and with a thread and author index, unless
  specifically told not to do so with the ``n'' format specifier.
  Naturally, lists set up without a message index (using the ezmlm-make
  ``-I'' switch) do not maintain thread information.


  44..2233..  HHooww ddiiggeessttss wwoorrkk..

  A ``digest'' is just an ordered collection of messages from a list,
  usually sent out regularly depending on the time and traffic volume
  since the last digest. Digest subscribers thus can read messages as
  ``threads'' once daily, rather than receiving a constant trickle of
  messages.

  As a major change in ezmlm-idx-0.30, the digest is no longer a totally
  separate ezmlm-list, but a part of the main list. This has security
  advantages, makes setup and administration easier, saves space, and
  allows a consistent way for subscribers of both ``list'' and ``list-
  digest'' to retrieve missed messages from a single archive.

  The digest of the list ``list'' is always called ``list-digest''. To
  set up a list with a digest, simply use the ezmlm-make(1) ``-d''
  switch. You subscribe to and unsubscribe from a digest the same way as
  for the main list, except that the request is sent to e.g. list-
  digest-subscribe@host rather than to list-subscribe@host.

  Any option such as remote admin or subscription moderation that is
  active for the list applies also to the digest list. Any restrictions
  in posts or archive retrieval set up for the list, automatically
  accept both subscribers of the main list and of the digest list.

  The changes in ezmlm-idx>=0.30 allow all programs to service both list
  and list-digest functions.  All digest-specific files are stored in
  DDIIRR//ddiiggeesstt//.  Digest list subscriber addresses in
  DDIIRR//ddiiggeesstt//ssuubbssccrriibbeerrss// and digest list bounce information in
  DDIIRR//ddiiggeesstt//bboouunnccee//. Text files are shared between list and digest. To
  get the local part of the list or list-digest name in a context
  sensitive manner, use ``<#l#>'' (lower case ``L'') in the text file.


  In order to generate digest, the list needs to be archived and indexed
  (both default).  You can retrieve sets of messages from the message
  archive. Such sets are always returned to the SENDER of the request.
  ``Digests'' are a special form of such a set/request. First, there are
  no restrictions on the number of messages that can be in a digest
  (which is balanced by the requirement for a ``digest code'' that needs
  to be specified in order to create a digest based on a mailed
  request).  Second, special files (DDIIRR//ddiiggiissssuuee and DDIIRR//ddiiggnnuumm) keep
  track of the digest issue and the message number, amount, and time
  when the last digest was created.  Thus, the system is adapted to make
  it easy to create the regular collections of messages commonly
  referred to as ``digests''.

  Digest can be generated in several different ways:

     CCoommmmaanndd lliinnee
        ezmlm-get can be invoked on the command line, or via a script
        from e.g.  crond(8):


                  % ezmlm-get DIR


     If for some reason the digest should be disseminated via a separate
     list, the digest can be redirected to a ``target address'' with the
     ezmlm-get(1) ``-t'' switch. This may be useful if a non-standard
     digest list name is required. In this case, the list disseminating
     the digest must be set up as a sublist of the main list (see ``How
     sublists work'').


     ffrroomm DDIIRR//eeddiittoorr
        This is the default and does not require and additional setup.
        It works well with most lists. The only possible advantage is
        for very low traffic lists and for lists where it is important
        that a digest be sent out at a specific time (as DDIIRR//eeddiittoorr
        digests are triggered only when messages are received).

        In DDIIRR//eeddiittoorr, ezmlm-get(1) needs to be combined with ezmlm-
        tstdig(1) so that digests are generated only if certain criteria
        are met (in this case, more than 30 messages, 64 kbytes of
        message body or 48 hours since the latest digest). Add these
        lines after the ezmlm-send line in DDIIRR//eeddiittoorr:


                  |/usr/local/bin/ezmlm/ezmlm-tstdig -t48 -m30 -k64 DIR || exit 99
                  |/usr/local/bin/ezmlm/ezmlm-get diglist@host DIR || exit 0


     To set this up automatically when you create the list:


                  % ezmlm-make -d DIR dot local host [code]


     Again, the ezmlm-get(1) ``-t'' switch can be used for non-standard
     arrangements to redirect the digest.  The ezmlm-make(1) ``-4''
     switch can be used to specify alternative ezmlm-tstdig(1) parame-
     ters.

     ffrroomm DDIIRR//mmaannaaggeerr
        This is useful only if you want digests at specific times, and
        you do not have access to crond(8) on the list host.  ezmlm-
        get(1) is in it's normal place in DDIIRR//mmaannaaggeerr before ezmlm-
        manage(1), but a digest code is specified in the ezmlm-get(1)
        command line. To trigger digests requires a regular trigger
        messages generated from e.g. crond(8) (see below), but this can
        be done from _any_ host, not only the list host.  ezmlm-make(1)
        sets up ezmlm-get(1) this way if a digest ``code'' is given as
        the 5th ezmlm-make(1) command line argument. However, you need
        to set up the trigger messages separately (see below):


                  % ezmlm-make DIR dot local host code


     To also test for message volume with this setup, generate trigger
     messages with the granularity you'd like, and add a ezmlm-tstdig(1)
     line to DDIIRR//mmaannaaggeerr. E.g., use a trigger message every 3 hours and
     the following ezmlm-tstdig(1) line before ezmlm-get(1):


                  |/usr/local/bin/ezmlm/ezmlm-tstdig -t24 -m30 -k64 DIR || exit 99


     In general, a cron-triggered digest is preferred for very large
     lists and for lists with very low traffic.  Again, the ezmlm-get(1)
     ``-t'' switch can be used for non-standard arrangements to redirect
     the digest.  For most lists, the digesting from DDIIRR//eeddiittoorr works
     very well, and does not require any extra setup work.

     CCoommbbiinnaattiioonn sseettuuppss
        The default setup in the ezmlmrc(5) file included in the
        distribution is the DDIIRR//eeddiittoorr triggered setup described above.
        If you in addition use ezmlm-cron(1) or crond(8) directly to
        generate trigger messages to list-dig.code@host, you can get
        regular digests (via the trigger messages and DDIIRR//mmaannaaggeerr), with
        extra digest sent when traffic is unusually high (via the ezmlm-
        tstdig/ezmlm-get limits set in DDIIRR//eeddiittoorr).  This works best
        when the time argument on the ezmlm-tstdig(1) command line is
        the same as the trigger message interval, and the other ezmlm-
        tstdig(1) parameters are set so that they are only rarely
        exceeded within the normal digest interval.


  44..2244..  HHooww WWWWWW aarrcchhiivvee aacccceessss wwoorrkkss..

  If the list is set up with ezmlm-make -i, ezmlm-archive(1) will be
  invoked from DDIIRR//eeddiittoorr. This program creates indices for threads,
  subjects, and authors under DDIIRR//aarrcchhiivvee from the iinnddeexx files.  ezmlm-
  cgi(1) is set up per user or globally (see man page) and told about
  different lists via the //eettcc//eezzmmllmm//eezzccggiirrcc file. ezmlm-cgi(1) presents
  and used the index created by ezmlm-archive(1) and converts these and
  the messages to html on-the-fly. To be as efficient as possible,
  ezmlm-cgi(1) outputs only basic html. However, style sheets are
  supported and can be used to customize formatting without modification
  of ezmlm-cgi(1).  Extra buttons can be added via the config file. See
  man page for details.


  44..2255..  HHooww eezzmmllmm--ttssttddiigg wwoorrkkss..

  ezmlm-tstdig(1) looks at DDIIRR//nnuumm and DDIIRR//ddiiggnnuumm to determine how many
  messages and how much traffic (in terms of bytes of message body) has
  arrived to the list since the latest digest. It also determines how
  much time has passed since the last digest was generated. If any of
  the criteria specified by command line switches exists, ezmlm-
  tstdig(1) exits 0, causing the invocation of the next line in the
  .qmail file. If not, ezmlm-tstdig(1) exits 99 causing qmail to skip
  the rest of the .qmail file. ezmlm-tstdig(1) looks at LOCAL to
  determine if it is invoked in the command line, in DDIIRR//eeddiittoorr, or in
  DDIIRR//mmaannaaggeerr. In the latter two cases, ezmlm-tstdig(1) verifies that
  the list local address is correct. If invoked in DDIIRR//mmaannaaggeerr, ezmlm-
  tstdig(1) exits 0 for all action requests except list-dig, so that is
  does not interfere with the normal functions of ezmlm-get(1) and
  ezmlm-manage(1). ezmlm-tstdig(1) uses DDIIRR//ttssttddiigg as a flag to avoid
  problems caused by starting the program when another copy is already
  running.

  ezmlm-make(1) automatically configures ezmlm-tstdig(1) with the
  parameters ``-t48 -m30 -k64'', which can be overridden with the ``-3''
  switch.


  44..2266..  HHooww ssuubblliissttss wwoorrkk..

  ezmlm uses the concept of sublists.  Sublists are regular ezmlm lists,
  except that they only accept messages from their parent list, which is
  placed in the file DDIIRR//ssuubblliisstt.

  sublists are used to split the load of a large mailing list among
  several hosts. All you need to do to set up a local sublist of e.g.
  the qmail@list.cr.yp.to list is to create a ezmlm list, and put
  ``qmail@list.cr.yp.to'' into DDIIRR//ssuubblliisstt of you list, and subscribe
  the sublist to the main qmail list. Now anyone can subscribe to your
  local list which handles its own bounces, subscribe requests, etc.
  The load on the main list is only the single message to your local
  list.

  Sublists will not add their own mailing list header and they will not
  add a subject prefix. Normally, sublists will use their own message
  number, rather than that used by the main list.  With ezmlm-idx>=0.23,
  sublists that are not archived and not indexed, will instead use the
  main list message number. This way, bounce messages from the sublist
  can refer the subscriber to the main list archive. This is not done
  for indexed/archived sublists for security reasons (an attacker could
  overwrite messages in the sublist archive).

  With ezmlm-idx>=0.31, there is support for using ezmlm as a sublist of
  a mailing list run by another mailing list manager. To set this up,
  set up a normal ezmlm sublist, then edit DDIIRR//eeddiittoorr so that the _e_z_m_l_m_-
  _s_e_n_d line contains the command line option ``--hh _X_-_L_i_s_t_p_r_o_c_e_s_s_o_r_-
  _V_e_r_s_i_o_n_:'' (before DDIIRR). As the header text, you need to use a header
  that the main list manager adds to messages. Now your sublist will
  accept only messages from the main list requiring that they come from
  that list _a_n_d contain the header specified.

  ezmlm-idx>=0.313 also has added protection against the malicious
  subscription of the ezmlm list to mailing lists run by other list
  managers. If the ezmlm-reject(1) line in DDIIRR//eeddiittoorr has ``-h'' and
  ``DDIIRR'' on it, ezmlm-reject(1) will read DDIIRR//hheeaaddeerrrreejjeecctt and reject
  messages that have any header specified in that file. See the ezmlm-
  reject(1) man page for suitable headers.


  44..2277..  HHooww ssuubblliissttiinngg ccaann bbee mmaaddee ttrraannssppaarreenntt ttoo tthhee uusseerr..

  Often you create a local sublist of a list that you do not control.
  Local users know to subscribe to your local list. However,
  occasionally, you want to run your own list as a main list and a
  series of sublists per geographic site, or split onto several hosts if
  the list is too large to be handled by a single computer. You may also
  want to split the load of a ``well known'' list host that is getting
  overwhelmed with traffic. ezmlm supports sublists, but here the fact
  that the user has to interact with the correct sublist is a problem.
  What if the user doesn't remember which sublist s/he is subscribed to?
  What if you change the name of a sublist host or move a sublist to a
  different host?

  ezmlm-idx&-0.32 adds ezmlm-split(1), which allows sublisting
  transparent to the user. This program is invoked before ezmlm-
  manage(1) in DDIIRR//mmaannaaggeerr. If it detects a subscribe or unsubscribe
  command, it will forward the command to the appropriate sublist based
  on a ``split file'' DDIIRR//sspplliitt. This file contains entries, one per
  line, of the format:


               domain:lo:hi:sublistname@sublisthost
               edu:::othersub@otherhost
               :1:26:third@thirdhost


  For each address, a hash in the range 0-52 is calculated. The
  ``domain'' is the last two parts of the host name, reversed. Thus, for
  id.wustl.edu it would be ``edu.wustl''. The domain is considered to
  match if the characters in the split file match. It is advisable to
  use only the last part of the domain for compatibility with the SQL
  version version  (see section ``ezmlm support for SQL datbases'').

  Thus, any address *@*.domain with a hash between ``lo'' and ``hi''
  inclusive would match the first line and be forwarded to
  sublistname@sublisthost.  *@*.edu (independent of hash) would match
  the second line and be forwarded to othersub@otherhost. Of remaining
  requests, a request for any target address with a hash between 1 and
  26 would be forwarded to the sublist third@thirdhost. Remaining
  requests would be passed on to the local list.

  The domain is useful for ``geographic'' splitting, and the hash for
  load splitting (within a domain). The user interacts only with the
  main list, and does not need to know from which sublist s/he is
  serviced.

  ezmlm-idx sublists use the message number of the main list message if
  they are not indexed. This allows sublists to in bounce messages refer
  the subscriber to the main list archive. Use ezmlm-make(1) in
  conjunction with ezmlmsubrc(5) to set up the sublists. See man pages
  for further details.

  Since the addresses are stored locally, the system is very fast and
  robust, but it is difficult to add new sublists. ezmlm-split(1) -D
  supports parsing addresses on stdin and splitting them to stdout (see
  man page). Thus, if you divide the domain of some sublist(s) onto a
  net set of sublists, you can use ezmlm-list(1) to collect the
  addresses, ezmlm-split -D with the new split file to split them, then
  after clearing the local subscriber databases use ezmlm-sub(1) to add
  the correct addresses to each new sublist.  The section on SQL support
  describes an alternative way of managing sublists (see section ``ezmlm
  support for SQL datbases'').

  44..2288..  HHooww ttoo sseerrvviiccee ccoommmmaannddss iinn tthhee ssuubbjjeecctt lliinnee..

  Rfc2142 (standards track) says that for each mailing list list@host,
  there MUST be an administrative address list-request@host. This is not
  the default for ezmlm, but can be added with ezmlm-make(1) ``-q'',
  which adds a ezmlm-request(1) line before the ezmlm-manage(1) line in
  DDIIRR//mmaannaaggeerr. This address is used to manage commands in the
  ``Subject:'' line, by translating them into appropriate ezmlm command
  messages.

  When migrating from other mailing list managers which use this method
  to issue list commands, configuring ezmlm to respond to such commands
  may be useful. In addition, some software manufacturers sell MUAs and
  mail gateways that are unable to correctly transport rfc822-compliant
  Internet mail with certain characters in the local part of the
  address.

  ezmlm-request(1) services the list-request@host address per rfc2142
  (standards track). It is usually invoked in DDIIRR//mmaannaaggeerr before ezmlm-
  get(1) and ezmlm-manage(1). It ignores all requests that are not for
  the list-request address. For requests to the list-request@host
  address, ezmlm-request(1) parses the ``Subject:'' line. If a ezmlm
  command address starting with the contents of DDIIRR//oouuttllooccaall (e.g. list-
  get45) is on the command line, ezmlm-request(1) generates the
  corresponding full ezmlm request message. If the subject does not
  start with the contents of DDIIRR//oouuttllooccaall, ezmlm-request(1) prefixes the
  line with the contents of DDIIRR//oouuttllooccaall, thereby building a complete
  ezmlm command. If a host name is specified, it must match the contents
  of DDIIRR//oouutthhoosstt, i.e. ezmlm-request(1) in this function will only
  generate command messages for the local list.

  Thus, a subject of ``subscribe'' to list-request@host will be auto-
  magically rewritten as a message to list-subscribe-
  userlocal=userhost@host.  Similarly, any ezmlm command or ``Reply-
  To:'' address can be pasted into the subject field and sent to list-
  request@host.  ezmlm-request(1) does not validate the command name,
  but invalid commands result in a ``help'' message in reply via ezmlm-
  manage(1). This allows ezmlm-request(1) to also service custom
  commands, like list-faq@host that you may have created for your list.

  If the ``Subject:'' is empty or does not start with a letter, ezmlm-
  request(1) will attempt to interpret the first message body line that
  starts with a letter in the first position.

  When ezmlm-request(1) has successfully processed a ''request''
  command, it exits 99 to skip the rest of DDIIRR//mmaannaaggeerr.

  To set up a list to include ezmlm-request processing, use the ezmlm-
  make(1) ``-q'' switch. The default is to not do this.


  44..2299..  HHooww ttoo ssuuppppoorrtt aalltteerrnnaattiivvee ccoommmmaanndd nnaammeess..

  ezmlm-idx>=0.23 allows alternate names for all user commands. This can
  be used to e.g. make a message to list-remove@host to result in an
  ``unsubscribe'' action. This may help migration from other mailing
  list managers and in non-English environments. The use of aliases
  allows ezmlm to respond to new command names, while always responding
  correctly to the standard commands. If ezmlm-request(1) is used it
  will automatically be able to deal with any commands you set up for
  the list, within ezmlm or as separate programs.  See ``Multiple
  language support'' on how to set up command aliases.


  44..3300..  HHooww ttoo aadddd yyoouurr oowwnn ccoommmmaannddss..

  The qmail/ezmlm mechanism makes it very easy to add your own commands.
  You can add them to DDIIRR//mmaannaaggeerr, but this requires great care in terms
  of ordering and exit codes. Easier is to set them up separately with a
  ..qqmmaaiill--lliisstt--ccoommmmaanndd file.

  Let's assume you want to allow anyone to determine how many
  subscribers are subscribed to your list with the command list-
  count@host.  Just create a program to do the work:


               #!/bin/sh
               DTLINE='Delivered-To: list-count@host processor'
               grep "$DTLINE" > /dev/null &&
                       { echo "This message is looping"; exit 100; }
               {
                 echo "$DTLINE"
                 cat <<EOF
                 From: list-help@host
                 To: $SENDER
                 Subject: list@host subscriber count

                 Current number of subscribers:
                 EOF
                 ezmlm-list ~/DIR | wc -l
               } | /var/qmail/qmail-inject -f list-return- "$SENDER"
               exit 0


  Then, create DDIIRR//ccoouunntt containing ``|/path/program'' and then do ``ln
  -sf DIR/count ~/.qmail-list-count''. Now, the command will pass the
  message to ``program''. The first thing ``program'' looks for is its
  delivered-to line to detect looping. If not found, it goes on to print
  this header, followed by some minimal text and the subscriber number.
  This can of course be made prettier with ezmlm-list error checking,
  and maybe in perl, but shows how easy it is to extend ezmlm. All
  thanks to the DJB/qmail delivery mechanism.


  44..3311..  HHooww rreemmoottee aaddmmiinniissttrraattoorrss ccaann rreettrriieevvee aa ssuubbssccrriibbeerr lliisstt

  A user with shell access can always manipulate subscriber lists with
  ezmlm-sub(1), ezmlm-unsub(1), and ezmlm-list(1) for the lists s/he
  owns.

  Sometimes a remote administrator requires a list of subscriber E-mail
  addresses. At the same time, the list should be kept out of the hands
  of spammers and all unauthorized entities. By default, ezmlm does not
  allow remote subscriber list retrieval.  You can enable the ``-list''
  command for remote retrieval of a subscriber list by using the ezmlm-
  make(1) ``-l'' switch or by adding the ``-l'' switch to the ezmlm-
  manage(1) line in DIR/manager. With this switch, ezmlm will permit
  retrieval of a subscriber list, but only to remote administrators.
  Subscribers cannot get the list membership, and any outsider would
  have to be able to read a remote administrator's mail to get the list.
  _N_o_t_e_: _T_h_i_s _o_p_t_i_o_n _i_s _n_o_t _f_u_n_c_t_i_o_n_a_l _u_n_l_e_s_s _t_h_e _l_i_s_t _i_s _c_o_n_f_i_g_u_r_e_d _f_o_r
  _r_e_m_o_t_e _a_d_m_i_n_i_s_t_r_a_t_i_o_n_, _i_._e_. _t_h_e _e_z_m_l_m_-_m_a_k_e_(_1_) _`_`_-_r_l_'_' _s_w_i_t_c_h_e_s _n_e_e_d _t_o
  _b_o_t_h _b_e _u_s_e_d_.

  The list returned is unsorted for efficiency reasons. You can easily
  sort it or use your mail reader to find a specific entry. The number
  of subscribers is shown at the bottom of the list. To get the number
  of subscribers from the command line, use:
               % ezmlm-list DIR | wc -l


  44..3322..  HHooww rreemmoottee aaddmmiinniissttrraattoorrss ccaann ddeetteerrmmiinnee tthhee nnuummbbeerr ooff ssuubb--
  ssccrriibbeerrss

  For the list aaa@example.com, send a message to aaa-listn@example.com.
  This is preferable to the ``-list'' command for very large lists.


  44..3333..  HHooww rreemmoottee aaddmmiinnss ccaann sseeee iiff aann aaddddrreessss iiss aa ssuubbssccrriibbeerr oorr nnoott

  For the list aaa@example.com, and subscriber user@host.cn send a
  message to aaa-query=host.cn@example.com. Users can do this as well,
  but in that case the reply is sent to the target address
  (user@host.cn) and not to the SENDER to protect the subscriber
  addresses.


  44..3344..  HHooww rreemmoottee aaddmmiinniissttrraattoorrss ccaann sseeaarrcchh tthhee ssuubbssccrriippttiioonn lloogg

  The same conditions that enable remote administrators to retrieve a
  subscriber list (see ``'') also enable the remote admin to retrieve
  the subscription log, i.e. the log of changes made to the subscriber
  list. The command is list-log@host. The entries are of the form ``date
  timestamp dir event address comment''. ``dir'' is ``+'' for addition
  of an address, ``-'' for removal, ``event'' is empty for normal
  (un)subscribe ``manual'' for changes made with ezmlm-(un)sub, and
  ``probe'' for removals via bounce handling. ``address'' is the
  subscription address, and ``comment'' is empty or the subscribers
  ``From:'' line. The log can be used to look at recent
  additions/removals and to try to track down a subscriber address from
  e.g. the name on the ``From:'' line. The log is written on a best-
  effort basis. In contrast to the subscriber database, entries in the
  log may be lost at a system crash.

  The remote administrator can do a case-insensitive search through the
  log with the command list-log.xxx@host, where ``xxx'' is any sequence
  of letters/numbers that must occur on a line in order for that line to
  be included in the reply. A ``_'' is a wild card and should be used
  for special characters as well. Thus, to search for any entry with a
  host name of host* mail list-log._host and to find entries for ``Keith
  John...'' etc, use list-log.keith_john.

  For SQL-enabled lists, this command searches the ``list_slog'' table.


  44..3355..  HHooww tteexxtt ffiillee eeddiittiinngg wwoorrkkss..

  If a list is set up with the ezmlm-make(1) ``-n'' switch, or if the
  ``-e'' switch is added to the ezmlm-manage(1) line in DDIIRR//mmaannaaggeerr,
  ezmlm allows remote administrators to edit the text files that make up
  most of the ezmlm responses.  Of course, this will work only if remote
  administration is enabled for the list. Replies are sent only if the
  target address is a remote administrator.  Thus, ezmlm does not rely
  on SENDER (easily forged) but on the notion that only the recipient
  receives the message.  This is a reasonable assumption for remote
  administrators that receive mail on the local system.

  With this switch, ezmlm replies to the -edit command with a list of
  the files in DDIIRR//tteexxtt//.  Only files where editing seems reasonable are
  included in the list. The remote administrator can edit any file in
  DDIIRR//tteexxtt// by sending e-mail containing the new text to -edit.file
  where ``file'' is the name of the file replaced (edited). The file
  must exist and the name consist of only lower case letters and '-'.
  Any '-' (hyphen) must be substituted by a '_' (underscore). For remote
  administrator convenience, the substitution has been made in the list
  of files sent in reply to the -edit command.

  In reply to this command, ezmlm sends a message with the file and
  editing instructions. A ``cookie'' based on the date, file name, and
  contents of the file is added to the ``Reply-To:'' address. The cookie
  becomes invalid as soon as the file has been changed, or after 27
  hours, whichever is shorter.  Also, the cookie cannot be used to edit
  any other file, even if the other file has exactly the same contents.
  If you sent an edit request, and decide not to edit the file, you can
  simply delete the message.

  To apply standard changes to all your text files it is easier to edit
  ~~//..eezzmmllmmrrcc. To reset the list's text files back to their default
  contents (as specified by eezzmmllmmrrcc((55))), use the ezmlm-make(1) ``-ee''
  switch together with any other switches used to set up the list, or
  the ``-++'' switch and any switches that you whish to change from the
  current configuration.


  44..3366..  HHooww ssuubbjjeecctt lliinnee pprreeffiixxeess wwoorrkk..

  First of all, it is against a number of RFCs to modify the
  ``Subject:'' header of messages. However, it is frequently requested
  by users who have seen it on other list managers. Second, it is many
  times worse to have a prefix that changes from message to message,
  such as a prefix with the message number.  However, a number of lists,
  especially in Japan, use this feature and in its absence these lists
  might be unable to take advantage of ezmlm. Thus, while we recommend
  against using a prefix, ezmlm-idx supports it.

  To add a subject prefix, just put the text into DDIIRR//pprreeffiixx. The only
  format that makes any sense is ``list:'' or ``(list)'' or such.

  The message number prefix is activated by putting e.g. ``(list-#)''
  into DDIIRR//pprreeffiixx. ``#'' is replaced by the message number. ezmlm
  refuses to make more drastic changes in the subject of a message. As a
  consequence, the message number prefix is added only when the subject
  does not already contain a prefix. Thus, replies will have the message
  number of the original message. Doing anything else and still
  supporting rfc2047-encoded subjects in the archive threading (much
  more important) would require decoding the subject, removing/editing
  the prefix, and re-encoding the subject. This is far too invasive.

  The entire thread can always be retrieved by sending a message to
  list-thread-x where ``x'' is the message number in the prefix of any
  message in the thread.


  44..3377..  HHooww bboouunncceess aarree hhaannddlleedd..

  Ezmlm messages are sent with an envelope sender (``Return-Path'') that
  directs bounces to DDIIRR//bboouunncceerr and also via ``VERP'' contain
  information about the intended recipient. Thus, programs run from
  DDIIRR//bboouunncceerr know the subscriber for whom the message bounced. ezmlm-
  weed(1) is used to weed out delivery delay notification and other
  junk.  For others ezmlm-return(1) decides if the address is a
  subscriber.  If so, it saves the first bounce message and a list of
  bounced-message numbers. ezmlm-warn(1) executed from e.g. DDIIRR//eeddiittoorr
  goes through these bounce files. If it finds any that are older than
  1,000,000 seconds (about 11.6 days) it sends a warning message to the
  subscriber. If this warning message bounces, ezmlm-return(1) sets up a
  "warning flag" for the subscriber. If ezmlm-warn(1) finds a warning
  flag older than 11.6 days, it sends a "probe" to the subscriber.  If
  ezmlm-return(1) receives a bounced probe, the subscriber is
  automatically unsubscribed.

  The ezmlm-warn(1) ``-t'' switch can be used to change the time-out (in
  days).  The ezmlm-warn(1) ``-d'' switch causes processing of ``list-
  digest'' bounces rather than ``list'' bounces. ezmlm-weed(1) and
  ezmlm-return(1) can handle bounces for either list.

  ezmlm-warn(1) also removes any files in the bounce directory that are
  older than 3 times the bounce time-out.

  ezmlm-warn(1) is normally run from DDIIRR//eeddiittoorr. This can take quite a
  lot of resources, if there are a large number of bouncing addresses
  (>>1000) on a busy list, since by default all bounces are stored in a
  single directory and ezmlm-warn(1) examines all of them with each
  invocation.  ezmlm-idx->=0.32 changes bounce handling to improve
  performance for large lists. Bounces are stored in subdirectories of
  DDIIRR//bboouunnccee//dd//, one per 10,000 seconds. The corresponding address
  hashes are stored in 16 subdirectories of DDIIRR//bboouunnccee//hh//. Instead of
  looking at all bounces, ezmlm-warn(1) processes only the bounces in
  DDIIRR//bboouunnccee//dd// subdirectories that are ``due''. In addition, ezmlm-
  warn(1) uses DDIIRR//bboouunnccee//llaassttdd as a simple lockout, to assure that it
  will do work only at most once every 5.5 hours. (Times are scaled to
  the ezmlm-warn(1) ``-t'' argument if used.)  Together, these changes
  assure that bounce handling will scale well in the default
  configuration, even for very large lists.


  44..3388..  HHooww tthhee iinnffoo aanndd ffaaqq ccoommmmaannddss wwoorrkk..

  The _-_i_n_f_o and _-_f_a_q commands simply reply with the contents of the
  DDIIRR//tteexxtt//iinnffoo and DDIIRR//tteexxtt//ffaaqq files. Edit these files directly or
  remotely (see ``How to remotely edit dir/text files'').  The
  DDIIRR//tteexxtt//iinnffoo file should start with a single line that is meaningful
  as is and describes the list. This will be used in later versions to
  allow automatic assembly of the global ``list-of-lists'' (see ``How to
  set up a global list address like majordomo@host or listserv@host'').


  44..3399..  HHooww tthhee gglloobbaall eezzmmllmm lliisstt aaddddrreessss wwoorrkkss..

  Sometimes, it is desirable to have a host- or user-wide address that
  can list available mailing lists.

  ezmlm-request(1) can be used to set up a global address, such as
  ezmlm@host which allows the user to see and interact with a number of
  different mailing lists. This is especially useful when your users are
  used to other mailing list managers, such as ``majordomo'' or
  ``listproc''. ezmlm-request(1) is set up to answer requests to the
  address (see ``How to set up a global list address like majordomo@host
  or listserv@host'').  There, it interprets the first line of the
  message body as a command. It will reply directly to ``lists'' and
  ``which'' commands. All other commands will be used to construct
  messages to the respective lists. Where other mailing list managers
  use synonyms of ezmlm commands, ezmlm-request(1) recognizes these and
  translates them to the corresponding ezmlm commands.  ezmlm-request(1)
  will build commands also of unrecognized commands. Thus, if you create
  new commands for a list, ezmlm-request(1) will automatically support
  them.

  If the user does not specify the complete list address, ezmlm-
  request(1) will attempt to complete the name. See the ezmlm-reject(1)
  man page for more info.


  44..4400..  HHooww eezzmmllmm--ccrroonn wwoorrkkss..

  If you are a user and have crond(8) access, if you do not need to get
  digests at specific times, or if you are a system administrator
  setting up lists, there is no reason for you to use ezmlm-cron(1). If
  you are a system administrator not allowing users crond(8) access or a
  user that needs digests at specific times, but without crond(8)
  access, read on.

  ezmlm-cron(1) is a very restrictive interface to crond(8).  ezmlm-
  cron(1) can be used to create digest trigger messages. If a list is
  set up with a digest code (see ezmlm-make(1) and ezmlm-get(1)) ezmlm
  will generate a digest from the list joe-sos@host sent to to
  subscribers of joe-sos-digest@dighost when receiving a message to joe-
  sos-dig-code@host where ``code'' is the digest code. ezmlm-cron(1) can
  be used to generate such messages at regular intervals.  The file
  eezzccrroonnrrcc is set up by the sysadmin and controls what trigger messages
  specific users may set up via ezmlm-cron(1).

  Usually, the ezcronrc of that use will have an entry like
  ``user:user-:host:10'' allowing ``user'' to create trigger messages
  for up to 10 lists with names starting with ``user-'' and on the host
  ``host''.

  To list the ezcronrc line controlling your use of ezmlm-cron(1):


               % ezmlm-cron -c


  To list all entries that you've created:


               % ezmlm-cron -l


  To add an entry to trigger digests from list@host every morning at
  0230:


               % ezmlm-cron -t 02:30 -i24 list@host code


  A new entry for the same list overwrites an old entry.

  To delete the entry above:


               % ezmlm-cron -d list@host


  or use ezmlm-cron to trigger messages at a different time:


               % ezmlm-cron -t 16:16 -i24 list@host code


  44..4411..  HHooww eezzmmllmm--mmaakkee wwoorrkkss..

  ezmlm lists allow almost infinite customization. The component build,
  together with the qmail delivery mechanism makes it possible to create
  any variant of list function imaginable. However, this complexity
  makes it somewhat daunting to the average user wanting to set up a
  mailing list. ezmlm-make(1) allows automated list setup, while
  permitting a large amount of configurability.

  At first glance, ezmlm-make(1) has many complicated options. However,
  these can be applied iteratively through the ezmlm-make(1) edit
  mechanism. Also, they are intended to be relatively complete so that
  execution of ezmlm-make(1) by e.g. a GUI can be used to safely set up
  and edit any list.

  ezmlm-make(1) reads its command line arguments and switches, then
  creates the list directory. If the ``-e'' edit or ``-+'' sticky edit
  switches are not specified, ezmlm-make(1) will fail if the directory
  already exists. The directory argument must be an absolute path
  starting with a slash. The dot-qmail file argument, if specified, must
  also be absolute.

  ezmlm-make(1) next reads ezmlmrc(5) located in the //eettcc// directory
  with a default install. If not found, the file in the ezmlm binary
  directory will be used. The second ezmlm-make command line argument
  specify the root name of the .qmail files. If the ezmlm-make(1) ``-c''
  switch is used, ezmlm-make(1) will look in that directory for a
  ..eezzmmllmmrrcc file and use it instead. If this file does not exist, ezmlm-
  make(1) will print a warning and use the previously discussed
  ezmlmrc(5) files in the same order.  You can also use ``-C
  _e_z_m_l_m_r_c_._a_l_t'' to use _e_z_m_l_m_r_c_._a_l_t as the ezmlmrc(5) file. Again, ezmlm-
  make(1) will fall back to the others with a warning, if the specified
  ezmlmrc(5) file is not found.

  When not run in ``-e edit'' or ``-+'' sticky edit modes, ezmlm-make(1)
  first creates the list directory.  It also as the last step of its
  action creates DDIIRR//kkeeyy containing the key used for cookie generation.

  The ezmlmrc(5) file consists of a number of file names relative to the
  list directory, followed by conditional flags (see ezmlm-make(1) and
  ezmlmrc(5) for details). If all the conditional flags (controlled by
  the corresponding command line switches) are true, the lines that
  follow are entered into the named file. There are also tags to erase
  files.  Tags in the format <#X#> (where ``X'' is any number, except
  ``1'' and ``2'') are replaced by the corresponding ezmlm-make(1)
  switch argument. The ezmlm-make(1) command line arguments and the
  ezmlm binary path can be similarly substituted into the text. Thus,
  ezmlmrc(5) controls (within reason) the entire operation of ezmlm-
  make(1). ezmlmrc(5) is also set up so that no messages or file
  containing list state information are lost. Therefore, ezmlm-make(1)
  can be used to safely edit existing lists. The only caveat is that the
  list state is undefined while editing is in progress. Thus, it is
  advisable to prevent mail delivery by setting the ``sticky'' bit on
  the user's home directory while editing lists.

  ezmlm-make(1) will create the file DDIIRR//ccoonnffiigg. This files saves all
  the flags that were set at the last execution of ezmlm-make, as well
  as all the switch and command line arguments. When editing a list,
  only ``DIR'' and the non-default letter switches need to be specified.
  Other command line arguments and the ``digit switch'' arguments are
  read from DDIIRR//ccoonnffiigg.  To remove a digit switch, simply use it with
  two single quotes as the argument.

  You can also easily determine how a list was set up by looking at
  DDIIRR//ccoonnffiigg.

  _N_o_t_e_: DDIIRR//tteexxtt// files will be created but not overwritten when using
  the ``-e'' or ``-+'' edit switches. This is to preserve manual
  customizations. To overwrite these and reset the files to the content
  specified by eezzmmllmmrrcc, use ``-ee'' or ``-++''.

  _N_o_t_e_: As of ezmlm-idx-0.40 the ezmlm-make(1) ``-c'' and ``-C file''
  switches are sticky when using ``-+'' or ``-++'', so you do not need
  to specify them. This feature is disabled if ezmlm-make(1) is run as
  root.


  44..4422..  WWhhaatt nnaammeess ccaann II uussee ffoorr mmyy lliissttss??

  Rather than restrict you to a single E-mail address (user@host), qmail
  in the default setup gives you control over an infinite number of
  addresses user-*@host. Of course, you (normally) have no way of
  controlling elsewhere@host since that could lead to overlap between
  users' ``e-mail address space''. As a consequence, all you mailing
  lists have to be named user-xx@host where ``user'' is your user name
  and ``xx'' is anything. You cannot create e.g. mylist@host, only user-
  mylist@host. To create the list user-list@host do:


               % ezmlm-make ~/list ~/.qmail-list user-list host


  Notice that ``user'' is nnoott part of the ..qqmmaaiill file name.

  There are two way to create lists with names not starting with your
  user name: First, qmail can be set up so that you control a virtual
  domain (see below).  Second, the system administrator can set up lists
  with arbitrary names within the ~~aalliiaass// directory.


  44..4433..  LLiissttss iinn vviirrttuuaall ddoommaaiinnss

  If you use qmail>=1.02 and ezmlm-idx>=0.32, lists under virtual
  domains work just like other lists and require no adjustments. You can
  choose any local name for the list and the ezmlm-make(1) argument
  ``local'' is that name; ``host'' is the name of the virtual domain.


  44..4444..  HHooww ddoo II mmaakkee ccuussttoommiizzaattiioonn ssiimmppllee ffoorr mmee//mmyy uusseerrss??

  All non-default switches, ezmlm-issubn(1) setups, etc, can be made
  standard for new lists by customizing the ezmlm-make(1) configuration
  file named ``eezzmmllmmrrcc''.  A default eezzmmllmmrrcc((55)) is installed in the
  ezmlm binary directory. If installed, a system-wide customized ezmlmrc
  file in //eettcc//eezzmmllmmrrcc (or symlinked from there) overrides this.
  Installing a ~~//..eezzmmllmmrrcc file in a user ddoottddiirr and using the ezmlm-
  make(1) ``-c'' switch allows further per user customization (see
  ``Customizing ezmlm-make operation'').


  55..  eezzmmllmm ssuuppppoorrtt ffoorr SSQQLL ddaattaabbaasseess..


  55..11..  WWhhyy uussee aann SSQQLL ddaattaabbaassee wwiitthh eezzmmllmm??

  The main advantages are that you are using an address database system
  that can easily be accessed from any number of other programs via
  ODBC, perl, java, PHP, ... You can easily hook up ezmlm with your
  customer database, etc.  ezmlm programs compiled with SQL support (and
  when available also those compiled with support for other SQL servers)
  are entirely backwards compatible. You can mix SQL dbs with normal
  ezmlm dbs, and convert lists between them.


  55..22..  WWhhyy nnoott ttoo uussee aann SSQQLL ddaattaabbaassee wwiitthh eezzmmllmm..

  The main disadvantages of the SQL version are that you need to be
  familiar with the SQL server, the binaries are quite a bit larger, and
  you are trusting your addresses to a large database program, rather
  than a small and easily audited set of ezmlm programs. Also, the SQL
  server becomes a single point of failure.

  Ezmlm with SQL support continues to rely on qmail stability. If
  connection fails, ezmlm aborts with a temporary error causing
  redelivery at a later time point.


  55..33..  TTaabblleess uusseedd ffoorr ((MMyy))SSQQLL ssuuppppoorrtt..

  The basic philosophy is that the database can be on any host (if you
  use SENDER restrictions, connectivity to the main host is more
  important than to the sublists), and you choose the database and
  ``table root'' names. The default database is ``ezmlm'' and the
  default table root is ``list''. Each list has a separate table root.
  Any number of lists can share a database.

  The main list address table is named with the table root only, others
  have that name with various suffixes. In the following ``list'' is
  used as the table root.


  55..33..11..  AAddddrreessss ttaabblleess..


     lliisstt
        List subscriber addresses.

     lliisstt__ddiiggeesstt
        Digest list subscriber addresses.

     lliisstt__aallllooww
        List subscriber alias addresses. Used only if SENDER
        restrictions are used for the list. This is configured in the
        default SQL list setup, but a local (ezmlm-style non-SQL)
        database could also be used.

     lliisstt__ddeennyy
        List deny addresses. This table is created, but the default
        configuration, if it uses the ``deny'' addresses at all, will do
        so with a local database.

     lliisstt__mmoodd
        Moderator addresses. Created for completeness, but not used in
        the default configuration. If moderators are used, the addresses
        are stored in a local database.


  55..33..22..  SSuubbssccrriibbeerr lloogg ttaabblleess..

  For each of the above tables, there is a ``*_slog'' table that
  contains one row per transaction against the corresponding address
  table. The entries contain a time stamp, the subscription address; a
  direction indicator (``-'' for removals, ``+'' for additions); a type
  indicator (blank for ezmlm-manage, ``m'' for ``manual'', ``p'' for
  ``probe, i.e. bounce handling; and the subscriber ``From:'' line
  contents (only additions and only when made by ezmlm-manage or by
  ``ezmlm-sub(1) -n'').


  55..33..33..  MMeessssaaggee llooggggiinngg ttaabblleess..

  For both the list and the digest list, there are a pair of tables that
  log messages:


     lliisstt__ccooookkiiee
        The main list stores the message number and a pseudo-random
        cookie in this table when it processes the message. The cookie
        is derived from the secret DDIIRR//kkeeyy, the message sender and the
        message number. Thus, it is non-repeating and virtually
        impossible to guess beforehand. Sublists will check that the
        cookie sent with the message is the same as the one received
        with the message.

        The digest list is created similarly, except that it is ezmlm-
        get(1) that originates the message and creates the cookie.  This
        is done in ``list_digest_cookie''.


     lliisstt__mmlloogg
        Both the main list and the sublists make entries in this table.
        Each entry consists of a time stamp, a message number, a list
        number, and a code. The code is 0 for message arrival, 1 for
        ``finished processing'', 2 for ``receipt received'' and -1 for
        bounce. The lists will refuse to process messages that do not
        have the correct cookie, or if the message already has an entry
        with a code of greater than 0. To inject a message at the
        sublist, an attacker would have to inject a message with the
        correct code before the list has processed the ``real'' message,
        or subvert the SQL server. In practice, this is very hard to do,
        unless the attacker has broken security at the database server
        or a sublist. This authentication mechanism is intended to make
        it safe to sublist moderated lists. It also blocks any message
        duplication between main list and sublist from being propagated
        to the subscribers.

        The codes 2 for ``receipt received'' and -1 for bounce are
        entered by ezmlm-receipt(1) at the main list. This program is
        configured instead of ezmlm-return(1) if the main list was set
        up with ``ezmlm-make -w6''.  ezmlm-receipt(1) checks the cookie
        of messages addresses to mainlocal-return-receipt@mainhost and
        if correct enters the ``receipt received'' code. This address is
        normally in the subscriber database with a hash of 98, so that
        each list sends a message to the address _a_f_t_e_r all subscriber
        addresses.

        Bounces of sublist messages should not lead to removal of the
        sublist from the database. ezmlm-receipt(1) will instead log the
        bounce to the ``list_mlog'' table. It will also store up to 50
        bounces in the bounce directory. This helps error detection and
        diagnosis. After the first 50 bounces, no more bounces are
        stored, until you manually remove the old ones. This is to
        prevent filling up your hard disk in case a configuration error
        causes a deluge of bounces.

        The digest list is treated in the same manner. Here, the tables
        is ``list_digest_mlog'' and the feedback address is mainlocal-
        digest-return-receipt@mainhost.


  55..44..  HHooww ttoo sseett uupp aa ssiimmppllee lliisstt wwiitthh SSQQLL ssuuppppoorrtt..

  To use SQL database support, you have to compile the programs with SQL
  support. Currently, only MySQL support is available. See IINNSSTTAALLLL..iiddxx
  in the package on how to do this.

  The programs with SQL support will work exactly like the normal
  programs for standard lists. However, if the file ssqqll exists in the
  basedir, it turns on the SQL mode and it is expected to contain SQL
  server connect info in the format

       ``host:port:user:password:database:table''


  Here, ``Host'' is the SQL database server host, ``port'' can be left
  blank to use the default port, ``user'' and  ``password'' are connec-
  tion credentials for a user you need to define and grant access to the
  database. ``Table'' is the name of the address table (``list'' in the
  examples above and ``list_digest'' for the corresponding digest list).
  For list clusters, ``:sublist'' is suffixed to this info and it is the
  name/address of the sublist.

  For each address database, you also need to create the address table
  as well as the ``*_slog'' subscription log table. In addition, you
  should create a ``*_cookie'' and ``*_mlog'' table for message logging.
  This is all it takes to start using an SQL database.


  55..44..11..  HHeellppeerr pprrooggrraammss ffoorr SSQQLL--eennaabblleedd lliissttss..

  Two programs are supplied in the distribution to make it easier to
  create the database user and tables. Also, ezmlm-make(1) has support
  for setting up SQL-enabled lists.


     CCrreeaattiinngg tthhee ttaabblleess
        ezmlm-mktab(1) will create the necessary tables:


                  % ezmlm-mktab -d table


     Pipe this into the SQL client with the appropriate administrator
     credentials needed to create tables (see MySQL documentation, e.g.
     <http://www.tcx.se/>).

     For most lists, the only addresses that are stored in the SQL
     database are the subscribers of list and digest, and the ``allow''
     aliases. It is NOT normally advisable to store moderator addresses
     there, since they are needed only at the main list and secrecy is
     more important. ``Deny'' addresses are few and again only needed at
     the main list. ``Allow'' are put in the SQL database when using the
     default ezmlmrc file only to make all relevant addresses
     manipulatable via the SQL server. The other tables are created, in
     case they are  wanted (the cost for having them as empty table is
     zero). The basedir/sql file is the decision point. If it exists, an
     SQL table is used; if not a local ezmlm db is used.


     CCrreeaattiinngg aa uusseerr eennttrryy
        Create a user that has full access to the database from the list
        host. How to do this depends on the RDBMS.


     CCrreeaattiinngg tthhee lliisstt
        ezmlm-make(1) supports SQL-enabled lists with the ``-6'' switch:


                  % ezmlm-make other_switches -6 'host:port:user:pw:db:table' \
                          dir dot local host


     Will create an SQL-enabled list that uses the SQL server for the
     main list subscribers, digest list subscribers (if configured) and
     ``allow'' poster alias addresses (if configured).


  55..55..  MMaannuuaallllyy mmaanniippuullaattiinngg tthhee ssuubbssccrriibbeerrss ooff aa SSQQLL--eennaabblleedd lliisstt..

  ezmlm-sub(1), ezmlm-unsub(1), and ezmlm-list(1) work as you would
  expect also with a SQL-enabled list. ezmlm-list(1) may be minimally
  slower (depending on network speed) if the SQL server is not local.
  ezmlm-sub(1) and ezmlm-unsub(1) will be faster, but this is noticeable
  only with very large subscriber lists and addition/removal of large
  numbers of addresses (more than several thousands).


  55..66..  CCoonnvveerrttiinngg ttoo aanndd ffrroomm aanndd SSQQLL ddaattaabbaassee..

  Just like other programs, ezmlm-list(1), ezmlm-sub(1), and ezmlm-
  unsub(1) will work with normal address databases in the absence of
  DDIIRR//ssqqll.  However, they also have a ``-M'' switch to force this
  behavior even in the presence of DDIIRR//ssqqll. This is used to convert an
  address database from the standard type to the SQL type:


               % ezmlm-list -M dir | xargs ezmlm-sub dir


  or from the SQL version to the standard type:


               % ezmlm-list dir | xargs ezmlm-sub -M dir


  To synchronize the two, remove one and then update it with ezmlm-
  sub(1) from the other. Alternatively, sort the ezmlm-list(1) output
  for both, use diff and sed/awk to get separate files of the differ-
  ences, and use ezmlm-sub(1) and ezmlm-unsub(1) to apply the differ-
  ences to the appropriate database.

  This type of conversion can serve as a convenient means to convert a
  list from one type to another, to back up databases, and to move
  subscriber addresses from a standard list to a SQL table for other
  purposes, or from a SQL database to a standard mailing list (you may
  need to use addresses from a SQL table, without wanting your lists to
  be dependent on an SQL server for day to day operation).

  _N_o_t_e_: This inter-conversion requires the DDIIRR//ssqqll file. If you do not
  run the list against an SQL server, you need to disable deliveries
  before you temporarily create this file. Otherwise, the list will run
  against the SQL database during the time DDIIRR//ssqqll exists.


  55..77..  OOppttiimmiizziinngg MMyySSQQLL ffoorr eezzmmllmm..


  55..77..11..  AAddddrreessss SSEELLEECCTTss,, aaddddiittiioonnss,, rreemmoovvaallss..

  ezmlm-idx-0.40 simplifies the SQL support and queries over ezmlm-
  idx-0.32 at the cost of dropping distributed sublist support. We have
  figured out a simpler way to support the latter, which hopefully will
  be incorporated into ezmlm in the future (written under contract).

  With the simplification, the queries are very straight forward, and
  tuning is indicated only under extreme circumstances (very many very
  large and busy lists or constant addition/removal of many addresses).


  55..88..  MMaaiinntteennaannccee ooff tthhee MMyySSQQLL ddaattaabbaassee..

  Weekly to monthly error checks on MySQL tables is recommended. Best is
  to use:


               # isamchk -s -O readbuffer=2M */*.ISM


  Other options allow automatic correction of errors, but are dangerous
  if tables are accessed while isamchk is running.

  Other isamchk options allow recovery of space after frequent
  insert/delete of addresses (can also be done with ``OPTIMIZE TABLE''),
  key optimization, etc.  See the MySQL documentation (
  <http://www.tcx.se>) for more info.


  66..  PPoossssiibbllee eerrrroorr ccoonnddiittiioonnss iinn eezzmmllmm lliissttss..


  66..11..  WWhhaatt ddoo II ddoo iiff eezzmmllmm ddooeessnn''tt wwoorrkk??

  Try to determine where the problem occurs and how to reproduce it:

  +o  Do messages to ezmlm return an error message to the sender or not?

  +o  What is/are the error message(s)?

  +o  What does ezmlm log into the mail log?

  +o  Are you using a setup with virtual domains, and qmail<1.02 or
     ezmlm-idx<0.31? If so, have you adjusted DDIIRR//iinnllooccaall (see
     ``Adapting ezmlm-make for virtual domains'')?

  +o  Are posts sent out to the subscribers?

  +o  Are there subscribers?


       %  ezmlm-list DIR


  +o  Are there moderators?


  % ezmlm-list moddir


  where ``moddir'' is the contents of DDIIRR//rreemmoottee (for remote admin
  lists), of DDIIRR//mmooddssuubb (for subscription moderated lists) or DDIIRR//mmoodd--
  ppoosstt (for message moderation), if and only if the contents start with
  a forward slash. The default in all cases is DDIIRR//mmoodd//. If both
  DDIIRR//mmooddssuubb and DDIIRR//rreemmoottee contain directory names, the one in DDIIRR//mmoodd--
  ssuubb is used for both subscription moderation and remote admin.

  +o  Are the ownerships of all files correct, i.e. read/writable for the
     owner?


       % chown -R user DIR


  For lists under alias:


       % chown -R alias DIR


  If you use custom moderator databases, those directories and all their
  contents must also be readable for the user under which the list oper-
  ates (i.e. the user qmail changes to during the delivery).

  +o  Read the qmail log and capture relevant parts.

  +o  Did you customize the package at all? If so, try the default
     settings which are known to work.

  +o  Did you customize eezzmmllmmrrcc((55))? Try to use the default copy (skip the
     -c switch).

  +o  Did your customization of ..eezzmmllmmrrcc fail to have an effect?
     Remember to use the -c switch. The ..eezzmmllmmrrcc file used is the one in
     ``dotdir'', i.e. the directory where the ..qqmmaaiill files go, usually,
     but NOT necessarily, the one in your home directory.

  +o  Make sure you followed the instructions in man pages and other
     documentati