diff options
Diffstat (limited to 'imap/docs/BUILD')
| -rw-r--r-- | imap/docs/BUILD | 491 |
1 files changed, 491 insertions, 0 deletions
diff --git a/imap/docs/BUILD b/imap/docs/BUILD new file mode 100644 index 00000000..e094e065 --- /dev/null +++ b/imap/docs/BUILD @@ -0,0 +1,491 @@ +/* ======================================================================== + * Copyright 1988-2007 University of Washington + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * + * ======================================================================== + */ + + BUILD AND INSTALLATION NOTES + Last Updated: 15 November 2007 + +Table of Contents: +1. UNIX Build Notes +2. UNIX Installation Notes +3. Win32 Build Notes +4. Win32 Installation Notes +5. Inactive Ports (TOPS-20, VMS) +6. Other ports (Macintosh, DOS/Win16, Windows CE, Amiga, OS/2) + + + UNIX BUILD NOTES + + The default build on many systems with IPv4 only. To build with IPv6, +add "IP=6" to the make command line, e.g. + make lnp IP=6 + + The default build is to build with SSL and disabling plaintext passwords +unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This means that +OpenSSL MUST be installed before building the IMAP toolkit. Please refer to +the SSLBUILD file for more information. + + To build without SSL, add "SSLTYPE=none" to the make command line. +Note that doing so will produce an IMAP server which is NON-COMPLIANT with +RFC 3501. + + You must build through the top-level imap-2007/Makefile, which will run +a "process" step the first time and create the imap-2007/c-client, +imap-2007/ipopd, and imap-2007/imapd directories in which building actually +takes place. + + Before doing a make on UNIX, you should read imap-2007/Makefile and see +if your system type is known. The various system types are three-letter codes. +If your system type is known, then use this as the make option. After the +first time you do a make, this option is remembered in a file called OSTYPE, +so just typing "make" suffices. + + For example, if you are using a more or less modern Linux system, your +system type is probably one of the specific distribution types (such as lrh for +RedHat). For more generic builds, try slx (shadow passwords only) or lnp (PAM). +To build for RedHat, do: + make lrh + + There are other make options, described in imap-2007/src/osdep/Makefile. + + It's probably best to see if an existing port will work on your system +before inventing a new port. Try: + sv4 generic SVR4, non-ANSI compiler + a32 modern SVR4 + bsd basic 4.3 BSD, non-ANSI compiler + bsf modern BSD + + If you must invent a new port, you need to create an entry in +imap-2007/Makefile and imap-2007/src/osdep/Makefile for your new port, as +well as osdep/os_???.h and osdep/os_???.c files with the appropriate +OS-dependent support for that system. You also need to determine which setup +process to use. You should use the ua process unless you are sure that your +compiler supports *ALL* aspects of ANSI C prototyping. Note that some +compilers, such as Ultrix, support some aspects of ANSI C but not others; +c-client really beats on the full prototyping capability of ANSI C so you +have to use the non-ANSI source tree for such systems. + + If you send a new port back to us, we will make it available for others +who use your particular system type. + + The mbox driver is now enabled by default. If the file "mbox" exists on +the user's home directory and is in UNIX mailbox format, then when INBOX is +opened this file will be selected as INBOX instead of the mail spool file. +Messages will be automatically transferred from the mail spool file into the +mbox file. To disable this behavior, delete "mbox" from the EXTRADRIVERS list +in the top-level Makefile and rebuild. + + WARNING: The SVR2 (sv2) port is *incomplete*. SVR2 does not appear to +have any way to do ftruncate(), which is needed by the mbox, mbx, mmdf, mtx, +tenex, and unix drivers. + + UNIX INSTALLATION NOTES + + Binaries from the build are: + imap-2007/mtest/mtest c-client testbed program + imap-2007/ipopd/ipop2d POP2 daemon + imap-2007/ipopd/ipop3d POP3 daemon + imap-2007/imapd/imapd IMAP4rev1 daemon + + mtest is normally not used except by c-client developers. + +STEP 1: [x]inetd setup + + The ipop2d, ipop3d, and imapd daemons should be installed in a system +daemon directory and invoked by a listener such as xinetd or inetd. In the +following examples, /usr/local/etc is used). + +STEP 1(A): xinetd-specific setup + + If your system uses xinetd, the daemons are invoked by files in your +/etc/xinetd.d directory with names corresponding to the service names (that +is: imap, pop2, pop3). You will need to consult your local xinetd +documentation to see what should go into these files. Here is a a sample +/etc/xinetd.d/imap file: + +service imap +{ + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/etc/imapd + groups = yes + flags = REUSE IPv6 +} + +STEP 1(B): inetd-specific setup + + If your system still uses inetd, the daemons are invoked by your +/etc/inetd.conf file with lines such as: + +pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d +pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d +imap stream tcp nowait root /usr/local/etc/imapd imapd + + Note that different variants of UNIX have different versions of inetd, +so you should verify the precise form of these commands (for example, some +versions of inetd do not require the "nowait"). + + IMPORTANT NOTE: inetd has a limit of how many new connections it will +allow in a certain interval, and when this limit is exceeded, it shuts down +the server. If you have anything beyond a small-scale server, you are +probably going to run up against this limit. You'll know when it happens; +your syslog will give the misleading message "imap/tcp server failing +(looping), service terminated" and users will complain that IMAP service is +unavailable for the next 10 minutes. Similarly with "pop3/tcp server +failing"... + + It must be emphasized that this is *NOT* a bug in the IMAP or POP +servers, nor is it anything that I can "fix". It is an inetd problem, and +the only way to fix it is to change inetd's behavior. + + By default, the parameters of this limit are (from inetd.c source code): + +#define TOOMANY 40 /* don't start more than TOOMANY */ +#define CNT_INTVL 60 /* servers in CNT_INTVL sec. */ +#define RETRYTIME (60*10) /* retry after bind or server fail */ + +That is, no more than 40 connections (TOOMANY) in 60 seconds (CNT_INTL), and +if exceeded, shut down the server for 10 minutes (RETRYTIME). This was a +good setting in the 1980s ARPAnet, but is much too small today. + + Some versions of inetd allow you to see a higher maximum in the +/etc/inetd.conf file. Read "man inetd" and see if you see something like +this in the text: + + The wait/nowait entry is applicable to datagram sockets only [...] + [...] The optional ``max'' suffix (separated from + ``wait'' or ``nowait'' by a dot) specifies the maximum number of server + instances that may be spawned from inetd within an interval of 60 sec- + onds. When omitted, ``max'' defaults to 40. + +If you see this, then edit the /etc/inetd.conf entry for imapd to be +something like: + +imap stream tcp nowait.100 root /usr/local/etc/imapd imapd + (or, if you use TCP wrappers) +imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd + + Otherwise, you'll need to edit the inetd source code to set TOOMANY to a +higher value, then rebuild inetd. + + +STEP 2: services setup + + You may also have to edit your /etc/services (or Yellow Pages, +NetInfo, etc. equivalent) to register these services, such as: + +pop 109/tcp +pop3 110/tcp +imap 143/tcp + + +STEP 3: PAM setup + + If your system has PAM (Pluggable Authentication Modules -- most +modern systems do) then you need to set up PAM authenticators for imap and +pop. The correct file names are + /etc/pam.d/imap +and + /etc/pam.d/pop + + It probably works to copy your /etc/pam.d/ftpd file to the above two +names. + + Many people get these file names wrong, and then spend a lot of time +trying to figure out why it doesn't work. Common mistakes are: + /etc/pam.d/imapd + /etc/pam.d/imap4 + /etc/pam.d/imap4rev1 + /etc/pam.d/ipop3d + /etc/pam.d/pop3d + /etc/pam.d/popd + /etc/pam.d/pop3 + + +STEP 4: optional rimap setup + + If you want to enable the rimap capability, which allows users with a +suitable client and .rhosts file on the server to access IMAP services +without transmitting her password in the clear over the network, you need +to have /etc/rimapd as a link to the real copy of imapd. Assuming you have +imapd installed on /usr/local/etc as above: + % ln -s /usr/local/etc/imapd /etc/rimapd + + Technical note: rimap works by having the client routine tcp_aopen() +invoke `rsh _host_ exec /etc/rimapd' in an child process, and then returning +pipes to that process' standard I/O instead of a TCP socket. You can set up +`e-mail only accounts' by making the shell be something which accepts only +that string and not ordinary UNIX shell commands. + + +STEP 4: notes on privileges + + Neither user "root", not any other UID 0 account, can log in via IMAP or +POP. "That's not a bug, it's a feature!" + + This software is designed to run without privileges. The mail spool +directory must be protected 1777; that is, with world write and the sticky +bit. Of course, mail *files* should be protected 600! + + An alternative to having the mail spool directory protected 1777, at the +cost of some performance, is to use the external "mlock" program, available +as part of the imap-utils package. With mlock installed as /etc/mlock and +setgid mail, the spool directory can be protected 775 with group mail. +Please disregard this paragraph if you don't understand it COMPLETELY, and +know EXACTLY what to do without question. + + +STEP 5: SVR4 specific setup + + There is one "gotcha" on System V Release 4 based systems such as +Solaris. These systems do not use the standard UNIX mail format, but rather a +variant of that format that depends upon a bogus "Content-Length:" message +header. This is widely recognized to have been a terrible mistake. One +symptom of the problem is that under certain circumstances, a message may get +broken up into several messages. I'm also aware of security bugs caused by +programs that foolishly trust "Content-Length:" headers with evil values. + + To fix your system, edit your sendmail.cf to change the Mlocal line to +have the -E flag. A typical entry will lool like: + +Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, A=mail.local -d $u + + WIN32 BUILD NOTES + + Visual C++ 6.0 along with the current Microsoft Platform SDK +(specifically the CORE SDK and the Internet Development SDK) is required +to build on Windows 9x/Me/NT/2K/XP. If you do not have the Platform SDK +installed or in your path properly, you'll get errors when building os_nt.c, +typically in env_nt.c, ssl_nt.c, ssl_w2k.c, or gss_shim.c. You can download +the Microsoft Platform SDK from Microsoft's web site. + + There is also considerable debate about how new mail is to be snarfed. +I am currently using something that seems to work with WinSMTP. Look at +the definition of MAILFILE in imap-2007/src/osdep/nt/mailfile.h and at the +sysinbox() function in imap-2007/src/osdep/nt/env_nt.c to see what's there +now, so you have a clue about how to hack it. + + To build under Windows 95/98/NT, connect to the imap-2007 directory +and do: + nmake -f makefile.nt +The resulting binaries will support SSL if either schannel.dll or +security.dll is installed in Windows, using the old, undocumented, SSL +interfaces. You can also use this to build under Me/2000/XP, but it is +not the preferred build on this platform. + + To build with MIT Kerberos support, connect to the imap-2007 directory +and do: + nmake -f makefile.ntk +The resulting binaries will support SSL if either schannel.dll or +security.dll is installed in Windows, using the old, undocumented SSL +interfaces. They will also support MIT Kerberos. Note, however, that +these binaries will only run on systems which have the MIT Kerberos DLLs +installed, and will not run otherwise. + + To build under Windows Me/2000/XP, connect to the imap-2007 directory +and do: + nmake -f makefile.w2k +The resulting binaries will support SSL and Microsoft Kerberos, using the +official, documented, Microsoft interfaces. Note, however, that these +binaries will not run under Windows 95, Windows 98, or Windows NT4. + + WIN32 INSTALLATION NOTES + + The resulting binaries will be: + imap-2007\mtest\mtest.exe (testbed client) + imap-2007\ipopd\ipop2d.exe POP2 server + imap-2007\ipopd\ipop3d.exe POP3 server + imap-2007\imapd\imapd.exe IMAP4rev1 server + + These servers are stdio servers. I wrote a simple network listener +for NT called inetlisn; currently it is available as: + ftp://ftp.cac.washington.edu/mail/nt/inetlisn.tar +To build this, use "nmake" after connecting to the inetlisn directory. +inetlisn takes two arguments, the first being the port number and the second +being the binary to run to serve a connection on that port, e.g. + c:\bin\inetlisn 143 c:\mail_daemons\imapd + + Note that NT imapd must be started as SYSTEM in order to be recognized as +being "not logged in"; otherwise it will preauth as whatever user it is +running as which is probably not what you want. One way to have it run as +system is to have inetlisn run by an AT command, e.g. if the time now is +2:05PM, try something like: + AT 14:06 "c:\bin\inetlisn 143 c:\mail_daemons\imapd" + + A more advanced network listener called wsinetd is available on: + http://wsinetd.sourceforge.net +It is based on inetlisn, and essentially is a "completed" version of inetlisn. + + Bottom line: this is not plug-and-play. If you're not a hacker and/or +are unwilling to invest the time to do some programming, you probably want to +buy a commercial server product. + + INACTIVE PORTS + + The TOPS-20 and VMS ports were developed at one time or another, but are +no longer actively developed. However, from time to time I test build both +of these to make sure that they compile without errors and that mtest runs, +and will continue doing so as long as I have access to systems running these +operating systems. + + + TOPS-20 BUILD NOTES + + I have provided a c-client port for TOPS-20 systems, but you're on your +own in terms of a nice TOPS-20 like main program. Maybe someday some nice +person will try porting Pine to TOPS-20. This assumes the use of KCC 6, and +probably will not build with other compilers or older versions of KCC. + + You do not use imap-2007/Makefile under TOPS-20, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/tops-20 onto a single directory on TOPS-20 and build from +that. The command: + DO BUILD.CTL +will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let +BATCON execute it. + + + VMS BUILD NOTES + + The VMS port has been tested with imap-2007, but as I am soon going +to lose access to a VMS system I will no longer be able able to test and +this port will be moved to the "other ports" category". + + You do not use imap-2007/Makefile under VMS, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/vms onto a single directory on VMS and build from that. +The command to build it is: + @BUILD MULTINET +or @BUILD NETLIB +If you just do @BUILD it will build with dummy TCP code, and since only TCP +based drivers are provided here this isn't too useful. + + If you aren't on the Pacific coast of the US or Canada, you probably will +need to change the wired-in timezone in the BUILD.COM file. Apparently, the +wonderful VMS system that DEC loves so much doesn't maintain any concept of +time zone; the VMS C compiler returns a null pointer from gmtime()! + + Otherwise you're pretty much on your own here. + + OTHER PORTS + + The following ports were developed at one time or another, but are no +longer actively developed or tested. It is not known if they still work or +not. + + Port Status + ---- ------ +Macintosh Obsolete; Mac OS X uses UNIX port +DOS/Win16 Obsolete; modern PCs use Win32 port +Windows CE Never completed +Amiga Unknown +OS/2 Unknown + + MACINTOSH BUILD NOTES + + This port is for the old Mac OS system, not Mac OS X. + + If you are building a Macintosh client, you will need MacTCP installed on +your system as well as the MacTCP C includes and libraries. + + You do not use imap-2007/Makefile on the Mac, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/mac onto a single directory on the Mac and build from +that. mtext.sit.hqx is a THINK C project file and cute icon for building +mtest, encoded with Binhex and StuffIt. + + THINK C is a truly wretched product which help make me understand why +Macintosh has lost most of its market share. Not only does it do cretinous +things such as barf about a cast in front of an lvalue, it also limits the size +of code *or* data in a single file to 32K! So much for having large character +set tables. Symantec says that "MacOS requires it, break up your files into +smaller pieces" yet somehow gcc under MachTen contrives to compile C programs +without subjecting the programmer to this idiocy. + + As a result of this, I found myself obliged to comment out the #includes +of the East Asian character sets in utf8.c in order to get it to build. It's +also necessary to break up some of the files, at least mail.c and imap4r1.c. +Maybe you don't have to do this in CodeWarrior or whatever the new compiler is +called, but I've pretty much given up on Macintosh. + + If you use precompiled headers, you may get some compilation errors since +some Apple symbols need to be redefined in order to get it to build under all +versions of MacOS. Try turning off the precompiled headers (so it will +re-read the .h files) and see if it builds any better. + + If you use a Mac C compiler with 2-byte ints (such as THINK C's normal +mode) you will need to fix some bugs in the MacTCP C includes and libraries to +prevent it from generating bad code, since those MacTCP files violate Apple's +standards of always using explicit shorts or longs, never ints. You could +avoid this if you set 4-byte ints in THINK C; however, the ANSI and UNIX +libraries in THINK C use 2-byte ints so you will also need to build 4-byte int +versions of these. c-client itself is 2-byte int or 4-byte int clean; it can +be used in either mode. + + The most important bug in the MacTCP files that you need to fix is in the +file AddressXlation.h, you need to change the definition of the rtnCode member +of the hostInfo structure to be long instead of int. There are several other +changes you need to make if you decide to compile dnr.c under THINK C instead +of using the Apple-supplied object file; see me for details if you decide to +undertake such an effort. This is fixed in newer versions from Apple. + + + DOS/WIN16 BUILD NOTES + + If you are building a DOS client, you will need a TCP/IP stack installed +on your DOS system along with its development environment. The currently +supported stacks are Beame & Whiteside, PC-NFS, Novell, PC/IP, Waterloo, and +Winsock. mtest and a version of Pine called PC Pine run under DOS. + + You do not use imap-2007/Makefile under DOS, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/dos onto a single directory on DOS and build from that. +The MAKE command on DOS takes an argument identifying the TCP/IP stack in use. +For example, do: + MAKE MAKEFILE OS=WSK (or MAKE -F MAKEFILE OS=WSK) +to build for Winsock. + + If you write a program for DOS/Win16, you will probably have to write a +replacement cache manager (look at mm_cache()) and otherwise disable most of +c-client's caching. Even so, memory limitations will be an ongoing problem, +particularly with DOS, and you will have some severe performance problems. +It's a bit better on Win16, but in my opinion you are better off writing a +32-bit program and telling your Win16 customers to upgrade to Windows 95 or at +least install Win32s. + + + WINDOWS CE BUILD NOTES + + I build using Visual C++ 6.0 with the WCE extensions. The current code +has SH3 wired in for the compiler building. + + To build under NT, connect to the imap-2007 directory and do: + nmake -f makefile.wce + + The only binary produced is a cclient.lib file. I haven't gotten as far +as building mtest on WCE, mainly because I don't have a stdlib library. + + + AMIGA BUILD AND INSTALLATION NOTES + + The Amiga port was contributed. Maybe the UNIX notes will help. + + + OS2 BUILD NOTES + + The OS2 port was contributed. Maybe the Win32 Build Notes will help. |