--- /dev/null
+/* ========================================================================
+ * 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.
+\f
+ 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
+\f
+ 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.
+\f
+ 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.
+\f
+ 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.
+\f
+ 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.
projects / uw-imap / commitdiff