ezmlm-cgi - provide WWW access to the list archive
is executed by the httpd daemon and generates HTTP/CGI/html
4.0-compliant self-referencing output of index pages for threads in a given
month, messages in a thread, messages by a given author, messages by date, and
messages themselves with full navigation controls. It uses the archive
directly, aided by index files created by ezmlm-idx(1)
as part of normal archive access and digest indexing, and
uses the httpd-supplied variables PATH_INFO
the list number, QUERY_STRING
to obtain the command, as well as
, and SCRIPT_NAME
to create a
is invoked without a command, it shows the threads for the
current month. If no list number is supplied, the default list is shown (see
expects to find configuration info in /etc/ezmlm/ezcgirc
when run SUID root, or .ezcgirc
otherwise. The entries in this file
describe one list per line. Blank lines and comments starting with a ``#'' in
position 1 are allowed and ignored. No extra blanks, tab, etc, are allowed.
Entries must be of the following format:
- is the list number using ``0'' for the default list if desired;
- the user id to switch to if installed SUID root (default invoking user id)
and if preceded by ``-'' chroot() is suppressed for SUID root
the absolute path to the list base directory (required);
- the list address as local@host (required) and if preceded by ``-'' the
``From:'' E-mail address is replaced by the posters name/handle as a
further precaution against address harvesting;
- a set of comma-separated fields of the type
``[Home]=http://example.com/list.html''. The text before the ``=''
is the exact text displayed and the subsequent text should be the URL
linked to that button. Use the braces to make the buttons be consistent
with preexisting navigation buttons. It is desirable to add a ``[Help]''
button with a link to an explanation of the various displays generated by
- the character set used for the main pages (default ``iso-8859-1'');
- the style sheet used (default none, which doesn't look pretty);
- the path to a banner program which is given the name of the script and the
list as arguments (default none). The path is relative to ``listdir'' and
can point anywhere in the file system. However, for SUID root
installations access is normally restricted via chroot(3). (See
SECURITY.) If ``bannerprog'' starts with a less-than character
(''<'') it is assumed to be a URL which is inserted as is, rather than
- the separator can be any non-numeric character and can be different for
different ezcgirc lines. There is no quoting/escaping mechanism.
Thus, choose a character not present in any of the arguments.
``bannerprog'' as the last argument is an exception, and may contain any
characters except LF and NUL.
- If ``uid'' is preceded by a minus sign (``-''),
- ezmlm-cgi will not call chroot(3) . This potentially
decreases security, but may be needed to execute ``bannerprog''.
- If ``listaddr'' is preceded by a minus sign (``-''),
- ezmlm-cgi will, as a precaution against address harvesting robots,
remove the sender's E-mail address also in the message view. This is
already done in all other views. The archive user can still obtain the
address by requesting the message by E-mail.
outputs 5 different views.
- thread index
- shows the threads which have messages in a given month. The subject is
prefixed with the number of messages in the thread for the given month.
When ezmlm-archive(1) is first run against an existing archive, the
number is the total number of messages in the thread. The subject and
author are links to the respective thread or author index. The threads are
ordered in reverse order of latest message, i.e. the thread that last
received a message is listed last. When ezmlm-archive(1) is run
against an existing archive, the initial sort is in order of the first
message in the thread.
The subject in the thread index is a link to the last message in the
- shows the messages in the respective thread in date order. For each
message the author is shown linked to the message.
- author index
- shows the subject of all messages posted from a given address in order of
arrival at the list. Links are to the messages.
- message by date
- shows entries in order of arrival of sets of 100 messages. Links are to
the message and to the author.
- shows the message itself. The message has links to the previous and next
message by time, in the thread, or by the same author. There are also
links to the other views, as well as links to subscribe, or request FAQ,
the message or the thread by E-mail. The navigation bar is very concise to
optimize appearance in lynx. It is self-explanatory to anyone
daring to experiment. For others, you may wish to supply a ``help''
button. The message subject is a mailto: link for a follow-up post
to the list.
outputs html 4.0 in a format suitable for Lynx
text-mode browsers. The format is designed for easy optional enhancement via
CSS1/2 type style sheets in the format ``text/css''. ezmlm-cgi
self-documenting in this respect. Simply review the output in the different
views and the sample style sheet to see the class structure.
will accept a PATH_INFO of the following format:
- is the list number per config file;
- is the message number.
Thus, ezmlm-cgi/2/20000 will return message 20000 from list
ezmlm-cgi uses a second syntax based on QUERY_STRING for internal
links. This command set is implemented only as far as required for normal
ezmlm-cgi function. Useful are:
- which will return in order the list of messages posted by the author of
message message on list listno, and
- which will return in order the list of messages with the same subject as
message message on list listno, i.e. the ``thread''.
There are many possible URLs for the same message. To still allow external
supports the command ezmlm-cgi/index
returns a page with links to all lists, except the default list. These links
indirectly lead exactly once to each message. None of the links used contain a
``?''. Thus, to index the archives, allow access to scripts in the (separate)
is installed, but deny access to
directory /ezmlm-cgi?. Any message will have a
``nofollow'' robot META tag, and any view reached by a URL based on
QUERY_STRING will in addition have a ``noindex'' robot META tag to
avoid trapping robots in the archive.
can operate in two modes, SUID root
should not be installed SUID user
than root. Please see the SECURITY
section before installing SUID
will read the configuration file
from the working directory set by the httpd daemon (per
definition this should be the same directory as ezmlm-cgi
in), then change directory to the list directory. ``uid'' is ignored. For user
installations or systems where the httpd user has access to all the lists,
mode usually gives sufficient access.
In SUID root
will read the configuration
info from /etc/ezmlm/ezcgirc
then change directory to that directory,
then change root to that directory, then change userid to ``uid''. If ``uid''
is not specified, it will change to the uid of the process invoking
(normally the httpd user). If the archive files are
world-readable, but the list directory is not, it is safest to leave ``uid''
blank. The httpd user will still be able to read the files.
supports display of banners, but not execution of banner
programs. To obtain dynamic banners, use a URL that points to a banner program
will refuse to run as root.
does not write or lock any files.
has a short well commented segment of code that potentially
runs SUID root. Read the source to convince yourself that this is safe. If
possible, install it SUID user, or not SUID at all, if that meets your needs
(single list user, httpd user is list user, or httpd user has sufficient
access to all list directories and archives).
will not allow execution of banner programs.
updates the list message counter once a message is safely
archived, but before it is accepted by qmail(7)
. Also, the index
file is updated before the message is accepted by qmail(7)
resets the counter before
terminating. It is possible that in such a situation the message would be
replaced by a different one. If ezmlm-cgi
accesses a message that
ultimately fails and in that time interval, it may expose a message that
ultimately is replaced, especially when doing it via the ``Messages by date''
view which is based on the index
file. In practice, this is relatively
harmless. Avoiding it would require locking the list with significant
implications for security and performance.
ezmlm-archive(1), ezmlm-get(1), ezmlm-idx(1), ezmlm-send(1), ezmlm(5), qmail(7)