Pileus Git - ~andy/fetchmail/blob - design-notes.html

   1 <!doctype HTML public "-//W3O//DTD W3 HTML 2.0//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Design notes on fetchmail</TITLE>
   5 <link rev=made href=mailto:esr@snark.thyrsus.com>
   6 <meta name="description" content="Design notes on fetchmail.">
   7 <meta name="keywords" content="fetchmail, POP, POP2, POP3, IMAP, remote mail">
   8 </HEAD>
   9 <BODY>
  10 <H1><center>Design Notes On Fetchmail</center></H1>
  11
  12 Back to <A HREF="index.html">Fetchmail Home Page</A>.
  13 <hr>
  14
  15 This notes are for the benefit of future hackers and maintainers.
  16 The following sections are both functional and narrative, read from
  17 beginning to end.<P>
  18
  19 <H1>History</H1>
  20
  21 A direct ancestor of the fetchmail program was originally authored
  22 (under the name popclient) by Carl Harris <ceharris@mal.com>. I took
  23 over development in June 1996 and subsequently renamed the program
  24 `fetchmail' to reflect the addition of IMAP support.  In early
  25 November 1996 Carl officially ended support for the last popclient
  26 versions.<P>
  27
  28 Before accepting responsibility for the popclient sources from Carl, I
  29 had investigated and used and tinkered with every other UNIX
  30 remote-mail forwarder I could find, including fetchpop1.9,
  31 PopTart-0.9.3, get-mail, gwpop, pimp-1.0, pop-perl5-1.2, popc,
  32 popmail-1.6 and upop.  My major goal was to get a header-rewrite
  33 feature like fetchmail's working so I wouldn't have reply problems
  34 anymore.<P>
  35
  36 Despite having done a good bit of work on fetchpop1.9, when I found
  37 popclient I quickly concluded that it offered the solidest base for
  38 future development.  I was convinced of this primarily by the presence
  39 of multiple-protocol support.  The competition didn't do
  40 POP2/RPOP/APOP, and I was already having vague thoughts of maybe
  41 adding IMAP.  (This would advance two other goals: learn IMAP and get
  42 comfortable writing TCP/IP client software.)<P>
  43
  44 Until popclient 3.05 I was simply following out the implications of
  45 Carl's basic design.  He already had daemon.c in the distribution,
  46 and I wanted daemon mode almost as badly as I wanted the header
  47 rewrite feature.  The other things I added were bug fixes or
  48 minor extensions.<P>
  49
  50 After 3.1, when I put in SMTP-forwarding support (more about this
  51 below) the nature of the project changed -- it became a
  52 carefully-thought-out attempt to render obsolete every other program
  53 in its class.  The name change quickly followed.<P>
  54
  55 <H1>The rewrite option</H1>
  56
  57 RFC 1123 stipulates that MTAs ought to canonicalize the addresses of
  58 outgoing mail so that From:, To:, Cc:, Bcc: and other address headers
  59 contain only fully qualified domain names.  Failure to do so can break
  60 the reply function on many mailers.<P>
  61
  62 This problem only becomes obvious when a reply is generated on a
  63 machine different from where the message was delivered.  The
  64 two machines will have different local username spaces, potentially
  65 leading to misrouted mail.<P>
  66
  67 Most MTAs (and sendmail in particular) do not canonicalize address headers
  68 in this way (violating RFC 1123).  Fetchmail therefore has to do it.  This
  69 is the first feature I added to the ancestral popclient.<P>
  70
  71 <H1>Reorganization</H1>
  72
  73 The second thing I did reorganize and simplify popclient a lot.  Carl
  74 Harris's implementation was very sound, but exhibited a kind of
  75 unnecessary complexity common to many C programmers.  He treated the
  76 code as central and the data structures as support for the code.  As a
  77 result, the code was beautiful but the data structure design ad-hoc
  78 and rather ugly (at least to this old LISP hacker).<P>
  79
  80 I was able to improve matters significantly by reorganizing most of the
  81 program around the `query' data structure and eliminating a bunch of
  82 global context.  This especially simplified the main sequence in
  83 fetchmail.c and was critical in enabling the daemon mode changes.<P>
  84
  85 <H1>IMAP support and the method table</H1>
  86
  87 The next step was IMAP support.  I initially wrote the IMAP code
  88 as a generic query driver and a method table.  The idea was to have
  89 all the protocol-independent setup logic and flow of control in the
  90 driver, and the protocol-specific stuff in the method table.<P>
  91
  92 Once this worked, I rewrote the POP3 code to use the same organization.
  93 The POP2 code kept its own driver for a couple more releases, until
  94 I found sources of a POP2 server to test against (the breed seems
  95 to be nearly extinct).<P>
  96
  97 The purpose of this reorganization, of course, is to trivialize
  98 the development of support for future protocols as much as possible.
  99 All mail-retrieval protocols have to have pretty similar logical
 100 design by the nature of the task.  By abstracting out that common
 101 logic and its interface to the rest of the program, both the common
 102 and protocol-specific parts become easier to understand.<P>
 103
 104 Furthermore, many kinds of new features can instantly be supported
 105 across all protocols by modifying the one driver module.<P>
 106
 107 <H1>Implications of smtp forwarding</H1>
 108
 109 The direction of the project changed radically when Harry Hochheiser
 110 sent me his scratch code for forwarding fetched mail to the SMTP port.
 111 I realized almost immediately that a reliable implementation of this
 112 feature would make all the other delivery modes obsolete.<P>
 113
 114 Why mess with all the complexity of configuring an MDA or setting up
 115 lock-and-append on a mailbox when port 25 is guaranteed to be there on
 116 any platform with TCP/IP support in the first place?  Especially when
 117 this means retrieved mail is guaranteed to look like normal sender-
 118 initiated SMTP mail, which is really what we want anyway.<P>
 119
 120 Clearly, the right thing to do was (1) hack SMTP forwarding support
 121 into the generic driver, (2) make it the default mode, and (3) eventually
 122 throw out all the other delivery modes.  <P>
 123
 124 I hesitated over step 3 for some time, fearing to upset long-time
 125 popclient users dependent on the alternate delivery mechanisms.  In
 126 theory, they could immediately switch to .forward files or their
 127 non-sendmail equivalents to get the same effects.  In practice the
 128 transition might have been messy.<P>
 129
 130 But when I did it (see the NEWS note on the great options massacre)
 131 the benefits proved huge.  The cruftiest parts of the driver code
 132 vanished.  Configuration got radically simpler -- no more grovelling
 133 around for the system MDA and user's mailbox, no more worries about
 134 whether the underlying OS supports file locking.<P>
 135
 136 Also, the only way to lose mail vanished.  If you specified localfolder
 137 and the disk got full, your mail got lost.  This can't happen with
 138 SMTP forwarding because your SMTP listener won't return OK unless
 139 the message can be spooled or processed.<P>
 140
 141 Also, performance improved (though not so you'd notice it in a single
 142 run).  Another not insignificant benefit of this change was that the
 143 manual page got a lot simpler.<P>
 144
 145 Later, I had to bring --mda back in order to allow handling of some
 146 obscure situations involving dynamic SLIP.  But I found a much simpler
 147 way to do it.<P>
 148
 149 The moral?  Don't hesitate to throw away superannuated features when
 150 you can do it without loss of effectiveness.  I tanked a couple I'd
 151 added myself and have no regrets at all.  As Saint-Exupery said,
 152 "Perfection [in design] is achieved not when there is nothing more to
 153 add, but rather when there is nothing more to take away."  This
 154 program isn't perfect, but it's trying.<P>
 155
 156 <H1>The most-requested features that I will never add, and why not:</H1>
 157
 158 <H2>1. Password encryption in .fetchmailrc</H2>
 159
 160 The reason there's no facility to store passwords encrypted in the
 161 .fetchmailrc file is because this doesn't actually add protection.<P>
 162
 163 Anyone who's acquired the 0600 permissions needed to read your
 164 .fetchmailrc file will be able to run fetchmail as you anyway -- and
 165 if it's your password they're after, they'd be able to rip the
 166 necessary decoder out of the fetchmail code itself to get it.<P>
 167
 168 All .fetchmailrc encryption would do is give a false sense of
 169 security to people who don't think very hard.<P>
 170
 171 <H2>2. Truly concurrent queries to multiple hosts</H2>
 172
 173 Occasionally I get a request for this on "efficiency" grounds.  These
 174 people aren't thinking either.  True concurrency would do nothing to lessen
 175 fetchmail's total IP volume.  The best it could possibly do is change the
 176 usage profile to shorten the duration of the active part of a poll cycle
 177 at the cost of increasing its demand on IP volume per unit time.<P>
 178
 179 If one could thread the protocol code so that fetchmail didn't block
 180 on waiting for a protocol response, but rather switched to trying to
 181 process another host query, one might get an efficiency gain (close to
 182 constant loading at the single-host level).<P>
 183
 184 Fortunately, I've only seldom seen a server that incurred significant
 185 wait time on an individual response.  I judge the gain from this not
 186 worth the hideous complexity increase it would require in the code.<P>
 187
 188 <H1>Multidrop and alias handling</H1>
 189
 190 I decided to add the multidrop support partly because some users were
 191 clamoring for it, but mostly because I thought it would shake bugs out
 192 of the single-drop code by forcing me to deal with addressing in full
 193 generality.  And so it proved.<P>
 194
 195 There are two important aspects of the features for handling
 196 multiple-drop aliases and mailing lists which future hackers should be
 197 careful to preserve.<P>
 198
 199 <OL>
 200 <LI>
 201    The logic path for single-recipient mailboxes doesn't involve header
 202    parsing or DNS lookups at all.  This is important -- it means the code
 203    for the most common case can be much simpler and more robust.<P>
 204
 205 <LI>
 206    The multidrop handing does <EM>not</EM> rely on doing the equivalent of passing
 207    the message to sendmail -oem -t.  Instead, it explicitly mines members
 208    of a specified set of local usernames out of the header.<P>
 209
 210 <LI>
 211    We do <EM>not</EM> attempt delivery to multidrop mailboxes in the presence of DNS
 212    errors.  Before each multidrop poll we probe DNS to see if we have a
 213    nameserver handy.  If not, the poll is skipped. If DNS crashes during a
 214    poll, the error return from the next nameserver lookup aborts message
 215    delivery and ends the poll.  The daemon mode will then quietly spin until
 216    DNS comes up again, at which point it will resume delivering mail.<P>
 217 </OL>
 218
 219 When I designed this support, I was terrified of doing anything that could
 220 conceivably cause a mail loop (you should be too).  That's why the code
 221 as written can only append <EM>local</EM> names (never @-addresses) to the
 222 recipients list.<P>
 223
 224 The code in mxget.c is nasty, no two ways about it.  But it's utterly
 225 necessary, there are a lot of MX pointers out there.  It really ought
 226 to be a (documented!) entry point in the bind library.<P>
 227
 228 <H1>DNS error handling</H1>
 229
 230 Fetchmail's behavior on DNS errors is to suppress forwarding and
 231 deletion of the individual message that each occurs in, leaving it
 232 queued on the server for retrieval on a subsequent poll.  The
 233 assumption is that DNS errors are transient, due to temporary server
 234 outages.<P>
 235
 236 Unfortunately this means that if a DNS error is permanent a message
 237 can be perpetually stuck in the server mailbox.  We've had a couple
 238 bug reports of this kind due to subtle RFC822 parsing errors in the fetchmail
 239 code that resulted in impossible things getting passed to the DNS lookup
 240 routines.<P>
 241
 242 Alternative ways to handle the problem: ignore DNS errors (treating
 243 them as a non-match on the mailserver domain), or forward messages
 244 with errors to fetchmail's invoking user in addition to any other
 245 recipients.  These would fit an assumption that DNS lookup errors are
 246 likely to be permanent problems associated with an address.<P>
 247
 248 <H1>Lessons learned</H1>
 249
 250 <H3>1. Server-side state is essential</H3>
 251
 252 The person(s) responsible for removing LAST from POP3 deserve to suffer.
 253 Without it, a client has no way to know which messages in a box have been
 254 read by other means, such as an MUA running on the server.<P>
 255
 256 The POP3 UID feature described in RFC1725 to replace LAST is
 257 insufficient.  The only problem it solves is tracking which messages
 258 have been read <EM>by this client</EM> -- and even that requires
 259 tricky, fragile implementation.<P>
 260
 261 The underlying lesson is that maintaining accessible server-side
 262 `seen' state bits associated with Status headers is indispensible in a
 263 Unix/RFC822 mail server protocol.  IMAP gets this right.<P>
 264
 265 <H3>2. Readable text protocol transactions are a Good Thing</H3>
 266
 267 A nice thing about the general class of text-based protocols that SMTP,
 268 POP2, POP3, and IMAP belongs to is that client/server transactions are
 269 easy to watch and transaction code correspondingly easy to debug.  Given
 270 a decent layer of socket utility functions (which Carl provided) it's
 271 easy to write protocol engines and not hard to show that they're working
 272 correctly.<P>
 273
 274 This is an advantage not to be despised!  Because of it, this project has
 275 been interesting and fun --  no serious or persistent bugs, no long
 276 hours spent looking for subtle pathologies.<P>
 277
 278 <H3>3. IMAP is a Good Thing.</H3>
 279
 280 If there were a standard IMAP equivalent of the POP3 APOP validation,
 281 POP3 would be completely obsolete.<P>
 282
 283 <H3>4. SMTP is the Right Thing</H3>
 284
 285 In retrospect it seems clear that this program (and others like it)
 286 should have been designed to forward via SMTP from the beginning.
 287 This lesson may be applicable to other Unix programs that now call the
 288 local MDA/MTA as a program.<P>
 289
 290 <H3>5. Syntactic noise can be your friend</H3>
 291
 292 The optional `noise' keywords in the rc file syntax started out as
 293 a late-night experiment.  The English-like syntax they allow is
 294 considerably more readable than the traditional terse keyword-value
 295 pairs you get when you strip them all out.  I think there may be a
 296 wider lesson here.<P>
 297
 298 <H1>Motivation and validation</H1>
 299
 300 It is truly written: the best hacks start out as personal solutions to
 301 the author's everyday problems, and spread because the problem turns
 302 out to be typical for a large class of users.  So it was with Carl Harris
 303 and the ancestral popclient, and so with me and fetchmail.<P>
 304
 305 It's gratifying that fetchmail has become so popular.  Until just before
 306 1.9 I was designing strictly to my own taste.  The multi-drop mailbox
 307 support and the new --limit option were the first features to go in that
 308 I didn't need myself.<P>
 309
 310 By 1.9, four months after I started hacking on popclient and a month
 311 after the first fetchmail release, there were literally a hundred
 312 people on the fetchmail-friends contact list.  That's pretty powerful
 313 motivation.  And they were a good crowd, too, sending fixes and
 314 intelligent bug reports in volume.  A user population like that is
 315 a gift from the gods, and this is my expression of gratitude.<P>
 316
 317 The beta testers didn't know it at the time, but they were also the
 318 subjects of a sociological experiment.  The results are described in
 319 my paper, <cite>The Cathedral And The Bazaar</cite>, available on the
 320 <a href="http://www.ccil.org/~esr/fetchmail">Fetchmail home page</a>.
 321
 322 <H1>Credits</H1>
 323
 324 Special thanks go to Carl Harris, who built a good solid code base
 325 and then tolerated me hacking it out of recognition.  And to Harry
 326 Hochheiser, who gave me the idea of the SMTP-forwarding delivery mode.<P>
 327
 328 Other significant contributors to the code have included Dave Bodenstab
 329 (error.c code and --syslog), George Sipe (--monitor and --interface),
 330 Gordon Matzigkeit (netrc.c), Al Longyear (UIDL support), and Nalin
 331 Dahyabhai (Kerberos V4 support).<P>
 332
 333 <H1>Conclusion</H1>
 334
 335 At this point, the fetchmail code appears to be pretty stable.
 336 It will probably undergo substantial change only if and when support
 337 for a new retrieval protocol or authentication method is added.<P>
 338
 339 <H1>Relevant RFCS</H1>
 340
 341 Not all of these describe standards explicitly used in fetchmail, but they
 342 all shaped the design in one way or another.<P>
 343
 344 <DL>
 345 <DT>RFC821<DD>  SMTP protocol
 346 <DT>RFC822<DD>  Mail header format
 347 <DT>RFC937<DD>  Post Office Protocol - Version 2
 348 <DT>RFC974<DD>  MX routing
 349 <DT>RFC976<DD>  UUCP mail format
 350 <DT>RFC1081<DD> Post Office Protocol - Version 3
 351 <DT>RFC1123<DD> Host requirements (modifies 821, 822, and 974)
 352 <DT>RFC1176<DD> Interactive Mail Access Protocol - Version 2
 353 <DT>RFC1203<DD> Interactive Mail Access Protocol - Version 3
 354 <DT>RFC1225<DD> Post Office Protocol - Version 3
 355 <DT>RFC1344<DD> Implications of MIME for Internet Mail Gateways
 356 <DT>RFC1413<DD> Identification server
 357 <DT>RFC1428<DD> Transition of Internet Mail from Just-Send-8 to 8-bit SMTP/MIME
 358 <DT>RFC1460<DD> Post Office Protocol - Version 3
 359 <DT>RFC1521<DD> MIME: Multipurpose Internet Mail Extensions
 360 <DT>RFC1869<DD> SMTP Service Extensions (ESMTP spec)
 361 <DT>RFC1652<DD> SMTP Service Extension for 8bit-MIMEtransport
 362 <DT>RFC1725<DD> Post Office Protocol - Version 3
 363 <DT>RFC1730<DD> Interactive Mail Access Protocol - Version 4
 364 <DT>RFC1731<DD> IMAP4 Authentication Mechanisms
 365 <DT>RFC1732<DD> IMAP4 Compatibility With IMAP2 And IMAP2bis
 366 <DT>RFC1734<DD> POP3 AUTHentication command
 367 <DT>RFC1870<DD> SMTP Service Extension for Message Size Declaration
 368 <DT>RFC1891<DD> SMTP Service Extension for Delivery Status Notifications
 369 <DT>RFC1893<DD> Enhanced Mail System Status Codes
 370 <DT>RFC1894<DD> An Extensible Message Format for Delivery Status Notifications
 371 <DT>RFC1938<DD> A One-Time Password System
 372 <DT>RFC1939<DD> Post Office Protocol - Version 3
 373 <DT>RFC1985<DD> SMTP Service Extension for Remote Message Queue Starting
 374 <DT>RFC2060<DD> Internet Message Access Protocol - Version 4rev1
 375 <DT>RFC2061<DD> IMAP4 Compatibility With IMAP2bis
 376 <DT>RFC2062<DD> Internet Message Access Protocol - Obsolete Syntax
 377 </DL>
 378
 379 <HR>
 380 Back to <A HREF="index.html">Fetchmail Home Page</A>.<P>
 381 <ADDRESS>Eric S. Raymond <A HREF="mailto:esr@thyrsus.com">&lt;esr@snark.thyrsus.com&gt;</A></ADDRESS>
 382 </BODY>
 383 </HTML>