| 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 | |