ezmlm-cgi(1) ezmlm-cgi(1) NNAAMMEE ezmlm-cgi - provide WWW access to the list archive SSYYNNOOPPSSIISS eezzmmllmm--ccggii DDEESSCCRRIIPPTTIIOONN eezzmmllmm--ccggii 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 eezzmmllmm--iiddxx((11)), and eezzmmllmm--sseenndd((11)) as part of normal archive access and digest indexing, and by eezzmmllmm--aarrcchhiivvee((11)). eezzmmllmm--ccggii uses the httpd-supplied variables PPAATTHH__IINNFFOO to obtain the list number, QQUUEERRYY__SSTTRRIINNGG to obtain the command, as well as SSEERRVVEERR__NNAAMMEE, SSEERRVVEERR__PPOORRTT, and SSCCRRIIPPTT__NNAAMMEE to create a self-referencing URL. When eezzmmllmm--ccggii 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). CCOONNFFIIGGUURRAATTIIOONN eezzmmllmm--ccggii expects to find configuration info in //eettcc//eezzmmllmm//eezzccggiirrcc when run SUID root, or ..eezzccggiirrcc 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: _l_i_s_t_n_o_;_u_i_d_;_l_i_s_t_d_i_r_;_l_i_s_t_a_d_d_r_;_b_u_t_t_o_n_b_a_r_;_c_h_a_r_s_e_t_;_s_t_y_l_e_;_b_a_n_n_e_r_p_r_o_g wwhheerree:: _l_i_s_t_n_o is the list number using ‘‘0’’ for the default list if desired; _u_i_d 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; _l_i_s_t_d_i_r the absolute path to the list base directory (required); _l_i_s_t_a_d_d_r the list address as local@host (required) and if preceded by ‘‘-’’ the ‘‘From:’’ E-mail address is replaced by the posters name/han- dle as a further precaution against address harvesting; _b_u_t_t_o_n_b_a_r a set of comma-separated fields of the type _‘_‘_[_H_o_m_e_]_=_h_t_t_p_:_/_/_e_x_a_m_- _p_l_e_._c_o_m_/_l_i_s_t_._h_t_m_l_’_’_. 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 pre- existing navigation buttons. It is desirable to add a ‘‘[Help]’’ button with a link to an explanation of the various displays gen- erated by eezzmmllmm--ccggii. _c_h_a_r_s_e_t the character set used for the main pages (default ‘‘iso-8859-1’’); _s_t_y_l_e the style sheet used (default none, which doesn’t look pretty); _b_a_n_n_e_r_p_r_o_g 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 cchhrroooott((33)). (See SECURITY.) If _‘_‘_b_a_n_n_e_r_p_r_o_g_’_’ starts with a less- than character (’’<’’) it is assumed to be a URL which is inserted as is, rather than executed. _‘_‘_;_’_’ the separator can be any non-numeric character and can be differ- ent for different _e_z_c_g_i_r_c 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. OOPPTTIIOONNSS If ‘‘uid’’ is preceded by a minus sign (‘‘-’’), eezzmmllmm--ccggii will not call cchhrroooott((33)) .. This potentially decreases security, but may be needed to execute ‘‘bannerprog’’. If ‘‘listaddr’’ is preceded by a minus sign (‘‘-’’), eezzmmllmm--ccggii 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. OOUUTTPPUUTT eezzmmllmm--ccggii outputs 5 different views. _t_h_r_e_a_d _i_n_d_e_x shows the threads which have messages in a given month. The sub- ject is prefixed with the number of messages in the thread for the given month. When eezzmmllmm--aarrcchhiivvee((11)) 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 eezzmmllmm--aarrcchhiivvee((11)) is run against an existing archive, the initial sort is in order of the first message in the thread. The subject in the _t_h_r_e_a_d _i_n_d_e_x is a link to the last message in the thread. _t_h_r_e_a_d shows the messages in the respective thread in date order. For each message the author is shown linked to the message. _a_u_t_h_o_r _i_n_d_e_x shows the subject of all messages posted from a given address in order of arrival at the list. Links are to the messages. _m_e_s_s_a_g_e _b_y _d_a_t_e shows entries in order of arrival of sets of 100 messages. Links are to the message and to the author. _m_e_s_s_a_g_e 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 llyynnxx. It is self-explanatory to anyone daring to experiment. For others, you may wish to supply a ‘‘help’’ button. The mes- sage subject is a _m_a_i_l_t_o_: link for a follow-up post to the list. OOUUTTPPUUTT FFOORRMMAATTTTIINNGG eezzmmllmm--ccggii outputs html 4.0 in a format suitable for _L_y_n_x and other text-mode browsers. The format is designed for easy optional enhance- ment via CSS1/2 type style sheets in the format ‘‘text/css’’. eezzmmllmm-- ccggii 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. EEXXTTEERRNNAALL LLIINNKKSS TTOO MMEESSSSAAGGEESS eezzmmllmm--ccggii will accept a PATH_INFO of the following format: _/_l_i_s_t_n_o_/_m_e_s_s_a_g_e wwhheerree:: _l_i_s_t_n_o is the list number per config file; _m_e_s_s_a_g_e is the message number. Thus, eezzmmllmm--ccggii_/_2_/_2_0_0_0_0 will return message 20000 from list 2. eezzmmllmm--ccggii uses a second syntax based on QUERY_STRING for internal links. This command set is implemented only as far as required for normal eezzmmllmm--ccggii function. Useful are: eezzmmllmm--ccggii??lliissttnnoo??aammss::mmeessssaaggee which will return in order the list of messages posted by the author of message _m_e_s_s_a_g_e on list _l_i_s_t_n_o, and eezzmmllmm--ccggii??lliissttnnoo??ssmmss::mmeessssaaggee which will return in order the list of messages with the same sub- ject as message _m_e_s_s_a_g_e _m_e_s_s_a_g_e on list _l_i_s_t_n_o, i.e. the ‘‘thread’’. RROOBBOOTTSS There are many possible URLs for the same message. To still allow external indexing, eezzmmllmm--ccggii supports the command _e_z_m_l_m_-_c_g_i_/_i_n_d_e_x 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) _d_i_r_e_c_t_o_r_y where eezzmmllmm--ccggii is installed, but deny access to _d_i_r_e_c_t_o_r_y//eezzmmllmm--ccggii_?. Any message will have a ‘‘nofol- low’’ 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. EEXXEECCUUTTIIOONN eezzmmllmm--ccggii can operate in two modes, _S_U_I_D _r_o_o_t and _n_o_r_m_a_l. eezzmmllmm--ccggii should not be installed SUID _u_s_e_r other than root. Please see the SSEECCUURRIITTYY section before installing SUID _r_o_o_t. In _n_o_r_m_a_l mode, eezzmmllmm--ccggii will read the configuration file ..eezzccggiirrcc from the working directory set by the httpd daemon (per ccggii definition this should be the same directory as eezzmmllmm--ccggii is in), then change directory to the list directory. ‘‘uid’’ is ignored. For user instal- lations or systems where the httpd user has access to all the lists, _n_o_r_m_a_l mode usually gives sufficient access. In _S_U_I_D _r_o_o_t mode, eezzmmllmm--ccggii will read the configuration info from //eettcc//eezzmmllmm//eezzccggiirrcc 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 eezzmmllmm-- ccggii (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. EEXXEECCUUTTIIOONN OOFF BBAANNNNEERR PPRROOGGRRAAMMSS eezzmmllmm--ccggii supports display of banners, but not execution of banner pro- grams. To obtain dynamic banners, use a URL that points to a banner program elsewhere. SSEECCUURRIITTYY eezzmmllmm--ccggii will refuse to run as root. eezzmmllmm--ccggii does not write or lock any files. eezzmmllmm--ccggii 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). eezzmmllmm--ccggii will not allow execution of banner programs. BBUUGGSS eezzmmllmm--sseenndd((11)) updates the list message counter once a message is safely archived, but before it is accepted by qqmmaaiill((77)). Also, the _i_n_d_e_x file is updated before the message is accepted by qqmmaaiill((77)). If qqmmaaiill((77)) fails, eezzmmllmm--sseenndd((11)) resets the counter before terminating. It is pos- sible that in such a situation the message would be replaced by a dif- ferent one. If eezzmmllmm--ccggii 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_n_d_e_x file. In practice, this is relatively harm- less. Avoiding it would require locking the list with significant implications for security and performance. SSEEEE AALLSSOO ezmlm-archive(1), ezmlm-get(1), ezmlm-idx(1), ezmlm-send(1), ezmlm(5), qmail(7) ezmlm-cgi(1)