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