imapext-2007
view docs/BUILD @ 0:ada5e610ab86
imap-2007e
| author | yuuji@gentei.org |
|---|---|
| date | Mon, 14 Sep 2009 15:17:45 +0900 |
| parents | |
| children |
line source
1 /* ========================================================================
2 * Copyright 1988-2007 University of Washington
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *
11 * ========================================================================
12 */
14 BUILD AND INSTALLATION NOTES
15 Last Updated: 15 November 2007
17 Table of Contents:
18 1. UNIX Build Notes
19 2. UNIX Installation Notes
20 3. Win32 Build Notes
21 4. Win32 Installation Notes
22 5. Inactive Ports (TOPS-20, VMS)
23 6. Other ports (Macintosh, DOS/Win16, Windows CE, Amiga, OS/2)
26 UNIX BUILD NOTES
28 The default build on many systems with IPv4 only. To build with IPv6,
29 add "IP=6" to the make command line, e.g.
30 make lnp IP=6
32 The default build is to build with SSL and disabling plaintext passwords
33 unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This means that
34 OpenSSL MUST be installed before building the IMAP toolkit. Please refer to
35 the SSLBUILD file for more information.
37 To build without SSL, add "SSLTYPE=none" to the make command line.
38 Note that doing so will produce an IMAP server which is NON-COMPLIANT with
39 RFC 3501.
41 You must build through the top-level imap-2007/Makefile, which will run
42 a "process" step the first time and create the imap-2007/c-client,
43 imap-2007/ipopd, and imap-2007/imapd directories in which building actually
44 takes place.
46 Before doing a make on UNIX, you should read imap-2007/Makefile and see
47 if your system type is known. The various system types are three-letter codes.
48 If your system type is known, then use this as the make option. After the
49 first time you do a make, this option is remembered in a file called OSTYPE,
50 so just typing "make" suffices.
52 For example, if you are using a more or less modern Linux system, your
53 system type is probably one of the specific distribution types (such as lrh for
54 RedHat). For more generic builds, try slx (shadow passwords only) or lnp (PAM).
55 To build for RedHat, do:
56 make lrh
58 There are other make options, described in imap-2007/src/osdep/Makefile.
60 It's probably best to see if an existing port will work on your system
61 before inventing a new port. Try:
62 sv4 generic SVR4, non-ANSI compiler
63 a32 modern SVR4
64 bsd basic 4.3 BSD, non-ANSI compiler
65 bsf modern BSD
67 If you must invent a new port, you need to create an entry in
68 imap-2007/Makefile and imap-2007/src/osdep/Makefile for your new port, as
69 well as osdep/os_???.h and osdep/os_???.c files with the appropriate
70 OS-dependent support for that system. You also need to determine which setup
71 process to use. You should use the ua process unless you are sure that your
72 compiler supports *ALL* aspects of ANSI C prototyping. Note that some
73 compilers, such as Ultrix, support some aspects of ANSI C but not others;
74 c-client really beats on the full prototyping capability of ANSI C so you
75 have to use the non-ANSI source tree for such systems.
77 If you send a new port back to us, we will make it available for others
78 who use your particular system type.
80 The mbox driver is now enabled by default. If the file "mbox" exists on
81 the user's home directory and is in UNIX mailbox format, then when INBOX is
82 opened this file will be selected as INBOX instead of the mail spool file.
83 Messages will be automatically transferred from the mail spool file into the
84 mbox file. To disable this behavior, delete "mbox" from the EXTRADRIVERS list
85 in the top-level Makefile and rebuild.
87 WARNING: The SVR2 (sv2) port is *incomplete*. SVR2 does not appear to
88 have any way to do ftruncate(), which is needed by the mbox, mbx, mmdf, mtx,
89 tenex, and unix drivers.
91 UNIX INSTALLATION NOTES
93 Binaries from the build are:
94 imap-2007/mtest/mtest c-client testbed program
95 imap-2007/ipopd/ipop2d POP2 daemon
96 imap-2007/ipopd/ipop3d POP3 daemon
97 imap-2007/imapd/imapd IMAP4rev1 daemon
99 mtest is normally not used except by c-client developers.
101 STEP 1: [x]inetd setup
103 The ipop2d, ipop3d, and imapd daemons should be installed in a system
104 daemon directory and invoked by a listener such as xinetd or inetd. In the
105 following examples, /usr/local/etc is used).
107 STEP 1(A): xinetd-specific setup
109 If your system uses xinetd, the daemons are invoked by files in your
110 /etc/xinetd.d directory with names corresponding to the service names (that
111 is: imap, pop2, pop3). You will need to consult your local xinetd
112 documentation to see what should go into these files. Here is a a sample
113 /etc/xinetd.d/imap file:
115 service imap
116 {
117 disable = no
118 socket_type = stream
119 wait = no
120 user = root
121 server = /usr/local/etc/imapd
122 groups = yes
123 flags = REUSE IPv6
124 }
126 STEP 1(B): inetd-specific setup
128 If your system still uses inetd, the daemons are invoked by your
129 /etc/inetd.conf file with lines such as:
131 pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d
132 pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d
133 imap stream tcp nowait root /usr/local/etc/imapd imapd
135 Note that different variants of UNIX have different versions of inetd,
136 so you should verify the precise form of these commands (for example, some
137 versions of inetd do not require the "nowait").
139 IMPORTANT NOTE: inetd has a limit of how many new connections it will
140 allow in a certain interval, and when this limit is exceeded, it shuts down
141 the server. If you have anything beyond a small-scale server, you are
142 probably going to run up against this limit. You'll know when it happens;
143 your syslog will give the misleading message "imap/tcp server failing
144 (looping), service terminated" and users will complain that IMAP service is
145 unavailable for the next 10 minutes. Similarly with "pop3/tcp server
146 failing"...
148 It must be emphasized that this is *NOT* a bug in the IMAP or POP
149 servers, nor is it anything that I can "fix". It is an inetd problem, and
150 the only way to fix it is to change inetd's behavior.
152 By default, the parameters of this limit are (from inetd.c source code):
154 #define TOOMANY 40 /* don't start more than TOOMANY */
155 #define CNT_INTVL 60 /* servers in CNT_INTVL sec. */
156 #define RETRYTIME (60*10) /* retry after bind or server fail */
158 That is, no more than 40 connections (TOOMANY) in 60 seconds (CNT_INTL), and
159 if exceeded, shut down the server for 10 minutes (RETRYTIME). This was a
160 good setting in the 1980s ARPAnet, but is much too small today.
162 Some versions of inetd allow you to see a higher maximum in the
163 /etc/inetd.conf file. Read "man inetd" and see if you see something like
164 this in the text:
166 The wait/nowait entry is applicable to datagram sockets only [...]
167 [...] The optional ``max'' suffix (separated from
168 ``wait'' or ``nowait'' by a dot) specifies the maximum number of server
169 instances that may be spawned from inetd within an interval of 60 sec-
170 onds. When omitted, ``max'' defaults to 40.
172 If you see this, then edit the /etc/inetd.conf entry for imapd to be
173 something like:
175 imap stream tcp nowait.100 root /usr/local/etc/imapd imapd
176 (or, if you use TCP wrappers)
177 imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd
179 Otherwise, you'll need to edit the inetd source code to set TOOMANY to a
180 higher value, then rebuild inetd.
183 STEP 2: services setup
185 You may also have to edit your /etc/services (or Yellow Pages,
186 NetInfo, etc. equivalent) to register these services, such as:
188 pop 109/tcp
189 pop3 110/tcp
190 imap 143/tcp
193 STEP 3: PAM setup
195 If your system has PAM (Pluggable Authentication Modules -- most
196 modern systems do) then you need to set up PAM authenticators for imap and
197 pop. The correct file names are
198 /etc/pam.d/imap
199 and
200 /etc/pam.d/pop
202 It probably works to copy your /etc/pam.d/ftpd file to the above two
203 names.
205 Many people get these file names wrong, and then spend a lot of time
206 trying to figure out why it doesn't work. Common mistakes are:
207 /etc/pam.d/imapd
208 /etc/pam.d/imap4
209 /etc/pam.d/imap4rev1
210 /etc/pam.d/ipop3d
211 /etc/pam.d/pop3d
212 /etc/pam.d/popd
213 /etc/pam.d/pop3
216 STEP 4: optional rimap setup
218 If you want to enable the rimap capability, which allows users with a
219 suitable client and .rhosts file on the server to access IMAP services
220 without transmitting her password in the clear over the network, you need
221 to have /etc/rimapd as a link to the real copy of imapd. Assuming you have
222 imapd installed on /usr/local/etc as above:
223 % ln -s /usr/local/etc/imapd /etc/rimapd
225 Technical note: rimap works by having the client routine tcp_aopen()
226 invoke `rsh _host_ exec /etc/rimapd' in an child process, and then returning
227 pipes to that process' standard I/O instead of a TCP socket. You can set up
228 `e-mail only accounts' by making the shell be something which accepts only
229 that string and not ordinary UNIX shell commands.
232 STEP 4: notes on privileges
234 Neither user "root", not any other UID 0 account, can log in via IMAP or
235 POP. "That's not a bug, it's a feature!"
237 This software is designed to run without privileges. The mail spool
238 directory must be protected 1777; that is, with world write and the sticky
239 bit. Of course, mail *files* should be protected 600!
241 An alternative to having the mail spool directory protected 1777, at the
242 cost of some performance, is to use the external "mlock" program, available
243 as part of the imap-utils package. With mlock installed as /etc/mlock and
244 setgid mail, the spool directory can be protected 775 with group mail.
245 Please disregard this paragraph if you don't understand it COMPLETELY, and
246 know EXACTLY what to do without question.
249 STEP 5: SVR4 specific setup
251 There is one "gotcha" on System V Release 4 based systems such as
252 Solaris. These systems do not use the standard UNIX mail format, but rather a
253 variant of that format that depends upon a bogus "Content-Length:" message
254 header. This is widely recognized to have been a terrible mistake. One
255 symptom of the problem is that under certain circumstances, a message may get
256 broken up into several messages. I'm also aware of security bugs caused by
257 programs that foolishly trust "Content-Length:" headers with evil values.
259 To fix your system, edit your sendmail.cf to change the Mlocal line to
260 have the -E flag. A typical entry will lool like:
262 Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, A=mail.local -d $u
264 WIN32 BUILD NOTES
266 Visual C++ 6.0 along with the current Microsoft Platform SDK
267 (specifically the CORE SDK and the Internet Development SDK) is required
268 to build on Windows 9x/Me/NT/2K/XP. If you do not have the Platform SDK
269 installed or in your path properly, you'll get errors when building os_nt.c,
270 typically in env_nt.c, ssl_nt.c, ssl_w2k.c, or gss_shim.c. You can download
271 the Microsoft Platform SDK from Microsoft's web site.
273 There is also considerable debate about how new mail is to be snarfed.
274 I am currently using something that seems to work with WinSMTP. Look at
275 the definition of MAILFILE in imap-2007/src/osdep/nt/mailfile.h and at the
276 sysinbox() function in imap-2007/src/osdep/nt/env_nt.c to see what's there
277 now, so you have a clue about how to hack it.
279 To build under Windows 95/98/NT, connect to the imap-2007 directory
280 and do:
281 nmake -f makefile.nt
282 The resulting binaries will support SSL if either schannel.dll or
283 security.dll is installed in Windows, using the old, undocumented, SSL
284 interfaces. You can also use this to build under Me/2000/XP, but it is
285 not the preferred build on this platform.
287 To build with MIT Kerberos support, connect to the imap-2007 directory
288 and do:
289 nmake -f makefile.ntk
290 The resulting binaries will support SSL if either schannel.dll or
291 security.dll is installed in Windows, using the old, undocumented SSL
292 interfaces. They will also support MIT Kerberos. Note, however, that
293 these binaries will only run on systems which have the MIT Kerberos DLLs
294 installed, and will not run otherwise.
296 To build under Windows Me/2000/XP, connect to the imap-2007 directory
297 and do:
298 nmake -f makefile.w2k
299 The resulting binaries will support SSL and Microsoft Kerberos, using the
300 official, documented, Microsoft interfaces. Note, however, that these
301 binaries will not run under Windows 95, Windows 98, or Windows NT4.
303 WIN32 INSTALLATION NOTES
305 The resulting binaries will be:
306 imap-2007\mtest\mtest.exe (testbed client)
307 imap-2007\ipopd\ipop2d.exe POP2 server
308 imap-2007\ipopd\ipop3d.exe POP3 server
309 imap-2007\imapd\imapd.exe IMAP4rev1 server
311 These servers are stdio servers. I wrote a simple network listener
312 for NT called inetlisn; currently it is available as:
313 ftp://ftp.cac.washington.edu/mail/nt/inetlisn.tar
314 To build this, use "nmake" after connecting to the inetlisn directory.
315 inetlisn takes two arguments, the first being the port number and the second
316 being the binary to run to serve a connection on that port, e.g.
317 c:\bin\inetlisn 143 c:\mail_daemons\imapd
319 Note that NT imapd must be started as SYSTEM in order to be recognized as
320 being "not logged in"; otherwise it will preauth as whatever user it is
321 running as which is probably not what you want. One way to have it run as
322 system is to have inetlisn run by an AT command, e.g. if the time now is
323 2:05PM, try something like:
324 AT 14:06 "c:\bin\inetlisn 143 c:\mail_daemons\imapd"
326 A more advanced network listener called wsinetd is available on:
327 http://wsinetd.sourceforge.net
328 It is based on inetlisn, and essentially is a "completed" version of inetlisn.
330 Bottom line: this is not plug-and-play. If you're not a hacker and/or
331 are unwilling to invest the time to do some programming, you probably want to
332 buy a commercial server product.
334 INACTIVE PORTS
336 The TOPS-20 and VMS ports were developed at one time or another, but are
337 no longer actively developed. However, from time to time I test build both
338 of these to make sure that they compile without errors and that mtest runs,
339 and will continue doing so as long as I have access to systems running these
340 operating systems.
343 TOPS-20 BUILD NOTES
345 I have provided a c-client port for TOPS-20 systems, but you're on your
346 own in terms of a nice TOPS-20 like main program. Maybe someday some nice
347 person will try porting Pine to TOPS-20. This assumes the use of KCC 6, and
348 probably will not build with other compilers or older versions of KCC.
350 You do not use imap-2007/Makefile under TOPS-20, nor do you build any
351 components other than c-client and mtest. Merge the contents of
352 imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
353 imap-2007/src/osdep/tops-20 onto a single directory on TOPS-20 and build from
354 that. The command:
355 DO BUILD.CTL
356 will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let
357 BATCON execute it.
360 VMS BUILD NOTES
362 The VMS port has been tested with imap-2007, but as I am soon going
363 to lose access to a VMS system I will no longer be able able to test and
364 this port will be moved to the "other ports" category".
366 You do not use imap-2007/Makefile under VMS, nor do you build any
367 components other than c-client and mtest. Merge the contents of
368 imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
369 imap-2007/src/osdep/vms onto a single directory on VMS and build from that.
370 The command to build it is:
371 @BUILD MULTINET
372 or @BUILD NETLIB
373 If you just do @BUILD it will build with dummy TCP code, and since only TCP
374 based drivers are provided here this isn't too useful.
376 If you aren't on the Pacific coast of the US or Canada, you probably will
377 need to change the wired-in timezone in the BUILD.COM file. Apparently, the
378 wonderful VMS system that DEC loves so much doesn't maintain any concept of
379 time zone; the VMS C compiler returns a null pointer from gmtime()!
381 Otherwise you're pretty much on your own here.
383 OTHER PORTS
385 The following ports were developed at one time or another, but are no
386 longer actively developed or tested. It is not known if they still work or
387 not.
389 Port Status
390 ---- ------
391 Macintosh Obsolete; Mac OS X uses UNIX port
392 DOS/Win16 Obsolete; modern PCs use Win32 port
393 Windows CE Never completed
394 Amiga Unknown
395 OS/2 Unknown
397 MACINTOSH BUILD NOTES
399 This port is for the old Mac OS system, not Mac OS X.
401 If you are building a Macintosh client, you will need MacTCP installed on
402 your system as well as the MacTCP C includes and libraries.
404 You do not use imap-2007/Makefile on the Mac, nor do you build any
405 components other than c-client and mtest. Merge the contents of
406 imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
407 imap-2007/src/osdep/mac onto a single directory on the Mac and build from
408 that. mtext.sit.hqx is a THINK C project file and cute icon for building
409 mtest, encoded with Binhex and StuffIt.
411 THINK C is a truly wretched product which help make me understand why
412 Macintosh has lost most of its market share. Not only does it do cretinous
413 things such as barf about a cast in front of an lvalue, it also limits the size
414 of code *or* data in a single file to 32K! So much for having large character
415 set tables. Symantec says that "MacOS requires it, break up your files into
416 smaller pieces" yet somehow gcc under MachTen contrives to compile C programs
417 without subjecting the programmer to this idiocy.
419 As a result of this, I found myself obliged to comment out the #includes
420 of the East Asian character sets in utf8.c in order to get it to build. It's
421 also necessary to break up some of the files, at least mail.c and imap4r1.c.
422 Maybe you don't have to do this in CodeWarrior or whatever the new compiler is
423 called, but I've pretty much given up on Macintosh.
425 If you use precompiled headers, you may get some compilation errors since
426 some Apple symbols need to be redefined in order to get it to build under all
427 versions of MacOS. Try turning off the precompiled headers (so it will
428 re-read the .h files) and see if it builds any better.
430 If you use a Mac C compiler with 2-byte ints (such as THINK C's normal
431 mode) you will need to fix some bugs in the MacTCP C includes and libraries to
432 prevent it from generating bad code, since those MacTCP files violate Apple's
433 standards of always using explicit shorts or longs, never ints. You could
434 avoid this if you set 4-byte ints in THINK C; however, the ANSI and UNIX
435 libraries in THINK C use 2-byte ints so you will also need to build 4-byte int
436 versions of these. c-client itself is 2-byte int or 4-byte int clean; it can
437 be used in either mode.
439 The most important bug in the MacTCP files that you need to fix is in the
440 file AddressXlation.h, you need to change the definition of the rtnCode member
441 of the hostInfo structure to be long instead of int. There are several other
442 changes you need to make if you decide to compile dnr.c under THINK C instead
443 of using the Apple-supplied object file; see me for details if you decide to
444 undertake such an effort. This is fixed in newer versions from Apple.
447 DOS/WIN16 BUILD NOTES
449 If you are building a DOS client, you will need a TCP/IP stack installed
450 on your DOS system along with its development environment. The currently
451 supported stacks are Beame & Whiteside, PC-NFS, Novell, PC/IP, Waterloo, and
452 Winsock. mtest and a version of Pine called PC Pine run under DOS.
454 You do not use imap-2007/Makefile under DOS, nor do you build any
455 components other than c-client and mtest. Merge the contents of
456 imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
457 imap-2007/src/osdep/dos onto a single directory on DOS and build from that.
458 The MAKE command on DOS takes an argument identifying the TCP/IP stack in use.
459 For example, do:
460 MAKE MAKEFILE OS=WSK (or MAKE -F MAKEFILE OS=WSK)
461 to build for Winsock.
463 If you write a program for DOS/Win16, you will probably have to write a
464 replacement cache manager (look at mm_cache()) and otherwise disable most of
465 c-client's caching. Even so, memory limitations will be an ongoing problem,
466 particularly with DOS, and you will have some severe performance problems.
467 It's a bit better on Win16, but in my opinion you are better off writing a
468 32-bit program and telling your Win16 customers to upgrade to Windows 95 or at
469 least install Win32s.
472 WINDOWS CE BUILD NOTES
474 I build using Visual C++ 6.0 with the WCE extensions. The current code
475 has SH3 wired in for the compiler building.
477 To build under NT, connect to the imap-2007 directory and do:
478 nmake -f makefile.wce
480 The only binary produced is a cclient.lib file. I haven't gotten as far
481 as building mtest on WCE, mainly because I don't have a stdlib library.
484 AMIGA BUILD AND INSTALLATION NOTES
486 The Amiga port was contributed. Maybe the UNIX notes will help.
489 OS2 BUILD NOTES
491 The OS2 port was contributed. Maybe the Win32 Build Notes will help.