src/mailman/archiving/docs/common.txt

   1 =========
   2 Archivers
   3 =========
   4
   5 Mailman supports pluggable archivers, and it comes with several default
   6 archivers.
   7
   8     >>> from mailman.app.lifecycle import create_list
   9     >>> mlist = create_list('test@example.com')
  10     >>> msg = message_from_string("""\
  11     ... From: aperson@example.org
  12     ... To: test@example.com
  13     ... Subject: An archived message
  14     ... Message-ID: <12345>
  15     ...
  16     ... Here is an archived message.
  17     ... """)
  18
  19 Archivers support an interface which provides the RFC 2369 List-Archive
  20 header, and one that provides a 'permalink' to the specific message object in
  21 the archive.  This latter is appropriate for the message footer or for the RFC
  22 5064 Archived-At header.
  23
  24 Pipermail does not support a permalink, so that interface returns None.
  25 Mailman defines a draft spec for how list servers and archivers can
  26 interoperate.
  27
  28     >>> archivers = {}
  29     >>> from operator import attrgetter
  30     >>> for archiver in sorted(config.archivers, key=attrgetter('name')):
  31     ...     print archiver.name
  32     ...     print '   ', archiver.list_url(mlist)
  33     ...     print '   ', archiver.permalink(mlist, msg)
  34     ...     archivers[archiver.name] = archiver
  35     mail-archive
  36         http://go.mail-archive.dev/test%40example.com
  37         http://go.mail-archive.dev/ZaXPPxRMM9_hFZL4vTRlQlBx8pc=
  38     mhonarc
  39         http://lists.example.com/.../test@example.com
  40         http://lists.example.com/.../RSZCG7IGPHFIRW3EMTVMMDNJMNCVCOLE
  41     pipermail
  42         http://www.example.com/pipermail/test@example.com
  43         None
  44     prototype
  45         http://lists.example.com
  46         http://lists.example.com/RSZCG7IGPHFIRW3EMTVMMDNJMNCVCOLE
  47
  48
  49 Sending the message to the archiver
  50 ===================================
  51
  52 The archiver is also able to archive the message.
  53
  54     >>> archivers['pipermail'].archive_message(mlist, msg)
  55
  56     >>> import os
  57     >>> from mailman.interfaces.archiver import IPipermailMailingList
  58     >>> pckpath = os.path.join(
  59     ...     IPipermailMailingList(mlist).archive_dir(),
  60     ...     'pipermail.pck')
  61     >>> os.path.exists(pckpath)
  62     True
  63
  64 Note however that the prototype archiver can't archive messages.
  65
  66     >>> archivers['prototype'].archive_message(mlist, msg)
  67     Traceback (most recent call last):
  68     ...
  69     NotImplementedError
  70
  71
  72 The Mail-Archive.com
  73 ====================
  74
  75 The Mail-Archive <http://www.mail-archive.com> is a public archiver that can
  76 be used to archive message for free.  Mailman comes with a plugin for this
  77 archiver; by enabling it messages to public lists will get sent there
  78 automatically.
  79
  80     >>> archiver = archivers['mail-archive']
  81     >>> print archiver.list_url(mlist)
  82     http://go.mail-archive.dev/test%40example.com
  83     >>> print archiver.permalink(mlist, msg)
  84     http://go.mail-archive.dev/ZaXPPxRMM9_hFZL4vTRlQlBx8pc=
  85
  86 To archive the message, the archiver actually mails the message to a special
  87 address at the Mail-Archive.  The message gets no header or footer decoration.
  88
  89     >>> archiver.archive_message(mlist, msg)
  90
  91     >>> from mailman.queue.outgoing import OutgoingRunner
  92     >>> from mailman.testing.helpers import make_testable_runner
  93     >>> outgoing = make_testable_runner(OutgoingRunner, 'out')
  94     >>> outgoing.run()
  95
  96     >>> from operator import itemgetter
  97     >>> messages = list(smtpd.messages)
  98     >>> len(messages)
  99     1
 100
 101     >>> print messages[0].as_string()
 102     From: aperson@example.org
 103     To: test@example.com
 104     Subject: An archived message
 105     Message-ID: <12345>
 106     X-Message-ID-Hash: ZaXPPxRMM9_hFZL4vTRlQlBx8pc=
 107     Sender: test-bounces@example.com
 108     Errors-To: test-bounces@example.com
 109     X-Peer: 127.0.0.1:...
 110     X-MailFrom: test-bounces@example.com
 111     X-RcptTo: archive@mail-archive.dev
 112     <BLANKLINE>
 113     Here is an archived message.
 114
 115     >>> smtpd.clear()
 116
 117 However, if the mailing list is not public, the message will never be archived
 118 at this service.
 119
 120     >>> mlist.archive_private = True
 121     >>> print archiver.list_url(mlist)
 122     None
 123     >>> print archiver.permalink(mlist, msg)
 124     None
 125     >>> archiver.archive_message(mlist, msg)
 126     >>> list(smtpd.messages)
 127     []
 128
 129 Additionally, this archiver can handle malformed Message-IDs.
 130
 131     >>> mlist.archive_private = False
 132     >>> del msg['message-id']
 133     >>> msg['Message-ID'] = '12345>'
 134     >>> print archiver.permalink(mlist, msg)
 135     http://go.mail-archive.dev/bXvG32YzcDEIVDaDLaUSVQekfo8=
 136
 137     >>> del msg['message-id']
 138     >>> msg['Message-ID'] = '<12345'
 139     >>> print archiver.permalink(mlist, msg)
 140     http://go.mail-archive.dev/9rockPrT1Mm-jOsLWS6_hseR_OY=
 141
 142     >>> del msg['message-id']
 143     >>> msg['Message-ID'] = '12345'
 144     >>> print archiver.permalink(mlist, msg)
 145     http://go.mail-archive.dev/ZaXPPxRMM9_hFZL4vTRlQlBx8pc=
 146
 147     >>> del msg['message-id']
 148     >>> msg['Message-ID'] = '    12345    '
 149     >>> print archiver.permalink(mlist, msg)
 150     http://go.mail-archive.dev/ZaXPPxRMM9_hFZL4vTRlQlBx8pc=
 151
 152
 153 MHonArc
 154 =======
 155
 156 The MHonArc archiver <http://www.mhonarc.org> is also available.
 157
 158     >>> archiver = archivers['mhonarc']
 159     >>> print archiver.name
 160     mhonarc
 161
 162 Messages sent to a local MHonArc instance are added to its archive via a
 163 subprocess call.
 164
 165     >>> archiver.archive_message(mlist, msg)
 166     >>> archive_log = open(os.path.join(config.LOG_DIR, 'archiver'))
 167     >>> try:
 168     ...     contents = archive_log.read()
 169     ... finally:
 170     ...     archive_log.close()
 171     >>> print 'LOG:', contents
 172     LOG: ... /usr/bin/mhonarc -add
 173         -dbfile /.../private/test@example.com.mbox/mhonarc.db
 174         -outdir /.../mhonarc/test@example.com
 175         -stderr /.../logs/mhonarc
 176         -stdout /.../logs/mhonarc
 177         -spammode -umask 022
 178         ...