MAN page from Fedora 40 ezmlm-idx-cgi-7.2.4-1.1.x86_64.rpm

ezmlm-cgi

Section: User Commands (1)
Index

NAME

ezmlm-cgi - provide WWW access to the list archive

SYNOPSIS

ezmlm-cgi

DESCRIPTION

ezmlm-cgiis executed by the httpd daemon and generates HTTP/CGI/html 4.0-compliantself-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 thearchive directly, aided by index files created byezmlm-idx(1),andezmlm-send(1)as part of normal archive access and digest indexing, andbyezmlm-archive(1).

ezmlm-cgiuses the httpd-supplied variablesPATH_INFOto obtain the list number,QUERY_STRINGto obtain the command, as well asSERVER_NAME,SERVER_PORT,andSCRIPT_NAMEto create a self-referencing URL.

Whenezmlm-cgiis invoked without a command, it shows the threads for thecurrent month.If no list number is supplied, the default list is shown (see below).

CONFIGURATION

ezmlm-cgiexpects to find configuration info in/etc/ezmlm/ezcgircwhen run SUID root, or.ezcgircotherwise. The entries in this file describe one list per line. Blank linesand commentsstarting with a ``#'' in position 1 are allowed and ignored. No extrablanks, tab, etc, are allowed. Entries must beof 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) andif preceded by ``-'' chroot() is suppressed for SUID root installations;
listdir: the absolute path to the list base directory (required);
listaddr: the list address as localAATThost (required) and if preceded by ``-'' the``From:'' E-mail address is replaced by the posters name/handle as afurther 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 subsequenttext should be the URL linked to that button. Use the braces to make thebuttons be consistent with preexisting navigation buttons. It is desirableto add a ``[Help]'' button with a link to an explanation of the variousdisplays generated byezmlm-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 giventhe name of the script and the list as arguments (default none). The pathis relative to ``listdir'' and can point anywhere in the file system. However,for SUID root installations access is normally restricted viachroot(3).(See SECURITY.)If``bannerprog''starts with a less-than character (''<'') it is assumed tobe a URL which is inserted as is, rather than executed.
``;'': the separator can be any non-numeric character and can be different fordifferentezcgirclines. Thereis no quoting/escaping mechanism. Thus, choose a character not present inany 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-cgiwill not callchroot(3) .This potentially decreases security, but may be needed toexecute ``bannerprog''.
If ``listaddr'' is preceded by a minus sign (``-''),: ezmlm-cgiwill, as a precaution against address harvesting robots,remove the sender's E-mail address also in the message view. This isalready done in all other views. The archive user can still obtain the addressby requesting the message by E-mail.

OUTPUT

ezmlm-cgioutputs 5 different views.

thread index: shows the threads which have messages in a given month. The subject isprefixed with the number of messages in the thread for the given month. Whenezmlm-archive(1)is first run against an existing archive, the number is the total number ofmessages in the thread. The subject and author are links to the respectivethread or author index. The threads are ordered in reverse order of latestmessage, i.e. the thread that last received a message is listed last. Whenezmlm-archive(1)is run against an existing archive, the initial sort is in order of thefirst message in the thread.
The subject in thethread indexis a link to the last message in the thread.
thread: shows the messages in the respective thread in date order. For each messagethe author is shown linked to the message.
author index: shows the subject of all messages posted from a given address in order ofarrival at the list. Links are to the messages.
message by date: shows entries in order of arrival of sets of 100 messages. Links are tothe message and to the author.
message: shows the message itself. The message has links to the previous and nextmessage by time, in the thread, or by the same author. There are also linksto 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 conciseto optimize appearance inlynx.It is self-explanatory to anyone daring to experiment. For others, you maywish to supply a ``help'' button.The message subject is amailto:link for a follow-up post to the list.

OUTPUT FORMATTING

ezmlm-cgioutputs html 4.0 in a format suitable forLynxand other text-mode browsers. The format is designed for easy optionalenhancementvia CSS1/2 typestyle sheets in the format ``text/css''.ezmlm-cgiis self-documenting in this respect. Simply review the output in the differentviews and the sample style sheet to see the class structure.

EXTERNAL LINKS TO MESSAGES

ezmlm-cgiwill 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/20000will return message 20000 from list 2.

ezmlm-cgiuses a second syntax based on QUERY_STRING for internal links. Thiscommand set is implemented only as far as required for normalezmlm-cgifunction. Useful are:

ezmlm-cgi?listno?ams:message

which will return in order the list of messages posted by the author of messagemessageon listlistno,and

ezmlm-cgi?listno?sms:message

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

ROBOTS

There are many possible URLs for the same message.To still allow external indexing,ezmlm-cgisupports the commandezmlm-cgi/indexwhich returns a page with links to all lists, except the default list. Theselinks indirectly lead exactly once to each message.None of the links used containa ``?''. Thus, to index the archives, allow access to scripts in the(separate)directorywhereezmlm-cgiis installed, but deny access todirectory/ezmlm-cgi?.Any message will have a ``nofollow'' robot META tag, and any view reached bya URL based on QUERY_STRING will in addition have a ``noindex'' robot META tagto avoid trapping robots in the archive.

EXECUTION

ezmlm-cgican operate in two modes,SUID rootandnormal.ezmlm-cgishould not be installed SUIDuserother than root.Please see theSECURITYsection before installing SUIDroot.

Innormalmode,ezmlm-cgiwill read the configuration file.ezcgircfrom the working directory set by the httpd daemon(percgidefinition this should be the same directory asezmlm-cgiis in), thenchange directory to the list directory. ``uid'' is ignored.For user installations or systems wherethe httpd user has access to all the lists,normalmode usually gives sufficient access.

InSUID rootmode,ezmlm-cgiwill read the configuration info from/etc/ezmlm/ezcgircthen change directory to that directory, thenchange root to that directory, then changeuserid to ``uid''. If ``uid'' is not specified, it will change to theuid of the process invokingezmlm-cgi(normally the httpd user). If the archive files are world-readable, but the listdirectory is not, it is safest to leave ``uid'' blank. The httpd user will stillbe able to read the files.

EXECUTION OF BANNER PROGRAMS

ezmlm-cgisupports display of banners, but not execution of banner programs. Toobtain dynamic banners, use a URL that points to a banner program elsewhere.

SECURITY

ezmlm-cgiwill refuse to run as root.

ezmlm-cgidoes not write or lock any files.

ezmlm-cgihas a short well commented segment of code that potentially runs SUID root.Read the source to convince yourself that this is safe. If possible, installit SUID user, or not SUID at all, if that meets your needs (single listuser, httpd user is list user, or httpd user has sufficient access to alllist directories and archives).

ezmlm-cgiwill not allow execution of banner programs.

BUGS

ezmlm-send(1)updates the list message counter once a message is safely archived, butbefore it is accepted byqmail(7).Also, theindexfile is updated before the message is accepted byqmail(7).Ifqmail(7)fails,ezmlm-send(1)resets the counter before terminating. It is possible that in such a situationthe message would be replaced by a different one.Ifezmlm-cgiaccesses a message that ultimately fails and in that time interval,it may expose a message that ultimately is replaced, especially when doing itvia the ``Messages by date'' view which is based on theindexfile. In practice, this is relatively harmless. Avoiding it would requirelocking the list with significant implications for security and performance.

This document was created byman2html,using the manual pages.