Commit | Line | Data |
---|---|---|
f8beb284 MW |
1 | .TH ezmlm-cgi 1 |
2 | .SH NAME | |
3 | ezmlm-cgi \- provide WWW access to the list archive | |
4 | .SH SYNOPSIS | |
5 | .B ezmlm-cgi | |
6 | .SH DESCRIPTION | |
7 | .B ezmlm-cgi | |
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 | |
13 | .BR ezmlm-idx(1) , | |
14 | and | |
15 | .B ezmlm-send(1) | |
16 | as part of normal archive access and digest indexing, and | |
17 | by | |
18 | .BR ezmlm-archive(1) . | |
19 | ||
20 | .B ezmlm-cgi | |
21 | uses the httpd-supplied variables | |
22 | .B PATH_INFO | |
23 | to obtain the list number, | |
24 | .B QUERY_STRING | |
25 | to obtain the command, as well as | |
26 | .BR SERVER_NAME , | |
27 | .BR SERVER_PORT , | |
28 | and | |
29 | .B SCRIPT_NAME | |
30 | to create a self-referencing URL. | |
31 | ||
32 | When | |
33 | .B ezmlm-cgi | |
34 | is invoked without a command, it shows the threads for the | |
35 | current month. | |
36 | If no list number is supplied, the default list is shown (see below). | |
37 | .SH CONFIGURATION | |
38 | .B ezmlm-cgi | |
39 | expects to find configuration info in | |
40 | .B /etc/ezmlm/ezcgirc | |
41 | when run SUID root, or | |
42 | .B .ezcgirc | |
43 | otherwise. The entries in this file describe one list per line. Blank lines | |
44 | and comments | |
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: | |
48 | ||
49 | .EX | |
50 | .I listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog | |
51 | .EE | |
52 | ||
53 | .B where: | |
54 | .TP 5 | |
55 | .I listno | |
56 | is the list number using ``0'' for the default list if desired; | |
57 | .TP 5 | |
58 | .I uid | |
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; | |
61 | .TP 5 | |
62 | .I listdir | |
63 | the absolute path to the list base directory (required); | |
64 | .TP 5 | |
65 | .I listaddr | |
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; | |
69 | .TP 5 | |
70 | .I buttonbar | |
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 | |
77 | displays generated by | |
78 | .BR ezmlm-cgi . | |
79 | .TP 5 | |
80 | .I charset | |
81 | the character set used for the main pages (default ``iso-8859-1''); | |
82 | .TP 5 | |
83 | .I style | |
84 | the style sheet used (default none, which doesn't look pretty); | |
85 | .TP 5 | |
86 | .I bannerprog | |
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 | |
91 | .BR chroot(3) . | |
92 | (See SECURITY.) | |
93 | If | |
94 | .I ``bannerprog'' | |
95 | starts with a less-than character (''<'') it is assumed to | |
96 | be a URL which is inserted as is, rather than executed. | |
97 | .TP 5 | |
98 | .I ``;'' | |
99 | the separator can be any non-numeric character and can be different for | |
100 | different | |
101 | .I ezcgirc | |
102 | lines. There | |
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. | |
106 | .SH OPTIONS | |
107 | .TP 5 | |
108 | If ``uid'' is preceded by a minus sign (``-''), | |
109 | .B ezmlm-cgi | |
110 | will not call | |
111 | .B chroot(3) . | |
112 | This potentially decreases security, but may be needed to | |
113 | execute ``bannerprog''. | |
114 | .TP 5 | |
115 | If ``listaddr'' is preceded by a minus sign (``-''), | |
116 | .B ezmlm-cgi | |
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. | |
121 | .SH OUTPUT | |
122 | .B ezmlm-cgi | |
123 | outputs 5 different views. | |
124 | .TP | |
125 | .I thread index | |
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 | |
128 | .B ezmlm-archive(1) | |
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 | |
133 | .B ezmlm-archive(1) | |
134 | is run against an existing archive, the initial sort is in order of the | |
135 | first message in the thread. | |
136 | ||
137 | The subject in the | |
138 | .I thread index | |
139 | is a link to the last message in the thread. | |
140 | .TP | |
141 | .I thread | |
142 | shows the messages in the respective thread in date order. For each message | |
143 | the author is shown linked to the message. | |
144 | .TP | |
145 | .I author index | |
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. | |
148 | .TP | |
149 | .I message by date | |
150 | shows entries in order of arrival of sets of 100 messages. Links are to | |
151 | the message and to the author. | |
152 | .TP | |
153 | .I message | |
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 | |
159 | .BR lynx . | |
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 | |
163 | .I mailto: | |
164 | link for a follow-up post to the list. | |
165 | .SH "OUTPUT FORMATTING" | |
166 | .B ezmlm-cgi | |
167 | outputs html 4.0 in a format suitable for | |
168 | .I Lynx | |
169 | and other text-mode browsers. The format is designed for easy optional | |
170 | enhancement | |
171 | via CSS1/2 type | |
172 | style sheets in the format ``text/css''. | |
173 | .B ezmlm-cgi | |
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" | |
177 | .B ezmlm-cgi | |
178 | will accept a PATH_INFO of the following format: | |
179 | ||
180 | .EX | |
181 | .I /listno/message | |
182 | .EE | |
183 | ||
184 | .B where: | |
185 | .TP 5 | |
186 | .I listno | |
187 | is the list number per config file; | |
188 | .TP 5 | |
189 | .I message | |
190 | is the message number. | |
191 | ||
192 | Thus, | |
193 | .B ezmlm-cgi\fI/2/20000 | |
194 | will return message 20000 from list 2. | |
195 | ||
196 | .B ezmlm-cgi | |
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 | |
199 | .B ezmlm-cgi | |
200 | function. Useful are: | |
201 | .TP | |
202 | .B ezmlm-cgi\fB?listno?ams:message | |
203 | which will return in order the list of messages posted by the author of message | |
204 | .I message | |
205 | on list | |
206 | .IR listno , | |
207 | and | |
208 | .TP | |
209 | .B ezmlm-cgi\fB?listno?sms:message | |
210 | which will return in order the list of messages with the same subject as message | |
211 | .I message | |
212 | .I message | |
213 | on list | |
214 | .IR listno , | |
215 | i.e. the ``thread''. | |
216 | .SH ROBOTS | |
217 | There are many possible URLs for the same message. | |
218 | To still allow external indexing, | |
219 | .B ezmlm-cgi | |
220 | supports the command | |
221 | .I ezmlm-cgi/index | |
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 | |
226 | (separate) | |
227 | .I directory | |
228 | where | |
229 | .B ezmlm-cgi | |
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. | |
235 | .SH EXECUTION | |
236 | .B ezmlm-cgi | |
237 | can operate in three modes, | |
238 | .IR SUID\ root , | |
239 | .IR SUID\ user , | |
240 | and | |
241 | .IR normal . | |
242 | ||
243 | In | |
244 | .I normal | |
245 | and | |
246 | .I SUID user | |
247 | mode, | |
248 | .B ezmlm-cgi | |
249 | will read the configuration file | |
250 | .B .ezcgirc | |
251 | from the working directory set by the httpd daemon | |
252 | (per | |
253 | .B cgi | |
254 | definition this should be the same directory as | |
255 | .B ezmlm-cgi | |
256 | is in), then | |
257 | change directory to the list directory. ``uid'' is ignored. | |
258 | .I SUID user | |
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, | |
262 | .I normal | |
263 | mode usually gives sufficient access. | |
264 | ||
265 | In | |
266 | .I SUID\ root | |
267 | mode, | |
268 | .B ezmlm-cgi | |
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 | |
275 | .B ezmlm-cgi | |
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 | |
285 | view itself. | |
286 | ||
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. | |
291 | ||
292 | .B chroot(3) | |
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 ``-''. | |
296 | .SH SECURITY | |
297 | .B ezmlm-cgi | |
298 | will refuse to run as root. | |
299 | ||
300 | .B ezmlm-cgi | |
301 | does not write or lock any files. | |
302 | ||
303 | .B ezmlm-cgi | |
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). | |
309 | ||
310 | .B ezmlm-cgi | |
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, | |
315 | .B ezmlm-cgi | |
316 | will never execute the program with root permissions. | |
317 | ||
318 | Input to the CGI script is not propagated to the banner program. | |
319 | .SH BUGS | |
320 | .B ezmlm-send(1) | |
321 | updates the list message counter once a message is safely archived, but | |
322 | before it is accepted by | |
323 | .BR qmail(7) . | |
324 | Also, the | |
325 | .I index | |
326 | file is updated before the message is accepted by | |
327 | .BR qmail(7) . | |
328 | If | |
329 | .B qmail(7) | |
330 | fails, | |
331 | .B ezmlm-send(1) | |
332 | resets the counter before terminating. It is possible that in such a situation | |
333 | the message would be replaced by a different one. | |
334 | If | |
335 | .B ezmlm-cgi | |
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 | |
339 | .I index | |
340 | file. In practice, this is relatively harmless. Avoiding it would require | |
341 | locking the list with significant implications for security and performance. | |
342 | .SH "SEE ALSO" | |
343 | ezmlm-archive(1), | |
344 | ezmlm-get(1), | |
345 | ezmlm-idx(1), | |
346 | ezmlm-send(1), | |
347 | ezmlm(5), | |
348 | qmail(7) | |
349 |