Skip to content

openwall/blists

Repository files navigation

blists is a web-based interface to mailing list archives that works off
indexed mbox files.  There are two programs: bindex and bit.  bindex
generates or updates the index file (yes, incremental updates are
supported).  bit is a CGI program, which generates web pages on the fly.

  blists homepage: https://www.openwall.com/blists/
  Live example with a high volume mailing list:
      https://lists.openwall.net/linux-kernel/

To compile, simply run "make".  There's currently no "install" target;
you're supposed to copy the bindex and bit programs in place on your
own, as appropriate for your setup.  Also you may need to setup for your
httpd: cgi, SSI (shtml), and mod_rewrite.

You will likely want to have bindex run after new messages arrive.  For
example, you may invoke it from a .procmailrc file like this:

    :0
    * ^TOlistname
    {
      :0 c
      Mail/listname
      
      :0
      | /usr/bin/bindex Mail/listname
    }

This delivers new messages to an mbox file called "listname" and it
immediately triggers update of the index file for it.  You can also
accomplish this from .forward and .qmail files.  Alternatively, you may
choose to run bindex on cron.

The index file name is produced by adding the .idx suffix to the mbox
filename, so in this example it will be "listname.idx" in the same
directory.  With the default params.h settings, the index file size is
typically 100 KB plus around 3.5% of the mbox file's size.

bit is meant to be invoked via SSI (it will refuse to work otherwise),
and it has only been tested with Apache so far.  Here's an example
SSI-enabled HTML file (usually with extension .shtml):

    <!DOCTYPE html>
    <html>
    <head>
    <!--#include virtual="/cgi-bin/bit?header"-->
    <style type="text/css">
    .cal_brief { text-align: center; }
    .cal_brief td:first-child { background: inherit; }
    .cal_brief td { background: #ccc; width: 5ex; padding: 2px; }
    .cal_big { text-align: center; padding: 0; margin: 0; }
    .cal_big td { padding: 0 2px; }
    .cal_mon { text-align: center; }
    .cal_mon th { font-size: small; padding: 0; margin: 0; }
    .cal_mon td { background: #ccc; width: 5ex; height: 1.5em;
                padding: 2px; text-align: right; }
    .cal_mon td[colspan] { background: inherit; }
    .cal_mon sup { color: #F0F0F0; text-align: left; float: left;
                margin-top: -2pt; font-weight: bold; }
    .cal_mon a { text-align: right; margin-left: -4em; float: right; }
    </style>
    </head>
    <body>
    <!--#include virtual="/cgi-bin/bit?body"-->
    </body>
    </html>

bit output it in UTF-8, so you will need to configure charset, for
Apache add this (for example to to .htaccess in the directory
where bit.shtml is):

    AddCharset UTF-8 .shtml

Obviously, you'll also need to adjust the /cgi-bin/bit paths, and you
might need to add a filename suffix to match your web server
configuration (for example it could be bit.cgi).

You may need to configure MAIL_SPOOL_PATH definition in params.h to
tell bit where mboxes are located, otherwise bit will assume they
are in ../../blists/ relative to cgi-bin directory (where bit is).

In order for the links generated by bit to point to valid URLs, as well
as for the URLs to look pretty, you may use mod_rewrite rules like
this:

    RewriteEngine On
    RewriteRule ^((listname1|listname2)/([0-9]{4}/([0-9]{2}/([0-9]{2}/([1-9][0-9]*)?)?)?)?)$ list.shtml?$1 [L]
    RewriteRule ^((listname1|listname2)/[0-9]{4}/[0-9]{2}/[0-9]{2}/[1-9][0-9]*/[1-9][0-9]*)$ /cgi-bin/bit?attachment+$1 [L]

Direct call to bit is required to set HTTP headers for attachments.

To workaround a bug in Lynx where it would omit the trailing slash when
following links to "..", add:

    RewriteRule ^[a-z-]+([/0-9]*[0-9])?$ https://%{SERVER_NAME}%{REQUEST_URI}/ [R,L]

(where "[a-z-]+" is supposed to match your list names; adjust it if
not).

To have separate HTML wrapper pages for different lists (such as to
include different additional info on those pages), use:

    RewriteRule ^(listname1|listname2)/(([0-9]{4}/([0-9]{2}/([0-9]{2}/([1-9][0-9]*)?)?)?)?)$ list-$1.shtml?$1/$2 [L]

To make use of the censorship feature (to hide spam messages), create a
separate HTML wrapper page with:

    <!--#include virtual="/cgi-bin/bit?header-censored"-->
    ...
    <!--#include virtual="/cgi-bin/bit?body-censored"-->

then refer to it in more specific RewriteRule directives, which you need
to place above the catch-all ones:

    RewriteRule ^(listname1/2011/01/02/3)$ list-censor.shtml?$1 [L]

You may match multiple messages at once with trickier regexps:

    RewriteRule ^(listname1/2011/01/(09/1|12/1|12/2))$ list-censor.shtml?$1 [L]

Good luck!