Import ezmlm-idx 0.40

[ezmlm] / ezmlm-cgi.1

.TH ezmlm-cgi 1
.SH NAME
ezmlm-cgi \- provide WWW access to the list archive
.SH SYNOPSIS
.B ezmlm-cgi
.SH DESCRIPTION
.B 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
.BR ezmlm-idx(1) ,
and
.B ezmlm-send(1)
as part of normal archive access and digest indexing, and
by
.BR ezmlm-archive(1) .

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

When
.B 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).
.SH CONFIGURATION
.B ezmlm-cgi
expects to find configuration info in
.B /etc/ezmlm/ezcgirc
when run SUID root, or
.B .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:

.EX
.I listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog
.EE

.B where:
.TP 5
.I listno
is the list number using ``0'' for the default list if desired;
.TP 5
.I 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;
.TP 5
.I listdir
 the absolute path to the list base directory (required);
.TP 5
.I 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;
.TP 5
.I buttonbar
a set of comma-separated fields of the type
.IR ``[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
.BR ezmlm-cgi .
.TP 5
.I charset
the character set used for the main pages (default ``iso-8859-1''); 
.TP 5
.I style
the style sheet used (default none, which doesn't look pretty);
.TP 5
.I 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
.BR chroot(3) .
(See SECURITY.)
If
.I ``bannerprog''
starts with a less-than character (''<'') it is assumed to
be a URL which is inserted as is, rather than executed.
.TP 5
.I ``;''
the separator can be any non-numeric character and can be different for
different
.I 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.
.SH OPTIONS
.TP 5
If ``uid'' is preceded by a minus sign (``-''),
.B ezmlm-cgi
will not call
.B chroot(3) .
This potentially decreases security, but may be needed to
execute ``bannerprog''.
.TP 5
If ``listaddr'' is preceded by a minus sign (``-''),
.B 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.
.SH OUTPUT
.B ezmlm-cgi
outputs 5 different views.
.TP
.I 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
.B 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
.B 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
.I thread index
is a link to the last message in the thread.
.TP
.I thread
shows the messages in the respective thread in date order. For each message
the author is shown linked to the message.
.TP
.I 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.
.TP
.I message by date
shows entries in order of arrival of sets of 100 messages. Links are to
the message and to the author.
.TP
.I 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
.BR 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
.I mailto:
link for a follow-up post to the list. 
.SH "OUTPUT FORMATTING"
.B ezmlm-cgi
outputs html 4.0 in a format suitable for
.I 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''.
.B 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.
.SH "EXTERNAL LINKS TO MESSAGES"
.B ezmlm-cgi
will accept a PATH_INFO of the following format:

.EX
.I /listno/message
.EE

.B where:
.TP 5
.I listno
is the list number per config file;
.TP 5
.I message
is the message number.

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

.B 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
.B ezmlm-cgi
function. Useful are:
.TP
.B ezmlm-cgi\fB?listno?ams:message
which will return in order the list of messages posted by the author of message
.I message
on list
.IR listno ,
and
.TP
.B ezmlm-cgi\fB?listno?sms:message
which will return in order the list of messages with the same subject as message
.I message
.I message
on list
.IR listno ,
i.e. the ``thread''.
.SH ROBOTS
There are many possible URLs for the same message.
To still allow external indexing,
.B ezmlm-cgi
supports the command
.I 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)
.I directory
where
.B ezmlm-cgi
is installed, but deny access to
.IR directory\fB/ezmlm-cgi\fI? .
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.
.SH EXECUTION
.B ezmlm-cgi
can operate in three modes,
.IR SUID\ root ,
.IR SUID\ user ,
and
.IR normal .

In
.I normal
and
.I SUID user
mode,
.B ezmlm-cgi
will read the configuration file
.B .ezcgirc
from the working directory set by the httpd daemon
(per
.B cgi
definition this should be the same directory as
.B ezmlm-cgi
is in), then
change directory to the list directory. ``uid'' is ignored.
.I SUID user
may 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,
.I normal
mode usually gives sufficient access.

In
.I SUID\ root
mode,
.B ezmlm-cgi
will read the configuration info from
.B /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
.B 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.
.SH "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
produced) is output even if the banner program fails.

.B 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 ``-''.
.SH SECURITY
.B ezmlm-cgi
will refuse to run as root.

.B ezmlm-cgi
does not write or lock any files.

.B 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).

.B 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,
.B ezmlm-cgi
will never execute the program with root permissions.

Input to the CGI script is not propagated to the banner program.
.SH BUGS
.B ezmlm-send(1)
updates the list message counter once a message is safely archived, but
before it is accepted by
.BR qmail(7) .
Also, the
.I index
file is updated before the message is accepted by
.BR qmail(7) .
If
.B qmail(7)
fails,
.B 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
.B 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
.I index
file. In practice, this is relatively harmless. Avoiding it would require
locking the list with significant implications for security and performance.
.SH "SEE ALSO"
ezmlm-archive(1),
ezmlm-get(1),
ezmlm-idx(1),
ezmlm-send(1),
ezmlm(5),
qmail(7)