ezmlm-cgi(1) ezmlm-cgi(1)
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 com-
mand, 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 sup-
plied, 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 other-
wise. 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;ban-
nerprog
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 pre-
ceded by ``-'' the ``From:'' E-mail address is
replaced by the posters name/handle as a further
1
ezmlm-cgi(1) ezmlm-cgi(1)
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 but-
ton. 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 explana-
tion 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 exe-
cuted.
``;''
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. ``ban-
nerprog'' 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 har-
vesting 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.
2
ezmlm-cgi(1) ezmlm-cgi(1)
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 opti-
mize appearance in lynx. It is self-explanatory to
anyone daring to experiment. For others, you may
wish to supply a ``help'' button. The message sub-
ject 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 struc-
ture.
3
ezmlm-cgi(1) ezmlm-cgi(1)
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 func-
tion. 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 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 com-
mand 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 addi-
tion have a ``noindex'' robot META tag to avoid trapping
robots in the archive.
EXECUTION
ezmlm-cgi can operate in three modes, SUID root,
SUID user, and normal.
In normal and SUID user mode, ezmlm-cgi will read the con-
figuration 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. SUID user may
4
ezmlm-cgi(1) ezmlm-cgi(1)
be required to read the particular archive if it is not
owned by the httpd user. 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 (nor-
mally 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
A banner program can be specified in the config file. It
is executed immediately before the end of the text. The
formatting for ``<BODY>'' is active and the banner program
output is encapsulated in a ``<DIV class=banner>'' segment
to allow additional formatting. The banner program is
called for all summary views, but not for the message view
itself.
The banner program is give the list local name as argument
1, and the host name as argument 2. It is expected to exit
0 on success. The return code is checked, but the archive
page (and whatever the banner program has already pro-
duced) is output even if the banner program fails.
chroot(3) may make it difficult to run banner programs
that depend on e.g. ``sh'' or ``perl''. For this reason,
the chroot call can be suppressed by prefixing the ``uid''
with a ``-''.
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 suf-
ficient access to all list directories and archives).
ezmlm-cgi will allow execution of banner programs that are
located outside of the list directory. These are executed
with the privileges of the userid set in the config file.
If the program is installed SUID root, banner programs
outside of the list directory are not normally accessible.
Even when this is overridden, ezmlm-cgi will never execute
the program with root permissions.
5
ezmlm-cgi(1) ezmlm-cgi(1)
Input to the CGI script is not propagated to the banner
program.
BUGS
ezmlm-send(1) updates the list message counter once a mes-
sage is safely archived, but before it is accepted by
qmail(7). Also, the index file is updated before the mes-
sage is accepted by qmail(7). If qmail(7) fails, ezmlm-
send(1) resets the counter before terminating. It is pos-
sible that in such a situation the message would be
replaced by a different one. If ezmlm-cgi accesses a mes-
sage that ultimately fails and in that time interval, it
may expose a message that ultimately is replaced, espe-
cially 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 per-
formance.
SEE ALSO
ezmlm-archive(1), ezmlm-get(1), ezmlm-idx(1), ezmlmsend(1)
, ezmlm(5), qmail(7)
6
© 1994 Man-cgi 1.15, Panagiotis Christias <christia@theseas.ntua.gr>