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