Commit | Line | Data |
---|---|---|
f8beb284 MW |
1 | .TH ezmlm-get 1 |
2 | .SH NAME | |
3 | ezmlm-get \- handles mailing list archive retrieval and digests | |
4 | .SH SYNOPSIS | |
5 | .B ezmlm-get | |
6 | [ | |
7 | .B \-bBcCpPsSvV | |
8 | ][ | |
9 | .B \-f | |
10 | .I format | |
11 | ] | |
12 | .I dir | |
13 | [ | |
14 | .I digestcode[f] | |
15 | ] | |
16 | .SH OPTIONS | |
17 | .TP | |
18 | .B \-b | |
19 | (Default.) | |
20 | Copy administrative information and the request to the bottom of replies. | |
21 | This informs the recipient of other commands, and allows some error tracking | |
22 | in case the recipient did not originate the request. | |
23 | .TP | |
24 | .B \-B | |
25 | Suppress the normal administrative information and request copy. This may make | |
26 | it harder for the recipient to diagnose problems and learn commands. | |
27 | .TP | |
28 | .B \-c | |
29 | (Default.) | |
30 | Process and reply to commands (does not affect digests). | |
31 | .TP | |
32 | .B \-C | |
33 | Ignore all commands except digest. | |
34 | .TP | |
35 | .B \-f \fIformat | |
36 | .B ezmlm-get | |
37 | will use | |
38 | .I format | |
39 | as the default format for all returned message collections. The default | |
40 | is 'm' for MIME with a header subset (see below). Format specifiers | |
41 | send with individual requests override the default set with the | |
42 | .B \-f | |
43 | switch. | |
44 | .TP | |
45 | .B \-p | |
46 | \-get, \-index, and \-thread commands are available to all users, | |
47 | provided other flags are permissive. This overrides normal behavior, | |
48 | which is to allow archive retrieval only to moderators, when | |
49 | .I dir\fB/public | |
50 | does not exist. This is useful to set up non-public lists that still give | |
51 | users archive access. | |
52 | .TP | |
53 | .B \-P | |
54 | \-get, \-index, and \-thread commands are available | |
55 | only to moderators, even if | |
56 | .I dir\fB/public | |
57 | exists. The | |
58 | .B \-C | |
59 | and | |
60 | .B \-s | |
61 | flags can restrict this further. This is useful for public lists with | |
62 | archive retrieval restricted to a subset of users (moderators). | |
63 | .TP | |
64 | .B \-s | |
65 | \-get, \-index, and \-thread requests are processed only if | |
66 | .B SENDER | |
67 | is a subscriber. | |
68 | .TP | |
69 | .B \-S | |
70 | (Default.) | |
71 | Anyone can issue \-get, \-index, and \-thread requests. | |
72 | .TP | |
73 | .B \-v | |
74 | Print version info. | |
75 | .TP | |
76 | .B \-V | |
77 | Print version info. | |
78 | .SH DESCRIPTION | |
79 | .B ezmlm-get | |
80 | handles archive retrieval and optionally makes and sends out | |
81 | digests for the mailing list | |
82 | stored in | |
83 | .IR dir . | |
84 | Subscribers of the digest list are stored in | |
85 | .IR dir\fB/digest/subscribers/ . | |
86 | ||
87 | The contents of | |
88 | .I dir\fB/headeradd | |
89 | are added to the header of outgoing messages. | |
90 | ||
91 | .B ezmlm-get | |
92 | is normally invoked from a | |
93 | .B .qmail(7) | |
94 | file. | |
95 | ||
96 | It reads a mail message from its standard input, | |
97 | and a mail envelope from the | |
98 | .BR SENDER , | |
99 | .BR LOCAL , | |
100 | and | |
101 | .BR HOST | |
102 | environment variables. | |
103 | ||
104 | .B ezmlm-get | |
105 | uses | |
106 | .B LOCAL | |
107 | to determine where it is invoked. If | |
108 | .B LOCAL | |
109 | is the list local name only, | |
110 | .B ezmlm-get | |
111 | assumes it is run from | |
112 | .I dir\fB/editor | |
113 | to produce a digest. | |
114 | The digest is sent directly to the digest list subscribers. | |
115 | ||
116 | If | |
117 | .B LOCAL | |
118 | is empty or undefined, | |
119 | .B ezmlm-get | |
120 | assumes it is run from the command line or a script. In this case | |
121 | it behaves as if run from | |
122 | .I dir\fB/editor | |
123 | and sends out a digest to the digest subscribers. | |
124 | ||
125 | Otherwise, | |
126 | .B ezmlm-get | |
127 | expects | |
128 | .B LOCAL | |
129 | to be of the form | |
130 | .IR list\fB-\fIaction . | |
131 | Here | |
132 | .I list | |
133 | is the first line of | |
134 | .IR dir\fB/inlocal | |
135 | and | |
136 | .I action | |
137 | is a request. | |
138 | The output is sent to the envelope sender. | |
139 | ||
140 | .BR ezmlm-get | |
141 | checks | |
142 | .I action | |
143 | for | |
144 | .BR dig\.\fIdigestcode , | |
145 | .BR index , | |
146 | .BR thread , | |
147 | and | |
148 | .BR get . | |
149 | If | |
150 | .I action | |
151 | is one of these, | |
152 | .B ezmlm-get | |
153 | handles the request and sends a reply. If successful, it | |
154 | exits 99 (ignore remaining | |
155 | .B .qmail(7) | |
156 | file entries). | |
157 | If | |
158 | .I action | |
159 | is not one of these, | |
160 | .B ezmlm-get | |
161 | exits 0 (success) to pass the message on to later handlers, | |
162 | such as | |
163 | .BR ezmlm-manage(1) . | |
164 | ||
165 | .B ezmlm-get | |
166 | expects | |
167 | .B HOST | |
168 | to match the first line of | |
169 | .IR dir\fB/inhost . | |
170 | ||
171 | .BR ezmlm-dig\.\fIdigestcode | |
172 | returns a digest of messages received since the last digest, unless | |
173 | numerical arguments are given. | |
174 | .I digestcode | |
175 | must be alphanumeric, and match (case-insensitive) | |
176 | .I digestcode | |
177 | on the | |
178 | .B ezmlm-get | |
179 | command line. Otherwise, the request will be ignored. This is to restrict | |
180 | digest creation. The body of the requesting message up to the first line | |
181 | starting with '-' is copied into the | |
182 | .I administrivia | |
183 | section of the digest. This is followed by the contents of | |
184 | .IR dir\fB/text/digest , | |
185 | if this file exists. | |
186 | ||
187 | .B Note: | |
188 | Anyone who can read your | |
189 | .I dir\fB/manager | |
190 | file, digest-requesting scripts, or mail log knows the | |
191 | .I digestcode | |
192 | and can trigger digests. | |
193 | ||
194 | .B ezmlm-get | |
195 | copies | |
196 | .I dir\fB/mailinglist | |
197 | into a | |
198 | .B Mailing-List | |
199 | field in its response. | |
200 | If the incoming message has a | |
201 | .B Mailing-List | |
202 | field, | |
203 | .B ezmlm-get | |
204 | refuses to respond. | |
205 | .B ezmlm-get | |
206 | also refuses to respond to bounce messages. | |
207 | ||
208 | If | |
209 | .I dir\fB/listid | |
210 | exists, | |
211 | .B ezmlm-get | |
212 | will assume that the format is correct and | |
213 | create a ``List-ID:'' header by placing the contents after the | |
214 | text ``List-ID: ''. | |
215 | ||
216 | If | |
217 | .I dir\fB/qmqpservers | |
218 | exists, | |
219 | .B ezmlm-get will use | |
220 | .B qmail-qmqp(1) | |
221 | to send digests. Other messages are sent by the normal qmail mechanism. | |
222 | ||
223 | If | |
224 | .I dir\fB/public | |
225 | does not exist, | |
226 | .B ezmlm-get | |
227 | rejects all archive retrieval attempts, unless the | |
228 | .B \-p | |
229 | command line switch is used. | |
230 | ||
231 | Archive retrieval actions can be of the form | |
232 | .BR action[f] , | |
233 | .BR action[f].\fInum | |
234 | or | |
235 | .BR action[f].\fInum_num2 , | |
236 | where | |
237 | .I num | |
238 | is the message number for the action or | |
239 | .I num_num2 | |
240 | the range of message numbers for the action. | |
241 | ||
242 | .B f | |
243 | is an optional format specifier for | |
244 | .IR \-get , | |
245 | .IR \-thread , | |
246 | and | |
247 | .I \-dig | |
248 | requests. It is allowed, but ignored for | |
249 | .I \-index | |
250 | requests. Currently, the following are allowed: | |
251 | ||
252 | .TP | |
253 | .B r | |
254 | rfc1153. This is a ``plain'' non-MIME format for dumb clients. | |
255 | .TP | |
256 | .B m | |
257 | (Default.) MIME | |
258 | .I multipart/digest | |
259 | with a subset of ordered headers sorted. | |
260 | Currently, the following headers are | |
261 | included in the order listed: | |
262 | Date:, | |
263 | To:, | |
264 | From:, | |
265 | Reply-To:, | |
266 | Cc:, | |
267 | MIME-Version:, | |
268 | Content-Type:, | |
269 | Message-ID:, | |
270 | and Keywords:. | |
271 | This can be customized with the optional file | |
272 | .IR dir\fB/digheaders , | |
273 | which should contain the desired headers up to but not including the colon. | |
274 | ||
275 | The format is no longer compliant | |
276 | with rfc1153, as the rfc1153 format is incompatible with rfc2046, which | |
277 | which the format is (should be) compatible. | |
278 | .TP | |
279 | .B x | |
280 | MIXED: This is the same as the default MIME | |
281 | format, except that the Content-Type is | |
282 | .IR multipart/mixed . | |
283 | This helps circumnavigate a Pine bug: when the digest is | |
284 | content-transfer-encoded, Pine will refuse to display the initial | |
285 | text/plain part of a | |
286 | .I multipart/digest | |
287 | message, but display the same part of a | |
288 | .I multipart/mixed | |
289 | message. Some MUAs for some strange reason treat the two multipart formats | |
290 | differently. In some cases, ``x'' works better than ``m''. | |
291 | .TP | |
292 | .B v | |
293 | VIRGIN: This is MIME | |
294 | .I multipart/digest | |
295 | with messages returned without any header filtering. | |
296 | .TP | |
297 | .B n | |
298 | NATIVE: This is VIRGIN format without threading, i.e. messages are | |
299 | presented in numerical order and the message index is suppressed. | |
300 | ||
301 | .PP | |
302 | For flexibility and backwards compatibility, the '.' separating the action from | |
303 | the first argument can be replaced by '\-', | |
304 | or omitted. | |
305 | Any non-alphanumeric character can separate | |
306 | .I num2 | |
307 | from | |
308 | .IR num . | |
309 | .PP | |
310 | ||
311 | If | |
312 | .I action | |
313 | is | |
314 | .IR dig.digestcode , | |
315 | .B ezmlm-get | |
316 | returns a digest of the messages received since the last digest, and updates | |
317 | the digest issue counter. | |
318 | ||
319 | If | |
320 | .I action | |
321 | is | |
322 | .IR get , | |
323 | .B ezmlm-get | |
324 | sends back message(s) | |
325 | .I num | |
326 | or | |
327 | .I num | |
328 | through | |
329 | .IR num2 . | |
330 | from | |
331 | .IR dir\fB/archive/ . | |
332 | If | |
333 | .I num | |
334 | is omitted and | |
335 | .I dir\fB/dignum | |
336 | does not exist or is 0, the latest HISTGET message (default 30) are | |
337 | returned. Otherwise, | |
338 | the messages since the latest digest are returned including the last | |
339 | message in that digest, so that always at least 1 message is send. If the | |
340 | number of messages | |
341 | exceeds MAXGET (default 100), only the MAXGET last messages are returned. | |
342 | if | |
343 | .I num | |
344 | is greater than the latest message in the archive _and_ | |
345 | .I num2 | |
346 | is specified, the latest messages back to HISTGET before the end of the | |
347 | latest digest up to MAXGET messages are returned. This is a good way of | |
348 | always getting at least the latest 30 messages without knowing the latest | |
349 | message number. A link with such a command could be put into e.g. | |
350 | .IR dir\fB/text/sub-ok . | |
351 | ||
352 | .I num | |
353 | and | |
354 | .I num2 | |
355 | are adjusted to make both > 0, and | |
356 | .I num2 | |
357 | >= | |
358 | .IR num . | |
359 | If either is greater than | |
360 | the largest message number processed, it is silently | |
361 | set to the largest message number. | |
362 | At most 100 messages are | |
363 | returned. | |
364 | ||
365 | If | |
366 | .I action | |
367 | is | |
368 | .BI index , | |
369 | .B ezmlm-get | |
370 | sends back the subjects and authors of the message(s) | |
371 | .I num | |
372 | or | |
373 | .IR num | |
374 | through | |
375 | .I num2 | |
376 | in sets of 100 from | |
377 | .IR dir\fB/archive/ . | |
378 | .I num | |
379 | and | |
380 | .I num2 | |
381 | are reasonable adjusted as for 'get'. No warnings are | |
382 | sent. At most 20 sets of 100 message entries are returned per request. If | |
383 | .I num | |
384 | is omitted, | |
385 | .B ezmlm-get | |
386 | returns the last 100-200 message entries, which automatically gives | |
387 | information about the last message number. | |
388 | ||
389 | If | |
390 | .I action | |
391 | is | |
392 | .BI thread , | |
393 | .B ezmlm-get | |
394 | sends back the message(s) that have an index subject entry identical to | |
395 | that of message | |
396 | .I num | |
397 | from | |
398 | .IR dir\fB/archive/ . | |
399 | ||
400 | If | |
401 | .I num2 | |
402 | is given it is ignored. If | |
403 | .I num | |
404 | is out of range, and error | |
405 | message is returned. The message range scanned for the subject is limited | |
406 | to 2000 messages before and after the master message, i.e. the | |
407 | .BR thread | |
408 | argument. | |
409 | This limit protects very large archives. | |
410 | Most threads are expected to be considerably more short-lived. | |
411 | In the unlikely event that there are further messages, | |
412 | these can be retrieved by a second request for the | |
413 | highest/lowest message returned in the first request. | |
414 | .SH "CHARACTER SETS" | |
415 | If | |
416 | .I dir\fB/charset | |
417 | exists, | |
418 | .B ezmlm-get | |
419 | will use the character set listed for all messages. Otherwise, the | |
420 | default ``us-ascii'' will be used. The character set can be suffixed | |
421 | by ``:'' followed by a code. If the code is ``Q'', outgoing messages are | |
422 | sent as ``Quoted-Printable'', if it is ``B'' they are sent ``base64'' encoded. | |
423 | Otherwise, text is sent as is. | |
424 | .SH "FILES" | |
425 | .TP | |
426 | .I dir\fB/dignum | |
427 | The last message included in the latest normal mode digest. | |
428 | .TP | |
429 | .I dir\fB/digissue | |
430 | The issue number of the latest normal mode digest. | |
431 | .TP | |
432 | .I dir\fB/text/get-bad | |
433 | Returned if a/the message cannot be found. | |
434 | .TP | |
435 | .I dir\fB/text/digest | |
436 | Copied into the | |
437 | .I Administrivia | |
438 | section of digests after the body of the requesting message. | |
439 | .TP | |
440 | .I dir\fB/charset | |
441 | The character set used for all | |
442 | .B ezmlm-get | |
443 | messages (see above). | |
444 | If not present, the default, ``us-ascii'', is used without encoding. | |
445 | .SH BUGS | |
446 | The digest format per rfc2046 | |
447 | should (but is not required to) be multipart/mixed | |
448 | with the table-of-contents a text/plain part, and the entire remainder of | |
449 | the digest a multipart/digest part. The multipart/digest in turn should | |
450 | contain all the messages. Many | |
451 | MUA's fail to split out the individual messages from such a hierarchy, so the | |
452 | format used by | |
453 | .B ezmlm-get | |
454 | is a simple multipart/digest, explicitly typing the table-of-contents | |
455 | to text/plain, with the ``x'' format changing the mail content-type to | |
456 | multipart/mixed. | |
457 | .SH "SEE ALSO" | |
458 | ezmlm-make(1), | |
459 | ezmlm-manage(1), | |
460 | ezmlm-send(1), | |
461 | ezmlm(5), | |
462 | qmail-command(8), | |
463 | qmail-qmqp(1) | |
464 |