X-Git-Url: https://git.distorted.org.uk/~mdw/ezmlm/blobdiff_plain/5b62e993b0af39700031c2875d7f6654e6a02850..f8beb284087c279acfb30506f5bb32baa4949b44:/ezmlm-cgi.1

diff --git a/ezmlm-cgi.1 b/ezmlm-cgi.1
new file mode 100644
index 0000000..6103ed8
--- /dev/null
+++ b/ezmlm-cgi.1
@@ -0,0 +1,349 @@
+.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)
+