3 ezmlm-cgi \- provide WWW access to the list archive
8 is executed by the httpd daemon and generates HTTP/CGI/html 4.0-compliant
9 self-referencing output of index pages for threads in a given month,
10 messages in a thread, messages by a given author, messages by date,
11 and messages themselves with full navigation controls. It uses the
12 archive directly, aided by index files created by
16 as part of normal archive access and digest indexing, and
18 .BR ezmlm-archive(1) .
21 uses the httpd-supplied variables
23 to obtain the list number,
25 to obtain the command, as well as
30 to create a self-referencing URL.
34 is invoked without a command, it shows the threads for the
36 If no list number is supplied, the default list is shown (see below).
39 expects to find configuration info in
41 when run SUID root, or
43 otherwise. The entries in this file describe one list per line. Blank lines
45 starting with a ``#'' in position 1 are allowed and ignored. No extra
46 blanks, tab, etc, are allowed. Entries must be
47 of the following format:
50 .I listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog
56 is the list number using ``0'' for the default list if desired;
59 the user id to switch to if installed SUID root (default invoking user id) and
60 if preceded by ``-'' chroot() is suppressed for SUID root installations;
63 the absolute path to the list base directory (required);
66 the list address as local@host (required) and if preceded by ``-'' the
67 ``From:'' E-mail address is replaced by the posters name/handle as a
68 further precaution against address harvesting;
71 a set of comma-separated fields of the type
72 .IR ``[Home]=http://example.com/list.html''.
73 The text before the ``='' is the exact text displayed and the subsequent
74 text should be the URL linked to that button. Use the braces to make the
75 buttons be consistent with preexisting navigation buttons. It is desirable
76 to add a ``[Help]'' button with a link to an explanation of the various
81 the character set used for the main pages (default ``iso-8859-1'');
84 the style sheet used (default none, which doesn't look pretty);
87 the path to a banner program which is given
88 the name of the script and the list as arguments (default none). The path
89 is relative to ``listdir'' and can point anywhere in the file system. However,
90 for SUID root installations access is normally restricted via
95 starts with a less-than character (''<'') it is assumed to
96 be a URL which is inserted as is, rather than executed.
99 the separator can be any non-numeric character and can be different for
103 is no quoting/escaping mechanism. Thus, choose a character not present in
104 any of the arguments. ``bannerprog'' as the last argument is an exception,
105 and may contain any characters except LF and NUL.
108 If ``uid'' is preceded by a minus sign (``-''),
112 This potentially decreases security, but may be needed to
113 execute ``bannerprog''.
115 If ``listaddr'' is preceded by a minus sign (``-''),
117 will, as a precaution against address harvesting robots,
118 remove the sender's E-mail address also in the message view. This is
119 already done in all other views. The archive user can still obtain the address
120 by requesting the message by E-mail.
123 outputs 5 different views.
126 shows the threads which have messages in a given month. The subject is
127 prefixed with the number of messages in the thread for the given month. When
129 is first run against an existing archive, the number is the total number of
130 messages in the thread. The subject and author are links to the respective
131 thread or author index. The threads are ordered in reverse order of latest
132 message, i.e. the thread that last received a message is listed last. When
134 is run against an existing archive, the initial sort is in order of the
135 first message in the thread.
139 is a link to the last message in the thread.
142 shows the messages in the respective thread in date order. For each message
143 the author is shown linked to the message.
146 shows the subject of all messages posted from a given address in order of
147 arrival at the list. Links are to the messages.
150 shows entries in order of arrival of sets of 100 messages. Links are to
151 the message and to the author.
154 shows the message itself. The message has links to the previous and next
155 message by time, in the thread, or by the same author. There are also links
156 to the other views, as well as links to subscribe, or request FAQ,
157 the message or the thread by E-mail. The navigation bar is very concise
158 to optimize appearance in
160 It is self-explanatory to anyone daring to experiment. For others, you may
161 wish to supply a ``help'' button.
162 The message subject is a
164 link for a follow-up post to the list.
165 .SH "OUTPUT FORMATTING"
167 outputs html 4.0 in a format suitable for
169 and other text-mode browsers. The format is designed for easy optional
172 style sheets in the format ``text/css''.
174 is self-documenting in this respect. Simply review the output in the different
175 views and the sample style sheet to see the class structure.
176 .SH "EXTERNAL LINKS TO MESSAGES"
178 will accept a PATH_INFO of the following format:
187 is the list number per config file;
190 is the message number.
193 .B ezmlm-cgi\fI/2/20000
194 will return message 20000 from list 2.
197 uses a second syntax based on QUERY_STRING for internal links. This
198 command set is implemented only as far as required for normal
200 function. Useful are:
202 .B ezmlm-cgi\fB?listno?ams:message
203 which will return in order the list of messages posted by the author of message
209 .B ezmlm-cgi\fB?listno?sms:message
210 which will return in order the list of messages with the same subject as message
217 There are many possible URLs for the same message.
218 To still allow external indexing,
222 which returns a page with links to all lists, except the default list. These
223 links indirectly lead exactly once to each message.
224 None of the links used contain
225 a ``?''. Thus, to index the archives, allow access to scripts in the
230 is installed, but deny access to
231 .IR directory\fB/ezmlm-cgi\fI? .
232 Any message will have a ``nofollow'' robot META tag, and any view reached by
233 a URL based on QUERY_STRING will in addition have a ``noindex'' robot META tag
234 to avoid trapping robots in the archive.
237 can operate in three modes,
249 will read the configuration file
251 from the working directory set by the httpd daemon
254 definition this should be the same directory as
257 change directory to the list directory. ``uid'' is ignored.
259 may be required to read the particular archive if it is not owned by the
260 httpd user. For user installations or systems where
261 the httpd user has access to all the lists,
263 mode usually gives sufficient access.
269 will read the configuration info from
270 .B /etc/ezmlm/ezcgirc
271 then change directory to that directory, then
272 change root to that directory, then change
273 userid to ``uid''. If ``uid'' is not specified, it will change to the
274 uid of the process invoking
276 (normally the httpd user). If the archive files are world-readable, but the list
277 directory is not, it is safest to leave ``uid'' blank. The httpd user will still
278 be able to read the files.
279 .SH "EXECUTION OF BANNER PROGRAMS"
280 A banner program can be specified in the config file. It is executed
281 immediately before the end of the text. The formatting for
282 ``<BODY>'' is active and the banner program output is encapsulated in
283 a ``<DIV class=banner>'' segment to allow additional formatting.
284 The banner program is called for all summary views, but not for the message
287 The banner program is give the list local name as argument 1, and the host
288 name as argument 2. It is expected to exit 0 on success. The return code is
289 checked, but the archive page (and whatever the banner program has already
290 produced) is output even if the banner program fails.
293 may make it difficult to run banner programs that depend on e.g. ``sh''
294 or ``perl''. For this reason, the chroot call can be suppressed by prefixing
295 the ``uid'' with a ``-''.
298 will refuse to run as root.
301 does not write or lock any files.
304 has a short well commented segment of code that potentially runs SUID root.
305 Read the source to convince yourself that this is safe. If possible, install
306 it SUID user, or not SUID at all, if that meets your needs (single list
307 user, httpd user is list user, or httpd user has sufficient access to all
308 list directories and archives).
311 will allow execution of banner programs that are located outside of the list
312 directory. These are executed with the privileges of the userid set in the
313 config file. If the program is installed SUID root, banner programs outside
314 of the list directory are not normally accessible. Even when this is overridden,
316 will never execute the program with root permissions.
318 Input to the CGI script is not propagated to the banner program.
321 updates the list message counter once a message is safely archived, but
322 before it is accepted by
326 file is updated before the message is accepted by
332 resets the counter before terminating. It is possible that in such a situation
333 the message would be replaced by a different one.
336 accesses a message that ultimately fails and in that time interval,
337 it may expose a message that ultimately is replaced, especially when doing it
338 via the ``Messages by date'' view which is based on the
340 file. In practice, this is relatively harmless. Avoiding it would require
341 locking the list with significant implications for security and performance.
~mdw / ezmlm / blob