/* ======================================================================== * 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.