.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 ``'' is active and the banner program output is encapsulated in a ``