NAME

ezmlm-cgi - provide WWW access to the list archive

SYNOPSIS

ezmlm-cgi

DESCRIPTION

ezmlm-cgi 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), and ezmlm-send(1) as part of normal archive access and digest indexing, and by ezmlm-archive(1).

ezmlm-cgi uses the httpd-supplied variables PATH_INFO to obtain the list number, QUERY_STRING to obtain the command, as well as SERVER_NAME, SERVER_PORT, and SCRIPT_NAME to create a self-referencing URL.

When ezmlm-cgi 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 below).

CONFIGURATION

ezmlm-cgi 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:

listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog

where:

listno: is the list number using ``0'' for the default list if desired;
uid: the user id to switch to if installed SUID root (default invoking user id) and if preceded by ``-'' chroot() is suppressed for SUID root installations;
listdir: the absolute path to the list base directory (required);
listaddr: 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;
buttonbar: 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 ezmlm-cgi.
charset: the character set used for the main pages (default ``iso-8859-1'');
style: the style sheet used (default none, which doesn't look pretty);
bannerprog: 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 executed.
``;'': 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.

OPTIONS

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.

OUTPUT

ezmlm-cgi 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 thread.
thread: 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.
message: 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.

OUTPUT FORMATTING

ezmlm-cgi outputs html 4.0 in a format suitable for Lynx and other text-mode browsers. The format is designed for easy optional enhancement via CSS1/2 type style sheets in the format ``text/css''. ezmlm-cgi is self-documenting in this respect. Simply review the output in the different views and the sample style sheet to see the class structure.

EXTERNAL LINKS TO MESSAGES

ezmlm-cgi will accept a PATH_INFO of the following format:

/listno/message

where:

listno

is the list number per config file;

message

is the message number.

Thus, ezmlm-cgi/2/20000 will return message 20000 from list 2.

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:

ezmlm-cgi?listno?ams:message

which will return in order the list of messages posted by the author of message message on list listno, and

ezmlm-cgi?listno?sms:message

which will return in order the list of messages with the same subject as message message on list listno, i.e. the ``thread''.

ROBOTS

There are many possible URLs for the same message. To still allow external indexing, ezmlm-cgi supports the command ezmlm-cgi/index which 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) directory where ezmlm-cgi 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.

EXECUTION

ezmlm-cgi can operate in two modes, SUID root and normal. ezmlm-cgi should not be installed SUID user other than root. Please see the SECURITY section before installing SUID root.

In normal mode, ezmlm-cgi will read the configuration file .ezcgirc from the working directory set by the httpd daemon (per cgi definition this should be the same directory as ezmlm-cgi is 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, normal mode usually gives sufficient access.

In SUID root mode, ezmlm-cgi 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 ezmlm-cgi (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.

EXECUTION OF BANNER PROGRAMS

ezmlm-cgi supports display of banners, but not execution of banner programs. To obtain dynamic banners, use a URL that points to a banner program elsewhere.

SECURITY

ezmlm-cgi will refuse to run as root.

ezmlm-cgi does not write or lock any files.

ezmlm-cgi 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).

ezmlm-cgi will not allow execution of banner programs.

BUGS

ezmlm-send(1) 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). If qmail(7) fails, ezmlm-send(1) 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.