imap-2007f~dfsg/0000755000000000000000000000000011612414525012301 5ustar rootrootimap-2007f~dfsg/SUPPORT0000644000000000000000000000147511612411705013404 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ BUG REPORTING ADDRESS Bug reports, comments, or questions regarding this software may be reported to the imap-uw@u.washington.edu mailing list (this replaces the old c-client@u.washington.edu mailing list). You can subscribe to this list by sending a message to: imap-uw-subscribe@mailman.u.washington.edu An alternative is to use the comp.mail.imap newsgroup. imap-2007f~dfsg/docs/0000755000000000000000000000000011740100527013225 5ustar rootrootimap-2007f~dfsg/docs/SSLBUILD0000644000000000000000000002572211612411704014401 0ustar rootroot/* ======================================================================== * 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 * * * ======================================================================== */ SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX Last Updated: 15 November 2007 PREREQUISITES BEFORE STARTING: 1) Review the information in imap-2007/docs/BUILD. 2) Obtain a copy of OpenSSL. OpenSSL is available from third parties. We do not provide OpenSSL. 3) Make sure that you know how to build OpenSSL properly on the standard /usr/local/ssl directory. In particular, /usr/local/ssl/include (and /usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up from the OpenSSL build. If you have a non-standard installation, then you must modify the imap-2007/src/osdep/unix/Makefile file to point to the appropriate locations. 4) Make sure that you know how to obtain appropriate certificates on your system. NOTE: We can NOT provide you with support in building/installing OpenSSL, or in obtaining certificates. If you need help in doing this, try the contacts mentioned in the OpenSSL README. SSL BUILD: By default, the IMAP toolkit builds with SSL and disabling plaintext passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This produces an IMAP server which is compliant with RFC 3501 security requirements. To build with SSL but allow plaintext passwords in insecure sessions, add "SSLTYPE=unix" to the make command line. Note that doing so will produce an IMAP server which is NON-COMPLIANT with RFC 3501. 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. There are other make options relevant to SSL, described in imap-2007/src/osdep/unix/Makefile The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA. SSLDIR is set to /usr/local/ssl by default. This is the normal installation directory for OpenSSL. If your system uses a different directory you will need to change this. SSLCRYPTO is set to -lcrypto by default. Older versions of MIT Kerberos also have a libcrypto and will cause a library name conflict. If you are using an older version of Kerberos, you may need to change SSLCRYPTO to $(SSLLIB)/libcrypto.a SSLRSA is set empty by default. It can be set to specify the RSAREF libraries, which you once had to use with OpenSSL to use RSA algorithms legally if you are in the USA, due to patent issues. Since RSA Security Inc. released the RSA algorithm into the public domain on September 6, 2000, there is no longer any reason to do this. SSL INSTALLATION: 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: 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, imaps, pop2, pop3, pop3s). 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/imaps file: service imaps { 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 pop3s stream tcp nowait root /usr/local/etc/ipop3d ipop3d imaps stream tcp nowait root /usr/local/etc/imapd imapd Please refer to imap-2007/docs/BUILD for an important note about inetd's limit on the number of new connections. If that note applies to you, and you can configure the number of connection in /etc/inetd.conf as described in imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL: pop3 stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d imap stream tcp nowait.100 root /usr/local/etc/imapd imapd imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd (or, if you use TCP wrappers) pop3 stream tcp nowait.100 root /usr/local/etc/tcpd ipop3d imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services! I don't know why, but it doesn't work with TCP wrappers. 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 imaps 993/tcp pop3s 995/tcp NOTE: The SSL IMAP service *MUST* be called "imaps", and the SSL POP3 service *MUST* be called "pop3s". 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/imaps /etc/pam.d/ipop3d /etc/pam.d/pop3d /etc/pam.d/popd /etc/pam.d/pop3 /etc/pam.d/pop3s STEP 4: certificates setup NOTE: We can NOT provide you with support in obtaining certificates. If you need help in doing this, try the contacts mentioned in the OpenSSL README. WARNING: Do NOT install servers built with SSL support unless you also plan to install proper certificates! It is NOT supported to run SSL-enabled servers on a system without the proper certificates. You must set up certificates on /usr/local/ssl/certs (this may be different if you have a non-standard installation of OpenSSL; for example, FreeBSD has modified OpenSSL to use /usr/local/certs). You should install both the certificate authority certificates from the SSL distribution after building OpenSSL, plus your own certificates. The latter should have been purchased from a certificate authority, although self-signed certificates are permissible. A sample certificate file is at the end of this document. Install the resulting certificate file on /usr/local/ssl/certs, with a file name consisting of the server name and a suffix of ".pem". For example, install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d certificate on /usr/local/ssl/certs/ipop3d.pem. These files should be protected against random people accessing them. It is permissible for imapd.pem and ipop3d.pem to be links to the same file. The imapd.pem and ipop3d.pem must contain a private key and a certificate. The private key must not be encrypted. The following command to openssl can be used to create a self-signed certificate with a 10-year expiration: req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650 *** IMPORTANT *** We DO NOT recommend, encourage, or sanction the use of self-signed certificates. Nor will we be responsible for any problems (including security problems!) which result from your use of a self-signed certificate. Use of self-signed certificates should be limited to testing only. Buy a real certificate from a certificate authority! *** IMPORTANT *** If you have a multihomed system with multiple domain names (and hence separate certificates for each domain name), you can append the IP address to the service name. For example, the IMAP certificate for [12.34.56.78] would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on. You only need to use this feature if you need to use multiple certificates (because different DNS names are used). SAMPLE CERTIFICATE FILE Here is a sample certificate file. Do *NOT* use this on your own machine; it is simply an example of what one would look like. -----BEGIN RSA PRIVATE KEY----- MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP 7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1 DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9 p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1 ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0 cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5 Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG 4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0 cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5 Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4= -----END CERTIFICATE----- imap-2007f~dfsg/docs/RELNOTES0000644000000000000000000010320311612411705014403 0ustar rootroot/* ======================================================================== * Copyright 1988-2008 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 * * * ======================================================================== */ Updated: 22 July 2011 imap-2007f fixes a couple bugs. Fix for RFC 4959 Initial Client Response auth failures noted first by MacOSX Lion Mail users. Adjust tcp_open.c:tcp_socket_open to make it a little more useful by adding a write file descriptor test to the select in the case that the open timeout is set. In osdep/unix/env_unix.c:create_path there was a printf that should have been an sprintf. Doesn't matter on modern systems. Updated: 16 December 2008 imap-2007e is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users plus a security fix for users of the RFC822BUFFER routines. Updated: 29 October 2008 imap-2007d is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users plus a security fix for users of tmail or dmail. Updated: 25 March 2008 imap-2007b is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 2 January 2008 imap-2007a is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 20 December 2007 imap-2007 is a release corresponding with the release of Alpine 1.0. The primary focus of the imap-2007 release is bugfixes and reliability improvements. This includes: . fixes to problems discovered between the Alpine 0.99999 pre-release and Alpine 1.0 . fixes to the mix driver to timing race problems uncovered by Timo Sirainen's imaptest suite. imap-2007 using the mix format is believed to pass imaptest completely. A new function, utf8_csvalidmap(), has been added for the benefit of Alpine to use in examining UTF-8 text and determining efficiently whether it can be downgraded to a legacy charset. If you develop an MUA, this may be useful for you too, although you'll have to read the source code to see how to use it. The purpose of the "not-CJK" bit is to prevent messages being downgraded to a CJK charset if all they have in that charset are some special punctuation. Updated: 5 September 2007 imap-2006k is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. The primary focus of this maintenance release is to correct deadlock issues. There were two major causes of the deadlocks: . a change in imap-2006i attempted to resolve a glibc mutex-based deadlock in imapd's signal handler, but ended up worsening the problem. . a bug in the mbx driver, introduced as part of the UIDPLUS work in 2006, applied an mbx-style lock briefly on a traditional UNIX format mailbox. If the traditional UNIX format mailbox was already locked by some other process, the result would be a deadlock of both processes. imapd's signal handling logic is rewritten to avoid the mutex issue, and the mbx driver is fixed so that mbx-style locks are only applied to mbx format mailboxes. imapd now supports the WITHIN extension. Updated: 14 June 2007 imap-2006j is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 5 June 2007 imap-2006i is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. imapd now supports the CHILDREN and ESEARCH extensions. imapd's attempt to return COPYUID/APPENDUID information for a traditional UNIX (and MMDF) format mailbox when the mailbox is open by another process has been declared to be a failure and is now revoked. It was subject to a timing race, loss of which involved an expensive reset of the mailbox's UID regime. Any imapd COPY or APPEND to a traditional UNIX or MMDF format that is open by some other process will now no longer return COPYUID/APPEND. Although this is technically in violation of RFC 4315, there is a loophole in that document and the timing race/performance problem is worse. Updated: 4 April 2007 imap-2006h is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 30 March 2007 imap-2006g is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 30 January 2007 imap-2006f is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. For the benefit of multi-threaded applications, use of strtok() has been abolished in the c-client library. imapd and ipop3d stuff use it though. The TOPS-20 and VAX/VMS ports still use strtok() since they don't use UNIX threads. This version has been test-built on Linux, Mac OS X, NeXT, Windows XP, TOPS-20, and VAX/VMS. This will probably be the last test-build on VAX/VMS since the system I use for that purpose is being shut down. I have no way to test-build on DOS, legacy Mac OS (OS 9 and earlier), OS/2, or Windows CE; and the builds on those systems are probably broken. Updated: 26 January 2007 imap-2006e is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. Updated: 6 December 2006 imap-2006d is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. The decomposition mapping, title-case mapping, and character widths tables have been updated to comply with the Unicode 5.0 standard. Prototypes for the utf8aux.c functions have been moved to a new utf8aux.h. The general c-client modules now include c-client.h instead of the individual files. Use of c-client.h instead of individual include files insulates against future shuffling of include files. Updated: 23 October 2006 imap-2006c is a maintenance release, consisting primarily of bugfixes to problems discovered in the release that affected a small number of users. By popular request, if a user has a mix (or other dual-use) format INBOX, it will no longer be listed as \NoInferiors. It's a bad idea to depend upon this due to the case ambiguity issue, but it's there. Updated: 26 September 2006 imap-2006b is a maintenance release, consisting entirely of bugfixes to problems discovered in the release that affected a small number of users. Updated: 15 September 2006 imap-2006a is a maintenance release, consisting entirely of bugfixes to problems discovered in the release that affected a small number of users. If it is necessary to build IPv4-only on one of the ports that has IPv6 preconfigured (ldb, lfd, lmd, lrh, lsu, osx, oxp), this can be done by using IP6=4. You can't do IP=4 in the build command directly since these ports set IP themselves; however, now instead of setting IP=6 they now set IP=$(IP6). Updated: 30 August 2006 imap-2006 is a major release. Programs written for imap-2004g should build with this version with minor or no modification. imap-2005 was not released except as development snapshots. imap-2006 contains major extensions to its Unicode support. Searching and sorting are now done with strings canonicalized to titlecase and decomposed form. Among other things, this means that Latin letters with diacriticals will now sort with the basic Latin letter, and case-independent searching of such letters (e.g., German umlauts) now works. Previously, sorting was done strictly by Unicode codepoint, and case-independence only worked with ASCII. imapd now supports the UIDPLUS extension for mailboxes in unix, mmdf, mbx, mx, and mix formats. UID EXPUNGE is fully implemented. Note that UIDPLUS is not supported in the little-used drivers (mh, mtx, tenex) in which meaningful APPENDUID/COPYUID data can not be returned. Refer to bugs.txt for more details. The new mix format is a dual-use mailbox format designed for performance and reliability with large mailboxes. mix is documented in file mixfmt.txt. SSL/TLS certificate validation on UNIX now checks the alternative names in the certificate if the CN does not match. The new /tls-sslv23 flag in a mailbox name causes a TLS session to use the (incorrect) SSLv23 client method instead of the TLSv1 client method. Some broken servers use the SSLv23 server method, and this flag works around that problem. WARNING: use of this flag will cause TLS negotiation to fail with a server which uses the proper TLSv1 server method. Additionally, there are known security risks in SSLv2; so users should be suspicious if this switch suddenly becomes necesary. The silly mailbox flag combination /ssl/tls is now rejected as an invalid remote specification. Previous versions tried to negotiate TLS over an SSL session; even if the server permitted such a thing it couldn't work. The memory management of several drivers has been redesigned to consume less memory and hopefully be faster. The private.data member of the MESSAGECACHE (elt) has been replaced with a union that contains private.spare.data and private.spare.ptr, the latter being a pointer. A new FT_RETURNSTRINGSTRUCT flag has been added for mail_fetch_body() and mail_fetch_text() calls. If this flag is set, *and* if the function returns NIL, then the requested string data is available on a stringstruct on stream->private.string. This is a special hack for the IMAP and POP servers and is subject to incompatible change. The result is a major performance improvement in the servers with the mbx driver, particularly with large messages. Updated: 15 September 2005 imap-2004g is a maintenance release, and consists solely of a bugfix to quoted string handling in the mailbox name parsing routine. Updated: 15 August 2005 imap-2004f is a maintenance release, and consists solely of a bugfix to the TCP code. Also included is a new version of the UNIX SSL/TLS routines that allows the SSL/TLS certificate validation client code to validate alternative names in server certificates. This code has not been thoroughly regression-tested but is believed to work. To use this new code instead of the old support: cd imap-2004f/src/osdep/unix mv ssl_unix.c ssl_unix.old mv ssl_unix.new ssl_unix.c Then rebuild. Updated: 21 June 2005 imap-2004e is a maintenance release, consisting entirely of bugfixes. There are no user-visible functional enhancements in this version. Updated: 20 April 2005 imap-2004d is a maintenance release, released concurrently with Pine 4.63, and consists primarily of bugfixes There is now a workaround for RedHat breaking flock(). However, since RedHat has said that they don't support flock(), there is no guarantee that they won't break it in the future. So you may want to consider some other Linux distribution or BSD instead. See: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=123415 for the gruesome details. There are no user-visible functional enhancements in this version. Updated: 18 January 2005 imap-2004c is a maintenance release, released concurrently with Pine 4.62, including fixes to quoted-printable encoding and CRAM-MD5 authentication. NNTP proxy in imapd now supports the LIST and LSUB commands. There are no other user-visible functional enhancements in this version. Updated: 29 November 2004 imap-2004b is a maintenance release, consisting primarily of bugfixes. Programs written for imap-2004a will build with this version without modifification. There are new ports for Solaris with Blastwave Community Open Source Software (gcs) and Mandrake Linux (lmd). SET_SNARFINTERVAL now controls how frequently local drivers will move new mail from the mail spool as well as from a maildrop. Maildrops are still tied to a minimum interval of 1 minute, but there is now no minimum for the spool file. Character set conversions now map non-breaking space to space if the destination character set doesn't have nbsp. JIS Roman yen sign is now mapped to Unicode yen sign. There are no user-visible functional enhancements in this version. Updated: 8 July 2004 imap-2004a is a maintenance release, consisting primarily of critical bugfixes. Programs written for imap-2004 will build with this version without modification. imapd now has a supported NNTP proxy capability. If the file /etc/imapd.nntp exists, the contents of that file are used as the host name of an NNTP server which will be used whenever a #news. name is used. For example, if /etc/imapd.nntp contains nntp.example.com, and the IMAP client SELECTs or EXAMINEs the name #news.comp.mail.imap, what will actually be opened in imapd is {nntp.example.com/nntp}comp.mail.imap The OSF/1 port (Digital UNIX, Tru64) now uses flocksim instead of flcksafe. Some cretin decided to delete the winning flock() call and make flock() use the losing fcntl() call instead. The unix[nt] and mmdf drivers now prevent mail_append() from writing Status:, X-Status:, X-UID, X-IMAP[base]:, and X-Keywords: header lines to a traditional UNIX or MMDF format mailbox. If any such lines are in the text supplied to mail_append(), they will be quoted by prefixing with "X-Original-" (e.g. Status: will become X-Original-Status:). There are no user-visible functional enhancements in this version. Updated: 10 May 2004 imap-2004 is a major release. Programs written for imap-2002e should build with this version with minor modification. imap-2003 was not released except as development snapshots. mailutil has three new commands: delete, rename, and prune. IPv6 support now exists for UNIX and W2K. It is the default in W2K builds. On UNIX, add "IP=6" to the make command line. Windows IPv6 support is only for W2K builds. The NNTP driver now supports NNTP SASL and TLS. The ldb (Debian) and lrh (RedHat) ports now look for mlock on /usr/sbin/mlock instead of /etc/mlock. imapd now supports the LITERAL+ and SASL-IR initial-response extensions. The IMAP driver has some additional checks to reduce the amount of network traffic, including executing "silly searches" (searches of sequence numbers only) locally. The IMAP, POP, SMTP, and NNTP drivers now have diagnostic code to provide better information about servers which violate SASL's empty challenge requirements (e.g. with the PLAIN mechanism). There is a new mail_fetch_overview_sequence() function which is like mail_fetch_overview() but takes a sequence number string as an argument. There should have been a flags argument and FT_UID bit as in all the other mail_fetch_???() functions but compatibility with the past... :-( The overview_t callback (from mail_fetch_overview()) now has a fourth argument which contains the message sequence number (as opposed to the UID which is in the second argument). It turned out that some applications were calling mail_msgno() (which can be moderately expensive) to get the sequence number, and c-client already knew it. Many declarations which are completely internal to a driver have been removed from the driver .h file, and in those cases where there are no external declarations left the .h file has been eliminated entirely. As part of this, the mbox driver routines are now incorporated with the unix driver routines as opposed to being a separate file. The mbox driver still needs to be lunk in order to get the mbox functionality. Updated: 27 August 2003 imap-2002e is a minor release, released concurrently with Pine 4.58, and contains primarily bugfixes. Programs written for imap-2002d will build with this version without modification. The NNTP client code now tries to perform better with legacy NNTP servers which do not comply with the current NNTP protocol specification draft, most notably Netscape Collabra. Delivery notifications now work reliably with SMTP servers that support it. The following changes are primarily of concern to developers and power users: There is a "limited advertise" option in env_unix.c which, if set, will only advertise the user's own namespace and the #shared/ namespace. It is now possible to build the IMAP toolkit with a separate SSL KEY file from the certificate file (SSLKEYS vs. SSLCERTS). A new BODY structure element, sparep, is available for the main program to use as a pointer for its own purposes; as well as a SET_FREEBODYSPAREP function, similar to SET_FREEENVELOPESPAREP, SET_FREEELTSPAREP, etc. Updated: 28 May 2003 imap-2002d is a minor release, released concurrently with Pine 4.56, and contains primarily bugfixes. Programs written for imap-2002 should build with this version without modification, with one exception. That exception is the ngbogus envelope flag, which stopped being used in imap-2002c and is now gone for good. The NNTP newsgroup listing code now tries to use wildmats on the NNTP server, which should result in better performance especially on slow lines. It is also once again permitted to log in on NNTP servers when /loser is set. imapd now supports the UNSELECT command. A new envelope flag, imapenvonly, indicates that the envelope in a MESSAGE/RFC822 BODY structure only has the IMAP envelope components and not the additional components from c-client: Newsgroups, Followup-To, and References. Updated: 7 April 2003 imap-2002c is a minor release, released concurrently with Pine 4.55, and contains primarily bugfixes. Programs written for imap-2002 will build with this version without modification. The POP3 driver will, with new servers that support CAPA, use the LIST command to get the elt->rfc822_size and the TOP command to get the message header, instead of fetching the entire message. Note that it is a bad idea to do this with old servers, since they may misimplement LIST and TOP. The result is a substantial performance improvement. Subject extraction for comparisons in SORT and THREAD are now done in full compliance with the rules laid out in the specification. This only makes a difference if "re:" was part of a MIME quoted-word. The new experimental #move namespace allows download-and-delete from a source mailbox to a destination mailbox. Immediately following #move is a delimiter character which must not appear in the source mailbox name, then the source mailbox name, then the delimiter again, then the destination mailbox name. For example: #move+{pop3.foo.com/pop3}+INBOX will download messages from "pop3.foo.com" into your local INBOX. The NNTP driver now uses the LIST EXTENSIONS command as described in the current NNTP protocol specification draft, and will prefer to use OVER over XOVER, HDR over XHDR, etc. The SET_NNTPRANGE function of mail_parameters() can be used to limit the number of articles recognized by the NNTP driver, resulting in a substantial performance improvement with NNTP servers that may have hundreds of thousands of old articles in the spool. If set non-zero, then only the last n article numbers will be considered. If you are on a slow link, you may want to set this to 1000 or less. Besides the normally tested UNIX and 32-bit Microsoft platforms, this release has also been tested and will once build under TOPS-20 and VAX/VMS. I also fixed a bug which would keep it from building on 16-bit DOS, but I don't know if it will build on that platform or not since I no longer have a system with the old DOS C compiler. It has not been tested on Macintosh (note however that Mac OS X is a type of UNIX and should build), Amiga, or OS/2, and probably no longer builds on those platforms. Updated: 7 January 2003 imap-2002b is a maintenace release, released concurrently with Pine 4.52, and contains only bugfixes. Programs written for imap-2002 will build with this version without modification. Drivers which do not announce new mail are now indicated by the DR_NONEWMAIL driver flag. Driver which do not announce new mail when read-only are now indicated by the DR_NONEWMAILRONLY flag. There are no user-visible functional enhancements in this version. Updated: 10 December 2002 imap-2002a is a maintenance release, consisting entirely of critical bugfixes. Programs written for imap-2002 will build with this version without modification. There are no functional enhancements in this version. Updated: 28 October 2002 imap-2002 is a major release. Programs written for imap-2001 will probably build with this version without modification, with one exception. That exception is if the program uses [GS]ET_DISABLEAUTOMATICSHAREDNAMESPACES, which has been renamed to [GS]ET_DISABLEAUTOSHAREDNS in order to placate some compilers which don't like very long names. SSLTYPE=nopwd is now the default, in accordance with current IESG security requirements. In order to build the IMAP toolkit without SSL/TLS you must now use SSLTYPE=none. At initial build time, you will be told if the SSLTYPE setting is in compliance with IESG security requirements, and if it is not you will be asked to confirm to continue the build. ORDEREDSUBJECT threading has been changed in accordance with draft 12 of the IMAP threading specification. Previously, each non-root message in an ORDEREDSUBJECT thread has been a child of the message immediately preceeding it in the thread. Draft 12 changes this so that the second message in the thread is the child of the first (root) message, and all subsequent messages are siblings of the first message. This is significant in MUAs which display the thread structure graphically; the new definition is much saner than the old one since it does not nest endlessly due to parent/child relationships that may not exist. This also impacts imapd, since imapd's THREAD command will return a thread structure. RFC 1730 server support, which was disabled in imap-2001, is now fully removed from imapd. imapd still supports IMAP2bis, specifically the FIND command, since there are still a few IMAP2 clients out there. The IMAP client routines in the c-client library continue to support recognize RFC 1730 servers, but do not implement the deprecated features of RFC 1730. The Frequently Asked Questions file is now in HTML format, although a text version (generated from the HTML version with Lynx) is also provided. A new program, mailutil, is now bundled with the IMAP toolkit. mailutil replaces the old chkmail, imapcopy, imapmove, imapxfer, mbxcopy, mbxcreat, and mbxcvt programs that were distributed in the imap-utils. In addition, the tmail, dmail, and mlock programs from the imap-utils are now also bundled with the IMAP toolkit. In addition to the usual bugfixes, the following c-client functionalities are new in imap-2002: The SET_DISABLE822TZTEXT parameter allows a client to suppress generation of the "human friendly" time zone text in RFC822 dates. This placates netnews and some broken SMTP servers which think that long timezone names from Windows are an attempt at a buffer overflow attack. The restrictBox option in env_unix.c sets "restricted box" functionality, which disables access to the root (leading "/"), access to other user's directories (leading "~"), and access to superior directories via "..". Content-Location is now supported by the "location" member of the BODY structure. Note that there is a bug in the IMAP client code in older versions of the c-client library that causes it to handle BODYSTRUCTURE extension data improperly if that data is a literal. The new functionality for Content-Location may trigger this bug. The fix is either to upgrade the IMAP client program to the imap-2002 version of c-client or to remove the Content-Location support from imapd. There are now 8 spare bits for application use in both the elts and the mail streams. mail_search() now returns a value (previously it was void). If mail_search() returns NIL, then the supplied charset was invalid or the IMAP server returned NO (probably because the supplied charset was invalid). New utf8_charset() routine to look up a charset and return c-client's database about that charset if found. Among other things, this will give you the scripts supported by that charset and its Unicode conversion table. New FT_NOLOOKAHEAD flag for mail_fetch_structure() disables fetching of any envelopes other than the one specified. Otherwise, it will try to do anticipatory fetching (up to IMAPLOOKAHEAD). New GET_FETCHLOOKAHEAD allows better control of mail_fetch_structure() lookahead. Instead of looking IMAPLOOKAHEAD messages forward from the specified message, it will use a supplied SEARCHSET to generate message sequences and ranges. It will stop at IMAPLOOKAHEAD messages or at the completion of a range which exceeds IMAPLOOKAHEAD. The search set only applies to the next mail_fetch_structure() on that stream, and is cleared once it is used. Call with SEARCHSET **set = (SEARCHSET **) mail_parameters (stream,GET_FETCHLOOKAHEAD,(void *) stream); *set = pointer to desired search set New mail_shortdate() routine returns an date in the format expected by SEARCHPGMs. Updated: 2 November 2001 imap-2001a is a maintenance release, consisting primarily of bugfixes including some critical bugfixes to crash and denial of service problems. Programs written for imap-2001 will build with this version without modification. The following new facilities have also been added: The new /norsh switch in mailbox names provides a more intuitive way of disabling rsh-IMAP than the existing :143 or setting the rsh-timeout to 0. Passwords are no longer returned in mm_dlog() callbacks unless the application sets the SET_DEBUGSENSITIVE parameter. The SET_NETFSSTATBUG parameter allows an application to force the traditional UNIX mailbox driver to close and reopen the mailbox at ping time. This is EXTREMELY inefficient, and should only be used to access files stored on AFS and old NFS systems. The ISO 8859 and Windows conversion tables have been updated to comply with Unicode 3.1, and the KOI8-R table has been verified as compliant with Unicode 3.1. The SPECIALS mechanism for passing parameters to the lowest level Makefile has been updated to be more general. See the next item for why you might care. New lrh port to build on Red Hat Linux 7.2, with pre-set definitions for the places where Red Hat has placed Kerberos and SSL. It's actually just the lnp port with SPECIALS defined accordingly. You may want to use it as a model if your system needs such definitions. Note that SPECIALS is primarily for IMAP toolkit (and Pine) purposes, and that user settings should use EXTRASPECIALS instead. Updated: 22 June 2001 imap-2001 is a major release. Programs written for imap-2000 will probably build with this version without modification. The FAQ document has been significantly expanded. Be sure to read it for more information. In addition to the usual bugfixes, the following features are new in imap-2001: SSL is now fully integrated into the IMAP toolkit; the old "alt" kludges to be able to produce a "sanitized" version of the IMAP toolkit to comply with late unlamented US export regulations are now completely gone. Full client and server TLS support is also in this release. The server certificate must be signed by a trusted certificate authority and the name in the certificate match the user's entry for the server host name; this means that the user must enter a fully-qualified host name. To build with SSL/TLS on UNIX, you now use "SSLTYPE=unix" instead of the former "SPECIALAUTHENTICATORS=ssl". To build with SSL/TLS on UNIX and disable the use of plaintext passwords except when under SSL/TLS, use "SSLTYPE=nopwd" instead of "SSLTYPE=unix". RFC 1730 (IMAP4 as opposed to IMAP4rev1) support is turned off by default in imapd. No clients should still be using RFC 1730 protocol. Look at the imapd Makefile for how to re-enable RFC 1730 support. Note that this code may be removed in the future, so if you think you need it you had better let me know. There are some new options (turned off by default) which attempt to work around problems in certain clients. See the FAQ file for more details. Updated: 24 January 2001 imap-2000c is a maintenance release, consisting primarily of bugfixes. Updated: 9 January 2001 imap-2000b is a maintenance release, consisting primarily of bugfixes. Updated: 9 November 2000 imap-2000a is a maintenance release, consisting primarily of bugfixes. Updated: 19 September 2000 imap-2000 is a major release. There are major internal and external changes from earlier versions (imap-4.x and imap-3.x series). Programs written for imap-4.x will probably build with this version without modification. It is extremely unlikely that a program written for imap-3.x or earlier series will build with this version without modifications. Drivers written for earlier versions will definitely need to be rewritten. In addition to the usual bugfixes, the following features are new in imap-2000: SSL support is now available. For UNIX, it is necessary to install some version of OpenSSL; see imap-2000/docs/SSLBUILD for more information. SSL support is now automatic for the NT, NTK, and W2K ports. SSL use is indicated by the /ssl switch in the mailbox name. With SSL connections, the server certificate is validated by the client code on UNIX, and Windows 2000 unless /novalidate-cert is specified. Server certificates are currently is not validated on Windows 9x, Windows Millenium, or Windows NT 4; this is an artifact of the operating system and not the port (e.g. client code using the NT port will validate certificates if running on Windows 2000). On UNIX, the server certificate must be signed by a trusted certificate authority. On Windows 2000, the certificate must be signed by a trusted certificate authority and match the user's entry for the server host name; this means that the user must enter a fully-qualified host name. Calendar reclama for the benefit of old broken non-Y2K compliant software. Two digit years from 00 to 69 will be interpreted as 2000 through 2069. In addition, three digit years from 100 to 105 will be interpreted as 2000 through 2005. Support for REFERENCES threading (in addition to the previously-existing ORDEREDSUBJECT threading). Support for the IMAP MULTIAPPEND extension. This allows much faster uploading of multiple messages to an IMAP server. Support for the LOGINDISABLED IMAP capability. If the IMAP server sends LOGINDISABLED as a capability, the client code will never attempt to send an IMAP LOGIN command. Support for SASL authentication identity vs. authorization identity. If the authentication method does not support this concept (e.g. AUTH=CRAM-MD5, AUTH=LOGIN, LOGIN command), the "*" character in the user name may be used to indicate a separate authentication identity; for example, "fred*joe" indicates authorization identity "fred", authentication identity "joe". UNIX-specific Changes: Support for SASL authentication identity vs. authorization identity in the IMAP and POP3 servers. If the user indicated by the authentication identity is in the "mailadm" group, he may specify any authorization identity and get logged in as the authorization identity user. If the IMAP and POP3 servers are build with PASSWDTYPE=nul, it will send LOGINDISABLED as a capability and also disable the AUTH=LOGIN and AUTH=PLAIN SASL authenticators. New MAILSUBDIR build option to change the default mailbox directory from the user's home directory to a subdirectory of the user's home directory. See imap-2000/Makefile for more information. New CHROOT_SERVER build option for closed server systems only. If defined, a chroot() call to the user's home directory is done as part of the login process. See imap-2000/Makefile for more information. New ADVERTISE_THE_WORLD build option which will add an IMAP namespace that points to the root. Not for the faint of heart. UNIX format mailboxes no longer require the pseudo-message, nor will a pseudo-message be added to a mailbox that does not have one. A new X-IMAPbase: header will be written in the first message. This is rather less efficient and robust than the pseudo-message (which remains the encouraged mechanism; UNIX format mailboxes will always be created with it), but perhaps will pacify some people who get upset by the pseudo-message. When building with MIT Kerberos it will try to detect and use libk5crypto.a instead of libcrypto.a. The mbx driver is more aggressive about cleaning up expunged messages that couldn't be purged because of shared access to the mailbox at the time of expunge. Now, every checkpoint will try to purge such messages; and a checkpoint is attempted at close time. Windows-specific Changes: New W2K port for Windows 2000. In addition to supporting SSL using the official SSPI interface (the NT and NTK ports invoke SChannel.DLL directly), the W2K port also supports Microsoft Kerberos. Note that the NT and NTK ports will work on Windows 2000, but the W2K port will not work on NT4, Windows 9x, or Windows Millenium. There is now a #user namespace, equivalent to the "~" namespace on UNIX. Changes for Developers: New c-client.h file which acts as a master include. c-client based applications should now include c-client.h instead of the individual c-client files (mail.h, misc.h, etc.). It is believed that c-client.h will work in C++ applications. New GET_FREEENVELOPESPAREP/SET_FREEENVELOPESPAREP and GET_FREEELTSPAREP/SET_FREEELTSPAREP function callbacks to free the "sparep" member of the envelope and cache elements, respectively. New OP_MULNEWSRC flag to mail_open() to use multiple newsrc files, and new GET_NEWSRCQUERY/SET_NEWSRCQUERY function callbacks to get the name of the newsrc file for news access. New "secret" nntp_article() function to do the NNTP ARTICLE command; this is generally useful only when chasing news URLs. New GET_HIDEDOTFILES/SET_HIDEDOTFILES feature to suppress file names that start with "." in mail_list() results. imap-2007f~dfsg/docs/naming.txt0000644000000000000000000001163711612411704015247 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ Mailbox Name Conventions Mark Crispin 5 October 2005 Please refer to the file drivers.txt for related information. I. Special names Special names appear by themselves. I.a. INBOX The name INBOX is special and refers to primary incoming message mailbox on the local system. I.b. #mhinbox (UNIX only) The name #mhinbox is special and refers to the primary incoming mh format mailbox on the local system. Don't worry about this if you don't know what mh format is. II. Special prefixes All names which start with a "#" have a "special prefix" which identifies an alternative namespace. Special prefixes appear in front of some additional text which constitutes a suffix. II.a. #mh/ (UNIX only) The prefix #mh/ is special and refers to the mh format mailbox named with the suffix. For example, #mh/foo refers to the mh format mailbox named foo. Don't worry about this if you don't know what mh format is. II.b. #news. (UNIX only) The prefix #news. is special and refers to the newsgroup named with the suffix. For example, #news.comp.mail.misc refers to the newsgroup named comp.mail.misc. II.c. #ftp/ (UNIX only) The prefix #ftp/ is special and refers to the anonymous ftp filesystem named with the suffix. For example, #ftp/foo/bar refers to the file /foo/bar in the anonymous FTP filesystem. Anonymous FTP files are available to anonymous IMAP logins. II.d. #public/ (UNIX only) The prefix #public/ is special and refers to the public files filesystem named with the suffix. For example, #public/foo/bar refers to the file /foo/bar in the public filesystem. Public files are available to anonymous IMAP logins. II.e. #shared/ (UNIX only) The prefix #shared/ is special and refers to the shared files filesystem named with the suffix. For example, #shared/foo/bar frefers to the file /foo/bar in the shared filesystem. III. Remote names All names which start with "{" are remote names, and are in the form "{" remote_system_name [":" port] [flags] "}" [mailbox_name] where: remote_system_name Internet domain name or bracketed IP address of server. port optional TCP port number, default is the default port for that service flags optional flags, one of the following: "/service=" service mailbox access service, default is "imap" "/user=" user remote user name for login on the server "/authuser=" user remote authentication user; if specified this is the user name whose password is used (e.g. administrator) "/anonymous" remote access as anonymous user "/debug" record protocol telemetry in application's debug log "/secure" do not transmit a plaintext password over the network "/imap", "/imap2", "/imap2bis", "/imap4", "/imap4rev1" equivalent to /service=imap "/pop3" equivalent to /service=pop3 "/nntp" equivalent to /service=nntp "/norsh" do not use rsh or ssh to establish a preauthenticated IMAP session "/ssl" use the Secure Socket Layer to encrypt the session "/validate-cert" validate certificates from TLS/SSL server (this is the default behavior) "/novalidate-cert" do not validate certificates from TLS/SSL server, needed if server uses self-signed certificates "/tls" force use of start-TLS to encrypt the session, and reject connection to servers that do not support it "/tls-sslv23" use the depreciated SSLv23 client when negotiating TLS to the server. This is necessary with some broken servers which (incorrectly) think that TLS is just another way of doing SSL. "/notls" do not do start-TLS to encrypt the session, even with servers that support it "/readonly" request read-only mailbox open (IMAP only; ignored on NNTP, and an error with SMTP and POP3) "/loser" disable various protocol features and perform various client-side workarounds; for example, it disables the SEARCH command in IMAP and does client-side searching instead. The precise measures taken by /loser depend upon the protocol and are subject to change over time. /loser is intended for use with defective servers which do not implement the protocol specification correctly. It should be used only as a last resort since it will seriously degrade performance. mailbox_name remote mailbox name, default is INBOX For example: {imap.foo.com}INBOX opens an IMAP connection to system imap.foo.com and selects INBOX. IV. All other names All other names are treated as local file names, relative to the user's home directory. Read drivers.txt for more details. imap-2007f~dfsg/docs/commndmt.txt0000644000000000000000000001160011612411705015603 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ [I wrote this tongue-in-cheek, but there's a lot here that people who build IMAP clients should take careful note. Most existing clients violate at least one, generally several, of these commandments. These are based on known user-visible problems that occur with various commonly used clients. Put another way, behind each commandment is a plethora of user (and server administrator) complaints caused by a violator.] Ten Commandments of How to Write an IMAP client Mark Crispin 1. Thou shalt not assume that it is alright to open multiple IMAP sessions selected on the same mailbox simultaneously, lest thou face the righteous wrath of mail stores that doth not permit such access. Instead, thou shalt labor mightily, even unto having to use thy brain to thinketh the matter through, such that thy client use existing sessions that are already open. 2. Thou shalt not abuse the STATUS command by using it to check for new mail on a mailbox that you already have selected in an IMAP session; for that session hath already told thou about new mail without thy having to ask. 3. Thou shalt remember the 30 minute inactivity timeout, and remember to speak to the IMAP server before that timeout expires. If thou useth the IDLE command, thou shalt send DONE from the IDLE before 29 minutes hath passed, and issue a new IDLE. If thou maketh no use of IDLE, then thou shalt send NOOP every few minutes, and the server shalt tell you about new mail, and there will be much rejoicing in the land. 4. Thou shalt not assume that all names are both the name of a mailbox and the name of a upper level of hierarchy that contains mailboxes; lest thou face the righteous wrath of mail stores in which a mailbox is a file and a level of hierarchy is a directory. Thou shalt pay diligent attention to the \NoSelect and \NoInferiors flags, so that your users may praise you with great praise. 5. Thou shalt learn and understand the unique features of IMAP, such as the unsolicited data model, the strict ascending rule of UIDs, how UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE structures; so that thou may use the IMAP protocol effectively. For a POP client hacked to babble IMAP protocol is still no more than a POP client. 6. Thou shalt remember untagged data sent by the server, and when thou needest data thou shalt consult your memory before asking the server. For those who must analyze thy protocol transactions are weak of stomach, and are likely to lose their recent meal should they see thou repeatedly re-fetch static data. 7. Thou shalt labor with great effort to work within the IMAP deleted/expunge model, even if thy own model is that of a trashcan; for interoperability is paramount and a trashcan model can be done entirely in the user interface. 8. Thou shalt not fear to open multiple IMAP sessions to the server; but thou shalt use this technique with wisdom. For verily it is true; if thou doth desire to monitor continuously five mailboxes for new mail, it is better to have five IMAP sessions continuously open on the mailboxes. It is generally not good to do a succession of five SELECT or STATUS commands on a periodic basis; and it is truly wretched to open and close five sessions to do a STATUS or SELECT on a periodic basis. The cost of opening and closing a session is great, especially if that session is SSL/TLS protected; and the cost of a STATUS or SELECT can also be great. By comparison, the cost of an open session doing an IDLE or getting a NOOP every few minutes is small. Great praise shall be given to thy wisdom in doing what is less costly instead of "common sense." 9. Thou shalt not abuse subscriptions, for verily the LIST command is the proper way to discover mailboxes on the server. Thou shalt not subscribe names to the user's subscription list without explicit instructions from the user; nor shalt thou assume that only subscribed names are valid. Rather, thou shalt treat subscribed names as akin to a bookmarks, or perhaps akin to how Windows shows the "My Documents" folder -- a set of names that are separate from the hierarchy, for they are such. 10. Thou shalt use the LIST "*" wildcard only with great care. If thou doth not fully comprehend the danger of "*", thou shalt use only "%" and forget about the existance of "*". Honor these commandments, and keep them holy in thy heart, so that thy users shalt maximize their pleasure, and the server administrators shalt sing thy praises and recommend thy work as a model for others to emulate. imap-2007f~dfsg/docs/formats.txt0000644000000000000000000002164611612411704015452 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ Mailbox Format Characteristics Mark Crispin 11 December 2006 When a mailbox storage technology uses local files and directories directly, the file(s) and directories are layed out in a mailbox format. I. Flat-File Formats In these formats, a mailbox and all the messages inside are a single file on the filesystem. The mailbox name is the name of the file in the filesystem, relative to the user's "mail home directory." A flat-file format mailbox is always a file, never a directory. This means that it is impossible to have a flat-file format mailbox that has inferior mailbox names under it (so-called "dual-usage" mailboxes). For some inexplicable reason, some people want this. The mail home directory is usually the same as the user login home directory if that concept is meaningful; otherwise, it is some other default directory (e.g. "C:\My Documents" on Windows 98). This can be redefined by modifying the c-client source code or in an application via the SET_HOMEDIR mail_parameters() call. For example, a mailbox named "project" is likely to be found in the file "project" in the user's home directory. Similarly, a mailbox named "test/trial1" (assuming a UNIX system) is likely to be found in the file "trial1" in the subdirectory "test" in the user's home directory. Note that the name "INBOX" has special semantics and rules, as described in the file naming.txt. The following flat-file formats are supported by c-client as of the time of this writing: . unix This is the traditional UNIX mailbox format, in use for nearly 30 years. It uses a line starting with "From " to indicate start of message, and stores the message status inside the RFC822 message header. unix is not particularly efficient; the entire mailbox file must be read when the mailbox is open, and when reading message texts it is necessary to convert the newline convention to Internet standard CR LF form. unix preserves UIDs, and allows the creation of keywords. Only one process may have a unix-format mailbox open read/write at a time. . mmdf This is the format used by the MMDF mailer. It uses a line consisting of 4 (0x01) characters to indicate start and end of message. Optionally, there may also be a unix format "From " line. It otherwise has the same characteristics as unix format. . mbx This is the current preferred mailbox format. It can be handled quite efficiently by c-client, without the problems that exist with unix and mmdf formats. Messages are stored in Internet standard CR LF format. mbx permits shared access, including shared expunge. It preserves UIDs, and allows the creation of keywords. . mtx This is supported for compatibility with the past. This is the old Tenex/TOPS-20 mail.txt format. It can be handled quite efficiently by c-client, and has most of the characteristics of mbx format. mtx is deficient in that it does not support shared expunge; it has no means to store UIDs; and it has no way to define keywords except through an external configuration file. . tenex This is supported for compatibility with the past. This is the old Columbia MM format. This is similar to mtx format, only it uses UNIX-style bare-LF newlines instead of CR LF newlines, thus incurring a performance penalty for newline conversion. . phile This is not strictly a format. Any file which is not in a recognized format is in phile format, which treats the entire contents of the file as a single message. II. File/Message Formats In these formats, a mailbox is a directory, and each the messages inside are separate files inside the directory. The file names of these files are generally the text form of a number, which also matches the UID of the message. In the case of mx, the mailbox name is the name of the directory in the filesystem, relative to the user's "mail home directory." In the case of news and mh, the mailbox name is in a separate namespace as described in the file naming.txt. A file/message format mailbox is always a directory. This means that it is possible to have a file/message format mailbox that has inferior mailbox names under it (so-called "dual-usage" mailboxes). For some inexplicable reason, some people want this. Note that the name "INBOX" has special semantics and rules, as described in the file naming.txt. The following file/message formats are supported by c-client as of the time of this writing: . mx This is an experimental format, and may be removed in a future release. An mx format mailbox has a .mxindex file which holds the message status and unique identifiers. Messages are stored in Internet standard CF LF form, so the file size of the message file equals the size of the message. mx is somewhat inefficient; the entire directory must be read and each file stat()'d. We found it intolerable for a moderate sized mailbox (2000 messages) and have more or less abandoned it. . mh This is supported for compatibility with the past. This is the format used by the old mh program. mh is very inefficient; the entire directory must be read and each file stat()'d, and in order to determine the size of a message, the entire file must be read and newline conversion performed. mh is deficient in that it does not support any permanent flags or keywords; and has no means to store UIDs (because the mh "compress" command renames all the files, that's why). . news This is an export of the local filesystem's news spool, e.g. /var/spool/news. Access to mailboxes in news format is read only; however, message "deleted" status is preserved in a .newsrc file in the user's home directory. There is no other status or keywords. news is very inefficient; the entire directory must be read and each file stat()'d, and in order to determine the size of a message, the entire file must be read and newline conversion performed. news is deficient in that it does not support permanent flags other than deleted; does not support keywords; and has no expunge. Soapbox on File/Message Formats If it sounds from the above descriptions that we're not putting too much effort into file/message formats, you are correct. There's a general reason why file/message formats are a bad idea. Just about every filesystem in existance serializes file creation and deletions because these manipulate the free space map. This turns out to be an enormous problem when you start creating/deleting more than a few messages per second; you spend all your time thrashing in the filesystem. It is also extremely slow to do a text search through a file/message format mailbox. All of those open()s and close()s really add up to major filesystem thrashing. What about Cyrus and Maildir? Both formats are vulnerable to the filesystem thrashing outlined above. The Cyrus format used by CMU's Cyrus server (and Esys' server) has a special associated flat file in each directory that contains extensive data (including pre-parsed ENVELOPEs and BODYSTRUCTUREs) about the messages. Put another way, it's a (considerably) more featureful form of mx. It also uses certain operating system facilities (e.g. file/memory mapping) which are not available on older systems, at a cost of much more limited portability than c-client. These considerably ameliorate the fundamental problems with file/message formats; in fact, Cyrus is halfway to being a database. Rather than support Cyrus format in c-client, you should run Cyrus or Esys if you want that format. The Maildir format used by qmail has all of the performance disadvantages of mh noted above, with the additional problem that the files are renamed in order to change their status so you end up having to rescan the directory frequently to locate the current names (particularly in a shared mailbox scenario). It doesn't scale, and it represents a support nightmare; it is therefore not supported in the official distribution. Maildir support code for c-client is available from third parties; but, if you use it, it is entirely at your own risk (read: don't complain about how poorly it performs or bugs). So what does this all mean? A database (such as used by Exchange) is really a much better approach if you want to move away from flat files. mx and especially Cyrus take a tenative step in that direction; mx failed mostly because it didn't go anywhere near far enough. Cyrus goes much further, and scores remarkable benefits from doing so. However, a well-designed pure database without the overhead of separate files would do even better. imap-2007f~dfsg/docs/drivers.txt0000644000000000000000000001707011612411705015452 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ c-client Driver Characteristics Mark Crispin 11 December 2006 Drivers are code modules that support different mailbox storage technologies. A mailbox storage technology may be implemented by 1) files and directories on the local system 2) a database 3) a network protocol. In the case of files and directories on the local system, a driver supports a particular mailbox format. Mailbox formats are discussed in more detail in the file formats.txt. As of the date this document was written, there was no bundled support for any databases in c-client. However, it should not be particularly difficult to write a driver that communicates with a database. Network protocols supported by c-client drivers are the Internet Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and IMAP2); the Post Office Protocol (version 3); and the Network News Transport Protocol (NNTP). In addition, c-client also supports NNTP and the Simple Mail Transport Protocol (SMTP) for mailbox transport. By default, all drivers are enabled. There is little benefit to be gained by disabling a driver, with one exception. The mbox driver implements the behavior of automatically moving new mail from the spool directory to the "mbox" file on the user's home directory, if and *only* if the "mbox" exists and is in mailbox format. The mbox driver is listed under EXTRADRIVERS; if you wish to disable it just remove it from that list and rebuild. I. Special name "INBOX" The following rules to select INBOX and its format apply in the order given if "black box mode" is not in effect: 1) mbox format is selected if file ~/mbox exists, and is in unix format or is zero-length. 2) mx format is selected if file ~/INBOX/.mxindex exists. 3) mbx format is selected if file ~/INBOX exists and is in mbx format. 4) tenex format is selected if: a) file ~/mail.txt exists, and is in tenex format or is zero-length. b) file ~/INBOX exists and is in tenex format. 5) mtx format is selected if: a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length. b) file ~/INBOX exists and is in mtx format. 6) mmdf format is selected if the spool directory file exists and is in mmdf format. 7) unix format is selected if the spool directory file exists and is in unix format. 8) the dummy driver is selected if the spool directory file does not exist, or exists and is empty. If "black box mode" is not in effect, messages are automatically transferred ("snarfed") from the spool directory to an INBOX in mbox, mx, mbx, tenex, and mtx formats. The following rules to select INBOX and its format apply in the order given if "black box mode" is in effect: 1) mx format is selected if file ~/INBOX/.mxindex exists. 2) mbx format is selected if file ~/INBOX exists and is in mbx format. 3) tenex format is selected if file ~/INBOX exists and is in tenex format. 4) mtx format is selected if file ~/INBOX exists and is in mtx format. 5) mmdf format is selected if file ~/INBOX exists and is in mmdf format. 6) unix format is selected if file ~/INBOX exists and is in unix format. 7) the dummy driver is selected if ~/INBOX does not exist, or exists and is empty. II. Special Name #mhinbox #mhinbox always refers to the directory "inbox" in the MH path, which is declared in the ~/.mh_profile file. Messages are automatically transferred from the spool directory to #mhinbox mailbox. III. Special Prefix "#mh/" Any name prefixed with "#mh/" always refers to a directory in the MH path, which is declared in the ~/.mh_profile file. For example, the name "#mh/foo" refers to directory "foo" in the MH path. IV. Special prefix "#news." Any name prefixed with "#news" always refers to a newsgroup. For example, the name "#news.comp.mail.misc" refers to newsgroup "comp.mail.misc". V. All Other Names The driver is selected by generating a file name from the mailbox name, and then examining the data of the object with the resulting name. The formats are checked in order: mx, mbx, tenex, mtx, mmdf, unix, and phile. The dummy driver is selected if the file is empty. The file name is generated according to certain rules, based upon the prefix of the mailbox name. On UNIX, the following rules apply: Prefix Interpretation of Suffix ------ ------------------------ / [black box] preceeds a user name; "/foo/bar" means "black box user foo's mailbox bar" [not black box] preceeds an absolute path name. ~ [not black box] preceeds a user name; "~foo/bar" means "UNIX user foo's mailbox bar" #ftp/ preceeds UNIX user ftp's mailbox name #public/ preceeds UNIX user imappublic's mailbox name #shared/ preceeds UNIX user imapshared's mailbox name All other names are interpreted in the context of the UNIX user's home directory (not black box), the black box user's black box directory (black box), or UNIX user ftp's home directory (anonymous). The strings "..", "//", and /~ are forbidden in names in: black box mode #ftp, #public, or #shared names anonymous users Anonymous users may only access: INBOX (belonging to UNIX user ftp) files in or below UNIX user ftp's home directory #ftp, #news, and #public namespace VI. Driver Comparison The following information about the local file drivers is an elaboration of a table compiled by Osma Ahvenlampi. Driver CA CE UID Kwd Sub NFS Performance Layout ------ -- -- --- --- --- --- ----------- ------ unix no no yes yes no limited fair file ;;; traditional UNIX format mbox no no yes yes no limited fair file ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic ;;; moving from the mail spool directory. mmdf no no yes yes no limited fair file ;;; default on SCO systems mbx yes yes yes yes no no very good prefile ;;; best performing local file driver; preferred format at UW tenex yes no no limited no no good prefile ;;; compatible with UNIX MM mtx yes no no limited no no very good prefile ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex ;;; but instead CRLF newlines instead of LF mx yes buggy yes yes yes no poor ixdir ;;; fullest function; *not* recommended due to performance problems and bugs; ;;; to be redesigned/rewritten mh yes no no no yes yes very poor dir ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names news yes no yes no yes yes very poor ixdir ;;; local news spool access; #news. prefix for all names phile no no no no no yes good file ;;; reads arbitrary file as a single readonly message IMPORTANT: the "performance" ratings are relative to other drivers, and not necessarily to other software which implements those formats. They relate to the driver's performance in typical operations such as an IMAP "FETCH ALL". Key to headings: CA: concurrent read/write access CE: expunge permitted in concurrent read/write access UID: sticky UIDs Kwd: keyword flags Sub: subfolders NFS: usable over network filesystems (NFS, AFS, etc.) Layout: file - single file prefile - file with preallocated space for state dir - directory, messages are files ixdir - directory, messages are files, with helper index In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and POP3 protocols respectively. imap-2007f~dfsg/docs/internal.txt0000644000000000000000000034060111612411705015607 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ Documentation of c-client Functions and Interfaces REVISED: 19 August 1996 Credits The original version of this document was written by Mark Crispin at the University of Washington, and described the version of c-client that supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols. This version is a substantial rewrite of that document, and was written by Mark Crispin with funding from Sun Microsystems, Incorporated. Sun's generous support of this work is gratefully acknowledged. Road Map This document is organized into the following sections. Except as noted, an implementor of an application that uses c-client needs to be familiar with all of these sections. Someone who plans to write a new mailbox driver for c-client (or otherwise modify it) needs to be familiar with all sections, no exception. History History of how c-client came about. Overview Read this before designing an application that uses c-client. c-client Structures Documentation of several important c-client structs which are used in, and returned by, c-client calls. String Structures Documentation of the concept of a "string structure", which provides random access to strings without requiring that the string be in memory. c-client Support Functions Documentation of support functions for c-client; these deal with c-client functionality. Only mail_parameters() is of interest to most application developers. Advanced application developers, particularly for limited memory systems, may also need to know about the readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function pointer types, and possibly also the mail_valid_net_parse() function. Mailbox Access Functions Documentation of functions which deal with mailboxes; listing, subscribing, creating, deleting, renaming, status inquiries, opening, and closing mailboxes. Handle Functions Documentation of mail stream handles, which provide protection for an advanced application which may have multiple pointers to a single mail stream. If a stream has a handle on it, closing the stream does not release its memory, so pointers to it in the application remain valid. Freeing the last handle will free the entire stream. This is only of interest for advanced application developers. Message Data Fetching Functions Documentation on message data fetching in an open mailbox, including parsed representations of RFC-822 and MIME headers and message text. Also how to fetch message attributes (flags, internal date, sizes). Message Status Manipulation Functions Documentation on altering message flags in an open mailbox. Mailbox Searching Documentation on searching an open mailbox for messages which match certain criteria (e.g. "messages sent July 4 from Jones with text `Paris'"). Miscellaneous Mailbox and Message Functions Documentation on other operations that would be used by an application but that don't fit into any of the above categories. Date/Time Handling Functions Documentation on functions that deal with date/time strings. This is only of interest for advanced application developers and for implementors of new c-client drivers. Utility Functions Documentation on internal utility functions. This is primarily of interest for implementors of new c-client drivers, but advanced application developers may also use some of these functions. Data Structure Instantiation/Destruction functions Documentation on creating and destroy c-client structures. This is primarily of interest for implementors of new c-client drivers. However, application developers will need some of these functions to create and destroy structures which are used as arguments to various application functions. Authentication Functions Documentation on support for network protocol authentication functions. This is only of interest for implementors of new c-client drivers which deal with authentication mechanisms. Network Access Functions Documentation on creating and destroy c-client structures. This is primarily of interest for implementors of new c-client drivers which deal with a network. However, advanced application developers may need to use this information if they wish to insert their own layer into a network session. Subscription Management Functions Documentation on managing the local (client-based) subscription database file. This is primarily of interest to advanced application developers. Miscellaneous Utility Functions Documentation on various useful utility functions, such as "make a copy of this string." SMTP Functions Documentation on posting email messages via SMTP protocol. NNTP Functions Documentation on posting netnews messages via NNTP protocol. RFC 822 Support Functions Documentation on public RFC-822/MIME functions. This is primarily of interest for implementors of new c-client drivers and advanced application developers. Operating System-Dependent Public Interface Documentation on OS-dependent functions. With the exception of fs_get(), fs_give(), and fs_resize(), which should be called instead of malloc(), free(), and realloc(), these functions are primarily of interest for implementors of new c-client drivers. Main Program Callbacks Documentation of functions which the main program must provide as callbacks from c-client. Driver Interface Documentation of the driver dispatch vector and the functions which a driver must supply. This is primarily of interest for implementors of new c-client drivers. Driver Support Functions Documentation of support functions which are called by drivers. This is primarily of interest for implementors of new c-client drivers. History The c-client API was originally written by Mark Crispin at Stanford University as a set of routines to support IMAP and SMTP from a main program which would handle the user interface. In its original form, it was written as the low-level routines that were to be used as part of a Macintosh client. The first IMAP client, MM-D (for "MM on Xerox D machines" -- MM was a popular DEC-20 mail program) was written in Interlisp for Xerox Lisp machines. At that time, there was no name for the embryonic Mac client, but since it was the first one to be written in C instead of Lisp, it was given a development name of "C client". This name became "c-client" because that is the name of the subdirectory on UNIX where the source files were stored. To exercise the routines, a minimal main program which uses c-client, mtest, was written. mtest has subsequently been extended so that it runs on every platform that c-client is ported. The real Mac client, was eventually written by Frank Gilmurrary and Bill Yeager at Stanford using the autumn 1988 version of c-client and named "MacMS". In the winter of 1988-89, Mark Crispin, who had changed jobs to the University of Washington, developed MS as an MM-like text-based program for UNIX and MailManager as a GUI-based program for NeXT machines. The realization sunk in that this API needed its own name. As early as spring 1989, there were at least four programs (mtest, MS, MailManager, and MacMS) that used it. The name c-client thus became permanent. In its history, c-client has undergone two major redesigns, both by Mark Crispin who is now on the staff at the University of Washington. The first major redesign added the following: 1) ANSI C calling conventions throughout to assist in function argument type checking. 2) Vectoring mail access calls through "driver" methods; thus providing transparent access to multiple types of mail stores with the same call. 3) MIME support. The second major redesign was part of the IMAP4 project. Many c-client functions were extended with additional arguments and options. The driver interface was also made simpler, with more work done by driver-independent code. Overview The most important file for the author of an application using the c-client is mail.h. mail.h defines several important structures of data which are passed between the main program and the c-client. Although some functions (e.g. mail_fetchtext_body()) return the data fetched, for certain other data items (e.g. flags) you need to get the data as a structure reference. mail.h also defines a large number of useful constants and structures. When a function in mail.h exists to reference data, it MUST be used instead of referencing the structures directly. This is because in some cases the data is not actually fetched until a reference (via the function call) is made. For example, although the MESSAGECACHE element for a message can be obtained by indexing the proper cache element in the stream, there is no guarantee that the item in fact exists unless mail_fetchstructure_full() is called for that message. Less costly functions. also exist to create and load a MESSAGECACHE element. The main program will probably also need to include smtp.h, misc.h, and osdep.h, but this usage should be solely to receive function prototypes. Any other definitions in those files should be considered private to that module. Two important predefined symbols are NIL and T. NIL is any sort of "false"; T is any sort of "true". NIL is also used to null-specify certain optional arguments. * * * IMPORTANT * * * Any multi-threaded application should test stream->lock prior to calling any c-client stream functions. Any attempt to call a mail_xxx() function while one is already in progress on the same stream will cause the application to fail in unpredictable ways. Note that this check is insufficient in a preemptive-scheduling multi-tasking application due to the possibility of a timing race. Such applications must be written so that only one process accesses the stream, or to have a higher level lock. Since MAIL operations will not finish until they are completed, a single-tasking application does not have to worry about this problem, except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which case the stream is *always* locked. c-client Structures c-client has a large number of structures which are used for multiple functions. The most important of these are described here. The MAILSTREAM structure is used to reference open mailboxes. Applications may reference the following: char *mailbox; mailbox name unsigned short use; stream use count, this is incremented unsigned short sequence; stream sequence, this is incremented each time a stream is reused (i.e. mail_open() is called to open a different mailbox on this stream) unsigned int rdonly : 1; stream is open read-only unsigned int anonymous : 1; stream is open with anonymous access unsigned int halfopen : 1; stream is half-open; it can be reopened or used for functions that don't need a open mailbox such as mail_create() but no message data can be fetched unsigned int perm_seen : 1; Seen flag can be set permanently unsigned int perm_deleted : 1; Deleted flag can be set permanently unsigned int perm_flagged : 1; Flagged flag can be set permanently unsigned int perm_answered :1; Answered flag can be set permanently unsigned int perm_draft : 1; Draft flag can be set permanently unsigned int kwd_create : 1; new user flags can be created by referencing then in mail_setflag() or mail_clearflag(). Note: this can change during a session (e.g. if there is a limit on the number of keywords), so check after creating a new flag to see if any more can be created before letting the user try to do so unsigned long perm_user_flags; corresponding user flags can be set permanently. This is a bit mask which matches the entries in stream->user_flags[] unsigned long gensym; generated unique value. Always referenced with stream->gensys++ unsigned long nmsgs; number of messages in current mailbox unsigned long recent; number of recent messages in current mailbox unsigned long uid_validity; UID validity value; this is used to verify that recorded UIDs match the UIDs that the stream has. If the mailbox does not have matching UIDs (e.g. the UIDs were lost or not recorded) then the UID validity value will be different unsigned long uid_last; highest currently assigned UID in the current mailbox; a new UID will be assigned with ++stream->uid_last char *user_flags[NUSERFLAGS]; pointers to user flag names in bit order from stream->perm_user_flags or elt->user_flags The following MAILSTREAM values are only used internally: DRIVER *dtb; dispatch table for this driver void *local; pointer to driver local data unsigned int lock : 1; stream lock flag (an operation is in progress; used as a bug trap to detect recursion back to c-client from callback routines). unsigned int debug : 1; debugging information should be logged via mm_dlog(). unsigned int silent : 1; don't do main program callbacks on this stream (used when a stream is opened internally) unsigned int scache : 1; short caching; don't cache information in memory The following MAILSTREAM values are only used by the cache manager routine (see the documentation about mailcache_t above): unsigned long cachesize; size of c-client message cache union { void **c; to get at the cache in general MESSAGECACHE **s; message cache array LONGCACHE **l; long cache array } cache; The following MAILSTREAM values are for the convenience of drivers that use short caching and want to be able to garbage collect any values that they returned: unsigned long msgno; message number of `current' message ENVELOPE *env; pointer to `current' message envelope BODY *body; pointer to `current' message body char *text; pointer to `current' text The MESSAGECACHE structure (commonly called an "elt" as a nickname for "cache ELemenT") contains information about messages. Applications may use the following: unsigned long msgno; message number. If the elt is locked (by elt->lockcount++), then the elt pointer can be stored (e.g. with the data for a window which draws this message) and elt->msgno will change automatically whenever expunges are done so the window will always view the correct message. If elt->msgno becomes 0, then the message has been expunged, but the elt won't be freed until the elt lock count is decremented (by mail_free_elt()). unsigned long uid; message unique ID unsigned int hours: 5; internal date hours (0-23) unsigned int minutes: 6; internal date minutes (0-59) unsigned int seconds: 6; internal date seconds (0-59) unsigned int zoccident : 1; non-zero if internal date time zone is west of UTC unsigned int zhours : 4; internal date time zone hours from UTC (0-12) unsigned int zminutes: 6; internal date time zone minutes (0-59) unsigned int seen : 1; message Seen flag unsigned int deleted : 1; message Deleted flag unsigned int flagged : 1; message Flagged flag unsigned int answered : 1; message Answered glag unsigned int draft : 1; message Draft flag unsigned int valid : 1; flags are valid in this elt; an elt that was newly created but never loaded with flags won't have this set. unsigned int recent : 1; message recent flag unsigned int searched : 1; message matches search criteria in most recent mail_search_full() call unsigned int spare : 1; reserved for application use unsigned int spare2 : 1; reserved for application use unsigned int spare3 : 1; reserved for application use unsigned int lockcount : 8; non-zero if multiple references to this elt. Refer to the msgno member for more information. unsigned int day : 5; internal date day of month (1-31) unsigned int month : 4; internal date month of year (1-12) unsigned int year : 7; internal date year since BASEYEAR (currently 1970; was 1969 in older versions so use BASEYEAR instead of having the base year wired in) unsigned long user_flags; message user flags; this is a bit mask which matches the entries in stream->user_flags[] unsigned long rfc822_size; size of message in octets The following MESSAGECACHE values are only used internally by drivers: unsigned int sequence : 1; message is in sequence from either mail_sequence() or mail_uid_sequence() unsigned long data1; first data item unsigned long data2; second data item unsigned long data3; third data item unsigned long data4; fourth data item The ADDRESS structure is a parsed form of a linked list of RFC 822 addresses. It contains the following information: char *personal; personal name phrase char *adl; at-domain-list (also called "source route") char *mailbox; mailbox name char *host; domain name of mailbox's host char *error; error in address from smtp_mail(); if an error is returned from smtp_mail() for one of the recipient addresses the SMTP server's error text for that recipient can be found here. If it is null then there was no error (or an error was found with a prior recipient ADDRESS *next; pointer to next address in list The ENVELOPE structure is a parsed form of the RFC 822 header. Its member names correspond to the RFC 822 field names. It contains the following information: char *remail; remail header if any ADDRESS *return_path; error return address char *date; message composition date string ADDRESS *from; from address list ADDRESS *sender; sender address list ADDRESS *reply_to; reply address list char *subject; message subject string ADDRESS *to; primary recipient list ADDRESS *cc; secondary recipient list ADDRESS *bcc; blind secondary recipient list char *in_reply_to; replied message ID char *message_id; message ID char *newsgroups; USENET newsgroups char *followup_to; USENET reply newsgroups char *references; USENET references The BODY structure is a parsed form of a linked list of the MIME structure of a message. It contains the following information. unsigned short type; body primary type code. This is an index into the body_types vector of body type names. The following body types are pre-defined: TYPETEXT unformatted text TYPEMULTIPART multiple part TYPEMESSAGE encapsulated message TYPEAPPLICATION application data TYPEAUDIO audio TYPEIMAGE static image (GIF, JPEG, etc.) TYPEVIDEO video TYPEOTHER unknown Additional types up to TYPEMAX are dynamically defined if they are encountered by c-client. unsigned short encoding; body transfer encoding. This is an index into the body_encodings vector of body encoding names. The following body encodings are pre-defined: ENC7BIT 7 bit SMTP semantic data ENC8BIT 8 bit SMTP semantic data ENCBINARY 8 bit binary data ENCBASE64 base-64 encoded data ENCQUOTEDPRINTABLE human-readable 8-as-7 bit data ENCOTHER unknown Additional encodings up to ENCMAX are dynamically defined if they are encountered by c-client. char *subtype; body subtype string PARAMETER *parameter; parameter list char *id; body content identifier char *description; body content description unsigned char *contents.text; when composing a message that is NOT of TYPEMULTIPART, non-binary text of the content is stored here. Note that this happens even when the text is of TYPEMESSAGE. Text of encoding ENC8BIT may be converted to ENCQUOTEDPRINTABLE when it is sent. This should not be referenced for any other reason; in particular, this is NOT the way for an application to access content data (use mail_fetchbody_full() instead). BINARY *contents.binary; when composing a message that is NOT of TYPEMULTIPART, binary content (of encoding ENCBINARY) is stored here. It will be converted to ENCBASE64 when it is sent. This should not be referenced for any other reason; in particular, this is NOT the way for an application to access content data (use mail_fetchbody_full() instead). PART *contents.part; for body parts of TYPEMULTIPART, this contains the list of body parts in this multipart MESSAGE contents.msg; for body parts of TYPEMESSAGE with subtype "RFC822", this contains the encapsulated message unsigned long size.lines; size in lines unsigned long size.bytes; size in octets. This MUST be set when composing a message if the encoding is ENC8BIT or ENCBINARY. char *md5; body content MD5 checksum The following BODY information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. unsigned char *contents.text; drivers can store a pointer to the body contents as text here. unsigned long size.ibytes; internal size of the body content (prior to newline conversion, etc.) in octets The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME body part. It contains the following information: ENVELOPE *env; encapsulated message RFC 822 header BODY *body; encapsulated message MIME structure The following MESSAGE information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. char *hdr; encapsulated message header unsigned long hdrsize; message header size char *text; message in RFC 822 form unsigned long offset; offset of text from header The PARAMETER structure is a parsed form of a linked list of attribute/value pairs. It contains the following information: char *attribute; attribute name char *value; value PARAMETER *next; next parameter in list The PART structure is a parsed form of a linked list of MIME body parts. It contains the following information: BODY body; body information for this part PART *next; next body part The following PART information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. unsigned long offset; offset from body origin The NETMBX structure is a parsed form of a network mailbox name: char host[NETMAXHOST]; remote host name char user[NETMAXUSER]; remote user name if specified char mailbox[NETMAXMBX]; remote mailbox name char service[NETMAXSRV]; remote service name (IMAP4, NNTP, etc.) unsigned long port; TCP/IP port number if specified unsigned int anoflag : 1; anonymous access requested unsigned int dbgflag : 1; protocol debugging telemetry, via mm_dlog(), requested The STRINGLIST structure is a list of strings (which may have embedded NULs) and their lengths: char *text; string text unsigned long size; string length STRINGLIST *next; next string in list String Structures A string structure is analogous to a char*, and is used in some functions as an input argument. It represents a string of data in a way that does not necessarily require the entire string to be in memory at once. This is essential for small machines with highly-restricted memory limits (e.g. DOS). String Structure Access To use a string structure, the caller needs to know a string driver and needs to know the driver-dependent data used by that string structure. A simple string driver is mail_string, a string driver that takes an in-memory char* string as the driver-dependent data. The DOS port uses string drivers that take a struct holding a file descriptor and a file offset. Often the user of a string driver is the same module that defined it, so usually the programmer knows about its conventions. The following calls are used to access a string structure: void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size); s pointer to the string structure to be initialized d pointer to the string driver data pointer to driver-dependent data, from which the driver can determine string data size size of the string This call initializes the string stucture. unsigned long SIZE (STRING *s); s pointer to the string structure This call returns the number of characters remaining in the string after the current string character pointer. char CHR (STRING *s); s pointer to the string structure This call returns the character at the current string character pointer. char SNX (STRING *s); s pointer to the string structure This call returns the character at the current string character pointer, and increments the string character pointer. unsigned long GETPOS (STRING *s); s pointer to the string structure This returns the value of the current string character pointer. void SETPOS (STRING *s,unsigned long i); s pointer to the string structure i new string pointer value This method sets the string character pointer to the given value. String Structure Internals A string structure holds the following data: void *data; used by the string driver as it likes unsigned long data1; used by the string driver as it likes unsigned long size; static, holds the total length of the string from the INIT call char *chunk; current chunk of in-memory data; this is used for buffering to avoid unnecessary calls to the string driver's next method. unsigned long chunksize; size of an in-memory data chunk unsigned long offset; position of first character of the chunk in the overall string char *curpos; current position; this is what CHR() will access unsigned long cursize; number of characters remaining in the current string STRINGDRIVER *dtb; the string driver for this string structure A string structure is manipulated by a string driver, which has the following access methods: void (*init) (STRING *s,void *data,unsigned long size); s pointer to the string structure to be initialized data pointer to driver-dependent data, from which the driver can determine string data size size of the string This method initializes the string stucture. It can use the data, data1, and chunksize values as it likes. The remaining values must be set up as follows: size static, copied from the size argument chunk pointer to a buffer loaded with initial data chunksize size of the buffer offset 0 curpos copied from chunk cursize copied from chunksize dtb STRINGDRIVER identity pointer char (*next) (STRING *s); s pointer to the string structure This method returns the character at the current string character pointer, and increments the string character pointer. This method is likely to call the setpos method if the desired character is not in the current chunk. void (*setpos) (STRING *s,unsigned long i); s pointer to the string structure i new string pointer value This method sets the string character pointer to the given value. If the pointer is not in the current chunk, then a new chunk is loaded and the associated values (chunk, offset, curpos, cursize) are adjusted accordingly. c-client Support Functions void mail_string_init (STRING *s,void *data,unsigned long size); char mail_string_next (STRING *s); void mail_string_setpos (STRING *s,unsigned long i); These three functions are the init, next, and setpos string structure access methods for the build-in mail_string string driver. mail_string is a basic string driver for a char* string. See the documentation below on "String Structures" for more information. void mail_link (DRIVER *driver); driver pointer to the driver to be added This function adds the specified driver to the list of mailbox drivers. Initially there are no drivers lunk, so all programs which intend to use c-client need to have at least one call to this function. A function which uses IMAP4 would have a statement such as: mail_link (&imapdriver); /* link in IMAP driver */ early in the program's initialization. Normally, this is done by the statement #include "linkage.c" which will include the "system standard driver linkage" defined when c-client was built. By using linkage.c instead of explicit mail_link() calls, you are guaranteed that you will have a consistant linkage among all software built on this system. void auth_link (AUTHENTICATOR *auth); auth pointer to the authenticator to be added This function adds the specified authenticator to the list of authenticators. Initially there are no authenticators lunk. Normally, this is done by linkage.c so you don't need to call this routine explicitly. void *mail_parameters (MAILSTREAM *stream,long function,void *value); stream stream to poll or NIL function function code value new value for function codes that change a parameter This function fetches or changes the settings of various c-client operational parameters depending upon the function. If the stream is specified, only the action for the underlying driver for that stream is taken; however, the scope of the operational parameters is global so there is generally no reason for the stream argument ever to be non-NIL. The function codes ENABLE_DRIVER and DISABLE_DRIVER take a driver pointer as a value. These functions enable and disable mailbox processing by that driver. By default, all drivers are enabled. The remaining function codes are in a pair named GET_xxx to fetch an operational parameter and SET_xxx to set the parameter: GET_DRIVERS / SET_DRIVERS The list of currently lunk drivers. GET_GETS / SET_GETS If non-NIL, points to a function for reading message text. Defaults to NIL. This function is called with three arguments; a function pointer to a "reading function", a stream for the reading function, and a size in octets. The reading function is in turn called with the stream, a size in octets, and a pointer to a readin buffer. This function returns with a char* string, which will be returned by the mail_fetchheader(), mail_fetchtext(), or mail_fetchbody() function which triggered the message text reading. The purpose is to permit reading of large strings, without requiring an in-memory buffer for the entire string. The idea is that this function can store the data in some form other than a char* (e.g. a temporary file) and the main program will recognize that it should get the text from there instead of from the results from mail_fetch....(). This is only supported on DOS and Win16; on other platforms it is inconsistent whether or not it works. GET_CACHE / SET_CACHE Points to the c-client cache manager function. Defaults to mm_cache(). GET_SMTPVERBOSE / SET_SMTPVERBOSE If non-NIL, points to a function that accepts a char* string. This function is called any time the SMTP routines receive a response code less than 100. The argument is the text of the response code GET_RFC822OUTPUT / SET_RFC822OUTPUT If non-NIL, points to an alternate rfc822_output() function. rfc822_output() will call this function and return instead of doing its normal action. See the description of rfc822_output() for more information. GET_USERNAME / SET_USERNAME The logged-in user name. GET_HOMEDIR / SET_HOMEDIR The home directory path name. GET_LOCALHOST / SET_LOCALHOST The local host name. GET_SYSINBOX / SET_SYSINBOX The "system INBOX" (where mail is delivered) path name. GET_OPENTIMEOUT / SET_OPENTIMEOUT TCP/IP open timeout in seconds. Defaults to 0 (system default timeout, usually 75 seconds on Unix). GET_READTIMEOUT / SET_READTIMEOUT TCP/IP read timeout in seconds. Defaults to 0 (no timeout). GET_WRITETIMEOUT / SET_WRITETIMEOUT TCP/IP write timeout in seconds. Defaults to 0 (no timeout). GET_CLOSETIMEOUT / SET_CLOSETIMEOUT TCP/IP close timeout in seconds. Defaults to 0 (no timeout). GET_TIMEOUT / SET_TIMEOUT If non-NIL, points to the function called when a TCP/IP timeout occurs. This function is called with the number of seconds since the start of the TCP operation. If it returns non-zero, the TCP/IP operation is continued; if it returns non-zero, the TCP/IP connection is aborted. GET_RSHTIMEOUT / SET_RSHTIMEOUT rsh connection timeout in seconds. Defaults to 15 seconds. GET_MAXLOGINTRIALS / SET_MAXLOGINTRIALS The maximum number of login attempts permitted in an IMAP or POP connection. Defaults to 3. GET_LOOKAHEAD / SET_LOOKAHEAD The number of subsequent envelopes prefetched in IMAP when an envelope is fetched. Defaults to 20. GET_IMAPPORT / SET_IMAPPORT The IMAP port number. Defaults to 143. GET_PREFETCH / SET_PREFETCH The number of envelopes prefetched in IMAP from the results of a SEARCH. Defaults to 20. GET_CLOSEONERROR / SET_CLOSEONERROR If non-NIL, close an opening IMAP connection if the SELECT command fails instead of returning a half-open stream. Defaults to NIL. GET_POP3PORT / SET_POP3PORT The POP3 port number. Defaults to 110. GET_UIDLOOKAHEAD / SET_UIDLOOKAHEAD The number of UIDs premapped when a message number is translated to a UID. Defaults to 1000. GET_MBXPROTECTION / SET_MBXPROTECTION Default file protection for newly created mailboxes. Defaults to 0600. GET_DIRPROTECTION / SET_DIRPROTECTION Default file protection for newly created directories. Defaults to 0700. GET_LOCKPROTECTION / SET_LOCKPROTECTION Default file protection for locks. Defaults to 0666. WARNING: don't blithely change this. If other processes can't get access to a lock then they will have trouble in locking properly. GET_FROMWIDGET / SET_FROMWIDGET If non-NIL, APPEND in the Unix mbox format will insert a ">" character in front of all lines which begin with the string "From ". If NIL, it will only do so if the entire line looks like a message delimiter (that is, the date is also in correct format). Defaults to T. GET_NEWSACTIVE / SET_NEWSACTIVE Netnews active file path name. GET_NEWSSPOOL / SET_NEWSSPOOL Netnews spool directory path name. GET_NEWSRC / SET_NEWSRC Netnews newsgroup reading status file (.newsrc) path name. GET_EXTENSION / SET_EXTENSION If non-NIL, points to a string holding the extension for all mailbox files. This is only supported on DOS and Win16. GET_DISABLEFCNTLLOCK / SET_DISABLEFCNTLLOCK If non-NIL, disables fcntl() locking on SVR4. This is done if fcntl() tends to hang for no good reason. Now that the fcntl() code checks for NFS files and no-ops the locking, this problem usually doesn't happen much any more. Defaults to NIL. GET_LOCKEACCESERROR / SET_LOCKEACCESERROR If non-NIL, give a warning if an attempt to create a .lock file gets an EACCES ("Permission denied") error. This usually means that somebody protected the system inbox directory (e.g. /var/mail) instead of making it public-write with the sticky bit. Defaults to non-NIL, since this is usually bad news. GET_LISTMAXLEVEL / SET_LISTMAXLEVEL The maximum depth of recusion that LIST will go on a * wildcard. Defaults to 20. GET_ANONYMOUSHOME / SET_ANONYMOUSHOME The anonymous use home directory name. typedef long (*readfn_t) (void *stream,unsigned long size,char *buffer); stream a designator suitable size a number of octets to read buffer a buffer of at least size octets for readin This function reads the given number of octets into the buffer, using the given stream. What sort of object the stream is depends upon the function and its caller, so you must make sure that the readfn is suitable for the caller's purpose. Common uses include support of the mailgets function (see below) and of reading from local files on systems with limited address space. typedef char *(*mailgets_t) (readfn_t f,void *stream,unsigned long size); f the readfn to use stream stream argument for the readfn size total number of octets to read This is the argument to the SET_GETS mail_parameter() call. This function must read size octets from the stream, using the readfn f. It may call f multiple times to accomplish this; this will read the data in a serial fashion. So, for example, if size is a megabyte and there is only 4K of available buffer space, it can call f 256 times to satisfy the request. There is no way to back up in the reading, so any processing or saving of the data must be done when it is read. The function mm_gets() in mail.c is a sample mailgets function; it reads the first MAXMESSAGESIZE of data into memory and discards the rest. typedef void *(*mailcache_t) (MAILSTREAM *stream,unsigned long msgno,long op); stream stream to cache manage msgno message to cache manage in the stream op cache management operation This function manages the c-client cache. Normally, a program will use the default c-client cache manager routine mm_cache(). However, a main program may want to supply its own cache manager, e.g. it may want to store the data on a disk file instead of in memory on DOS and Win16 where memory is tight. If you write your own cache manager, you need to examine the default mm_cache() manager closely, as well as paying close attention to what goes into an elt (a MESSAGECACHE element). It is highly likely that if you roll elts out to disk, you will want to set stream->scache and *NOT* use long elts (because long elts have ENVELOPE and BODY pointers that you would have to know how to write to disk and read back). The cache management functions are one of the following: CH_INIT Initialize the entire cache for the stream. This is called only when creating a new stream or when freeing it. The msgno argument is ignored. CH_SIZE Make sure that the cache is at least large enough to support msgno. This is a request to grow the cache if necessary, not shrink it. CH_MAKELELT Return a long elt for msgno, creating it if necessary. This is the underlying support function for mail_lelt(). CH_LELT Return the long elt for msgno, or NIL if it does not already exist. CH_MAKEELT Return an elt for msgno, creating it if necessary. This is the underlying support function for mail_elt(). CH_ELT Return the elt for msgno, or NIL if it does not already exist. CH_FREE Free the [l]elt for msgno. CH_EXPUNGE Free the [l]elt for msgno, and reclaim its position. All subsequent elts are renumbered with their elt->msgno decremented by 1. [Hence msgno+1 becomes msgno, etc.] This supports message expunging from the cache. typedef long (*tcptimeout_t) (long time); time total time spent since TCP operation started This function is called when a TCP operation times out. It is set by the SET_TIMEOUT mail_parameter(). The function can return non-zero to continue the TCP operation (e.g. after outputting a "do you still want to wait" prompt) or zero if it wants the TCP operation to abort and close. If the TCP operation aborts, it will likely cause the upper level IMAP, SMTP, etc. stream to abort and close as well. DRIVER *mail_valid (MAILSTREAM *stream,char *mailbox,char *purpose); stream if non-NIL, stream to use for validation mailbox mailbox name to validate purpose filled in as xxx in "Can't xxx" in error messages This function validates the given mailbox name. It successful, it returns the driver that can open that name if successful, otherwise it returns NIL. If stream is non-NIL, the mailbox name must be valid for the type of mailbox associated with that stream (e.g. an NNTP name can not be used with an IMAP stream). If purpose is non-NIL, an error message is passed via mm_log() when an error occurs. DRIVER *mail_valid_net (char *name,DRIVER *drv,char *host,char *mailbox); name mailbox name to validate drv driver name to validate against host buffer to return host name if non-NIL mailbox buffer to return remote mailbox name if non-NIL This function is an alternative to mail_valid_net_parse(). It validates the given mailbox name as a network name and makes sure that its service name is the same as the driver in drv. If successful, it returns drv, and copies the host and mailbox strings as needed. Otherwise it returns NIL. long mail_valid_net_parse (char *name,NETMBX *mb); name mailbox name to parse mb pointer to NETMBX structure to return This function parses a network mailbox name. If the name is a network mailbox name, it returns non-NIL, with the NETMBX structure loaded with the results form the parse. Mailbox Access Functions void mail_list (MAILSTREAM *stream,char *ref,char *pat); void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); stream if non-NIL, stream to use ref mailbox reference string pat mailbox pattern string contents contents to search This function returns a list of mailboxes via the mm_list() callback. The reference is applied to the pattern in an implementation dependent fashion, and the resulting string is used to search for matching mailbox names. "*" is a wildcard which matches zero or more characters; "%" is a variant which does not descend a hierarchy level. Read the IMAP specification for more information. mail_scan() is a variant which takes a string to search for in the text of the mailbox. The string is a free-text string, without regard for message boundaries, and thus the choice of strings must be made with care. void mail_lsub (MAILSTREAM *stream,char *ref,char *pat); stream if non-NIL, stream to use ref mailbox reference string pat mailbox pattern string This function returns a list of subscribed mailboxes via the mm_lsub() callback. The reference is applied to the pattern in an implementation dependent fashion, and the resulting string is used to search for matching mailbox names in the subscription list. "*" is a wildcard which matches zero or more characters; "%" is a variant which does not descend a hierarchy level. Read the IMAP specification for more information. long mail_subscribe (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function adds the given name to the subscription list. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. long mail_unsubscribe (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function removes the given name from the subscription list. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. long mail_create (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function creates a mailbox with the given name. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to create INBOX or a mailbox name which already exists. long mail_delete (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function deletes the named mailbox. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to delete INBOX or a mailbox name which does not already exist. long mail_rename (MAILSTREAM *stream,char *old,char *newname); stream if non-NIL, stream to use old existing mailbox name newname new (not yet existing) mailbox name This function renames the old mailbox to the new mailbox name. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to reanme a mailbox that does not exist, or rename a mailbox to a name that already exists. It is permitted to rename INBOX; a new empty INBOX is created in its place. long mail_status (MAILSTREAM *stream,char *mbx,long flags); stream if non-NIL, stream to use mbx mailbox name flags option flags This function returns the status of the given mailbox name via the mm_status() callback. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. The options are a bit mask with one or more of the following, indicating the data which should be returned. SA_MESSAGES number of messages in the mailbox SA_RECENT number of recent messages in the mailbox SA_UNSEEN number of unseen messages in the mailbox SA_UIDNEXT next UID value to be assigned SA_UIDVALIDITY UID validity value Note that, depending upon implementation, some of these values may be more costly to get than others. For example, calculating the number of unseen messages may require opening the mailbox and scanning all of the message flags. A mail_status() call should thus be used with option flags specifying only the data that is actually needed. MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options); oldstream if non-NIL, stream to recycle name mailbox name to open options option flags. This function opens the mailbox and if successful returns a stream suitable for use by the other MAIL functions. If oldstream is non-NIL, an attempt is made to reuse oldstream as the stream for this mailbox; this is useful when you want to open another mailbox to the same IMAP or NNTP server without having to open a new connection. Doing this will close the previously open mailbox. The options are a bit mask with one or more of the following: OP_DEBUG Log IMAP protocol telemetry through mm_debug() OP_READONLY Open mailbox read-only. OP_ANONYMOUS Don't use or update a .newsrc file for news. OP_SHORTCACHE Don't cache envelopes or body structures OP_SILENT Don't pass mailbox events (internal use only) OP_PROTOTYPE Return the "prototype stream" for the driver associated with this mailbox instead of opening the stream OP_HALFOPEN For IMAP and NNTP names, open a connection to the server but don't open a mailbox. OP_EXPUNGE Silently expunge the oldstream before recycling NIL is returned if this function fails for any reason. MAILSTREAM *mail_close (MAILSTREAM *stream); MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options); stream stream to close options option flags This function closes the MAIL stream and frees all resources associated with it that it may have created (subject to any handles existing). The options for mail_close_full() are a bit mask with one or more of the following: CL_EXPUNGE Silently expunge before closing This function always returns NIL, so it can be used as: stream = mail_close (stream); Handle Functions Handles are used when an entity that wishes to access the stream may survive the stream without knowing that it outlived it. For example, an object reading a message may have a handle to a stream, but the message selection object that spawned it (and which owns the stream) may have gone away. A stream can be closed or recycled while handles are pointing at it, but it is not completely freed until all handles are gone. A stream may have an arbitrary number of handles. MAILHANDLE *mail_makehandle (MAILSTREAM *stream); stream stream to make handle to This function creates and returns a handle to the stream. void mail_free_handle (MAILHANDLE **handle); handle pointer to handle to release This function frees the handle and notifies the stream that it has one fewer handle. If this is the last handle on the stream and the stream has been closed, then the stream is freed. MAILSTREAM *mail_stream (MAILHANDLE *handle); handle handle to look up This function returns the stream associated with the handle if and only if the stream still represents the same MAIL connection associated with the handle. Otherwise, NIL is returned (meaning that there is no active stream associated with this handle). Message Data Fetching Functions [Note!! There is an important difference between a "sequence" and a "msgno". A sequence is a string representing one or more messages in IMAP4-style sequence format ("n", "n:m", or combination of these delimited by commas), whereas a msgno is an int representing a single message.] void mail_fetchfast (MAILSTREAM *stream,char *sequence); void mail_fetchfast_full (MAILSTREAM *stream,char *sequence,long flags); stream stream to fetch on sequence IMAP-format set of message sequence numbers flags option flags This function causes a cache load of all the "fast" information (internal date, RFC 822 size, and flags) for the given sequence. Since all this information is also fetched by mail_fetchstructure(), this function is generally not used unless the OP_SHORTCACHE option in the mail_open() call is used. The options for mail_fetchfast_full() are a bit mask with one or more of the following: FT_UID The sequence argument contains UIDs instead of sequence numbers void mail_fetchflags (MAILSTREAM *stream,char *sequence); void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags); This function causes a fetch of the flags for the given sequence. This main reason for using this function is to update the flags in the local cache in case some other process changed the flags (multiple simultaneous write access is allowed to the flags) as part of a "check entire mailbox" (as opposed to "check for new messages") operation. The options for mail_fetchflags_full() are a bit mask with one or more of the following: FT_UID The sequence argument contains UIDs instead of sequence numbers ENVELOPE *mail_fetchenvelope (MAILSTREAM *stream,unsigned long msgno); ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,unsigned long msgno, BODY **body); ENVELOPE *mail_fetchstructure_full (MAILSTREAM *stream,unsigned long msgno, BODY **body,long flags); stream stream to fetch on msgno message sequence number body pointer to where to return BODY structure if non-NIL flags option flags This function causes a fetch of all the structured information (envelope, internal date, RFC 822 size, flags, and body structure) for the given msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a parameter in IMAP2.H) subsequent messages which are not yet in the cache. No fetch is done if the envelope for the given msgno is already in the cache. The ENVELOPE and the BODY for this msgno is returned. It is possible for the BODY to be NIL, in which case no information is available about the structure of the message body. The options for mail_fetchstructure_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID This is the primary function for fetching non-text information about messages, and should be called before any attempt to reference cache information about this message via mail_elt(). char *mail_fetchheader (MAILSTREAM *stream,unsigned long msgno); char *mail_fetchheader_full (MAILSTREAM *stream,unsigned long msgno, STRINGLIST *lines,unsigned long *len,long flags); stream stream to fetch on msgno message sequence number lines list of header lines to fetch len returned length in octets flags option flags This function causes a fetch of the complete, unfiltered RFC 822 format header of the specified message as a text string and returns that text string. If the lines argument is non-NIL, it contains a list of header field names to use in subsetting the header text. Only those lines which have that header field name are returned, unless FT_NOT is set in which case only those lines which do not have that header field name are returned. If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string. This function always returns a valid string pointer; if no header exists or if it can not be fetched (e.g. by a deceased IMAP stream) an empty string is returned. The options for mail_fetchheader_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID FT_NOT The returned header lines are those that are not in the lines argument FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the same time. This avoids an extra RTT on an IMAP connection if a full message text is desired (e.g. in a "save to local file" operation) char *mail_fetchtext (MAILSTREAM *stream,unsigned long msgno); char *mail_fetchtext_full (MAILSTREAM *stream,unsigned long msgno, unsigned long *len,long flags); stream stream to fetch on msgno message sequence number len returned length in octets flags option flags This function causes a fetch of the non-header text of the specified message as a text string and returns that text string. No attempt is made to segregate individual body parts. If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string. This function always returns a valid string pointer; if no header exists or if it can not be fetched (e.g. by a deceased IMAP stream) an empty string is returned. The options for mail_fetchtext_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID FT_PEEK Do not set the \Seen flag if it not already set FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines char *mail_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *sec, unsigned long *len); char *mail_fetchbody_full (MAILSTREAM *stream,unsigned long msgno,char *sec, unsigned long *len,long flags); stream stream to fetch on msgno message sequence number sec section specifier len returned length in octets flags option flags This function causes a fetch of the particular section of the body of the specified message as a text string and returns that text string. The section specification is a string of integers delimited by period which index into a body part list as per the IMAP4 specification. Body parts are not decoded by this function; see rfc822_base64() and rfc822_quotedprintable(). If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string. This function may return NIL on error. The options for mail_fetchbody_full() are a bit mask with one or more of the following: FT_UID The msgno argument is a UID FT_PEEK Do not set the \Seen flag if it not already set FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno); stream stream to fetch on msgno message sequence number This function returns the UID for the given message sequence number. void mail_fetchfrom (char *s,MAILSTREAM *stream,unsigned long msgno, long length); s destination string stream stream to fetch on msgno message sequence number length maximum field length This function writes a "from" string of the specified length for the specified message, suitable for display to the user in a menu line, into the string pointed to by s. If the personal name of the first address in the envelope's from item is non-NIL, it is used; otherwise a string is created by appending the mailbox of the first address, an "@", and the host of the first address. The string is trimmed or padded with trailing spaces as necessary to make its length match the length argument. void mail_fetchsubject (char *s,MAILSTREAM *stream,unsigned long msgno, long length); s destination string stream stream to fetch on msgno message sequence number length maximum field length This function returns a "subject" string of the specified length for the specified message, suitable for display to the user in a menu line. The envelope's subject item is copied and trimmed as necessary to make its length be no more what the caller requested. Unlike mail_fetchfrom(), this function can return a string of shorter length than what the caller requested. LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno); MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno); stream stream to access msgno message sequence number This function returns the cache entry for the specified message. Although it will create a cache entry if it does not already exist, that functionality is for internal use only. This function should never be called without having first called mail_fetchfast() or mail_fetchstructure() on the message first. A cache entry holds the internal date/time, flags, and RFC 822 size of a message. It holds other data as well, but that is for internal use only. mail_lelt() is a variant that returns a `long' cache entry, which consists of an cache entry (as a structure, not a pointer), an envelope pointer, and a body pointer. This is used in conjunction with the elt lock count functionality, to allow an application to associate the cached envelope and body of a message with an open window even if the message is subsequently expunged or if the stream is closed. Unless your application wants to look at cached envelopes and bodies even after the message is expunged or the stream is closed, it should not use mail_lelt(). Instead, it should use a returned elt from mail_elt() and use the elt->msgsno as the argument to mail_fetchstructure(). BEWARE: the behavior of mail_lelt() is undefined if the stream is open with OP_SHORTCACHE. mail_lelt() is extremely special purpose, and should only be used in sophisticated special purpose applications after discussing its use with the c-client author. If you think you need this function, you are probably mistaken. In almost all cases, you should use mail_elt() and mail_fetchstructure() instead. Message Status Manipulation Functions void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag); void mail_setflag_full (MAILSTREAM *stream,char *sequence,char *flag, long flags); stream stream to use sequence IMAP-format set of message sequence numbers flag IMAP-format flag string flags option flags This function causes a store to add the specified flag to the flags set for the messages in the specified sequence. If there is any problem in setting flags, a message will be passed to the application via the mm_log() facility. The options for mail_setflag_full() are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers ST_SILENT Do not update the local cache with the new value of the flags. This is useful to save network bandwidth, at the cost of invalidating the cache. void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag); void mail_clearflag_full (MAILSTREAM *stream,char *sequence,char *flag, long flags); stream stream to use sequence IMAP-format set of message sequence numbers flag IMAP-format flag string flags option flags This function causes a store to delete the specified flag from the flags set for the messages in the specified sequence. If there is any problem in clearing flags, a message will be passed to the application via the mm_log() facility. The options for mail_setflag_full() are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers ST_SILENT Do not update the local cache with the new value of the flags. This is useful to save network bandwidth, at the cost of invalidating the cache. Mailbox Searching void mail_search (MAILSTREAM *stream,char *criteria); void mail_search_full (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, long flags); stream stream to search charset MIME character set to use when searching strings pgm search program flags option flags This function causes a mailbox search, using the given MIME charset (NIL means the default, US-ASCII) and the given search program. A search program is a structure that holds the following data: SEARCHSET *msgno; a set of message sequence numbers SEARCHSET *uid; a set of unique identifiers SEARCHOR *or; OR result of two search programs SEARCHPGMLIST *not; AND result of list of NOT'ed search programs SEARCHHEADER *header; message headers STRINGLIST *bcc; string(s) appear in bcc list STRINGLIST *body; string(s) appear in message body text STRINGLIST *cc; string(s) appear in cc list STRINGLIST *from; string(s) appear in from STRINGLIST *keyword; user flag string(s) set STRINGLIST *unkeyword; user flag strings() not set STRINGLIST *subject; string(s) appear in subject STRINGLIST *text; string(s) appear in message header or body STRINGLIST *to; string(s) appear in to list unsigned long larger; larger than this many octets unsigned long smaller; smaller than this many octes The following dates are in form: ((year - BASEYEAR) << 9) + (month << 5) + day unsigned short sentbefore; sent before this date unsigned short senton; sent on this date unsigned short sentsince; sent since this date unsigned short before; received before this date unsigned short on; received on this date unsigned short since; received since this date unsigned int answered : 1; message answered unsigned int unanswered : 1; message not answered unsigned int deleted : 1; message deleted unsigned int undeleted : 1; message not deleted unsigned int draft : 1; message is a draft unsigned int undraft : 1; message is not a draft unsigned int flagged : 1; message flagged as urgent unsigned int unflagged : 1; message not flagged as urgent unsigned int recent : 1; message recent since last parse of mailbox unsigned int old : 1; message not recent since last parse of mailbox unsigned int seen : 1; message read unsigned int unseen : 1; message not read The following auxillary structures are used by search programs: SEARCHHEADER: header line searching char *line; header line field name char *text; text header line SEARCHHEADER *next; next SEARCHHEADER in list (AND'ed) SEARCHSET: message number set unsigned long first; first number in set unsigned long last; if non-zero, last number in set SEARCHSET *next; next SEARCHSET in list (AND'ed) SEARCHOR: two search programs, OR'ed together SEARCHPGM *first; first program SEARCHPGM *second; second program SEARCHOR *next; next SEARCHOR in list SEARCHPGMLIST: list of search programs SEARCHPGM *pgm; search program (AND'd with others in list) SEARCHPGMLIST *next; next SEARCHPGM in list mail_search(), the older interface, accepts a search criteria argument as a character string in IMAP2 (RFC-1176) format. Do not try to use any IMAP4 search criteria with this interface. The application's mm_searched() function is called for each message that matches the search criteria. In addition, after the search is completed, the "fast" information (see mail_fetchfast_full() and envelopes of the searched messages are fetched (this is called pre-fetching). If there is any problem in searching, a message will be passed to the application via the mm_log() facility. The flags for mail_search_full() are a bit mask with one or more of the following: SE_UID Return UIDs instead of sequence numbers SE_FREE Return the search program to free storage after finishing SE_NOPREFETCH Don't prefetch searched messages. unsigned long *mail_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, SORTPGM *pgm,long flags); stream stream to sort charset MIME character set to use when sorting strings spg search program pgm sort program flags option flags This function is a variant of mail_search_full(). It accepts an additional argument, a sort program, which specifies one or more sort rules to be applied to the result. If the searching and sorting are successful, it returns a 0-terminated vector of message sequence numbers (or UIDs if SE_UID is set). This vector is created out of free storage, and must be freed with fs_give() when finished with it. A sort program is a structure that holds the following data: unsigned int reverse : 1; reverse sorting of this key short function; sort rule, one of the following: SORTDATE message Date SORTARRIVAL arrival date SORTFROM mailbox in first From address SORTSUBJECT message Subject SORTTO mailbox in first To address SORTCC mailbox in first cc address SORTSIZE size of message in octets SORTPGM *next; next sort program to be applied if two or more messages collate identically with this rule The flags for mail_search_full() are a bit mask with one or more of the following: SE_UID Return UIDs instead of sequence numbers SE_FREE Return the search program to free storage after finishing SE_NOPREFETCH Don't prefetch searched messages. SO_FREE Return the sort program to free storage after finishing Miscellaneous Mailbox and Message Functions long mail_ping (MAILSTREAM *stream); stream string to ping The function pings the stream to see if it is still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have an inactivity timeout. It returns T if the stream is still alive, NIL otherwise. If new mail is found, the application's mm_exists() function is called with the newly-determined number of messages in the mailbox. void mail_check (MAILSTREAM *stream); stream stream to checkpoint This function causes a mailstore-defined checkpoint of the mailbox. This may include such things as a writeback to disk, a check for flag changes in a shared mailbox, etc. It is not a "check for new mail"; mail_ping() performs this function (as potentially does any other function). The status of the check is passed to the application via the mm_log() facility. void mail_expunge (MAILSTREAM *stream); stream string to expunge This function causes an expunge (permanent removal of messages which are marked as deleted) of the mailbox. The application's mm_expunged() function is called for each message that has been expunged. The application's mm_exists() function is called at the start and end of the expunge to ensure synchronization. The status of the expunge is passed to the application via the mm_log() facility. Note that the decrementing of msgno's for subsequent messages happens immediately; for example, if three consequtive messages starting at msgno 5 are expunged, mm_expunged() will be called with a msgno of 5 three times. long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox); long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox); long mail_copy_full (MAILSTREAM *stream,char *sequence,char *mailbox, long options); stream stream to copy sequence IMAP-format set of message numbers mailbox destination mailbox name options option flags This function causes the messages in the specified sequence to be copied to the specified mailbox. T is returned if the copy is successful. mail_move() is equivalent to setting CP_MOVE in the options. If there is any problem in copying, a message will be passed to the application via the mm_log() facility and the function returns NIL. No copying is actually done in this case. Note that the mailbox must be on the same host as the stream and is a mailbox of the type of the source mailbox only. The flags for mail_search_full() are a bit mask with one or more of the following: CP_UID The sequence argument contains UIDs instead of sequence numbers CP_MOVE Delete the messages from the current mailbox after copying to the destination. long mail_append (MAILSTREAM *stream,char *mailbox,STRING *message); long mail_append_full (MAILSTREAM *stream,char *mailbox,char *flags,char *date, STRING *message); stream stream to use if non-NIL (in the IMAP case) mailbox destination mailbox name flags flags to set on message if non-NIL date internal date (received date) to set on message if non-NIL message string structure of message to write This function writes the message in the string structure to the destination mailbox, along with the flags and date if specified. This is useful in those cases where you can't use mail_copy(), e.g. when copying from one server to another; you can always fetch the message and then mail_append() it to the destination. It may also be useful for maintaining an outbox of your outgoing mail. void mail_gc (MAILSTREAM *stream,long gcflags); stream stream to GC if non-NIL (else GC's all streams) flags option flags This function garbage collects (purges) the cache of entries of a specific type. Some drivers do not allow purging of particular cache types, and an attempt to do so is ignored. The flags for mail_gc() are a bit mask with one or more of the following: GC_ELT message cache elements GC_ENV ENVELOPEs and BODYs GC_TEXTS cached texts Date/Time Handling Functions char *mail_date (char *string,MESSAGECACHE *elt); string destination string elt message cache element containing date This function accepts a message cache element that contains date information, and writes an IMAP-4 date string, that is, one in form: dd-mmm-yyyy hh:mm:ss +zzzz based upon the data in the elt. The destination string must be large enough to hold this string. char *mail_cdate (char *string,MESSAGECACHE *elt); string destination string elt message cache element containing date This function accepts a message cache element that contains date information, and writes a ctime() format date string, that is, one in form: www mmm dd hh:mm:ss yyyy\n based upon the data in the elt. The destination string must be large enough to hold this string. long mail_parse_date (MESSAGECACHE *elt,char *string); elt message cache element to store parsed date string source date string This function parses the date/time stored in the given string, in format: [www,] date [[hh:mm[:ss][-zzz| +zzzz] where the date can be any of: mm/dd/yy, mm/dd/yyyy, dd-mmm-yy, dd-mmm-yyyy, dd mmm yy, dd mmm yyyy and stores the result of the parse in the elt. If the parse is successful, T is returned, else NIL. unsigned long mail_longdate (MESSAGECACHE *elt); elt message cache element containing date. This function accepts a message cache element that contains date information, and returns the number of days since the base time of the imap-4 toolkit. At present, this is the same as the Unix time() value for that date/time, and hence can be used for functions such as utime(). Utility Functions void mail_debug (MAILSTREAM *stream); stream stream to debug This function enables telemetry logging for this stream. All telemetry is passed to the application via the mm_dlog() facility. void mail_nodebug (MAILSTREAM *stream); stream stream to disable debugging This function disables telemetry logging for this stream. long mail_sequence (MAILSTREAM *stream,char *sequence); stream stream to set the sequence bits sequence IMAP-format message set string This function parses the given sequence string for message numbers, sets the sequence bit in the stream's message cache element of all messages in the sequence (and turns it off in all other message cache elements). If the parse is successful, T is returned, else NIL. long mail_uid_sequence (MAILSTREAM *stream,char *sequence); stream stream to set the sequence bits sequence IMAP-format message set string This function parses the given sequence string for unique identifiers, sets the sequence bit in the stream's message cache element of all messages in the sequence (and turns it off in all other message cache elements). If the parse is successful, T is returned, else NIL. long mail_parse_flags (MAILSTREAM *stream,char *flag,unsigned long *uf); stream stream (used to get user flags) flag IMAP-format flag string to parse uf returned location of user flags The function parses the given flag string, and returns the system flags as its return value and the user flags in the location pointed to by the uf argument. If there is an error in parse, a log message is issued via mm_log() and this function returns NIL. unsigned long mail_filter (char *text,unsigned long len,STRINGLIST *lines, long flags); text RFC 822 text to filter len length in octets in the text argument lines string list of header file names to filter flags option flags This function supports the header lines filtering function of mail_fetchheader_full(). The lines argument contains a list of header field names to use in subsetting the header text. Only those lines which have that header field name are returned, unless FT_NOT is set in which case only those lines which do not have that header field name are returned. The options for mail_filter() are a bit mask with one or more of the following: FT_NOT The returned header lines are those that are not in the lines argument long mail_search_msg (MAILSTREAM *stream,unsigned long msgno,char *charset, SEARCHPGM *pgm); stream stream to search msgno message number of message to inspect charset character set of search strings pgm search program to test This function implements mail_search_full() locally in cases when it is not done by a server (e.g. local mail files, NNTP/POP). It inspects the given message on that stream to see if it matches the criteria or not. If it matches, T is returned, else NIL. SEARCHPGM *mail_criteria (char *criteria); criteria IMAP2-format search criteria string This function accepts an IMAP2-format search criteria string and parses it. If the parse is successful, it returns a search program suitable for use in mail_search_full(). WARNING: This function does not accept IMAP4 search criteria. The source string must be writeable (this restriction was also in the old IMAP2 c-client). Data Structure Instantiation/Destruction functions These functions are used to obtain structures from free storage and to release them. ENVELOPE *mail_newenvelope (void); ADDRESS *mail_newaddr (void); BODY *mail_newbody (void); BODY *mail_initbody (BODY *body); PARAMETER *mail_newbody_parameter (void); PART *mail_newbody_part (void); STRINGLIST *mail_newstringlist (void); SEARCHPGM *mail_newsearchpgm (void); SEARCHHEADER *mail_newsearchheader (char *line); SEARCHSET *mail_newsearchset (void); SEARCHOR *mail_newsearchor (void); SEARCHPGMLIST *mail_newsearchpgmlist (void); SORTPGM *mail_newsortpgm (void); These functions, all named mail_new...(), create a new structure of the given type and initialize all of its elements to zero or empty. void mail_free_body (BODY **body); void mail_free_body_parameter (PARAMETER **parameter); void mail_free_body_part (PART **part); void mail_free_cache (MAILSTREAM *stream); void mail_free_elt (MESSAGECACHE **elt); void mail_free_lelt (LONGCACHE **lelt); void mail_free_envelope (ENVELOPE **env); void mail_free_address (ADDRESS **address); void mail_free_stringlist (STRINGLIST **string); void mail_free_searchpgm (SEARCHPGM **pgm); void mail_free_searchheader (SEARCHHEADER **hdr); void mail_free_searchset (SEARCHSET **set); void mail_free_searchor (SEARCHOR **orl); void mail_free_searchpgmlist (SEARCHPGMLIST **pgl); void mail_free_sortpgm (SORTPGM **pgm); These functions, all named mail_free_...(), take a pointer to a structure pointer, free all contained strings and structures within the structure, and finally free the structure itself and set its pointer to NIL. For example, mail_free_envelope() frees all the ADDRESS structures contained in the envelope. Normally, mail_free_elt() and mail_free_lelt() are used only if the main program has a private pointer to cache elements. If so, it is expected to increment the cache element's lockcount when it makes a private pointer, and to call this function when it is finished with it. Authentication Functions char *mail_auth (char *mechanism,authresponse_t resp,int argc,char *argv[]); mechanism authentication mechanism name resp callback function for providing responses argc main() function argc value argv main() function argv value This server function searches the list of authenticators that was established by auth_link() for an authenticator with the given name. If an authenticator is found, authentication is initialized. The function pointed to by resp is called as the authenticator requires responses. AUTHENTICATOR *mail_lookup_auth (unsigned int i); i position in authenticator list This function returns the nth authenticator in the list, where n is the value of it. unsigned int mail_lookup_auth_name (char *mechanism); mechanism authentication mechanism name This function searches the list of authenticators for an authenticator with the given name, and returns its position in the authenticator list. The functions below are provided by c-client client drivers or by servers to support the protocol-dependent parts of authentication. typedef void *(*authchallenge_t) (void *stream,unsigned long *len); stream stream to read challenge len pointer to returned length in octets This driver function is called by an authenticator to read a challenge from the given protocol stream in a protocol-dependent way. It returns that challenge in binary and its length in octets to the authenticator. typedef long (*authrespond_t) (void *stream,char *s,unsigned long size); stream stream to send response s response string size length of response string in octets This driver function is called by an authenticator to send a challenge response to the given stream in a protocol-dependent way. It returns T if successful, NIL if failure. typedef char *(*authresponse_t) (void *challenge,unsigned long clen, unsigned long *rlen); challenge challenge string clen length of challenge string in octets rlen pointer to returned length of response string This server function is called with a challenge string of clen octets. It sends, according to whatever protocol (IMAP, POP, etc.) it uses, and returns the received response and response length in octets. typedef long (*authclient_t) (authchallenge_t challenger, authrespond_t responder,NETMBX *mb,void *s, unsigned long trial); challenger pointer to protocol-dependent challenge reader function responder pointer to protocol-dependent response sender function mb NETMBX struct of the mailbox desired to open s stream for protocol-dependent routines to use trial number of authentication attempts remaining This client authenticator function negotiates reading challenges and sending responses for a particular authenticator (Kerberos, etc.) over the protocol, and returns T if authenticated or NIL if failed. typedef char *(*authserver_t) (authresponse_t responder,int argc,char *argv[]); responder pointer to protocol-dependent responder function argc main() function argc value argv main() function argv value This server authenticator function negotiates sending challenges and reading responses for a particular authenticator (Kerberos, etc.), and returns either the authenticated user name or NIL if authentication failed. Network Access Functions These functions provide a layer of indirection between the TCP routines and upper level routines. This makes it possible to insert additional code (e.g. privacy or checksum handling). NETSTREAM *net_open (char *host,char *service,unsigned long port); host host name service contact service name port contact port number This function opens a TCP connection to the given host and service or port. NETSTREAM *net_aopen (NETMBX *mb,char *service,char *usrbuf); NETMBX parsed mailbox specification service stream to open (at present, only /etc/rimapd is used) usrbuf buffer to return login user name This function attempts to open a preauthenticated connection to the given mailbox and service. It will return the login user name of the preauthenticated connection, as well as an open network stream, if successful. char *net_getline (NETSTREAM *stream); stream network stream to read This routine reads a text line from the stream. It calls stream->dtb->getline, which normally points to tcp_getline() but can be set to some other function. long net_getbuffer (void *stream,unsigned long size,char *buffer); stream network stream to read size length of data in octets buffer buffer of at least size octets This routine reads data from the stream. It calls stream->dtb->getbuffer, which normally points to tcp_getbuffer() but can be set to some other function. long net_soutr (NETSTREAM *stream,char *string); stream network stream to write string null-terminated string to output This routine writes a null-terminated string to the stream. It calls stream->dtb->soutr, which normally points to tcp_soutr() but can be set to some other function. long net_sout (NETSTREAM *stream,char *string,unsigned long size); stream network stream to write string string to output size length of string in octets This routine writes a string of length size to the stream. It calls stream->dtb->sout, which normally points to tcp_sout() but can be set to some other function. void net_close (NETSTREAM *stream); stream stream to close This routine closes the stream. It calls stream->dtb->close, which normally points to tcp_close() but can point to some other function. char *net_host (NETSTREAM *stream); stream stream to inspect This routine returns the remote host name of the stream. It calls stream->dtb->host, which normally points to tcp_host() but can point to some other function. unsigned long net_port (NETSTREAM *stream); stream stream to inspect This routine returns the remote port number of the stream. It calls stream->dtb->port, which normally points to tcp_port() but can point to some other function. char *net_localhost (NETSTREAM *stream); stream stream to inspect This routine returns the local host name of the stream. It calls stream->dtb->localhost, which normally points to tcp_localhost() but can point to some other function. Subscription Management Functions long sm_subscribe (char *mailbox); mailbox mailbox name to subscribe This function adds the given mailbox name to the local subscription list, and returns T if successful, NIL if failure. long sm_unsubscribe (char *mailbox); mailbox mailbox name to unsubscribe This function removes the given mailbox name from the local subscription list, and returns T if successful, NIL if failure. char *sm_read (void **sdb); sdb data to use in subsequent calls, or NIL if first call This function returns the local subscription list as null terminated strings. Each call returns the next element in the list. The first call should be with sdb pointing to a NIL pointer; this will be filled in for subsequent calls. At the last call, NIL will be returned. Miscellaneous Utility Functions char *ucase (char *string); string string to convert This function converts each lowercase character of the specified string to uppercase and returns the string. char *lcase (char *string); string string to convert This function converts each uppercase character of the specified string to lowercase and returns the string. char *cpystr (char *string); string string to copy This function makes a copy of the string from free storage and returns the copy. long find_rightmost_bit (long *valptr); valptr pointer to value to search This function returns -1 if the 32-bit value pointed to by valptr is non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of the right-most bit in that value. This is used to convert from the bits in the cache's userflags item to an index into the stream's userFlags array of flag texts. long min (long i,long j); i first argument j second argument This function returns the minimum of the two integers. long max (long i,long j); i first argument j second argument This function returns the maximum of the two integers. long search (char *s,long c,char *pat,long patc); s string to search c size of string pat pattern to search in string patc size of pattern This function does a fast case-independent search for the given pattern in pat (length patc) in base string s, and returns T if the pattern is found in the string. long pmatch (char *s,char *pat,delim); long pmatch_full (char *s,char *pat,delim); s string to match pat wildcard (* and %) to match in pattern delim hierarchy delimiter This function returns T if the given wildcard pattern matches the string in s with hierarchy delimiter delim. Otherwise NIL is returned. long dmatch (char *s,char *pat,char delim); s string to match pat wildcard (* and %) to match in pattern delim hierarchy delimiter This function returns T if the given wildcard pattern matches the directory. If not, then none of the elements in the directory are considered for recursive checking with pmatch_full(). SMTP Functions SMTPSTREAM *smtp_open (char **hostlist,long debug); hostlist vector of SMTP server host names to try debug non-zero if want protocol telemetry debugging This function opens an SMTP connection to a one of the hosts in the host list and if successful returns a stream suitable for use by the other SMTP functions. The hosts are tried in order until a connection is successfully opened. If debug is non-NIL, protocol telemetry is logged via mm_dlog(). NIL is returned if this function fails to open a connection to any of the hosts in the list. void smtp_close (SMTPSTREAM *stream); stream stream to close This function closes the SMTP stream and frees all resources associated with it that it may have created. long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body); stream stream to transmit mail type mail type (MAIL, SEND, SAML, SOML) msg message envelope body message body This function negotiates an SMTP transaction of the specified type (one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified message. This function returns T if success or NIL if there is any failure. The text reason for the failure is in stream->reply item; if it is associated with a recipient it is also in that address' address->error item. void smtp_debug (SMTPSTREAM *stream); stream stream to enable debugging telemetry This function enables SMTP protocol telemetry logging for this stream. All SMTP protocol operations are passed to the application via the mm_dlog() facility. void smtp_nodebug (SMTPSTREAM *stream); stream stream to disable debugging telemetry This function disables SMTP protocol telemetry logging for this stream. typedef void (*smtpverbose_t) (char *buffer); buffer pointer to verbose reply buffer This is the argument to the SET_SMTPVERBOSE mail_parmameter() call. If this function pointer is non-NIL, then if a verbose SMTP response (with SMTP code less than 100) is received, this function is called with that response text as its argument. NNTP Functions NNTPSTREAM *nntp_open (char **hostlist,long debug); hostlist vector of NNTP server host names to try debug non-zero if want protocol telemetry debugging This function opens an NNTP connection to a one of the hosts in the host list and if successful returns a stream suitable for use by the other MTP functions. The hosts are tried in order until a connection is successfully opened. If debug is non-NIL, protocol telemetry is logged via mm_dlog(). NIL is returned if this function fails to open a connection to any of the hosts in the list. void nntp_close (NNTPSTREAM *stream); stream stream to close This function closes the NNTP stream and frees all resources associated with it that it may have created. long nntp_mail (NNTPSTREAM *stream,ENVELOPE *msg,BODY *body); stream stream to transmit mail msg message envelope body message body This function negotiates an NNTP posting transaction to deliver the specified news message. This function returns T if success or NIL if there is any failure. The text reason for the failure is in stream->reply item; if it is associated with a recipient it is also in that address' address->error item. RFC 822 Support Functions Although rfc822.c contains several additional functions besides these, only the functions documented here should be used by applications. The other functions are for internal use only. void rfc822_header (char *header,ENVELOPE *env,BODY *body); header buffer to write RFC 822 header env message ENVELOPE (used to obtain RFC 822 information) body message BODY (used to obtain MIME information) This function writes an RFC 822 format header into header based on the information in the envelope and body. The header buffer must be large enough to contain the full text of the resulting header. void rfc822_write_address (char *dest,ADDRESS *adr); dest buffer to write address list adr RFC 822 ADDRESS list This function writes an RFC 822 format address list into dest based on the information in adr. The dest buffer must be large enough to contain the full text of the resulting address list. void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i, STRING *b,char *host,char *tmp); en destination pointer where message ENVELOPE will be stored bdy destination pointer where message BODY will be stored s RFC 822 header to parse (character string) i length of RFC 822 header b stringstruct of message body host default host name if an address lacks an @host. temp scratch buffer, must be long enough to hold unwound header lines (a buffer that is i octets long is OK) This function parses the RFC 822 header pointed to by s with body pointed to by string structure b into the specified destination envelope and body pointers, using host as the default host name and tmp as a scratch buffer. New ENVELOPE and BODY structures are created; when finished with them the application must free them with mail_free_envelope() and mail_free_body(). Any parsing errors are noted via the mm_log() mechanism using log type PARSE. void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host); lst destination pointer where ADDRESS will be stored string string of addresses to parse host default host name if an address lacks an @host. This function parses the address list in the given string into an address list in lst. Any addresses missing a host name are have the host name defaulted from the host argument. If the destination list is non-empty it appends the new addresses to the list. Any parsing errors are noted via the mm_log() mechanism using log type PARSE. long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,void *s, long ok8bit); t scratch buffer, large enough to hold message header env message ENVELOPE body message BODY f I/O function to write to s stream for I/O function f ok8bit non-zero if OK to output 8-bit data This function writes the message described with the given envelope and body. Any body part contents of type ENCBINARY is converted to ENCBASE64 before sending. If ok8bit is NIL, any message data of type ENC8BIT is converted to ENCQUOTEDPRINTABLE before sending; if ok8bit is non-NIL then ENC8BIT data is sent as-is. T is returned if the function succeeds, else NIL is returned. The function f is typically net_soutr(), but it can be any function which matches typedef long (*soutr_t) (void *stream,char *string); where stream holds sufficient information to enable the output routine to know where to output to, and the string is a null-terminated string to output. This function returns either T or NIL, and that value is passed up to rfc822_output() for its return. void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len); src source string srcl size of source string in octets len pointer to where destination string length in octets will be returned This function decodes a BASE64 body part given a source string and its length. The decoded body part as a sequence of binary octets is returned, and its length is returned in len. char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len); src source string srcl size of source string in octets len pointer to where destination string length in octets will be returned This function decodes a QUOTED-PRINTABLE body part given a source string and its length. The decoded body part as an 8-bit character string is returned, and its length is returned in len. Operating System-Dependent Public Interface These functions are in OS-dependent code, and are rewritten each time c-client is ported to a new operating system. void rfc822_date (char *date); date buffer to write the date, must be large enough This function is called to get the current date and time in an RFC 822 format string into the given buffer. void *fs_get (size_t size); size number of octets requested This function allocates and returns a block of free storage of the specified size. Unlike malloc(), there is no failure return; this function must return with the requested storage. void fs_resize (void **block,size_t size); block pointer to pointer to block to be resized size new size in octets This function resizes the free storage block, updating the pointer if necessary. Unlike realloc(), there is no failure return; this function must return with the requested storage. void fs_give (void **block); block pointer to pointer to block to free This function releases a block of free storage allocated by fs_get(). It also erases the block pointer, so it isn't necessary to do this in the application. void fatal (char *string); string message string This function is called when an "impossible" error is detected and the client wishes to crash. The string should contain a reason. char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl); dst pointer to destination string pointer dstl pointer to destination string size src source strin srcl source string size This function is called to copy into a destination string dst of size dstl (resized if necessary), a CRLF newline form string from local format string src of size srcl. TCPSTREAM *tcp_open (char *host,long port); TCPSTREAM *tcp_aopen (char *host,char *service); char *tcp_getline (TCPSTREAM *stream); long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer); long tcp_soutr (TCPSTREAM *stream,char *string); void tcp_close (TCPSTREAM *stream); char *tcp_host (TCPSTREAM *stream); unsigned long tcp_port (TCPSTREAM *stream); char *tcp_localhost (TCPSTREAM *stream); These functions are TCP-specific versions of the more general net_xxx() functions. These should not be called directly by applications. char *tcp_clienthost (char *dst); dst destination string buffer This function should be called only by a server called by inetd or similar mechanism which maps standard input to a network socket. It returns the host name of the other end (e.g. the client of a server) using the given string buffer, or NIL if it can't get this information. Main Program Callbacks All applications which use the c-client must have the following callbacks to handle events from c-client. Note that in any callback which involves a mail stream, the stream is locked and you can not recursively call c-client from the callback. This may also be true in callbacks which do not have a stream; in general, the rule is "do not call c-client, especially any mail_xxx() function, from a c-client callback". void mm_flags (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called when c-client manipulates the flags for the given message number. This alerts the application that it may need to inspect that message's flags to see if there are any interesting changes. void mm_status (MAILSTREAM *stream,char *mailbox,MAILSTATUS *status); stream stream where event happened mailbox mailbox name for this status status MAILSTATUS structure with message status This function is called when c-client reports status of a mailbox (generally as the result of a mail_status() function call). The returned MAILSTATUS structure has the following members: long flags; validity flags. These are the same as the SA_xxx option flags in the mail_status() call, and they indicate which of the other members of the MAILSTATUS structure have usable data (i.e. if SA_MESSAGES is not set, do not believe status->messages!!). unsigned long messages; number of messages if SA_MESSAGES unsigned long recent; number of recent messages if SA_RECENT unsigned long unseen; number of unseen messages if SA_UNSEEN unsigned long uidnext; next UID to be assigned if SA_UIDNEXT unsigned long uidvalidity; UID validity value if SA_UIDVALIDITY void mm_searched (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that this message number matches a search (generally as the result of a mail_search_full() function call). void mm_exists (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that there are this many messages in the mailbox. It is also used to notify the main program of new mail, by announcing a higher number than the main program was previously aware. void mm_expunged (MAILSTREAM *stream,unsigned long number); stream stream where event happened number message number This function is called to notify the main program that this message number has been expunged from the mail file and that all subsequent messages are now referenced by a message number one less than before. This implicitly decrements the number of messages in the mailbox. void mm_list (MAILSTREAM *stream,char delim,char *name,long attrib); stream stream where event happened delim hierarchy delimiter name mailbox name attrib mailbox attributes This function is called to notify the main program that this mailbox name matches a mailbox listing request (generally as the result of a mail_list() function call). The hierarchy delimiter is a character that separates out levels of hierarchy in mailbox names. The attributes are a bit mask with one of the following: LATT_NOINFERIORS it is not possible for there to be any hierarchy inferiors to this name (that is, this name followed by the hierarchy delimiter and additional name characters). LATT_NOSELECT this is not a mailbox name, just a hierarchy level, and it may not be opened by mail_open() LATT_MARKED this mailbox may have recent messages LATT_UNMARKED this mailbox does not have any recent messages void mm_lsub (MAILSTREAM *stream,char delim,char *name,long attrib); stream stream where event happened delim hierarchy delimiter name mailbox name attrib mailbox attributes This function is called to notify the main program that this mailbox name matches a subscribed mailbox listing request (generally as the result of a mail_lsub() function call). The hierarchy delimiter is a character that separates out levels of hierarchy in mailbox names. The attributes are a bit mask with one of the following: LATT_NOINFERIORS it is not possible for there to be any hierarchy inferiors to this name (that is, this name followed by the hierarchy delimiter and additional name characters). LATT_NOSELECT this is not a mailbox name, just a hierarchy level, and it may not be opened by mail_open() LATT_MARKED this mailbox may have recent messages LATT_UNMARKED this mailbox does not have any recent messages void mm_notify (MAILSTREAM *stream,char *string,long errflg); stream stream where event happened string message string errflg message error level This function is called to deliver a stream-oriented message event. This is the mechanism by which any IMAP response codes for any application (e.g. TRYCREATE) are delivered to the application. No newline is included in the string, so this function has to output its own. The message error level is one of the following: NIL normal operation. The text is `babble' that may be interesting to the user, e.g. the greeting message from a server. WARN A warning event. This event should be displayed to the user. Examples: a mailbox rewrite failed because of disk full, but the previous mailbox contents were recovered. ERROR An error event. This event should be displayed to the user, or at least logged someplace. This type of error shouldn't happen, and so should be called to the attention of support staff. Whatever happened has probably disrupted the user's work. Examples: an untagged BAD from an IMAP server. void mm_log (char *string,long errflg); string message string errflg message error level This function is called to deliver a log message. No newline is included in the string, so this function has to output its own. In general, it is intended that these messages are logged someplace, and possibly shown to the user. The message error level is one of the following: NIL normal operation. The text is `babble' that may be interesting to the user, e.g. "Expunged 3 messages". PARSE An RFC 822 parsing error. Since bogus headers are all-too-common in the real world, these can often be ignored on the "garbage in, garbage out" princple. However, since surprising results can be yielded when trying to parse garbage, this message should be logged somewhere so it can be figured out what happened. WARN A warning event. This event should be displayed to the user. It occurs when an error condition has happened, but c-client knows what to do to recover. Examples: "Can't open read-write, so opening read-only", "Empty mailbox", "Login failed, try again", "Waiting for mailbox to become unlocked", "IMAP protocol error". Although a user should be told about a warning, it's generally not necessary to interrupt the flow of her work (e.g. it's alright to display the warning in a scrolling window, but not necessary to require the user to do anything). ERROR An error event. This event should be displayed to the user, or at least logged someplace. This is a serious error condition occured that aborted the requested operation and possibly also aborted the mail stream. This ranges from normal error conditions such as "Can't open mailbox", "too many login failures, go away" to bizarre conditions such as "Apparent new mail appeared in the mailbox that doesn't look like mail, program aborting". Errors must be called to the user's attention, and probably should require some sort of acknowledgement (e.g. answering a modal panel) before the application proceeds. void mm_dlog (char *string); string message string This function is called to deliver a debugging telemetry message. No newline is included in the string, so this function has to output its own. This is called only when debugging is enabled. void mm_login (NETMBX *mb,char *user,char *pwd,long trial); mb parsed mailbox specification user pointer to where to return user name pwd pointer to where to return password trial number of prior login attempts This function is called to get a user name and password for the given network mailbox. It stores the user name and password in the strings pointed to by the appropriate arguments. The trial argument is the number of attempts to perform the login and is initially zero (e.g. for a default username and password login functionality). It is incremented for each subsequent trial until the maximum number of trials are made. void mm_critical (MAILSTREAM *stream); stream stream where event happened This function is called to alert the application that c-client is about to run some critical code on that stream that may result in a clobbered mail file if it is interrupted. It may be desirable to disable CTRL/C, etc. during this time. void mm_nocritical (MAILSTREAM *stream); stream stream where event happened This function is called to alert the application that c-client is no longer running critical code on that stream that may result in a clobbered mail file if it is interrupted. long mm_diskerror (MAILSTREAM *stream,long errcode,long serious); stream stream where event happened errcode OS error code for disk error serious non-zero if c-client can not undo the operation (and thus must retry to avoid mail file damage) This function is called to alert the application that the c-client has encountered an unrecoverable write error when trying to update the mail file. errcode contains the system error code. If serious is non-zero, then it is probable that the disk copy of the mailbox has been damaged. The return value from this function is the abort flag; if serious is zero and the abort flag is non-zero, the operation is aborted. If the abort flag is zero or if serious was non-zero, a return from this function will retry the failing operation. void mm_fatal (char *string); string message string This function is called from the fatal() routine in the operating system code to notify the main program that it is about to crash. The string contains a reason. At the very minimum, the main program should do something like mm_log (string,ERROR); and then return. No newline is included in the string, so this function has to output its own. Driver interface When writing a new driver for the c-client, you must provide a DRIVER stucture giving a dispatch vector between MAIL and the driver. The DRIVER dispatch vector is described in mail.h. char *name; Name by which the driver is known to c-client. unsigned long flags; Attribute flags for this driver: DR_DISABLE This driver is currently disabled. DR_LOCAL This driver deals with local mailboxes; if this is off it deals with mailboxes over a network. DR_MAIL This driver supports e-mail messages. DR_NEWS This driver supports netnews messages DR_READONLY This driver only allows read-only access; mail_setflag(), mail_expunge(), etc. are no-ops. DR_NOFAST This driver does not implement mail_fetchfast() in a fast way (e.g. it may have to fetch the entire message text over a network to calculate sizes). DR_NAMESPACE This driver accepts and uses namespace format names. DR_LOWMEM This driver is designed for systems with very limited amounts of memory (e.g. DOS) and support routines called by this driver should try not to use much memory. DRIVER *next; Pointer to the next driver which this application supports (or NIL if this is the last driver). Drivers are lunk together via the mail_link() function. DRIVER *driver_valid (char *mailbox); This function returns a pointer to the driver's DRIVER dispatch vector iff this driver accepts the given name as a valid mailbox for this driver. Otherwise, it returns the value of the next driver's driver_valid() or NIL if there is no next driver. In other words, calling driver_valid() for the first driver will return the driver dispatch vector for the driver which supports this type of mailbox. void *driver_parameters (long function,void *value); This function implements mail_parameters() for this driver. void driver_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); This function implements mail_scan() for this driver. void driver_list (MAILSTREAM *stream,char *ref,char *pat); This function implements mail_list() for this driver. void driver_lsub (MAILSTREAM *stream,char *ref,char *pat); This function implements mail_lsub() for this driver. long driver_subscribe (MAILSTREAM *stream,char *mailbox); This function implements mail_subscribe() for this driver. long driver_unsubscribe (MAILSTREAM *stream,char *mailbox); This function implements mail_unsubscribe() for this driver. long driver_create (MAILSTREAM *stream,char *mailbox); This function implements mail_create() for this driver. long driver_delete (MAILSTREAM *stream,char *mailbox); This function implements mail_delete() for this driver. long driver_rename (MAILSTREAM *stream,char *old,char *new); This function implements mail_rename() for this driver. long driver_status (MAILSTREAM *stream,char *mailbox,long flags); This function implements mail_status() for this driver. MAILSTREAM *driver_open (MAILSTREAM *stream); This function opens the mailbox identified by the given stream. It may use the data on the stream and create additional data on stream->local as necessary. It should return the given stream unless it failed to open the mailbox, in which case it should return NIL. void driver_close (MAILSTREAM *stream,long options); This function implements mail_close() for this driver. void driver_fetchfast (MAILSTREAM *stream,char *sequence,long flags); This function implements mail_fetchfast() for this driver. void driver_fetchflags (MAILSTREAM *stream,char *sequence,long flags); This function implements mail_fetchflags() for this driver. ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,unsigned long msgno, BODY **body,long flags); This function implements mail_fetchstructure() for this driver. char *driver_fetchheader (MAILSTREAM *stream,unsigned long msgno, STRINGLIST *lines,unsigned long *len,long flags); This function implements mail_fetchheader() for this driver. char *driver_fetchtext (MAILSTREAM *stream,unsigned long msgno, unsigned long *len,long flags); This function implements mail_fetchtext() for this driver. char *driver_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *section, unsigned long *len,long flags); This function implements mail_fetchbody() for this driver. void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag,long flags); This function implements mail_setflag() for this driver. void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag, long flags); This function implements mail_clearflag() for this driver. void driver_search (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, long flags); This function implements mail_search() for this driver. unsigned long *driver_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, SORTPGM *pgm,long flags); This function implements mail_sort() for this driver. void *driver_thread (MAILSTREAM *stream,char *seq,long function,long flag); This dispatch is reserved for a future threading capability. long driver_ping (MAILSTREAM *stream); This function implements mail_ping() for this driver. void driver_check (MAILSTREAM *stream); This function implements mail_check() for this driver. void driver_expunge (MAILSTREAM *stream); This function implements mail_expunge() for this driver. long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox, long options); This function implements mail_copy() for this driver. long driver_append (MAILSTREAM *stream,char *mailbox,char *flags,char *date, STRING *message); This function implements mail_append() for this driver. void driver_gc (MAILSTREAM *stream,long gcflags); This function implements mail_gc() for this driver. Driver Support Functions void mail_searched (MAILSTREAM *stream,unsigned long msgno); stream stream where event happened msgno message number This function is called by the driver to notify c-client that this message number matches a search. It invokes the main program's mm_searched() function. void mail_exists (MAILSTREAM *stream,unsigned long nmsgs); stream stream where event happened nmsgs number of messages This function is called by the driver to notify c-client that this message number exists (i.e. there are this many messages in the mailbox). It invokes the main program's mm_exists() function. void mail_recent (MAILSTREAM *stream,unsigned long recent); stream stream where event happened recent number of messages This function is called by the driver to notify c-client that this many messages are "recent" (i.e. arrived in the mailbox since the previous time the mailbox was opened). void mail_expunged (MAILSTREAM *stream,unsigned long msgno); stream stream where event happened msgno number of messages This function is called by the driver to notify MAIL that this message number has been expunged from the mail file and that all subsequent messages are now referenced by a message number one less than before. It invokes the main program's mm_expunged() function. void mail_lock (MAILSTREAM *stream); stream stream where event happened This function sets the stream lock. It is an error to set the stream lock if the stream is already locked. This is mainly used to catch errors due to a callback function (e.g. mm_exists) inadvertantly recursing back to the MAIL routines and establishing an infinite recursion. Normally, drivers will set the lock prior to calling one of the callback functions above or, more likely, in the beginning of the driver's non-reentrant "do operation" section. In the IMAP4 driver, the stream lock is set when entering imap_send() and cleared on exit. void mail_unlock (MAILSTREAM *stream); stream stream where event happened This function releases the stream lock. It is an error to release the stream lock if the stream is not locked. imap-2007f~dfsg/docs/bugs.txt0000644000000000000000000002726511612411705014743 0ustar rootroot/* ======================================================================== * 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 * * * ======================================================================== */ KNOWN BUGS/MISFEATURES/DEFICIENCIES IN THE IMAP TOOLKIT Last Updated: 15 November 2007 The following are known problems/deficiencies in the imap-2007 toolkit: . Possible problems for some installations: . In some versions of Redhat Linux, SVR4-style timezone name lookup doesn't work properly due to a bug in glibc. The workaround is to edit os_lnx.c to include tz_bsd.c instead of tz_sv4.c. Note that other versions of Linux don't support BSD-style timezone name lookup, so don't make this change unless it's needed on your system. . In some systems, the OpenSSL distribution is installed other than at the standard /usr/local/ssl location. If this is the case on your system and you want to build with SSL support, you will need to set the SSLDIR variable, either by including a setting of EXTRASPECIALS in the make command line, e.g. build lnp SPECIALAUTHENTICATORS=ssl EXTRASPECIALS="SSLDIR=/usr/ssl" or by editing .../src/osdep/unix/Makefile . /tmp, /usr/tmp or /var/tmp (if present), and the mail spool directory must be protected 1777 (world write with sticky bit); otherwise mailbox locking and updates won't work. An alternative to 1777 on the mail spool directory is to install the mlock program that is bundled with the IMAP toolkit. . Multiple access protection locking does not work if the mailbox or /tmp are NFS mounted. . Shared access mailbox formats (mbx, mtx, mx, and tenex) do not work well with NFS and such usage is not supported. mmdf and unix formats are supported for use over NFS; however there won't be any multiple access locking protection. . Server startup delays may occur if a reverse DNS (IP address to name) lookup on the client's IP address does not complete in an expeditious fashion. This is actually a DNS problem and should be fixed in the DNS and/or the server's host table. A workaround exists (see the top-level Makefile for details) but is not recommended and can not be used at all with Kerberos. . At the insistance of the security gurus, SSL certification validation is now on by default. This means that you must now use the new /novalidate-cert switch if establishing an SSL connection to a server with a self-signed certificate; i.e. if "imap.example.com" has a self-signed certificate, you must use a mailbox name such as {imap.example.com/ssl/novalidate-cert}INBOX to get an SSL session instead of just {imap.example.com/ssl}INBOX . GCC 8.x and above on SGI systems does not correctly pass/return structures which are smaller than 16 bytes and are not 8 bytes. The problem is that structures are padded at the wrong end; e.g. a 4 byte structure is loaded into the lower 4 bytes of the register when it should be loaded into the upper 4 bytes of the register. This affects IRIX 6 the most because it is a 64-bit system and 4 byte structures are common. This compiler bug impacts the use of inet_ntoa() in c-client and causes syslog messages to show IP addresses as 255.255.255.255 instead of the correct values. The fix is either to use SGI's C compiler instead of GCC or link with an implementation of inet_ntoa() that was built with GCC instead of the standard SGI C library version. . By default, the UNIX SSL build assumes that RSAREF is not needed, because RSA Security Inc. released the RSA public key encryption algorithm into the public domain on September 6, 2000. There is no longer any need to use RSAREF, and since RSAREF is slower than OpenSSL's RSA routines there's good reason not to. If for some reason you still want to use RSAREF, you will need to edit .../src/osdep/unix/Makefile to change SSLRSA to load libRSAglue and librsaref. . By default, the UNIX SSL build assumes that no name conflict exists between OpenSSL and Kerberos 5. If you are using an older version of Kerberos, you may need to edit .../src/osdep/unix/Makefile to change SSLCRYPTO so that it loads the OpenSSL libcrypto library explicitly as libcrypto.a. . By default, host names are canonicalized via gethostbyname() and gethostbyaddr() for everything except for SSL certificate validation. This can represent a security bug due to DNS spoofing, but is more likely to deliver results that users expect and also may be necessary to get Kerberos to work. Set variable "trustdns" in mail.c to NIL if you want to disable this. . Bugs: . It doesn't work to have a "}" character as a user name in /user= in a mailbox name, even if the user name is quoted. In other words, {example.com/user="foo}bar"}zap won't work; foo will be interpreted as an unterminated quoted string and the remote mailbox name will be bar"}zap. . The experimental mx driver has performance problems and shouldn't be used . docs/internal.txt is out of date (again) . UIDPLUS bugs/limitations: . Not supported in all local file formats (see below). . There are two known issues with UIDPLUS in the mmdf and unix formats: (a) If the destination mailbox is currently selected (whether in this or another session), no COPYUID or APPENDUID is returned. The other choice was to assign a UID based upon the uid_last value and hope that the session selecting the mailbox would pick it up and update uid_last. The problem was a timing race if another message was copied/appended to that mailbox before the selecting session updated the mailbox. If the timing race is lost, then all UID in the mailbox would be reassigned by the selecting session, thus making the returned APPENDUID/COPYUID data useless and causing a performance problem. Earlier versions did the "hope for the best" method. This was revoked in favor of not returning COPYUID/APPENDUID. Although this violates RFC 4315, there is a loophole which, although for other purposes, permits this behavior. (b) There is a known failure if the destination mailbox is currently selected by legacy software (e.g. older versions of the IMAP server, Pine, etc.). In this case, all UIDs end up being reassigned by the legacy software. . Annoyances: . Friendly host names (e.g. "server" instead of "server.foo.com") can't be used in a mailbox name with SSL certificate validation; you have to enter the fully-qualified domain name. This is a requirement established by the security gurus. . IMAP client limitations: . No SASL protection mechanisms (SASL authentication mechanisms are supported) . NNTP client limitations: . Non-standard IMAP SCAN extension not supported . POP client limitations: . No SASL protection mechanisms (SASL authentication mechanisms are supported) . No POP3 UID support . Non-standard IMAP SCAN extension not supported . SMTP client limitations: . No SASL protection mechanisms (SASL authentication mechanisms are supported) . No support for use of TURN, ETRN, and pipelining. . No support for enhanced status codes . UNIX limitations: . IPv6 is supported but is not the default on most platforms; you have to use IP=6 in the make command . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile, tenex, unix . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI . Sticky UIDs are not supported in the mh, mtx, and tenex drivers . Creation of keywords is not supported in the mh, mtx, and tenex drivers . Copy and append of keywords only works in the mbx driver. . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit mailboxes to have inferior names . SSL temporary key should be seeded better than it is. . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats. . Non-standard IMAP SCAN extension not support for mh and news formats. . Amiga limitations: . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile, tenex, unix . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS . Sticky UIDs are not supported in the mh, mtx, and tenex drivers . Creation of keywords is not supported in the mh, mtx, and tenex drivers . Copy and append of keywords only works in the mbx driver. . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit mailboxes to have inferior names . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats. . Non-standard IMAP SCAN extension not supported for mh and news formats. . Win32 (Win9x/NT/Windows 2000) limitations: . IPv6 is supported in W2K builds but is not the default; you have to use IP=6 in the nmake command . Supported local file formats: mbx, mtx, tenex, unix . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI . No server SSL or TLS support. . No server authentication for GSSAPI . No server authentication for CRAM-MD5 on NT-based Windows (NT/2K/XP); it does work on DOS-based Windows (9x/Me). . Sticky UIDs are not supported in the mtxnt and tenexnt drivers . Creation of keywords is not supported in the mtxnt and tenexnt drivers . Copy and append of keywords only works in the mbxnt driver. . No support for TCP open timeouts . Flat file formats (mbx, mtx, tenex, unix) do not permit mailboxes to have inferior names . UIDPLUS support is limited to the unix and mbx formats. . Win16 (Win3.1)/DOS limitations: . IPv6 not supported . Supported local file formats: bezerk, mtx . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS . Supported TCPs: B&W, Novell, PC-NFs, PC/TCP, Waterloo, Winsock . Sticky UIDs are not supported on local files . Creation of keywords are not supported on local files . Bezerk driver is read-only and does not handle LF-only newlines well . No support for any TCP timeouts on Waterloo DOS . No support for TCP open timeouts on Winsock and generic DOS . Flat file formats (bezerk, mtx) do not permit mailboxes to have inferior names . Does not work well unless a mailgets routine is armed when fetching texts. . Mac limitations: . IPv6 not supported . No local file drivers . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS . Does not output human-friendly time zone string . TOPS-20 limitations: . IPv6 not supported . No local file drivers . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS . No support for any TCP timeouts . VMS limitations: . IPv6 not supported . No local file drivers . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS . Supported TCPs: Multinet, Netlib . No support for any TCP timeouts on VMS Netlib . No support for TCP open timeouts on VMS Multinet . Time zone must be configured at build time . Does not output human-friendly time zone string . Windows CE limitations: . IPv6 not yet supported . No local file drivers . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS . No support for TCP open timeouts . Not finished, only builds c-client library . OS/2 limitations: . IPv6 not supported . Not finished, does not build imap-2007f~dfsg/docs/FAQ.txt0000644000000000000000000043066011612411704014406 0ustar rootroot/* ======================================================================== * 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 * * * ======================================================================== */ IMAP Toolkit Frequently Asked Questions Table of Contents * 1. General/Software Feature Questions + 1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.? + 1.2 I am currently using qpopper as my POP3 server on UNIX. Do I need to replace it with ipop3d in order to run imapd? + 1.3 Can I set up a POP or IMAP server on Windows XP, 2000, NT, Me, 98, or 95? + 1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS? + 1.5 Can I set up a POP or IMAP server on Macintosh? + 1.6 Can I set up a POP or IMAP server on VAX/VMS? + 1.7 Can I set up a POP or IMAP server on TOPS-20? + 1.8 Are hierarchical mailboxes supported? + 1.9 Are "dual-use" mailboxes supported? + 1.10 Can I have a mailbox that has both messages and sub-mailboxes? + 1.11 What is the difference between "mailbox" and "folder"? + 1.12 What is the status of internationalization? + 1.13 Can I use SSL? + 1.14 Can I use TLS and the STARTTLS facility? + 1.15 Can I use CRAM-MD5 authentication? + 1.16 Can I use APOP authentication? + 1.17 Can I use Kerberos V5? + 1.18 Can I use PAM for plaintext passwords? + 1.19 Can I use Kerberos 5 for plaintext passwords? + 1.20 Can I use AFS for plaintext passwords? + 1.21 Can I use DCE for plaintext passwords? + 1.22 Can I use the CRAM-MD5 database for plaintext passwords? + 1.23 Can I disable plaintext passwords? + 1.24 Can I disable plaintext passwords on unencrypted sessions, but allow them on encrypted sessions? + 1.25 Can I use virtual hosts? + 1.26 Can I use RPOP authentication? + 1.27 Can I use Kerberos V4? + 1.28 Is there support for S/Key or OTP? + 1.29 Is there support for NTLM or SPA? + 1.30 Is there support for mh? + 1.31 Is there support for qmail and the maildir format? + 1.32 Is there support for the Cyrus mailbox format? + 1.33 Is this software Y2K compliant? * 2. What Do I Need to Build This Software? + 2.1 What do I need to build this software with SSL on UNIX? + 2.2 What do I need to build this software with Kerberos V on UNIX? + 2.3 What do I need to use a C++ compiler with this software to build my own application? + 2.4 What do I need to build this software on Windows? + 2.5 What do I need to build this software on DOS? + 2.6 Can't I use Borland C to build this software on the PC? + 2.7 What do I need to build this software on the Mac? + 2.8 What do I need to build this software on VMS? + 2.9 What do I need to build this software on TOPS-20? + 2.10 What do I need to build this software on Amiga or OS/2? + 2.11 What do I need to build this software on Windows CE? * 3. Build and Configuration Questions + 3.1 How do I configure the IMAP and POP servers on UNIX? + 3.2 I built and installed the servers according to the BUILD instructions. It can't be that easy. Don't I need to write a config file? + 3.3 How do I make the IMAP and POP servers look for INBOX at some place other than the mail spool directory? + 3.4 How do I make the IMAP server look for secondary folders at some place other than the user's home directory? + 3.5 How do I configure SSL? + 3.6 How do I configure TLS and the STARTTLS facility? + 3.7 How do I build/install OpenSSL and obtain/create certificates for use with SSL? + 3.8 How do I configure CRAM-MD5 authentication? + 3.9 How do I configure APOP authentication? + 3.10 How do I configure Kerberos V5? + 3.11 How do I configure PAM for plaintext passwords? + 3.12 It looks like all I have to do to make the server use Kerberos is to build with PAM on my Linux system, and set it up in PAM for Kerberos passwords. Right? + 3.13 How do I configure Kerberos 5 for plaintext passwords? + 3.14 How do I configure AFS for plaintext passwords? + 3.15 How do I configure DCE for plaintext passwords? + 3.16 How do I configure the CRAM-MD5 database for plaintext passwords? + 3.17 How do I disable plaintext passwords? + 3.18 How do I disable plaintext passwords on unencrypted sessions, but allow them in SSL or TLS sessions? + 3.19 How do I configure virtual hosts? + 3.20 Why do I get compiler warning messages such as: o passing arg 3 of `scandir' from incompatible pointer type o Pointers are not assignment-compatible. o Argument #4 is not the correct type. during the build? + 3.21 Why do I get compiler warning messages such as o Operation between types "void(*)(int)" and "void*" is not allowed. o Function argument assignment between types "void*" and "void(*)(int)" is not allowed. o Pointers are not assignment-compatible. o Argument #5 is not the correct type. during the build? + 3.22 Why do I get linker warning messages such as: o mtest.c:515: the `gets' function is dangerous and should not be used. during the build? Isn't this a security bug? + 3.23 Why do I get linker warning messages such as: o auth_ssl.c:92: the `tmpnam' function is dangerous and should not be used. during the build? Isn't this a security bug? + 3.24 OK, suppose I see a warning message about a function being "dangerous and should not be used" for something other than this gets() or tmpnam() call? * 4. Operational Questions + 4.1 How can I enable anonymous IMAP logins? + 4.2 How do I set up an alert message that each IMAP user will see? + 4.3 How does the c-client library choose which of its several mechanisms to use to establish an IMAP connection to the server? I noticed that it can connect on port 143, port 993, via rsh, and via ssh. + 4.4 I am using a TLS-capable IMAP server, so I don't need to use /ssl to get encryption. However, I want to be certain that my session is TLS encrypted before I send my password. How to I do this? + 4.5 How do I use one of the alternative formats described in the formats.txt document? In particular, I hear that mbx format will give me better performance and allow shared access. + 4.6 How do I set up shared mailboxes? + 4.7 How can I make the server syslogs go to someplace other than the mail syslog? * 5. Security Questions + 5.1 I see that the IMAP server allows access to arbitary files on the system, including /etc/passwd! How do I disable this? + 5.2 I've heard that IMAP servers are insecure. Is this true? + 5.3 How do I know that I have the most secure version of the server? + 5.4 I see all these strcpy() and sprintf() calls, those are unsafe, aren't they? + 5.5 Those /tmp lock files are protected 666, is that really right? * 6. Why Did You Do This Strange Thing? Questions + 6.1 Why don't you use GNU autoconfig / automake / autoblurdybloop? + 6.2 Why do you insist upon a build with -g? Doesn't it waste disk and memory space? + 6.3 Why don't you make c-client a shared library? + 6.4 Why don't you use iconv() for internationalization support? + 6.5 Why is the IMAP server connected to the home directory by default? + 6.6 I have a Windows system. Why isn't the server plug and play for me? + 6.7 I looked at the UNIX SSL code and saw that you have the SSL data payload size set to 8192 bytes. SSL allows 16K; why aren't you using the full size? + 6.8 Why is an mh format INBOX called #mhinbox instead of just INBOX? + 6.9 Why don't you support the maildir format? + 6.10 Why don't you support the Cyrus format? + 6.11 Why is it creating extra forks on my SVR4 system? + 6.12 Why are you so fussy about the date/time format in the internal "From " line in traditional UNIX mailbox files? My other mail program just considers every line that starts with "From " to be the start of the message. + 6.13 Why is traditional UNIX format the default format? + 6.14 Why do you write this "DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA" message at the start of traditional UNIX and MMDF format mailboxes? + 6.15 Why don't you stash the mailbox metadata in the first real message of the mailbox instead of writing this fake FOLDER INTERNAL DATA message? + 6.16 Why aren't "dual-use" mailboxes the default? + 6.17 Why do you use ucbcc to build on Solaris? + 6.18 Why should I care about some old system with BSD libraries? cc is the right thing on my Solaris system! + 6.19 Why do you insist upon writing .lock files in the spool directory? + 6.20 Why should I care about compatibility with the past? * 7. Problems and Annoyances + 7.1 Help! My INBOX is empty! What happened to my messages? + 7.2 Help! All my messages in a non-INBOX mailbox have been concatenated into one message which claims to be from me and has a subject of the file name of the mailbox! What's going on? + 7.3 Why do I get the message: o CREATE failed: Can't create mailbox node xxxxxxxxx: File exists and how do I fix it? + 7.4 Why can't I log in to the server? The user name and password are right! + 7.5 Help! My load average is soaring and I see hundreds of POP and IMAP servers, many logged in as the same user! + 7.6 Why does mail disappear even though I set "keep mail on server"? + 7.7 Why do I get the message o Moved ##### bytes of new mail to /home/user/mbox from /var/spool/mail/user and why did this happen? + 7.8 Why isn't it showing the local host name as a fully-qualified domain name? + 7.9 Why is the local host name in the From/Sender/Message-ID headers of outgoing mail not coming out as a fully-qualified domain name? + 7.10 What does the message: o Mailbox vulnerable - directory /var/spool/mail must have 1777 protection mean? How can I fix this? + 7.11 What does the message: o Mailbox is open by another process, access is readonly mean? How do I fix this? + 7.12 What does the message: o Can't get write access to mailbox, access is readonly mean? + 7.13 I set my POP3 client to "delete messages from server" but they never get deleted. What is wrong? + 7.14 What do messages such as: o Message ... UID ... already has UID ... o Message ... UID ... less than ... o Message ... UID ... greater than last ... o Invalid UID ... in message ..., rebuilding UIDs mean? + 7.15 What do the error messages: o Unable to read internal header at ... o Unable to find CRLF at ... o Unable to parse internal header at ... o Unable to parse message date at ... o Unable to parse message flags at ... o Unable to parse message UID at ... o Unable to parse message size at ... o Last message (at ... ) runs past end of file ... mean? I am using mbx format. + 7.16 What do the syslog messages: o imap/tcp server failing (looping) o pop3/tcp server failing (looping) mean? When it happens, the listed service shuts down. How can I fix this? + 7.17 What does the syslog message: o Mailbox lock file /tmp/.600.1df3 open failure: Permission denied mean? + 7.18 What do the syslog messages: o Command stream end of file, while reading line user=... host=... o Command stream end of file, while reading char user=... host=... o Command stream end of file, while writing text user=... host=... mean? + 7.19 Why did my POP or IMAP session suddenly disconnect? The syslog has the message: o Killed (lost mailbox lock) user=... host=... + 7.20 Why does my IMAP client show all the files on the system, recursively from the UNIX root directory? + 7.21 Why does my IMAP client show all of my files, recursively from my UNIX home directory? + 7.22 Why does my IMAP client show that I have mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and "#public"? + 7.23 Why does my IMAP client show all my files in my home directory? + 7.24 Why is there a long delay before I get connected to the IMAP or POP server, no matter what client I use? + 7.25 Why is there a long delay in Pine or any other c-client based application call before I get connected to the IMAP server? The hang seems to be in the c-client mail_open() call. I don't have this problem with any other IMAP client. There is no delay connecting to a POP3 or NNTP server with mail_open(). + 7.26 Why does a message sometimes get split into two or more messages on my SUN system? + 7.27 Why did my POP or IMAP session suddenly disconnect? The syslog has the message: o Autologout user=<...my user name...> host=<...my imap server...> + 7.28 What does the UNIX error message: o TLS/SSL failure: myserver: SSL negotiation failed mean? + 7.29 What does the PC error message: o TLS/SSL failure: myserver: Unexpected TCP input disconnect mean? + 7.30 What does the error message: o TLS/SSL failure: myserver: Server name does not match certificate mean? + 7.31 What does the UNIX error message: o TLS/SSL failure: myserver: self-signed certificate mean? + 7.32 What does the PC error message o TLS/SSL failure: myserver: Self-signed certificate or untrusted authority mean? + 7.33 What does the UNIX error message: o TLS/SSL failure: myserver: unable to get local issuer certificate mean? + 7.34 Why does reading certain messages hang when using Netscape? It works fine with Pine! + 7.35 Why does Netscape say that there's a problem with the IMAP server and that I should "Contact your mail server administrator."? + 7.36 Why is one user creating huge numbers of IMAP or POP server sessions? + 7.37 Why don't I get any new mail notifications from Outlook Express or Outlook after a while? + 7.38 Why don't I get any new mail notifications from Entourage? + 7.39 Why doesn't Entourage work at all? + 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all? + 7.41 Why can't I connect via SSL to Eudora? It says the connection has been broken, and in the server syslogs I see "Command stream end of file". + 7.42 Sheesh. Aren't there any good IMAP clients out there? + 7.43 But wait! PC Pine (or other PC program build with c-client) crashes with the message o incomplete SecBuffer exceeds maximum buffer size when I use SSL connections. This is a bug in c-client, right? + 7.44 My qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How can I fix this? + 7.45 Help! I installed the servers but I can't connect to them from my client! + 7.46 Why do I get the message o Can not authenticate to SMTP server: 421 SMTP connection went away! and why did this happen? There was also something about o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN + 7.47 Why do I get the message o SMTP Authentication cancelled and why did this happen? There was also something about o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN + 7.48 Why do I get the message o Invalid base64 string when I try to authenticate to a Cyrus server? * 8. Where to Go For Additional Information + 8.1 Where can I go to ask questions? + 8.2 I have some ideas for enhancements to IMAP. Where should I go? + 8.3 Where can I read more about IMAP and other email protocols? + 8.4 Where can I find out more about setting up and administering an IMAP server? _________________________________________________________________ 1. General/Software Feature Questions _________________________________________________________________ 1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.? Yes. Refer to the UNIX specific notes in files CONFIG and BUILD. _________________________________________________________________ 1.2 I am currently using qpopper as my POP3 server on UNIX. Do I need to replace it with ipop3d in order to run imapd? Not necessarily. Although ipop3d interoperates with imapd better than qpopper, imapd and qpopper will work together. The few qpopper/imapd interoperability issues mostly affect users who use both IMAP and POP3 clients; those users would probably be better served if their POP3 server is ipop3d. If you are happy with qpopper and just want to add imapd, you should do that, and defer a decision on changing qpopper to ipop3d. That way, you can get comfortable with imapd's performance, without changing anything for your qpopper users. Many sites have subsequently decided to change from qpopper to ipop3d in order to get better POP3/IMAP interoperability. If you need to do this, you'll know. There also seems to be a way to make qpopper work better with imapd; see the answer to the My qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How can I fix this? question. _________________________________________________________________ 1.3 Can I set up a POP or IMAP server on Windows XP, 2000, NT, Me, 98, or 95? Yes. Refer to the NT specific notes in files CONFIG and BUILD. Also, for DOS-based versions of Windows (Windows Me, 98, and 95) you *must* set up CRAM-MD5 authentication, as described in md5.txt. There is no file access control on Windows 9x or Me, so you probably will have to do modifications to env_unix.c to prevent people from hacking others' mail. Note, however, that the server is not plug and play the way it is for UNIX. _________________________________________________________________ 1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS? 1.5 Can I set up a POP or IMAP server on Macintosh? 1.6 Can I set up a POP or IMAP server on VAX/VMS? Yes, it's just a small matter of programming. _________________________________________________________________ 1.7 Can I set up a POP or IMAP server on TOPS-20? You have a TOPS-20 system? Cool. If IMAP2 (RFC 1176) is good enough for you, you can use MAPSER which is about the ultimate gonzo pure TOPS-20 extended addressing assembly language program. Unfortunately, IMAP2 is barely good enough for Pine these days, and most other IMAP clients won't work with IMAP2 at all. Maybe someone will hack MAPSER to do IMAP4rev1 some day. We don't know if anyone wrote a POP3 server for TOPS-20. There definitely was a POP2 server once upon a time. Or you can port the POP and IMAP server from this IMAP toolkit to it. All that you need for a first stab is to port the MTX driver. That'll probably be just a couple of hours of hacking. _________________________________________________________________ 1.8 Are hierarchical mailboxes supported? 1.9 Are "dual-use" mailboxes supported? 1.10 Can I have a mailbox that has both messages and sub-mailboxes? Yes. However, there is one important caveat. Some mailbox formats, including the default which is the traditional UNIX mailbox format, are stored as a single file containing all the messages. UNIX does not permit a name in the filesystem to be both a file and a directory; consequently you can not have a sub-mailbox within a mailbox that is in one of these formats. This is not a limitation of the software; this is a limitation of UNIX. For example, there are mailbox formats in which the name is a directory and each message is a file within that directory; these formats support sub-mailboxes within such mailboxes. However, for technical reasons, the "flat file" formats are generally preferred since they perform better. Read imap-2007/docs/formats.txt for more information on this topic. It is always permissible to create a directory that is not a mailbox, and have sub-mailboxes under it. The easiest way to create a directory is to create a new mailbox inside a directory that doesn't already exist. For example, if you create "Mail/testbox" on UNIX, the directory "Mail/" will automatically be created and then the mailbox "testbox" will be created as a sub-mailbox of "Mail/". It is also possible to create the name "Mail/" directly. Check the documentation for your client software to see how to do this with that software. Of course, on Windows systems you would use "\" instead of "/". _________________________________________________________________ 1.11 What is the difference between "mailbox" and "folder"? The term "mailbox" is IMAP-speak for what a lot of software calls a "folder" or a "mail folder". However, "folder" is often used in other contexts to refer to a directory, for example, in the graphic user interface on both Windows and Macintosh. A "mailbox" is specifically defined as a named object that contains messages. It is not required to be capable of containing other types of objects including other mailboxes; although some mailbox formats will permit this. In IMAP-speak, a mailbox which can not contain other mailboxes is called a "no-inferiors mailbox". Similarly, a directory which can not contain messages is not a mailbox and is called a "no-select name". _________________________________________________________________ 1.12 What is the status of internationalization? The IMAP toolkit is partially internationalized and multilingualized. Searching is supported in the following charsets: US-ASCII, UTF-8, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, ISO-8859-15, ISO-8859-16, KOI8-R, KOI8-U (alias KOI8-RU), TIS-620, VISCII, ISO-2022-JP, ISO-2022-KR, ISO-2022-CN, ISO-2022-JP-1, ISO-2022-JP-2, GB2312 (alias CN-GB), CN-GB-12345, BIG5 (alias CN-BIG5), EUC-JP, EUC-KR, Shift_JIS, Shift-JIS, KS_C_5601-1987, KS_C_5601-1992, WINDOWS_874, WINDOWS-1250, WINDOWS-1251, WINDOWS-1252, WINDOWS-1253, WINDOWS-1254, WINDOWS-1255, WINDOWS-1256, WINDOWS-1257, WINDOWS-1258. All ISO-2022-?? charsets are treated identically, and support ASCII, JIS Roman, hankaku katakana, ISO-8859-[1 - 10], TIS, GB 2312, JIS X 0208, JIS X 0212, KSC 5601, and planes 1 and 2 of CNS 11643. EUC-JP includes support for JIS X 0212 and hankaku katakana. c-client library support also exists to convert text in any of the above charsets into Unicode, including headers with MIME encoded-words. There is no support for localization (e.g. non-English error messages) at the present time, but such support is planned. _________________________________________________________________ 1.13 Can I use SSL? Yes. See the answer to the How do I configure SSL? question. _________________________________________________________________ 1.14 Can I use TLS and the STARTTLS facility? Yes. See the answer to the How do I configure TLS and the STARTTLS facility? question. _________________________________________________________________ 1.15 Can I use CRAM-MD5 authentication? Yes. See the answer to the How do I configure CRAM-MD5 authentication? question. _________________________________________________________________ 1.16 Can I use APOP authentication? Yes. See the How do I configure APOP authentication? question. Note that there is no client support for APOP authentication. _________________________________________________________________ 1.17 Can I use Kerberos V5? Yes. See the answer to the How do I configure Kerberos V5? question. _________________________________________________________________ 1.18 Can I use PAM for plaintext passwords? Yes. See the answer to the How do I configure PAM for plaintext passwords? question. _________________________________________________________________ 1.19 Can I use Kerberos 5 for plaintext passwords? Yes. See the answer to the How do I configure Kerberos 5 for plaintext passwords? question. _________________________________________________________________ 1.20 Can I use AFS for plaintext passwords? Yes. See the answer to the How do I configure AFS for plaintext passwords? question. _________________________________________________________________ 1.21 Can I use DCE for plaintext passwords? Yes. See the answer to the How do I configure DCE for plaintext passwords? question. _________________________________________________________________ 1.22 Can I use the CRAM-MD5 database for plaintext passwords? Yes. See the answer to the How do I configure the CRAM-MD5 database for plaintext passwords? question. _________________________________________________________________ 1.23 Can I disable plaintext passwords? Yes. See the answer to the How do I disable plaintext passwords? question. _________________________________________________________________ 1.24 Can I disable plaintext passwords on unencrypted sessions, but allow them on encrypted sessions? Yes. See the answer to the How do I disable plaintext passwords on unencrypted sessions, but allow them in SSL or TLS sessions? question. _________________________________________________________________ 1.25 Can I use virtual hosts? Yes. See the answer to the How do I configure virtual hosts? question. _________________________________________________________________ 1.26 Can I use RPOP authentication? There is no support for RPOP authentication. _________________________________________________________________ 1.27 Can I use Kerberos V4? Kerberos V4 is not supported. Kerberos V4 client-only contributed code is available in ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z This is a patchkit which must be applied to the IMAP toolkit according to the instructions in the patchkit's README. We can not promise that this code works. _________________________________________________________________ 1.28 Is there support for S/Key or OTP? There is currently no support for S/Key or OTP. There may be an OTP SASL authenticator available from third parties. _________________________________________________________________ 1.29 Is there support for NTLM or SPA? There is currently no support for NTLM or SPA, nor are there any plans to add such support. In general, I avoid vendor-specific mechanisms. I also believe that these mechanisms are being deprecated by their vendor. There may be an NTLM SASL authenticator available from third parties. _________________________________________________________________ 1.30 Is there support for mh? Yes, but only as a legacy format. Your mh format INBOX is accessed by the name "#mhinbox", and all other mh format mailboxes are accessed by prefixing "#mh/" to the name, e.g. "#mh/foo". The mh support uses the "Path:" entry in your .mh_profile file to identify the root directory of your mh format mailboxes. Non-legacy use of mh format is not encouraged. There is no support for permanent flags or unique identifiers; furthermore there are known severe performance problems with the mh format. _________________________________________________________________ 1.31 Is there support for qmail and the maildir format? There is no support for qmail or the maildir format in our distribution, nor are there any plans to add such support. Maildir support may be available from third parties. _________________________________________________________________ 1.32 Is there support for the Cyrus mailbox format? No. _________________________________________________________________ 1.33 Is this software Y2K compliant? Please read the files Y2K and calendar.txt. _________________________________________________________________ 2. What Do I Need to Build This Software? _________________________________________________________________ 2.1 What do I need to build this software with SSL on UNIX? You need to build and install OpenSSL first. _________________________________________________________________ 2.2 What do I need to build this software with Kerberos V on UNIX? You need to build and install MIT Kerberos first. _________________________________________________________________ 2.3 What do I need to use a C++ compiler with this software to build my own application? If you are building an application using the c-client library, use the new c-client.h file instead of including the other include files. It seems that c-client.h should define away all the troublesome names that conflict with C++. If you use gcc, you may need to use -fno-operator-names as well. _________________________________________________________________ 2.4 What do I need to build this software on Windows? You need Microsoft Visual C++ 6.0, Visual C++ .NET, or Visual C# .NET (which you can buy from any computer store), along with the Microsoft Platform SDK (which you can download from Microsoft's web site). You do not need to install the entire Platform SDK; it suffices to install just the Core SDK and the Internet Development SDK. _________________________________________________________________ 2.5 What do I need to build this software on DOS? It's been several years since we last attempted to do this. At the time, we used Microsoft C. _________________________________________________________________ 2.6 Can't I use Borland C to build this software on the PC? Probably not. If you know otherwise, please let us know. _________________________________________________________________ 2.7 What do I need to build this software on the Mac? It has been several years since we last attempted to do this. At the time, we used Symantec THINK C; but today you'll need a C compiler which allows segments to be more than 32K. _________________________________________________________________ 2.8 What do I need to build this software on VMS? You need the VMS C compiler, and either the Multinet or Netlib TCP. _________________________________________________________________ 2.9 What do I need to build this software on TOPS-20? You need the TOPS-20 KCC compiler. _________________________________________________________________ 2.10 What do I need to build this software on Amiga or OS/2? We don't know. _________________________________________________________________ 2.11 What do I need to build this software on Windows CE? This port is incomplete. Someone needs to finish it. _________________________________________________________________ 3. Build and Configuration Questions _________________________________________________________________ 3.1 How do I configure the IMAP and POP servers on UNIX? 3.2 I built and installed the servers according to the BUILD instructions. It can't be that easy. Don't I need to write a config file? For ordinary "vanilla" UNIX systems, this software is plug and play; just build it, install it, and you're done. If you have a modified system, then you may want to do additional work; most of this is to a single source code file (env_unix.c on UNIX systems). Read the file CONFIG for more details. Yes, it's that easy. There are some additional options, such as SSL or Kerberos, which require additional steps to build. See the relevant questions below. _________________________________________________________________ 3.3 How do I make the IMAP and POP servers look for INBOX at some place other than the mail spool directory? 3.4 How do I make the IMAP server look for secondary folders at some place other than the user's home directory? Please read the file CONFIG for discussion of this and other issues. _________________________________________________________________ 3.5 How do I configure SSL? 3.6 How do I configure TLS and the STARTTLS facility? imap-2007 supports SSL and TLS client functionality on UNIX and 32-bit Windows for IMAP, POP3, SMTP, and NNTP; and SSL and TLS server functionality on UNIX for IMAP and POP3. UNIX SSL build requires that a third-party software package, OpenSSL, be installed on the system first. Read imap-2007/docs/SSLBUILD for more information. SSL is supported via undocumented Microsoft interfaces in Windows 9x and NT4; and via standard interfaces in Windows 2000, Windows Millenium, and Windows XP. _________________________________________________________________ 3.7 How do I build/install OpenSSL and obtain/create certificates for use with SSL? If you need help in doing this, try the contacts mentioned in the OpenSSL README. We do not offer support for OpenSSL or certificates. _________________________________________________________________ 3.8 How do I configure CRAM-MD5 authentication? 3.9 How do I configure APOP authentication? CRAM-MD5 authentication is enabled in the IMAP and POP3 client code on all platforms. Read md5.txt to learn how to set up CRAM-MD5 and APOP authentication on UNIX and NT servers. There is no support for APOP client authentication. _________________________________________________________________ 3.10 How do I configure Kerberos V5? imap-2007 supports client and server functionality on UNIX and 32-bit Windows. Kerberos V5 is supported by default in Windows 2000 builds: nmake -f makefile.w2k Other builds require that a third-party Kerberos package, e.g. MIT Kerberos, be installed on the system first. To build with Kerberos V5 on UNIX, include EXTRAAUTHENTICATORS=gss in the make command line, e.g. make lnp EXTRAAUTHENTICATORS=gss To build with Kerberos V5 on Windows 9x, Windows Millenium, and NT4, use the "makefile.ntk" file instead of "makefile.nt": nmake -f makefile.ntk _________________________________________________________________ 3.11 How do I configure PAM for plaintext passwords? On Linux systems, use the lnp port, e.g. make lnp On Solaris systems and other systems with defective PAM implementations, build with PASSWDTYPE=pmb, e.g. make sol PASSWDTYPE=pmb On all other systems, build with PASSWDTYPE=pam, e.g make foo PASSWDTYPE=pam If you build with PASSWDTYPE=pam and authentication does not work, try rebuilding (after a "make clean") with PASSWDTYPE=pmb. _________________________________________________________________ 3.12 It looks like all I have to do to make the server use Kerberos is to build with PAM on my Linux system, and set it up in PAM for Kerberos passwords. Right? Yes and no. Doing this will make plaintext password authentication use the Kerberos password instead of the /etc/passwd password. However, this will NOT give you Kerberos-secure authentication. See the answer to the How do I configure Kerberos V5? question for how to build with Kerberos-secure authentication. _________________________________________________________________ 3.13 How do I configure Kerberos 5 for plaintext passwords? Build with PASSWDTYPE=gss, e.g. make sol PASSWDTYPE=gss However, this will NOT give you Kerberos-secure authentication. See the answer to the How do I configure Kerberos V5? question for how to build with Kerberos-secure authentication. _________________________________________________________________ 3.14 How do I configure AFS for plaintext passwords? Build with PASSWDTYPE=afs, e.g make sol PASSWDTYPE=afs _________________________________________________________________ 3.15 How do I configure DCE for plaintext passwords? Build with PASSWDTYPE=dce, e.g make sol PASSWDTYPE=dce _________________________________________________________________ 3.16 How do I configure the CRAM-MD5 database for plaintext passwords? The CRAM-MD5 password database is automatically used for plaintext password if it exists. Note that this is NOT CRAM-MD5-secure authentication. You probably want to consider disabling plaintext passwords for non-SSL/TLS sessions. See the next two questions. _________________________________________________________________ 3.17 How do I disable plaintext passwords? Server-level plaintext passwords can be disabled by setting PASSWDTYPE=nul, e.g. make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul Note that you must have a CRAM-MD5 database installed or specify at least one EXTRAAUTHENTICATOR, otherwise it will not be possible to log in to the server. When plaintext passwords are disabled, the IMAP server will advertise the LOGINDISABLED capability and the POP3 server will not advertise the USER capability. 3.18 How do I disable plaintext passwords on unencrypted sessions, but allow them in SSL or TLS sessions? Do not set PASSWDTYPE=nul or SSLTYPE=unix. Set SSLTYPE=nopwd instead, e.g. make lnx SSLTYPE=nopwd When plaintext passwords are disabled, the IMAP server will advertise the LOGINDISABLED capability and the POP3 server will not advertise the USER capability. Plaintext passwords will always be enabled in SSL sessions; the IMAP server will not advertise the LOGINDISABLED capability and the POP3 server will advertise the USER capability. If the client does a successful start-TLS in a non-SSL session, plaintext passwords will be enabled, and a new CAPABILITY or CAPA command (which is required after start-TLS) will show the effect as in SSL sessions. _________________________________________________________________ 3.19 How do I configure virtual hosts? This is automatic, but with certain restrictions. The most important one is that each virtual host must have its own IP address; otherwise the server has no way of knowing which virtual host is desired. As distributed, the software uses a global password file; hence user "fred" on one virtual host is "fred" on all virtual hosts. You may want to modify the checkpw() routine to implement some other policy (e.g. separate password files). Note that the security model assumes that all users have their own unique UNIX UID number. So if you use separate password files you should make certain that the UID numbers do not overlap between different files. More advanced virtual host support may be available as patches from third parties. _________________________________________________________________ 3.20 Why do I get compiler warning messages such as: passing arg 3 of `scandir' from incompatible pointer type Pointers are not assignment-compatible. Argument #4 is not the correct type. during the build? You can safely ignore these messages. Over the years, the prototype for scandir() has changed, and thus is variant across different UNIX platforms. In particular, the definitions of the third argument (type select_t) and fourth argument (type compar_t) have changed over the years, the issue being whether or not the arguments to the functions pointed to by these function pointers are of type const or not. The way that c-client calls scandir() will tend to generate these compiler warnings on newer systems such as Linux; however, it will still build. The problem with fixing the call is that then it won't build on older systems. _________________________________________________________________ 3.21 Why do I get compiler warning messages such as Operation between types "void(*)(int)" and "void*" is not allowed. Function argument assignment between types "void*" and "void(*)(int)" is not a llowed. Pointers are not assignment-compatible. Argument #5 is not the correct type. during the build? You can safely ignore these messages. All known systems have no problem with casting a function pointer to/from a void* pointer, certain C compilers issue a compiler diagnostic because this facility is listed as a "Common extension" by the C standard: K.5.7 Function pointer casts [#1] A pointer to an object or to void may be cast to a pointer to a function, allowing data to be invoked as a function (6.3.4). [#2] A pointer to a function may be cast to a pointer to an object or to void, allowing a function to be inspected or modified (for example, by a debugger) (6.3.4). It may be just a "common extension", but this facility is relied upon heavily by c-client. _________________________________________________________________ 3.22 Why do I get linker warning messages such as: mtest.c:515: the `gets' function is dangerous and should not be used. during the build? Isn't this a security bug? You can safely ignore this message. Certain linkers, most notably on Linux, give this warning message. It is indeed true that the traditional gets() function is not a safe one. However, the mtest program is only a demonstration program, a model of a very basic application program using c-client. It is not something that you would install, much less run in any security-sensitive context. mtest has numerous other shortcuts that you wouldn't want to do in a real application program. The only "security bug" with mtest would be if it was run by some script in a security-sensitive context, but mtest isn't particularly useful for such purposes. If you wanted to write a script to automate some email task using c-client, you'd be better off using imapd instead of mtest. mtest only has two legitimate uses. It's a useful testbed for me when debugging new versions of c-client, and it's useful as a model for someone writing a simple c-client application to see how the various calls work. By the way, if you need a more advanced example of c-client programming than mtest (and you probably will), I recommend that you look at the source code for imapd and Pine. _________________________________________________________________ 3.23 Why do I get linker warning messages such as: auth_ssl.c:92: the `tmpnam' function is dangerous and should not be used. during the build? Isn't this a security bug? You can safely ignore this message. Certain linkers, most notably on Linux, give this warning message, based upon two known issues with tmpnam(): there can be a buffer overflow if an inadequate buffer is allocated. there can be a timing race caused by certain incautious usage of the return value. Neither of these issues applies in the particular use that is made of tmpnam(). More importantly, the tmpnam() call is never executed on Linux systems. _________________________________________________________________ 3.24 OK, suppose I see a warning message about a function being "dangerous and should not be used" for something other than this gets() or tmpnam() call? Please forward the details for investigation. _________________________________________________________________ 4. Operational Questions _________________________________________________________________ 4.1 How can I enable anonymous IMAP logins? Create the file /etc/anonymous.newsgroups. At the present time, this file should be empty. This will permit IMAP logins as anonymous as well as the ANONYMOUS SASL authenticator. Anonymous users have access to mailboxes in the #news., #ftp/, and #public/ namespaces only. _________________________________________________________________ 4.2 How do I set up an alert message that each IMAP user will see? Create the file /etc/imapd.alert with the text of the message. This text should be kept to one line if possible. Note that this will cause an alert to every IMAP user every time they initiate an IMAP session, so it should only be used for critical messages. _________________________________________________________________ 4.3 How does the c-client library choose which of its several mechanisms to use to establish an IMAP connection to the server? I noticed that it can connect on port 143, port 993, via rsh, and via ssh. c-client chooses how to establish an IMAP connection via the following rules: + If /ssl is specified, use an SSL connection. Fail otherwise. + Else if client is a UNIX system and "ssh server exec /etc/rimapd" works, use that + Else if /tryssl is specified and an SSL connection works, use that. + Else if client is a UNIX system and "rsh server exec /etc/rimapd" works, use that. + Else use a non-SSL connection. _________________________________________________________________ 4.4 I am using a TLS-capable IMAP server, so I don't need to use /ssl to get encryption. However, I want to be certain that my session is TLS encrypted before I send my password. How to I do this? Use the /tls option in the mailbox name. This will cause an error message and the connection to fail if the server does not negotiate STARTTLS. _________________________________________________________________ 4.5 How do I use one of the alternative formats described in the formats.txt document? In particular, I hear that mbx format will give me better performance and allow shared access. The rumors about mbx format being preferred are true. It is faster than the traditional UNIX mailbox format and permits shared access. However, and this is very important, note that using an alternative mailbox format is an advanced facility, and only expert users should undertake it. If you don't understand any of the following notes, you may not be enough of an expert yet, and are probably better off not going this route until you are more comfortable with your understanding. Some of the formats, including mbx, are only supported by the software based on the c-client library, and are not recognized by other mailbox programs. The "vi" editor will corrupt any mbx format mailbox that it encounters. Another problem is that the certain formats, including mbx, use advanced file access and locking techniques that do not work reliably with NFS. NFS is not a real filesystem. Use IMAP instead of NFS for distributed access. Each of the following steps are in escalating order of involvement. The further you go down this list, the more deeply committed you become: + The simplest way to create a mbx-format mailbox is to prefix the name with "#driver.mbx/" when creating a mailbox through c-client. For example, if you create "#driver.mbx/foo", the mailbox "foo" will be created in mbx format. Only use "#driver.mbx/" when creating the mailbox. At all other times, just use the name ("foo" in this example); the software will automatically select the driver for mbx whenever that mailbox is accessed without you doing anything else. + You can use the "mailutil copy" command to copy an existing mailbox to a new mailbox in mbx format. Read the man page provided with the mailutil program for details. + If you create an mbx-format INBOX, by creating "#driver.mbx/INBOX" (note that "INBOX" must be all uppercase), then subsequent access to INBOX by any c-client based application will use the mbx-format INBOX. Any mail delivered to the traditional format mailbox in the spool directory (e.g. /var/spool/mail/$USER) will automatically be copied into the mbx-format INBOX and the spool directory copy removed. + You can cause any newly-created mailboxes to be in mbx-format by default by changing the definition of CREATEPROTO=unixproto to be CREATEPROTO=mbxproto in src/osdep/unix/Makefile, then rebuilding the IMAP toolkit (do a "make clean" first). Do not change EMPTYPROTO, since mbx format mailboxes are never a zero-byte file. If you use Pine or the imap-utils, you should probably also rebuild them with the new IMAP toolkit too. + You can deliver directly to the mbx-format INBOX by use of the tmail or dmail programs. tmail is for direct invocation from sendmail (or whatever MTA program you use); dmail is for calls from procmail. Both of these programs have man pages which must be read carefully before making this change. Most other servers (e.g. Cyrus) require use of a non-standard format. A full-fledged format conversion is not significantly different from what you have to do with other servers. The difference, which makes format conversion procedures somewhat more complicated with this server, is that there is no "all or nothing" requirement with this server. There are many points in between. A format conversion can be anything from a single mailbox or single user, to systemwide. This is good in that you can decide how far to go, or do the steps incrementally as you become more comfortable with the result. On the other hand, there's no "One True Way" which can be boiled down to a simple set of pedagogical instructions. A number of sites have done full-fledged format conversions, and are reportedly quite happy with the results. Feel free to ask in the comp.mail.imap newsgroup or the imap-uw mailing list for advice or help. _________________________________________________________________ 4.6 How do I set up shared mailboxes? At the simplest level, a shared mailbox is one which has UNIX file and directory protections which permit multiple users to access it. What this means is that your existing skills and tools to create and manage shared files on your UNIX system apply to shared mailboxes; e.g. chmod 666 mailbox You may want to consider the use of a mailbox format which permits multiple simultaneous read/write sessions, such as the mbx format. The traditional UNIX format only allows one read/write session to a mailbox at a time. An additional convenience item are three system directories, which can be set up for shared namespaces. These are: #ftp, #shared, and #public, and are defined by creating the associated UNIX users and home directories as described below. #ftp/ refers to the anonymous ftp filesystem exported by the ftp server, and is equivalent to the home directory for UNIX user "ftp". For example, #ftp/foo/bar refers to the file /foo/bar in the anonymous FTP filesystem, or ~ftp/foo/bar for normal users. Anonymous FTP files are available to anonymous IMAP logins. By default, newly-created files in #ftp/ are protected 644. #public/ refers to an IMAP toolkit convention called "public" files, and is equivalent to the home directory for UNIX user "imappublic". For example, #public/foo/bar refers to the file ~imappublic/foo/bar. Public files are available to anonymous IMAP logins. By default, newly-created files in #public are created with protection 0666. #shared/ refers to an IMAP toolkit convention called "shared" files, and is equivalent to the home directory for UNIX user "imapshared". For example, #shared/foo/bar refers to the file ~imapshared/foo/bar. Shared files are not available to anonymous IMAP logins. By default, newly-created files in #shared are created with protection 0660. _________________________________________________________________ 4.7 How can I make the server syslogs go to someplace other than the mail syslog? The openlog() call that sets the syslog facility is in src/osdep/unix/env_unix.c in routine server_init(). You need to edit this file to change the syslog facility from LOG_MAIL to the facility you want, then rebuild. You also need to set up your /etc/syslog.conf properly. Refer to the man pages for syslog and syslogd for more information on what the available syslog facilities are and how to configure syslogs. If you still don't understand what to do, find a UNIX system expert. _________________________________________________________________ 5. Security Questions _________________________________________________________________ 5.1 I see that the IMAP server allows access to arbitary files on the system, including /etc/passwd! How do I disable this? You should not worry about this if your IMAP users are allowed shell access. The IMAP server does not permit any access that the user can not have via the shell. If, and only if, you deny your IMAP users shell access, you may want to consider one of three choices. Note that these choices reduce IMAP functionality, and may have undesirable side effects. Each of these choices involves an edit to file src/osdep/unix/env_unix.c The first (and recommended) choice is to set restrictBox as described in file CONFIG. This will disable access to the filesystem root, to other users' home directory, and to superior directory. The second (and strongly NOT recommended) choice is to set closedBox as described in file CONFIG. This puts each IMAP session into a so-called "chroot jail", and thus setting this option is extremely dangerous; it can make your system much less secure and open to root compromise attacks. So do not use this option unless you are absolutely certain that you understand all the issues of a "chroot jail." The third choice is to rewrite routine mailboxfile() to implement whatever mapping from mailbox name to filesystem name (and restrictions) that you wish. This is the most general choice. As a guide, you can see at the start of routine mailboxfile() what the restrictBox choice does. _________________________________________________________________ 5.2 I've heard that IMAP servers are insecure. Is this true? There are no known security problems in this version of the IMAP toolkit, including the IMAP and POP servers. The IMAP and POP servers limit what can be done while not logged in, and as part of the login process discard all privileges except those of the user. As with other software packages, there have been buffer overflow vulnerabilities in past versions. All known problems of this nature are fixed in this version. There is every reason to believe that the bad guys are engaged in an ongoing effort to find vulnerabilities in the IMAP toolkit. We look for such problems, and when one is found we fix it. It's unfortunate that any vulnerabilities existed in past versions, and we're doing my best to keep the IMAP toolkit free of vulnerabilities. No new vulnerabilities have been discovered in quite a while, but efforts will not be relaxed. Beware of vendors who claim that their implementations can not have vulnerabilities. _________________________________________________________________ 5.3 How do I know that I have the most secure version of the server? The best way is to keep your server software up to date. The bad guys are always looking for ways to crack software, and when they find one, let all their friends know. Oldtimers used to refer to a concept of software rot: if your software hasn't been updated in a while, it would "rot" -- tend to acquire problems that it didn't have when it was new. The latest release version of the IMAP toolkit is always available at ftp://ftp.cac.washington.edu/mail/imap.tar.Z _________________________________________________________________ 5.4 I see all these strcpy() and sprintf() calls, those are unsafe, aren't they? Yes and no. It can be unsafe to do these calls if you do not know that the string being written will fit in the buffer. However, they are perfectly safe if you do know that. Beware of programmers who advocate doing a brute-force change of all instances of strcpy (s,t); to strncpy (s,t,n)[n] = '\0'; and similar measures in the name of "fixing all possible buffer overflows." There are examples in which a security bug was introduced because of this type of "fix", due to the programmer using the wrong value for n. In one case, the programmer thought that n was larger than it actually was, causing a NUL to be written out of the buffer; in another, n was too small, and a security credential was truncated. What is particularly ironic was that in both cases, the original strcpy() was safe, because the size of the source string was known to be safe. With all this in mind, the software has been inspected, and it is believed that all places where buffer overflows can happen have been fixed. The strcpy()s that are still are in the code occur after a size check was done in some other way. Note that the common C idiom of *s++ = c; is just as vulnerable to buffer overflows. You can't cure buffer overflows by outlawing certain functions, nor is it desirable to do so; sometimes operations like strcpy() translate into fast machine instructions for better performance. Nothing replaces careful study of code. That's how the bad guys find bugs. Security is not accomplished by means of brute-force shortcuts. _________________________________________________________________ 5.5 Those /tmp lock files are protected 666, is that really right? Yes. Shared mailboxes won't work otherwise. Also, you get into accidental denial of service problems with old lock files left lying around; this happens fairly frequently. The deliberate mischief that can be caused by fiddling with the lock files is small-scale; harassment level at most. There are many -- and much more effective -- other ways of harassing another user on UNIX. It's usually not difficult to determine the culprit. Before worrying about deliberate mischief, worry first about things happening by accident! _________________________________________________________________ 6. Why Did You Do This Strange Thing? Questions _________________________________________________________________ 6.1 Why don't you use GNU autoconfig / automake / autoblurdybloop? Autoconfig et al are not available on all the platforms where the IMAP toolkit is supported; and do not work correctly on some of the platforms where they do exist. Furthermore, these programs add another layer of complexity to an already complex process. Coaxing software that uses autoconfig to build properly on platforms which were not specifically considered by that software wastes an inordinate amount of time. When (not if) autoconfig fails to do the right thing, the result is an inpenetrable morass to untangle in order to find the problem and fix it. The concept behind autoconfig is good, but the execution is flawed. It rarely does the right thing on a platform that wasn't specifically considered. Human life is too short to debug autoconfig problems, especially since the current mechanism is so much easier. _________________________________________________________________ 6.2 Why do you insist upon a build with -g? Doesn't it waste disk and memory space? From time to time a submitted port has snuck in without -g. This has always ended up causing problems. There are only two valid excuses for not using -g in a port: + The compiler does not support -g + An alternate form of -g is needed with optimization, e.g. -g3. There will be no new ports added without -g (or a suitable alternative) being set. -g has not been arbitrarily added to the ports which do not currently have it because we don't know if doing so would break the build. However, any support issues with one of those port will lead to the correct -g setting being determined and permanently added. Processors are fast enough (and disk space is cheap enough) that -g should be automatic in all compilers with no way of turning it off, and /bin/strip should be a symlink to /bin/true. Human life is too short to deal with binaries built without -g. Such binaries should be a bad memory of the days of KIPS processors and disks that costs several dollars per kilobyte. _________________________________________________________________ 6.3 Why don't you make c-client a shared library? All too often, shared libraries create far more problems than they solve. Remember that you only gain the benefit of a shared library when there are multiple applications which use that shared library. Even without shared libraries, on most modern operating systems (and many ancient ones too!) applications will share their text segments between across multiple processes running the same application. This means that if your system only runs one application (e.g. imapd) that uses the c-client library, then you gain no benefit from making c-client a shared library even if it has 100 imapd processes. You will, however suffer added complexity. If you have a server system that just runs imapd and ipop3d, then making c-client a shared library will save just one copy of c-client no matter how many IMAP/POP3 processes are running. The problem with shared libraries is that you have to keep around a copy of the library every time something changes in the library that would affect the interface the library presents to the application. So, you end up having many copies of the same shared library. If you don't keep multiple copies of the shared library, then one of two things happens. If there was proper versioning, then you'll get a message such as "cannot open shared object file" or "minor versions don't match" and the application won't run. Otherwise, the application will run, but will fail in mysterious ways. Several sites and third-party distributors have modified the c-client makefile in order to make c-client be a shared library. When (not if) a c-client based application fails in mysterious ways because of a library compatibility problem, the result is a bug report. A lot of time and effort ends up getting wasted investigating such bug reports. Memory is so cheap these days that it's not worth it. Human life is too short to deal with shared library compatibility problems. _________________________________________________________________ 6.4 Why don't you use iconv() for internationalization support? iconv() is not ubiquitous enough. _________________________________________________________________ 6.5 Why is the IMAP server connected to the home directory by default? The IMAP server has no way of knowing what you might call "mail" as opposed to "some other file"; in fact, you can use IMAP to access any file. The IMAP server also doesn't know whether your preferred subdirectory for mailbox files is "mail/", ".mail/", "Mail/", "Mailboxes/", or any of a zillion other possibilities. If one such name were chosen, it would undoubtably anger the partisans of all the other names. It is possible to modify the software so that the default connected directory is someplace else. Please read the file CONFIG for discussion of this and other issues. _________________________________________________________________ 6.6 I have a Windows system. Why isn't the server plug and play for me? There is no standard for how mail is stored on Windows; nor a single standard SMTP server. The closest to either would be the SMTP server in Microsoft's IIS. So there's no default by which to make assumptions. As the software is set up, it assumes that the each user has an Windows login account and private home directory, and that mail is stored on that home directory as files in one of the popular UNIX formats. It also assumes that there is some tool equivalent to inetd on UNIX that does the TCP/IP listening and server startup. Basically, unless you're an email software hacker, you probably want to look elsewhere if you want IMAP/POP servers for Windows. _________________________________________________________________ 6.7 I looked at the UNIX SSL code and saw that you have the SSL data payload size set to 8192 bytes. SSL allows 16K; why aren't you using the full size? This is to avoid an interoperability problem with: + PC IMAP clients that use Microsoft's SChannel.DLL (SSPI) for SSL support + Microsoft Exchange server (which also uses SChannel). SChannel has a bug that makes it think that the maximum SSL data payload size is 16379 bytes -- 5 bytes too small. Thus, c-client has to make sure that it never transmits full sized SSL packets. The reason for using 8K (as opposed to, say, 16379 bytes, or 15K, or...) is that it corresponds with the TCP buffer size that the software uses elsewhere for input; there's a slight performance benefit to having the two sizes correspond or at least be a multiple of each other. Also, it keeps the size as a power of two, which might be significant on some platforms. There wasn't a significant difference that we could measure between 8K and 15K. Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which implies that this is a Pine issue, this bug also affects Microsoft Exchange server with any client that transmits full-sized SSL payloads. _________________________________________________________________ 6.8 Why is an mh format INBOX called #mhinbox instead of just INBOX? It's a long story. In brief, the mh format driver is less functional than any of the other drivers. It turned out that there were some users (including high-level administrators) who tried mh years ago and no longer use it, but still had an mh profile left behind. When the mh driver used INBOX, it would see the mh profile, and proceed to move the user's INBOX into the mh format INBOX. This caused considerable confusion as some things stopped working. _________________________________________________________________ 6.9 Why don't you support the maildir format? It is technically difficult to support maildir in IMAP while maintaining acceptable performance, robustness, following the requirements of the IMAP protocol specification, and following the requirements of maildir. No one has succeeded in accomplishing all four together. The various maildir drivers offered as patches all have these problems. The problem is exacerbated because this implementation supports multiple formats; consequently this implementation can't make any performance shortcuts by assuming that all the world is maildir. We can't do a better job than the maildir fan community has done with their maildir drivers. Similarly, if the maildir fan community provides the maildir driver, they take on the responsibility for answering maildir-specific support questions. This is as it should be, and that is why maildir support is left to the maildir fan community. _________________________________________________________________ 6.10 Why don't you support the Cyrus format? There's no point to doing so. An implementation which supports multiple formats will never do as well as one which is optimized to support one single format. If you want to use Cyrus mailbox format, you should use the Cyrus server, which is the native implementation of that format and is specifically optimized for that format. That's also why Cyrus doesn't implement any other format. _________________________________________________________________ 6.11 Why is it creating extra forks on my SVR4 system? This is because your system only has fcntl() style locking and not flock() style locking. fcntl() locking has a design flaw that causes a close() to release any locks made by that process on the file opened on that file descriptor, even if the lock was made on a different file descriptor. This design flaw causes unexpected loss of lock, and consequent mailbox corruption. The workaround is to do certain "dangerous operations" in another fork, thus avoiding doing a close() in the vulnerable fork. The best way to solve this problem is to upgrade your SVR4 (Solaris, AIX, HP-UX, SGI) or OSF/1 system to a more advanced operating system, such as Linux or BSD. These more advanced operating systems have fcntl() locking for compatibility with SVR4, but also have flock() locking. Beware of certain SVR4 systems, such as AIX, which have an "flock()" function in their C library that is just a jacket that does an fcntl() lock. This is not a true flock(), and has the same design flaw as fcntl(). _________________________________________________________________ 6.12 Why are you so fussy about the date/time format in the internal "From " line in traditional UNIX mailbox files? My other mail program just considers every line that starts with "From " to be the start of the message. You just answered your own question. If any line that starts with "From " is treated as the start of a message, then every message text line which starts with "From " has to be quoted (typically by prefixing a ">" character). People complain about this -- "why did a > get stuck in my message?" So, good mail reading software only considers a line to be a "From " line if it follows the actual specification for a "From " line. This means, among other things, that the day of week is fixed-format: "May 14", but "May 7" (note the extra space) as opposed to "May 7". ctime() format for the date is the most common, although POSIX also allows a numeric timezone after the year. For compatibility with ancient software, the seconds are optional, the timezone may appear before the year, the old 3-letter timezones are also permitted, and "remote from xxx" may appear after the whole thing. Unfortunately, some software written by novices use other formats. The most common error is to have a variable-width day of month, perhaps in the erroneous belief that RFC 2822 (or RFC 822) defines the format of the date/time in the "From " line (it doesn't; no RFC describes internal formats). I've seen a few other goofs, such as a single-digit second, but these are less common. If you are writing your own software that writes mailbox files, and you really aren't all that savvy with all the ins and outs and ancient history, you should seriously consider using the c-client library (e.g. routine mail_append()) instead of doing the file writes yourself. If you must do it yourself, use ctime(), as in: fprintf (mbx,"From %s@%h %s",user,host,ctime (time (0))); rather than try to figure out a good format yourself. ctime() is the most traditional format and nobody will flame you for using it. _________________________________________________________________ 6.13 Why is traditional UNIX format the default format? Compatibility with the past 30 or so years of UNIX history. This server is the only one that completely interoperates with legacy UNIX mail tools. _________________________________________________________________ 6.14 Why do you write this "DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA" message at the start of traditional UNIX and MMDF format mailboxes? This pseudo-message serves two purposes. First, it establishes the mailbox format even when the mailbox has no messages. Otherwise, a mailbox with no messages is a zero-byte file, which could be one of several formats. Second, it holds mailbox metadata used by IMAP: the UID validity, the last assigned UID, and mailbox keywords. Without this metadata, which must be preserved even when the mailbox has no messages, the traditional UNIX format wouldn't be able to support the full capabilities of IMAP. _________________________________________________________________ 6.15 Why don't you stash the mailbox metadata in the first real message of the mailbox instead of writing this fake FOLDER INTERNAL DATA message? In fact, that is what is done if the mailbox is non-empty and does not already have a FOLDER INTERNAL DATA message. One problem with doing that is that if some external program removes the first message, the metadata is lost and must be recreated, thus losing any prior UID or keyword list status that IMAP clients may depend upon. Another problem is that this doesn't help if the last message is deleted. This will result in an empty mailbox, and the necessity to create a FOLDER INTERNAL DATA message. _________________________________________________________________ 6.16 Why aren't "dual-use" mailboxes the default? Compatibility with the past 30 or so years of UNIX history, not to mention compatibility with user expectations when using shell tools. _________________________________________________________________ 6.17 Why do you use ucbcc to build on Solaris? It is a long, long story about why cc is set to ucbcc. You need to invoke the C compiler so that it links with the SVR4 libraries and not the BSD libraries, otherwise readdir() will return the wrong information. Of all the names in the most common path, ucbcc is the only name to be found (on /usr/ccs/bin) that points to a suitable compiler. cc is likely to be /usr/ucb/cc which is absolutely not the compiler that you want. The real SVR4 cc is probably something like /opt/SUNWspro/bin/cc which is rarely in anyone's path by default. ucbcc is probably a link to acc, e.g. /opt/SUNWspro/SC4.0/bin/acc, and is the UCB C compiler using the SVR4 libraries. If ucbcc isn't on your system, then punt on the SUN C compiler and use gcc instead (the gso port instead of the sol port). If, in spite of all the above warnings, you choose to change "ucbcc" to "cc", you will probably find that the -O2 needs to be changed to -O. If you don't get any error messages with -O2, that's a pretty good indicator that you goofed and are running the compiler that will link with the BSD libraries. To recap: + The sol port is designed to be built using the UCB compiler using the SVR4 libraries. This compiler is "ucbcc", which is lunk to acc. You use -O2 as one of the CFLAGS. + If you build the sol port with the UCB compiler using the BSD libraries, you will get no error messages but you will get bad binaries (the most obvious symptom is dropping the first two characters return filenames from the imapd LIST command. This compiler also uses -O2, and is very often what the user gets from "cc". BEWARE + If you build the sol port with the real SVR4 compiler, which is often hidden away or unavailable on many systems, then you will get errors from -O2 and you need to change that to -O. But you will get a good binary. However, you should try it with -O2 first, to make sure that you got this compiler and not the UCB compiler using BSD libraries. _________________________________________________________________ 6.18 Why should I care about some old system with BSD libraries? cc is the right thing on my Solaris system! Because there still are sites that use such systems. On those systems, the assumption that "cc" does the right thing will lead to corrupt binaries with no error message or other warning that anything is amiss. Too many sites have fallen victim to this problem. _________________________________________________________________ 6.19 Why do you insist upon writing .lock files in the spool directory? Compatibility with the past 30 years of UNIX software which deals with the spool directory, especially software which delivers mail. Otherwise, it is possible to lose mail. _________________________________________________________________ 6.20 Why should I care about compatibility with the past? This is one of those questions in which the answer never convinces those who ask it. Somehow, everybody who ever asks this question ends up answering it for themselves as they get older, with the very answer that they rejected years earlier. _________________________________________________________________ 7. Problems and Annoyances _________________________________________________________________ 7.1 Help! My INBOX is empty! What happened to my messages? If you are seeing "0 messages" when you open INBOX and you know you have messages there (and perhaps have looked at your mail spool file and see that messages are there), then probably there is something wrong with the very first line of your mail spool file. Make sure that the first five bytes of the file are "From ", followed by an email address and a date/time in ctime() format, e.g.: From fred@foo.bar Mon May 7 20:54:30 2001 _________________________________________________________________ 7.2 Help! All my messages in a non-INBOX mailbox have been concatenated into one message which claims to be from me and has a subject of the file name of the mailbox! What's going on? Something wrong with the very first line of the mailbox. Make sure that the first five bytes of the file are "From ", followed by an email address and a date/time in ctime() format, e.g.: From fred@foo.bar Mon May 7 20:54:30 2001 _________________________________________________________________ 7.3 Why do I get the message: CREATE failed: Can't create mailbox node xxxxxxxxx: File exists and how do I fix it? See the answer to the Are hierarchical mailboxes supported? question. _________________________________________________________________ 7.4 Why can't I log in to the server? The user name and password are right! There are a myriad number of possible answers to this question. The only way to say for sure what is wrong is run the server under a debugger such as gdb while root (yes, you must be root) with a breakpoint at routines checkpw() and loginpw(), then single-step until you see which test rejected you. The server isn't going to give any error messages other than "login failed" in the name of not giving out any unnecessary information to unauthorized individuals. Here are some of the more common reasons why login may fail: + You didn't really give the correct user name and/or password. + Your client doesn't send the LOGIN command correctly; for example, IMAP2 clients won't send a password containing a "*" correctly to an IMAP4 server. + If you have set up a CRAM-MD5 database, remember that the password used is the one in the CRAM-MD5 database, and furthermore that there must also be an entry in /etc/passwd (but the /etc/passwd password is not used). + If you are using PAM, have you created a service file for the server in /etc/pam.d? + If you are using shadow passwords, have you used an appropriate port when building? In particular, note that "lnx" is for Linux systems without shadow passwords; you probably want "slx" or "lnp" instead. + If your system has account or password expirations, check to see that the expiration date hasn't passed. + You can't log in as root or any other UID 0 user. This is for your own safety, not to mention the fact that the servers use UID 0 as meaning "not logged in". _________________________________________________________________ 7.5 Help! My load average is soaring and I see hundreds of POP and IMAP servers, many logged in as the same user! Certain inferior losing GUI mail reading programs have a "synchronize all mailboxes at startup" (IMAP) or "check for new mail every second" (POP) feature which causes a rapid and unchecked spawning of servers. This is not a problem in the server; the client is really asking for all those server sessions. Unfortunately, there isn't much that the POP and IMAP servers can do about it; they don't spawned themselves. Some sites have added code to record the number of server sessions spawned per user per hour, and disable login for a user who has exceeded a predetermined rate. This doesn't stop the servers from being spawned; it just means that a server session will commit suicide a bit faster. Another possibility is to detect excessive server spawning activity at the level where the server is spawned, which would be inetd or possibly tcpd. The problem here is that this is a hard time to quantify. 50 sessions in a minute from a multi-user timesharing system may be perfectly alright, whereas 10 sessions a minute from a PC may be too much. The real solution is to fix the client configuration, by disabling those evil features. Also tell the vendors of those clients how you feel about distributing denial-of-service attack tools in the guise of mail reading programs. _________________________________________________________________ 7.6 Why does mail disappear even though I set "keep mail on server"? 7.7 Why do I get the message Moved ##### bytes of new mail to /home/user/mbox from /var/spool/mail/user and why did this happen? This is probably caused by the mbox driver. 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. Note that if you do this, users won't be able to access the messages that have already been moved to mbox unless they open mbox instead of INBOX. _________________________________________________________________ 7.8 Why isn't it showing the local host name as a fully-qualified domain name? 7.9 Why is the local host name in the From/Sender/Message-ID headers of outgoing mail not coming out as a fully-qualified domain name? Your UNIX system is misconfigured. The entry for your system in /etc/hosts must have the fully-qualified domain name first, e.g. 105.69.1.234 myserver.example.com myserver A common mistake of novice system administrators is to have the short name first, e.g. 105.69.1.234 myserver myserver.example.com or to omit the fully qualified domain name entirely, e.g. 105.69.1.234 myserver The result of this is that when the IMAP toolkit does a gethostbyname() call to get the fully-qualified domain name, it would get "myserver" instead of "myserver.example.com". On some systems, a configuration file (typically named /etc/svc.conf, /etc/netsvc.conf, or /etc/nsswitch.conf) can be used to configure the system to use the domain name system (DNS) instead of /etc/hosts, so it doesn't matter if /etc/hosts is misconfigured. Check the man pages for gethostbyname, hosts, svc, and/or netsvc for more information. Unfortunately, certain vendors, most notably SUN, have failed to make this clear in their documentation. Most of SUN's documentation assumes a corporate network that is not connected to the Internet. net.folklore once (late 1980s) held that the proper procedure was to append the results of getdomainname() to the name returned by gethostname(), and some versions of sendmail configuration files were distributed that did this. This was incorrect; the string returned from getdomainname() is the Yellow Pages (a.k.a NIS) domain name, which is a completely different (albeit unfortunately named) entity from an Internet domain. These were often fortuitously the same string, except when they weren't. Frequently, this would result in host names with spuriously doubled domain names, e.g. myserver.example.com.example.com This practice has been thoroughly discredited for many years, but folklore dies hard. _________________________________________________________________ 7.10 What does the message: Mailbox vulnerable - directory /var/spool/mail must have 1777 protection mean? How can I fix this? In order to update a mailbox in the default UNIX format, it is necessary to create a lock file to prevent the mailer from delivering mail while an update is in progress. Some systems use a directory protection of 775, requiring that all mail handling programs be setgid mail; or of 755, requiring that all mail handling programs be setuid root. The IMAP toolkit does not run with any special privileges, and I plan to keep it that way. It is antithetical to the concept of a toolkit if users can't write their own programs to use it. Also, I've had enough bad experiences with security bugs while running privileged; the IMAP and POP servers have to be root when not logged in, in order to be able to log themselves in. I don't want to go any deeper down that slippery slope. Directory protection 1777 is secure enough on most well-managed systems. If you can't trust your users with a 1777 mail spool (petty harassment is about the limit of the abuse exposure), then you have much worse problems then that. If you absolutely insist upon requiring privileges to create a lock file, external file locking can be done via a setgid mail program named /etc/mlock (this is defined by LOCKPGM in the c-client Makefile). If the toolkit is unable to create a <...mailbox...>.lock file in the directory by itself, it will try to call mlock to do it. I do not recommend doing this for performance reasons. A sample mlock program is included as part of imap-2007. We have tried to make this sample program secure, but it has not been thoroughly audited. _________________________________________________________________ 7.11 What does the message: Mailbox is open by another process, access is readonly mean? How do I fix this? A problem occurred in applying a lock to a /tmp lock file. Either some other program has the mailbox open and won't relenquish it, or something is wrong with the protection of /tmp or the lock. Make sure that the /tmp directory is protected 1777. Some security scripts incorrectly set the protection of the /tmp directory to 775, which disables /tmp for all non-privileged programs. _________________________________________________________________ 7.12 What does the message: Can't get write access to mailbox, access is readonly mean? The mailbox file is write-protected against you. _________________________________________________________________ 7.13 I set my POP3 client to "delete messages from server" but they never get deleted. What is wrong? Make sure that your mailbox is not read-only: that the mailbox is owned by you and write enabled (protection 0600), and that the /tmp directory is longer world-writeable. /tmp must be world-writeable because lots of applications use it for scratch space. To fix this, do chmod 1777 /tmp as root. Make sure that your POP3 client issues a QUIT command when it finishes. The POP3 protocol specifies that deletions are discarded unless a proper QUIT is done. Make sure that you are not opening multiple POP3 sessions to the same mailbox. It is a requirement of the POP3 protocol than only one POP3 session be in effect to a mailbox at a time, however some, poorly-written POP3 clients violate this. Also, some background "check for new mail" tasks also cause a violation. See the answer to the What does the syslog message: Killed (lost mailbox lock) user=... host=... mean? question for more details. _________________________________________________________________ 7.14 What do messages such as: Message ... UID ... already has UID ... Message ... UID ... less than ... Message ... UID ... greater than last ... Invalid UID ... in message ..., rebuilding UIDs mean? Something happened to corrupt the unique identifier regime in the mailbox. In traditional UNIX-format mailboxes, this can happen if the user deleted the "DO NOT DELETE" internal message. This problem is relatively harmless; a new valid unique identifier regime will be created. The main effect is that any references to the old UIDs will no longer be useful. So, unless it is a chronic problem or you feel like debugging, you can safely ignore these messages. _________________________________________________________________ 7.15 What do the error messages: Unable to read internal header at ... Unable to find CRLF at ... Unable to parse internal header at ... Unable to parse message date at ... Unable to parse message flags at ... Unable to parse message UID at ... Unable to parse message size at ... Last message (at ... ) runs past end of file ... mean? I am using mbx format. The mbx-format mailbox is corrupted and needs to be repaired. You should make an effort to find out why the corruption happened. Was there an obvious system problem (crash or disk failure)? Did the user accidentally access the file via NFS? Mailboxes don't get corrupted by themselves; something caused the problem. Some people have developed automated scripts, but if you're comfortable using emacs it's pretty easy to fix it manually. Do not use vi or any other editor unless you are certain that editor can handle binary!!! If you are not comfortable with emacs, or if the file is too large to read with emacs, see the "step-by-step" technique later on for another way of doing it. After the word "at" in the error message is the byte position it got to when it got unhappy with the file, e.g. if you see: Unable to parse internal header at 43921: ne bombastic blurdybloop The problem occurs at the 43,931 byte in the file. That's the point you need to fix. c-client is expecting an internal header at that byte number, looking something like: 6-Jan-1998 17:42:24 -0800,1045;000000100001-00000001 The format of this internal line is: dd-mmm-yyyy hh:mm:ss +zzzz,ssss;ffffffffFFFF-UUUUUUUU The only thing that is variable is the "ssss" field, it can be as many digits as needed. All other fields (inluding the "dd") are fixed width. So, the easiest thing to do is to look forward in the file for the next internal header, and delete everything from the error point to that internal header. Here's what to do if you want to be smarter and do a little bit more work. Generally, you're in the middle of a message, and there's nothing wrong with that message. The problem happened in the *previous* message. So, search back to the previous internal header. Now, remember that "ssss" field? That's the size of that message. Mark where you are in the file, move the cursor to the line after the internal header, and skip that many bytes ("ssss") forward. If you're at the point of the error in the file, then that message is corrupt. If you're at a different point, then perhaps the previous message is corrupt and has a too long size count that "ate" into this message. Basically, what you need to do is make sure that all those size counts are right, and that moving "ssss" bytes from the line after the internal header will land you at another internal header. Usually, once you know what you're looking at, it's pretty easy to work out the corruption, and the best remedial action. Repair scripts will make the problem go away but may not always do the smartest/best salvage of the user's data. Manual repair is more flexible and usually preferable. Here is a step-by-step technique for fixing corrupt mbx files that's a bit cruder than the procedure outlined above, but works for any size file. In this example, suppose that the corrupt file is INBOX, the error message is Unable to find CRLF at 132551754 and the size of the INBOX file is 132867870 bytes. The first step is to split the mailbox file at the point of the error: + Rename the INBOX file to some other name, such as INBOX.bad. + Copy the first 132,551,754 bytes of INBOX.bad to another file, such as INBOX.new. + Extract the trailing 316,116 bytes (132867870-132551754) of INBOX.bad into another file, such as INBOX.tail. + You no longer need INBOX.bad. Delete it. In other words, use the number from the "Unable to find CRLF at" as the point to split INBOX into two new files, INBOX.new and INBOX.tail. Now, remove the erroneous data: + Verify that you can open INBOX.new in IMAP or Pine. + The last message of INBOX.new is probably corrupted. Copy it to another file, such as badmsg.1, then delete and expunge that last message from INBOX.new + Locate the first occurance of text in INBOX.tail which looks like an internal header, as described above. + Remove all the text which occurs prior to that point, and place it into another file, such as badmsg.2. Note that in the case of a single digit date, there is a leading space which must not be removed (e.g. " 6-Nov-2001" not "6-Nov-2001"). Reassemble the mailbox: + Append INBOX.tail to INBOX.new. + You no longer need INBOX.tail. Delete it. + Verify that you can open INBOX.new in IMAP or Pine. Reinstall INBOX.new as INBOX: + Check to see if you have received any new messages while repairing INBOX. + If you haven't received any new messages while repairing INBOX, just rename INBOX.new to INBOX. + If you have received new messages, be sure to copy the new messages from INBOX to INBOX.new before doing the rename. You now have a working INBOX, as well as two files with corrupted data (badmsg.1 and badmsg.2). There may be some useful data in the two badmsg files that you might want to try salvaging; otherwise you can delete the two badmsg files. _________________________________________________________________ 7.16 What do the syslog messages: imap/tcp server failing (looping) pop3/tcp server failing (looping) mean? When it happens, the listed service shuts down. How can I fix this? The error message "server failing (looping), service terminated" is not from either the IMAP or POP servers. Instead, it comes from inetd, the daemon which listens for TCP connections to a number of servers, including the IMAP and POP servers. inetd has a limit of 40 new server sessions per minute for any particular service. If more than 40 sessions are initiated in a minute, inetd will issue the "failing (looping), service terminated" message and shut down the service for 10 minutes. inetd does this to prevent system resource consumption by a client which is spawning infinite numbers of servers. It should be noted that this is a denial of service; however for some systems the alternative is a crash which would be a worse denial of service! For larger server systems, the limit of 40 is much too low. The limit was established many years ago when a system typically only ran a few dozen servers. On some versions of inetd, such as the one distributed with most versions of Linux, you can modify the /etc/inetd.conf file to have a larger number of servers by appending a period followed by a number after the nowait word for the server entry. For example, if your existing /etc/inetd.conf line reads: imap stream tcp nowait root /usr/etc/imapd imapd try changing it to be: imap stream tcp nowait.100 root /usr/etc/imapd imapd Another example (using TCP wrappers): imap stream tcp nowait root /usr/sbin/tcpd imapd try changing it to be: imap stream tcp nowait.100 root /usr/sbin/tcpd imapd to increase the limit to 100 sessions/minute. Before making this change, please read the information in "man inetd" to determine whether or not your inetd has this feature. If it does not, and you make this change, the likely outcome is that you will disable IMAP service entirely. Another way to fix this problem is to edit the inetd.c source code (provided by your UNIX system vendor) to set higher limits, rebuild inetd, install the new binary, and reboot your system. This should only be done by a UNIX system expert. In the inetd.c source code, the limits TOOMANY (normally 40) is the maximum number of new server sessions permitted per minute, and RETRYTIME (normally 600) is the number of seconds inetd will shut down the server after it exceeds TOOMANY. _________________________________________________________________ 7.17 What does the syslog message: Mailbox lock file /tmp/.600.1df3 open failure: Permission denied mean? This usually means that some "helpful" security script person has protected /tmp so that it is no longer world-writeable. /tmp must be world-writeable because lots of applications use it for scratch space. To fix this, do chmod 1777 /tmp as root. If that isn't the answer, check the protection of the named file. If it is something other than 666, then either someone is hacking or some "helpful" person modified the code to have a different default lock file protection. _________________________________________________________________ 7.18 What do the syslog messages: Command stream end of file, while reading line user=... host=... Command stream end of file, while reading char user=... host=... Command stream end of file, while writing text user=... host=... mean? This message occurs when the session is disconnected without a proper LOGOUT (IMAP) or QUIT (POP) command being received by the server first. In many cases, this is perfectly normal; many client implementations are impolite and do this. Some programmers think this sort of rudeness is "more efficient". The condition could, however, indicate a client or network connectivity problem. The server has no way of knowing whether there's a problem or just a rude client, so it issues this message instead of a Logout. Certain inferior losing clients disconnect abruptly after a failed login, and instead of saying that the login failed, just say that they can't access the mailbox. They then complain to the system manager, who looks in the syslog and finds this message. Not very helpful, eh? See the answer to the Why can't I log in to the server? The user name and password are right! question. If the user isn't reporting a problem, you can probably ignore this message. _________________________________________________________________ 7.19 Why did my POP or IMAP session suddenly disconnect? The syslog has the message: Killed (lost mailbox lock) user=... host=... This message only happens when either the traditional UNIX mailbox format or MMDF format is in use. This format only allows one session to have the mailbox open read/write at a time. The servers assume that if a second session attempts to open the mailbox, that means that the first session is probably owned by an abandoned client. The common scenario here is a user who leaves his client running at the office, and then tries to read his mail from home. Through an internal mechanism called kiss of death, the second session requests the first session to kill itself. When the first session receives the "kiss of death", it issues the "Killed (lost mailbox lock)" syslog message and terminates. The second session then seizes read/write access, and becomes the new "first" session. Certain poorly-designed clients routinely open multiple sessions to the same mailbox; the users of those clients tend to get this message a lot. Another cause of this message is a background "check for new mail" task which does its work by opening a POP session to server every few seconds. They do this because POP doesn't have a way to announce new mail. The solution to both situations is to replace the client with a good online IMAP client such as Pine. Life is too short to waste on POP clients and poorly-designed IMAP clients. _________________________________________________________________ 7.20 Why does my IMAP client show all the files on the system, recursively from the UNIX root directory? 7.21 Why does my IMAP client show all of my files, recursively from my UNIX home directory? A well-written client should only show one level of hierarchy and then stop, awaiting explicit user action before going lower. However, some poorly-designed clients will recursively list all files, which may be a very long list (especially if you have symbolic links to directories that create a loop in the filesystem graph!). This behavior has also been observed in some third-party c-client drivers, including maildir drivers. Consequently, this problem has even been observed in Pine. It is important to understand that this is not a problem in Pine or c-client; it is a problem in the third-party driver. A Pine built without that third-party driver will not have this problem. See also the answer to Why does my IMAP client show all my files in my home directory? _________________________________________________________________ 7.22 Why does my IMAP client show that I have mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and "#public"? These are IMAP namespace names. They represent other hierarchies in which messages may exist. These hierarchies may not necessarily exist on a server, but the namespace name is still in the namespace list in order to mark it as reserved. A few poorly-designed clients display all namespace names as if they were top-level mailboxes in a user's list of mailboxes, whether or not they actually exist. This is a flaw in those clients. _________________________________________________________________ 7.23 Why does my IMAP client show all my files in my home directory? As distributed, the IMAP server is connected to your home directory by default. It has no way of knowing what you might call "mail" as opposed to "some other file"; in fact, you can use IMAP to access any file. Most clients have an option to configure your connected directory on the IMAP server. For example, in Pine you can specify this as the "Path" in your folder-collection, e.g. Nickname : Secondary Folders Server : imap.example.com Path : mail/ View : In this example, the user is connected to the "mail" subdirectory of his home directory. Other servers call this the "folder prefix" or similar term. It is possible to modify the IMAP server so that all users are automatically connected to some other directory, e.g. a subdirectory of the user's home directory. Read the file CONFIG for more details. _________________________________________________________________ 7.24 Why is there a long delay before I get connected to the IMAP or POP server, no matter what client I use? There are two common occurances of this problem: + You are running a system (e.g. certain versions of Linux) which by default attempts to connect to an "IDENT" protocol (port 113) server on your client. However, a firewall or NAT box is blocking connections to that port, so the connection attempt times out. The IDENT protocol is a well-known bad idea that does not deliver any real security but causes incredible problems. The idea is that this will give the server a record of the user name, or at least what some program listening on port 113 says is the user name. So, if somebody coming from port nnnnn on a system does something bad, IDENT may give you the userid of the bad guy. The problem is, IDENT is only meaningful on a timesharing system which has an administrator who is privileged and users who are not. It is of no value on a personal system which has no separate concept of "system administrator" vs. "unprivileged user". On either type of system, security-minded people either turn IDENT off or replace it with an IDENT server that lies. Among other things, IDENT gives spammers the ability to harvest email addresses from anyone who connects to a web page. This problem has been showing up quite frequently on systems which use xinetd instead of inetd. Look for files named /etc/xinetd.conf, /etc/xinetd.d/imapd, /etc/inetd.d/ipop2d, and /etc/xinetd.d/ipop3d. In those files, look for lines containing "USERID", e.g. log_on_success += USERID Hunt down such lines, and delete them ruthlessly from all files in which they occur. Don't be shy about it. + The DNS is taking a long time to do a reverse DNS (PTR record) lookup of the IP address of your client. This is a problem in your DNS, which either you or you ISP need to resolve. Ideally, the DNS should return the client's name; but if it can't it should at least return an error quickly. As you may have noticed, neither of these are actual problems in the IMAP or POP servers; they are configuration issues with either your system or your network infrastructure. If this is all new to you, run (don't walk) to the nearest technical bookstore and get yourself a good pedagogical text on system administration for the type of system you are running. _________________________________________________________________ 7.25 Why is there a long delay in Pine or any other c-client based application call before I get connected to the IMAP server? The hang seems to be in the c-client mail_open() call. I don't have this problem with any other IMAP client. There is no delay connecting to a POP3 or NNTP server with mail_open(). By default, the c-client library attempts to make a connection through rsh (and ssh, if you enable that). If the command: rsh imapserver exec /etc/rimapd (or ssh if that is enabled) returns with a "* PREAUTH" response, it will use the resulting rsh session as the IMAP session and not require an authentication step on the server. Unfortunately, rsh has a design error that treats "TCP connection refused" as "temporary failure, try again"; it expects the "rsh not allowed" case to be implemented as a successful connection followed by an error message and close the connection. It must be emphasized that this is a bug in rsh. It is not a bug in the IMAP toolkit. The use of rsh can be disabled in any the following ways: + You can disable it for this particular session by either: o setting an explicit port number in the mailbox name, e.g. {imapserver.foo.com:143}INBOX o using SSL (the /ssl switch) + You can disable rsh globally by setting the rsh timeout value to 0 with the call: mail_parameters (NIL,SET_RSHTIMEOUT,0); _________________________________________________________________ 7.26 Why does a message sometimes get split into two or more messages on my SUN system? This is caused by an interaction of two independent design problems in SUN mail software. The first problem is that the "forward message" option in SUN's mail tool program includes the internal "From " header line in the text that it forwarded. This internal header line is specific to traditional UNIX mailbox files and is not suitable for use in forwarded messages. The second problem is that the mail delivery agent assumes that mail reading programs will not use the traditional UNIX mailbox format but instead an incompatible variant that depends upon a Content-Length: message header. Content-Length is widely recognized to have been a terrible mistake, and is no longer recommended for use in mail (it is used in other facilities that use MIME). 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 the mailer on 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 This fix will also work around the problem with mail tool, because it will insert a ">" before the internal header line to prevent it from being interpreted by mail reading software as an internal header line. _________________________________________________________________ 7.27 Why did my POP or IMAP session suddenly disconnect? The syslog has the message: Autologout user=<...my user name...> host=<...my client system...> This is a problem in your client. In the case of IMAP, it failed to communicate with the IMAP server for over 30 minutes; in the case of POP, it failed to communicate with the POP server for over 10 minutes. _________________________________________________________________ 7.28 What does the UNIX error message: TLS/SSL failure: myserver: SSL negotiation failed mean? 7.29 What does the PC error message: TLS/SSL failure: myserver: Unexpected TCP input disconnect mean? This usually means that an attempt to negotiate TLS encryption via the STARTTLS command failed, because the server advertises STARTTLS functionality, but doesn't actually have it (e.g. because no certificates are installed). Use the /notls option in the mailbox name to disable TLS negotiation. _________________________________________________________________ 7.30 What does the error message: TLS/SSL failure: myserver: Server name does not match certificate mean? An SSL or TLS session encryption failed because the server name in the server's certificate does not match the name that you gave it. This could indicate that the server is not really the system you think that it is, but can be also be called if you gave a nickname for the server or name that was not fully-qualified. You must use the fully-qualified domain name for the server in order to validate its certificate Use the /novalidate-cert option in the mailbox name to disable validation of the certificate. _________________________________________________________________ 7.31 What does the UNIX error message: TLS/SSL failure: myserver: self-signed certificate mean? 7.32 What does the PC error message: TLS/SSL failure: myserver: Self-signed certificate or untrusted authority mean? An SSL or TLS session encryption failed because your server's certificate is "self-signed"; that is, it is not signed by any Certificate Authority (CA) and thus can not be validated. A CA-signed certificate costs money, and some smaller sites either don't want to pay for it or haven't gotten one yet. The bad part about this is that this means there is no guarantee that the server is really the system you think that it is. Use the /novalidate-cert option in the mailbox name to disable validation of the certificate. _________________________________________________________________ 7.33 What does the UNIX error message: TLS/SSL failure: myserver: unable to get local issuer certificate mean? An SSL or TLS session encryption failed because your system does not have the Certificate Authority (CA) certificates installed on OpenSSL's certificates directory. On most systems, this directory is /usr/local/ssl/certs). As a result, it is not possible to validate the server's certificate. If CA certificates are properly installed, you should see factory.pem and about a dozen other .pem names such as thawteCb.pem. As a workaround, you can use the /novalidate-cert option in the mailbox name to disable validation of the certificate; however, note that you are then vulnerable to various security attacks by bad guys. The correct fix is to copy all the files from the certs/ directory in the OpenSSL distribution to the /usr/local/ssl/certs (or whatever) directory. Note that you need to do this after building OpenSSL, because the OpenSSL build creates a number of needed symbolic links. For some bizarre reason, the OpenSSL "make install" doesn't do this for you, so you must do it manually. _________________________________________________________________ 7.34 Why does reading certain messages hang when using Netscape? It works fine with Pine! There are two possible causes. Check the mail syslog. If you see the message "Killed (lost mailbox lock)" for the impacted user(s), read the FAQ entry regarding that message. Check the affected mailbox to see if there are embedded NUL characters in the message. NULs in message texts are a technical violation of both the message format and IMAP specifications. Most clients don't care, but apparently Netscape does. You can work around this by rebuilding imapd with the NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile); this will cause imapd to convert all NULs to 0x80 characters. A better solution is to enable the feature in your MTA to MIME-convert messages with binary content. See the documentation for your MTA for how to do this. _________________________________________________________________ 7.35 Why does Netscape say that there's a problem with the IMAP server and that I should "Contact your mail server administrator."? Certain versions of Netscape do this when you click the Manage Mail button, which uses an undocumented feature of Netscape's proprietary IMAP server. You can work around this by rebuilding imapd with the NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile) to a URL that points either to an alternative IMAP client (e.g. Pine) or perhaps to a homebrew mail account management page. _________________________________________________________________ 7.36 Why is one user creating huge numbers of IMAP or POP server sessions? The user is probably using Outlook Express, Eudora, or a similar program. See the answer to the Help! My load average is soaring and I see hundreds of POP and IMAP servers, many logged in as the same user! question. _________________________________________________________________ 7.37 Why don't I get any new mail notifications from Outlook Express or Outlook after a while? This is a known bug in Outlook Express. Microsoft is aware of the problem and its cause. They have informed us that they do not have any plans to fix it at the present time. The problem is also reported in Outlook 2000, but not verified. Outlook Express uses the IMAP IDLE command to avoid having to "ping" the server every few minutes for new mail. Unfortunately, Outlook Express overlooks the part in the IDLE specification which requires that a client terminate and restart the IDLE before the IMAP 30 minute inactivity autologout timer triggers. When this happens, Outlook Express displays "Not connected" at the bottom of the window. Since it's no longer connected to the IMAP server, it isn't going to notice any new mail. As soon as the user does anything that would cause an IMAP operation, Outlook Express will reconnect and new mail will flow again. If the user does something that causes an IMAP operation at least every 29 minutes, the problem won't happen. Modern versions of imapd attempt to work around the problem by automatically reporting fake new mail after 29 minutes. This causes Outlook Express to exit the IDLE state; as soon as this happens imapd revokes the fake new mail. As long as this behavior isn't known to cause problems with other clients, this workaround will remain in imapd. _________________________________________________________________ 7.38 Why don't I get any new mail notifications from Entourage? This is a known bug in Entourage. You built an older version of imapd with the MICROSOFT_BRAIN_DAMAGE option set, in order to disable support for the IDLE command. However, Entourage won't get new mail unless IDLE command support exists. Note: the MICROSOFT_BRAIN_DAMAGE option no longer exists in modern versions, as the Outlook Express problem which it attempted to solve has been worked around in another way. _________________________________________________________________ 7.39 Why doesn't Entourage work at all? It's hard to know. Entourage breaks almost every rule in the book for IMAP. It is highly instructive to do a packet trace on Entourage, as an example of how not to use IMAP. It does things like STATUS (MESSAGES) on the currently selected mailbox and re-fetching the same static data over and over again. It seems that every time we understand what it is doing wrong in Entourage and come up with a workaround, we learn about something else that's broken. Try building imapd with the ENTOURAGE_BRAIN_DAMAGE option set, in order to disable the diagnostic that occurs when doing STATUS on the currently selected mailbox. _________________________________________________________________ 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all? This is a bug in NSNOTIFY; it doesn't handle unsolicited data from the server correctly. Fortunately, there is no reason to use this program with IMAP; NSNOTIFY is a polling program to let you know when new mail has appeared in your maildrop. This is necessary with POP; but since IMAP dynamically announces new mail in the session you're better off (and will actually cause less load on the server!) keeping your mail reading program's IMAP session open and let IMAP do the notifying for you. Consequently, the recommended fix for the NSNOTIFY problem is to delete the NSNOTIFY binary. _________________________________________________________________ 7.41 Why can't I connect via SSL to Eudora? It says the connection has been broken, and in the server syslogs I see "Command stream end of file". There is a report that you can fix the problem by going into Eudora's advanced network configuration menu and increasing the network buffer size to 8192. _________________________________________________________________ 7.42 Sheesh. Aren't there any good IMAP clients out there? Yes! Pine is a wonderful client. It's fast, it uses IMAP well, and it generates text mail (life is too short to waste on HTML mail). Also, there are some really wonderful things in progress in the Pine world. There are some good GUI clients out there, mostly from smaller vendors. Without naming names, look for the vendors who are active in the IMAP protocol development community, and their products. Netscape, Eudora, and Outlook can be configured with enough effort to be good citizens and work well for users, but they can also be badly misconfigured, and often the misconfiguration is the default. _________________________________________________________________ 7.43 But wait! PC Pine (or other PC program build with c-client) crashes with the message incomplete SecBuffer exceeds maximum buffer size when I use SSL connections. This is a bug in c-client, right? It's a bug in the Microsoft SChannel.DLL, which implements SSL. Microsoft admits it (albeit with an unstatement: "it's not fully RFC compliant"). The problem is that SChannel indicates that the maximum SSL packet data size is 5 bytes smaller than the actual maximum. Thus, any IMAP server which transmits a maximum sized SSL packet will not work with PC Pine or any other program which uses SChannel. It can take a while for the problem to show up. The client has to do something that causes at least 16K of contiguous data. Many clients do partial fetching, which tends to reduce the number of cases where this can happen. However, all software which uses SChannel to support SSL is affected by this bug. This problem does not affect UNIX code, since OpenSSL is used on UNIX. This problem most recently showed up with the CommunigatePro IMAP server. They have an update which trims down their maximum contiguous data to less than 16K, in order to work around the problem. This problem has also shown up with the Exchange IMAP server with UNIX clients (including Pine built with an older version of c-client) which sends full-sized 16K SSL packets. Modern c-client works around the problem by trimming down its maximum outgoing SSL packet size to 8K. Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which implies that this is a Pine issue, this bug also affect Microsoft Exchange server with *any* UNIX based client that transmits full-sized SSL payloads. _________________________________________________________________ 7.44 My qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How can I fix this? This is an incompatibility between qpopper and the c-client library used by Pine, imapd, and ipop[23]d. Assuming that you want to continue using qpopper, look into qpopper's --enable-uw-kludge-flag configuration flag, which is documented as "check for and hide UW 'Folder Internal Data' messages". The other alternative is to switch from qpopper to ipop3d. _________________________________________________________________ 7.45 Help! I installed the servers but I can't connect to them from my client! Review the installation instructions carefully. Make sure that you have not skipped any of the steps. Make sure that you have made the correct entries in the configuration files; pay careful attention to the exact spelling of the service names and the path names. Make sure as well that you have properly restarted inetd. If you have a system with Yellow Pages/NIS such as Solaris, have you updated the service names there as well as in /etc/services? If you have a system with TCP wrappers, have you properly updated the TCP wrapper files (e.g. /etc/hosts.allow and /etc/hosts.deny) for the servers? If you have a system which uses xinetd instead of inetd, have you made sure that you have made the correct corresponding xinetd changes for those services? Try telneting to the server port (143 for IMAP, 110 for POP3). If you get a "refused" error, that probably means that you don't have the service set up in inetd.conf. If the connection opens and then closes with no message, the service is set up, but either the path name of the server binary in inetd.conf is wrong or your TCP wrappers are configured to deny access. If you don't know how to make the corresponding changes to these files, seek the help of a local expert for your system. _________________________________________________________________ 7.46 Why do I get the message Can not authenticate to SMTP server: 421 SMTP connection went away! and why did this happen? There was also something about SECURITY PROBLEM: insecure server advertised AUTH=PLAIN Some versions of qmail, including that running on mail.smtp.yahoo.com, disconnect the SMTP session if you fail to authenticate prior to attempting to transmit mail. An attempt to authenticate was made, but it failed because the server had already disconnected. To work around this, you need to specify /user=... in the host name specification. The SECURITY PROBLEM came about because the server advertised the AUTH=PLAIN SASL authentication mechanism outside of a TLS-encrypted session, in violation of RFC 4616. This message is just a warning, and in fact occurred after the server had disconnected. _________________________________________________________________ 7.47 Why do I get the message SMTP Authentication cancelled and why did this happen? There was also something about SECURITY PROBLEM: insecure server advertised AUTH=PLAIN This is a bug in the SMTP server. Some versions of qmail, including that running on mail.smtp.yahoo.com, have a bug in their implementation of SASL in their SMTP server, which renders it non-compliant with the standard. If the client does not provide an initial response in the command line for an authentication mechanism whose profile does not have an initial challenge, qmail issues a bogus response: 334 ok, go on The problem is the "ok, go on". This violates RFC 4954's requirement that the text part in a 334 response be a BASE64 encoded string; in other words, it is a protocol syntax error. In the case of AUTH=PLAIN, RFC 4422 (page 7) requires that the encoded string have no data. In other words, the appropropiate standards-compliant server response is "334" followed by a SPACE and a CRLF. The SECURITY PROBLEM came about because the server advertised the AUTH=PLAIN SASL authentication mechanism outside of a TLS-encrypted session, in violation of RFC 4616. This message is just a warning, and is not related the "Authentication cancelled" problem. _________________________________________________________________ 7.48 Why do I get the message Invalid base64 string when I try to authenticate to a Cyrus server? This slightly misleading message is the way that a Cyrus server indicates that an authentication exchange was cancelled. It is not indicative of a bug or protocol violation. The most common reason that this happens is if the Cyrus server offers Kerberos authentication, c-client is built with Kerberos support, but your client system is not within the Kerberos realm. In this case, the client code will try to authenticate via Kerberos, fail to get the Kerberos credentials, cancel the authentication attempt, and try the next available authentication technology. _________________________________________________________________ 8. Where to Go For Additional Information _________________________________________________________________ 8.1 Where can I go to ask questions? 8.2 I have some ideas for enhancements to IMAP. Where should I go? If you have questions about the IMAP protocol, or want to participate in discussions of future directions of the IMAP protocol, the appropriate mailing list is imap-protocol@u.washington.edu. You can subscribe to this list via imap-protocol-request@u.washington.edu If you have questions about this software, you can send me email directly or use the imap-uw@u.washington.edu mailing list. You can subscribe to this list via imap-uw-request@u.washington.edu If you have general questions about the use of IMAP software (not specific to the UW IMAP toolkit) use the imap-use@u.washington.edu mailing list. You can subscribe to this list via imap-use-request@u.washington.edu You must be a subscriber to post to these lists. As an alternative, you can use the comp.mail.imap newsgroup. _________________________________________________________________ 8.3 Where can I read more about IMAP and other email protocols? We recommend Internet Email Protocols: A Developer's Guide, by Kevin Johnson, published by Addison Wesley, ISBN 0-201-43288-9. _________________________________________________________________ 8.4 Where can I find out more about setting up and administering an IMAP server? We recommend Managing IMAP, by Dianna Mullet & Kevin Mullet, published by O'Reilly, ISBN 0-596-00012-X. This book also has an excellent comparison of the UW and Cyrus IMAP servers. Last Updated: 15 November 2007 imap-2007f~dfsg/docs/CONFIG0000644000000000000000000002030311612411705014114 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ UNIX Configuration Notes The IMAP and POP3 servers are plug-and-play on standard UNIX systems. There is no special configuration needed. Please ignore all rumors to the effect that you need to create an IMAP configuration file. If your system is non-standard, virtually everything that you are likely to want to modify can be found in the source file .../src/osdep/unix/env_unix.c In particular, special attention should be given to the routines: env_init() initialize c-client environment variables, especially the user name and home directory sysinbox() return the UNIX path of the INBOX in which mail delivery will place mail mailboxdir() translate a mailbox name into the associated UNIX directory for listing mailboxfile() translate a mailbox name into the associated UNIX file for opening There are also build options in the top-level makefile which you can give on the command line when building the software. The most common build options are "SSLTYPE=unix", to build the software with SSL, and "SSLTYPE=nopwd", to build the software with SSL and disable plaintext authentication unless the session is encrypted. You should modify these routines as necessary for local policy. The most common modifications are to env_init(), to modify the software's idea of the home directory (which is used everywhere as the default directory), and to sysinbox(), to modify where the software looks for newly-delivered mail. Example 1: suppose your mailer delivers mail to file ".mailbox" in the user's home directory instead of the default UNIX mail spool directory. You will want to change routine sysinbox(), changing the line that reads: sprintf (tmp,"%s/%s",MAILSPOOL,myusername ()); to be: sprintf (tmp,"%s/.mailbox",myhomedir ()); Example 2: suppose you want to change c-client's idea of the user's mailbox directory to be the "mail" subdirectory of the user's home directory instead of the user's home directory. You will want to change variable mailsubdir, changing the line that reads: static char *mailsubdir = NIL; /* mail subdirectory name */ to be: static char *mailsubdir = "mail";/* mail subdirectory name */ Example 3: suppose you want to disable plaintext authentication in the IMAP and POP servers. If you want to disable plaintext authentication in unencrypted sessions but permit it in encrypted sessions, you should use "SSLTYPE=nopwd" in the make command line when building the software. For example, to do this on a Linux system with PAM authentication, do: make lnp SSLTYPE=nopwd If you want to disable plaintext authentication under all circumstances (including SSL or TLS encrypted sessions), use "PASSWDTYPE=nul", e.g.: make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul which will make it impossible to log in except via Kerberos. Example 4: suppose you want the IMAP and POP servers to do a chroot() to the user's home directory. This is not recommended; there are known ways of attacking chroot() based security mechanisms. Furthermore, if you do this you can not use a traditional UNIX format INBOX in the mail spool directory, since chroot() will prevent access to that directory. If you really want to do this, you need to change variable closedBox, changing the line which reads: static short closedBox = NIL; /* is a closed box */ to be: static short closedBox = T; /* is a closed box */ Example 5: suppose you want to disable non-namespace access to the filesystem root and other users' names, but do not want to go to the extreme of chroot() and you want to allow access to a traditional UNIX format INBOX in the mail spool directory. You need to change variable restrictBox, changing the line which reads: static short restrictBox = NIL; /* is a restricted box */ to be: static short restrictBox = -1; /* is a restricted box */ Other values to set in restrictBox can be found in env_unix.h. Ignore all references in env_unix.c to a configuration file; that code is for UW-internal use only. It is extremely unlikely that that facility will work usefully for you; it is extremely likely that you will shoot yourself in the foot by using; and it frequently changes in an incompatible manner. There are two other build-time configuration issues which you may need to consider: drivers and authenticators. Both of these are set up in the top-level Makefile -- in particular, by the EXTRADRIVERS and EXTRAAUTHENTICATORS variables. Drivers are code modules that support different mailbox storage technologies. By default, all drivers are enabled. There is little benefit to be gained by disabling a driver, with one exception. The mbox driver implements the behavior of automatically moving new mail from the spool directory to the "mbox" file on the user's home directory, if and *only* if the "mbox" exists and is in mailbox format. The mbox driver is listed under EXTRADRIVERS; if you wish to disable it just remove it from that list and rebuild. Authenticators are code modules that support authentication technology for the server (password file lookup, Kerberos, S/Key, etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This subject can be complex; find a wizard if you can't figure it out. It is also possible to add your own drivers and authenticators. This is a topic for wizards, and is beyond the scope of this text. NT Configuration Notes This software is not plug-and-play on NT. 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 for NT. The primary issue that you need to deal with is the format of mail, where the INBOX is located, and where secondary folders are located. As distributed, the software supports mail in the default format used on UNIX (unix format) as well as mbx, mtx, and tenex formats. mbx format is encouraged if at all possible; mtx and tenex format are for compatibility with the past. However, it all depends upon how and where your SMTP server delivers mail. To change the default mailbox format, edit the symbol DEFAULTDRIVER in: ../src/osdep/nt/makefile.nt or ../src/osdep/nt/makefile.ntk To change the default location of INBOX, edit the file: ../src/osdep/nt/mailfile.h Virtually everything else having to do with environment that you are likely to want to modify can be found in the source file: .../src/osdep/nt/env_nt.c In particular, special attention should be given to the routines: env_init() initialize c-client environment variables, especially the user name and home directory sysinbox() return the NT path of the INBOX in which mail delivery will place mail mailboxdir() translate a mailbox name into the associated NT directory for listing mailboxfile() translate a mailbox name into the associated NT file for opening You should modify these routines as necessary. The most common modifications are to env_init(), to modify the software's idea of the home directory (which is used everywhere as the default directory), and to sysinbox(), to modify where the software looks for newly-delivered mail. There are two other build-time configuration issues which you may need to consider: drivers and authenticators. Both of these are set up in the top-level Makefile -- in particular, by the EXTRADRIVERS and EXTRAAUTHENTICATORS variables. Drivers are code modules that support different mailbox storage technologies. By default, all drivers are enabled. There is little benefit to be gained by disabling a driver. Authenticators are code modules that support authentication technology for the server (password file lookup, Kerberos, S/Key, etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This subject can be complex; find a wizard if you can't figure it out. It is also possible to add your own drivers and authenticators. imap-2007f~dfsg/docs/md5.txt0000644000000000000000000000731011612411705014455 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ MD5 Based Authentication Mark Crispin 1 November 1999 The IMAP toolkit makes available two MD5 based authentication mechanisms, CRAM-MD5 and APOP. CRAM-MD5 is described in RFC 2195, and is a SASL (RFC 2222) authentication mechanism. APOP is described in RFC 1939, the standard document for the POP3 protocol. These mechanisms use the same general idea. The server issues a challenge; the client responds with an MD5 checksum of the challenge plus the password; the server in compares the client's response with its own calculated value of the checksum. If the client's response matches the server's calulated value, the client is authenticated. Unlike plaintext passwords, this form of authentication is believed to be secure against the session being monitored; "sniffing" the session will not disclose the password nor will it provide usable information to authenticate in another session without knowing the password. The key disadvantage with this form of authentication is that the server must know a plaintext form of the password. In traditional UNIX authentication, the server only knows an encrypted form of the password. Consequently, the authentication database for this form of authentication must be kept strictly confidential; a bad guy who acquires access to this database can access any account in the database. CRAM-MD5 client support is implemented unconditionally; any client application built with the IMAP toolkit will use CRAM-MD5 with any server which advertises CRAM-MD5 SASL support. CRAM-MD5 and APOP server support is implemented if, and only if, the CRAM-MD5 authentication database exists. By default, the CRAM-MD5 authentication database is in a UNIX file called /etc/cram-md5.pwd It is recommended that this file be protected 0400. NOTE: FAILURE TO PROTECT THIS FILE AGAINST UNAUTHORIZED ACCESS WILL COMPROMSE CRAM-MD5 AND APOP AUTHENTICATION FOR ALL USERS LISTED IN THIS DATABASE. If the CRAM-MD5 authentication database exists, then plaintext password authentication (e.g. the LOGIN command) will also use the CRAM-MD5 passwords instead of UNIX passwords. Alternatively, it is possible to build the IMAP toolkit so that plaintext password authentication is disabled entirely, by using PASSWDTYPE=nul, e.g. make aix PASSWDTYPE=nul The CRAM-MD5 authentication database file consists of a series of text lines, consisting of a UNIX user name, a single tab, and the password. A line starting with a "#" character is ignored, as are any lines which are not in valid format. For example: ------------------------------Sample------------------------------ # CRAM-MD5 authentication database # Entries are in form # Lines starting with "#" are comments bill hubba-hubba hillary nysenator monica beret tripp wired kenstarr inquisitor reno waco jessie thebody billgates ruleworld ------------------------------Sample------------------------------ Every entry in the CRAM-MD5 authentication database must have a corresponding entry in the /etc/passwd file. It is STRONGLY RECOMMENDED that the CRAM-MD5 password NOT be the same as the /etc/passwd password. It is permitted for the /etc/passwd password to be disabled; /etc/passwd is just used to get the UID, GID, and home directory information. imap-2007f~dfsg/docs/BUILD0000644000000000000000000005114011612411705014011 0ustar rootroot/* ======================================================================== * 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. imap-2007f~dfsg/docs/IPv6.txt0000644000000000000000000001132011612411705014550 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ The following information about configuring inetd and xinetd for IPv6 was contributed by a user. I have not checked it for accuracy or completeness, but have included it as-is in the hope that it may be useful: --------------------------------------------------------------------------- One thing you might consider adding to the docs are hints for setting up inetd or xinetd to simultaneously listen on BOTH IPv4 and IPv6 for different OS. Some OS want to see separate IPv4-only and IPv6-only listening sockets configured in inetd.conf or xinetd.conf. Others will accept IPv4 connections on lines configured for IPv6 and actually generate errors if you have both configured when inetd or xinetd start up. It's not clear to me whether this difference is due to how inetd or xinetd are built or whether it's due to the kernel's IP stack implementation. I suspect it's really the latter. Below are some examples: Here's a fragment of /usr/local/etc/xinetd.conf for a FreeBSD 4.9 server: service imap { socket_type = stream protocol = tcp wait = no user = root server = /usr/local/libexec/imapd } service imap { flags = IPv6 socket_type = stream protocol = tcp wait = no user = root server = /usr/local/libexec/imapd } service imaps { socket_type = stream protocol = tcp wait = no user = root server = /usr/local/libexec/imapd } service imaps { flags = IPv6 socket_type = stream protocol = tcp wait = no user = root server = /usr/local/libexec/imapd } Note that you have to specify a nearly identical paragraph for each service which differs only by the 'flags = IPv6'. An equivalent inetd.conf would look something like: imap stream tcp nowait root /usr/local/libexec/imapd imapd imap stream tcp6 nowait root /usr/local/libexec/imapd imapd imaps stream tcp nowait root /usr/local/libexec/imapd imapd imaps stream tcp6 nowait root /usr/local/libexec/imapd imapd The man pages for inetd suggest that if you use a single entry with 'tcp46' replacing either 'tcp' or 'tcp6' the system will listen on both types of addresses. At least for the case of FreeBSD this is actually incorrect. Now if you were to use the above xinetd.conf on Fedora Linux, it would complain. What does work under Linux is to create a single service paragraph for each service which will accept connections on both IPv4 and IPv6: In /etc/xinetd.d/imap: service imap { flags = IPv6 disable = no socket_type = stream wait = no user = root server = /usr/local/sbin/imapd } In /etc/xinetd.d/imaps: service imaps { flags = IPv6 disable = no socket_type = stream wait = no user = root server = /usr/local/sbin/imapd } The man page for xinetd says the IPv6 flag means xinetd will listen ONLY on IPv6. However the actual behaviour (for Fedora Linux) is to listen on both IPv4 and IPv6. All of the above also applies to ipop3d. Anyway, this might save some folks a little bit of head scratching time. --------------------------------------------------------------------------- Addendum from the original submitter: --------------------------------------------------------------------------- I've since learned that the discrepancy really is a function of the OS. It seems those systems that force you to create separate IPv4 and IPv6 listeners in inetd (or xinetd) are the same systems that also disable IPv4-mapped IPv6 addresses by default. This is a boot-time configuration option. If you enable IPv4-mapped IPv6 addresses, then the 'tcp46' option in inetd works and the simplified config would look like: imap4 stream tcp46 nowait root /usr/local/libexec/imapd imapd imaps stream tcp46 nowait root /usr/local/libexec/imapd imapd In FreeBSD, enabling IPv4-mapped addresses is done by adding ipv6_ipv4mapping="YES" to /etc/rc.conf (in addition to ipv6_enable="YES"). imap-2007f~dfsg/docs/calendar.txt0000644000000000000000000003542211612411704015545 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ ALL ABOUT CALENDARS Although one can never be sure of what will happen at some future time, there is strong historical precedent for presuming that the present Gregorian calendar will still be in effect within the useful lifetime of the IMAP toolkit. We have therefore chosen to adhere to these precedents. The purpose of a calendar is to reckon time in advance, to show how many days have to elapse until a certain event takes place in the future, such as the harvest or the release of a new version of Pine. The earliest calendars, naturally, were crude and tended to be based upon the seasons or the lunar cycle. ANCIENT CALENDARS The calendar of the Assyrians, for example, was based upon the phases of the moon. They knew that a lunation (the time from one full moon to the next) was 29 1/2 days long, so their lunar year had a duration of 354 days. This fell short of the solar year by about 11 days. (The exact time for the solar year is approximately 365 days, 5 hours, 48 minutes, and 46 seconds.) After 3 years, such a lunar calendar would be off by a whole month, so the Assyrians added an extra month from time to time to keep their calendar in synchronization with the seasons. The best approximation that was possible in antiquity was a 19-year period, with 7 of these 19 years having 13 months (leap months). This scheme was adopted as the basis for the lunar calendar used by the Hebrews. The Arabs also used this calendar until Mohammed forbade shifting from 12 months to 13 months; this causes the Muslim holy month of Ramadan to move backwards through the seasons, completing a cycle every 32 1/2 years. When Rome emerged as a world power, the difficulties of making a calendar were well known, but the Romans complicated their lives because of their superstition that even numbers were unlucky. Hence their months were 29 or 31 days long, with the exception of February, which had 28 days. Every second year, the Roman calendar included an extra month called Mercedonius of 22 or 23 days to keep up with the solar year. JULIAN CALENDAR Even this algorithm was very poor, so that in 45 BCE, Caesar, advised by the astronomer Sosigenes, ordered a sweeping reform. By imperial decree, the year 46 BCE was made 445 days long to bring the calendar back in step with the seasons. The new calendar, similar to the one we now use was called the Julian calendar (named after Julius Caesar). Months in the Julian calendar were 30 or 31 days in length and every fourth year was made a leap year (having 366 days) by adding a day to the end of the year. This leap year rule was not consistantly applied until 8 CE. The year-ending month of February, never a popular month, was presently shortened so that Julius Caesar and Emperor Augustus could each have long months named after them. Caesar also decreed that the year would start with the first of January, which since 153 BCE was the day that Roman consuls took office, and not the vernal equinox in late March. Not everyone accepted that part of his reform, as we shall see. GREGORIAN CALENDAR Caesar's year was 11 1/2 minutes short of the calculations recommended by Sosigenes and eventually the date of the vernal equinox began to drift. Roger Bacon became alarmed and sent a note to Pope Clement IV, who apparently was not impressed. Pope Sixtus IV later became convinced that another reform was needed and called the German astronomer, Regiomontanus, to Rome to advise him. Unfortunately, Regiomontanus died of the plague shortly thereafter and the plans died as well. In 1545, the Council of Trent authorized Pope Gregory XIII to reform the calendar once more. Most of the mathematical work was done by Father Christopher Clavius, S.J. The immediate correction that was adopted was that Thursday, October 4, 1582 was to be the last day of the Julian calendar. The next day was Friday, with the date of October 15. For long range accuracy, a formula suggested by the Vatican librarian Aloysius Giglio was adopted. It said that every fourth year is a leap year except for century years that are not divisible by 400. Thus 1700, 1800 and 1900 would not be leap years, but 2000 would be a leap year since 2000 is divisible by 400. This rule eliminates 3 leap years every 4 centuries, making the calendar sufficiently correct for most ordinary purposes. This calendar is known as the Gregorian calendar and is the one that we now use today. It is interesting to note that in 1582, all the Protestant princes ignored the papal decree and so many countries continued to use the Julian calendar until either 1698 or 1752. Britain and its American colonies went from Wednesday, September 2, 1752 to Thursday, September 14. Prior to the changeover, the British used March 25 as the start of the new year. In Russia, it needed the revolution to introduce the Gregorian calendar in 1918. Turkey didn't adopt it until 1927. NUMBERING OF YEARS The numbering of the year is generally done according to an "era", such as the year of a ruler's reign. In about 525, a monk named Dionysius Exiguus suggested that the calculated year of Jesus' birth be designated as year 1 in the Julian calendar. This suggestion was adopted over the next 500 years and subsequently followed in the Gregorian calendar. For the benefit of those who seek religious significance to the calendar millenium, note that year 1 is too late by at least 4 years. Herod the Great, named in the Christian Bible as having all children in Bethlehem put to death in an attempt to kill the infant Jesus, died in 4 BCE. Nothing particularly significant of an historic or religious nature happened in Gregorian year 1; however it has become a worldwide standard as the "common era." In modern times, the terms "CE" (common era) and "BCE" (before common era) are preferred over the earlier (and, as we have seen, less accurate) "AD" (anno Domini, "the year of the Lord") and "BC" (before Christ). The Hebrew lunar calendar begins at 3760 BCE, the year of creation in Jewish tradition. The Muslim lunar calendar begins on July 16, 622, when Mohammed fled from Mecca to Medina. The Japanese, Taiwanese, and North Koreans use the Gregorian calendar, but number the year by political era. In Japan, an era begins when an emperor succeeds to the throne; year 1 of the Heisei era was 1989 when Emperor Akihito ascended to the throne (the first few days of 1989 was year 64 of the Shouwa era). In Taiwan, year 1 is the first full year after the founding of the Republic of China in 1911. In North Korea, year 1 is the year of the Juche (self-reliance) ideal, corresponding to the birth year of founder Kim Il-Sung (1912). Thus, year 2000 is Heisei 12 (Japan), 89th year of the Republic (Taiwan), and Juche 89 (North Korea). FURTHER MODIFICATIONS TO THE GREGORIAN CALENDAR Despite the great accuracy of the Gregorian calendar, it still falls behind very slightly every few years. The most serious problem is that the earth's rotation is slowing gradually. If you are very concerned about this problem, we suggest that you tune in short wave radio station WWV or the Global Positioning System, which broadcasts official time signals for use in the United States. About once every 3 years, they declare a leap second at which time you should be careful to adjust your system clock. If you have trouble picking up their signals, we suggest you purchase an atomic clock (not part of the IMAP toolkit). Another problem is that the Gregorian calendar represents a year of 365.2425 days, whereas the actual time taken for the earth to rotate around the Sun is 365.2421991 days. Thus, the Gregorian calendar is actually 26 seconds slow each year, resulting in the calendar being one day behind every 3,300 or so years (a Y3.3K problem). Consequently, the Gregorian calendar has been modified with a further rule, which is that years evenly divisible by 4000 are not leap years. Thus, the year 4000 will not be a leap year. Or, at least we assume that's what will happen assuming that the calendar remains unchanged for the next 2000 years. The modified Gregorian calendar represents a year of 365.24225 days. Thus, the modified Gregorian calendar is actually 4 seconds slow each year, resulting in the calendar being one day slow every 20,000 or so years. So there will be a Y20K problem. There is some dispute whether the modified Gregorian calendar was officially adopted, or if it's just a proposal. Other options (see below) exist; fortunately no decision needs to be made for several centuries yet. There is code in c-client to support the modified Gregorian calendar, although it is currently disabled. Sometime in the next 2000 years, someone will need to enable this code so that c-client is Y4K compiliant. Then, 18,000 years from now, someone will have to tear into c-client's code to fix the Y20K bug. EASTERN ORTHODOX MODIFICATION OF THE GREGORIAN CALENDAR The Eastern Orthodox church in 1923 established its own rules to correct the Julian calendar. In their calendar, century years modulo 900 must result in value of 200 or 600 to be considered a leap year. Both the Orthodox and Gregorian calendar agree that the years 2000 and 2400 will be leap years, and the years 1900, 2100, 2200, 2300, 2500, 2600, 2700 are not. However, the year 2800 will be a leap year in the Gregorian calendar but not in the Orthodox calendar; similarly, the year 2900 will be a leap year in the Orthodox calendar but not in the Gregorian calendar. Both calendars will agree that 3000 and 3100 are leap years, but will disagree again in 3200 and 3300. There is code in c-client to support the Orthodox calendar. It can be enabled by adding -DUSEORTHODOXCALENDAR=1 to the c-client CFLAGS, e.g. make xxx EXTRACFLAGS="-DUSEORTHODOXCALENDAR=1" The Orthodox calendar represents a year of 365.24222222... days. Thus, the Orthodox calendar is actually 2 seconds slow each year, resulting in the calendar being one day slow every 40,000 or so years. The Eastern Orthodox church has not yet made any statements on how the Y40K bug will be fixed. OTHER ISSUES AFFECTING THE CALENDAR IN THE FUTURE The effect of leap seconds also needs to be considered when looking at the Y3.3K/Y4K, Y20K, and Y40K problems. Leap seconds put the clock back in line with the Earth's rotation, whereas leap years put the calendar back in line with the Earth's revolution. Since leap seconds slow down the clock (and hence the calendar), they actually bring the day of reckoning for the Gregorian and Orthodox calendars sooner. Another factor is that the next ice age (technically, the end of the current interglacial period; we are in the middle of an ice age now!) is due around Y25K. It is not known what perturbations this will cause on the Earth's rotation and revolution, nor what calendar adjustments will be necessary at that time. Hence my use of "or so" in predicting the years that the calendar will fall behind. The actual point may be anywhere from decades (in the case of Y3.3K) to millenia (in the case of Y40K) off from these predictions. MEANINGS OF DAY NAMES The names of days of the week from a combination of Roman and Germanic names for celestial bodies: . Sunday Latin "dies solis" => "Sun's day" . Monday Latin "dies lunae" => "Moon's day" . Tuesday Germanic "Tiw's day" => "Mars' day" . Wednesday Germanic "Woden's day" => "Mercury's day" . Thursday Germanic "Thor's day" => "Jupiter's day" . Friday Germanic "Frigg's day" => "Venus' day" . Saturday Latin "dies Saturni" => "Saturn's day" MEANINGS OF MONTH NAMES The names of the months are from the Roman calendar: . January Janus, protector of doorways . February Februalia, a time for sacrifice to atone for sins . March Mars, god of war . April Latin "aperire" => "to open" buds . May Maia, goddess of plant growth . June Latin "juvenis" => "youth" . July Julius Caesar . August Augustus Caesar . September Latin "septem" => "seven" . October Latin "octo" => "eight" . November Latin "novem" => "nine" . December Latin "decem" => "ten" As you'll notice, the last four months are numbered 7 to 10, which is an artifact of the time when the new year started in March. INTERESTING FORMULAE There's another reason why the historical starting of the new year is significant. Starting with March, the length of months follows a mathematical series: 31 30 31 30 31 31 30 31 30 31 31 28 This means that you can calculate the day of week for any arbitrary day/month/year of the Gregorian calendar with the following formula (note all divisions are integral): _ _ | 7 + 31*(m - 1) y y y | dow = | d + -------------- + y + - - --- + --- | MOD 7 |_ 12 4 100 400_| where d := day of month (1..31) m := month in old style (March = 1..February = 12) y := year in old style dow := day of week (Tuesday = 0..Monday = 6) To convert from new style month/year to old style: if (m > 2) m -= 2; /* Mar-Dec: subtract 2 from month */ else m += 10,y--; /* Jan-Feb: months 11 & 12 of previous year */ Here's another fun formula. To find the number of days between two days, calculate a pair of calendar days with the formula (again, all divisions are integral), using new style month/year this time: m m + - 8 y y y d + 30 * (m - 1) + ----- + y * 365 + - - --- + --- - ld 2 4 100 400 where: d := day of month (1..31) m := month in new style (January = 1..December = 12) y := year in new style ld := leap day correction factor: 0 for January and February in non-leap years 1 for January and February in leap years 2 for all other months in all years In C code, the leap day correction factor is calculated as: (m < 3) ? !(y % 4) && ((y % 100) || !(y % 400)) : 2 It's up to you to figure out how to adapt these formulas for the Y4K bugfix and the Orthodox calendar. If you're really clever, try to use these formulae to implement the C library ctime(), gmtime(), and mktime() functions. Most C library implementations use a table of the number of days in a month. You don't need it. ACKNOWLEDGEMENT: The original version is from an old Digital Equipment Corporation SPR answer for VMS. Modifications for c-client, and additional information added by Mark Crispin. imap-2007f~dfsg/docs/imaprc.txt0000644000000000000000000006475711612411704015264 0ustar rootroot/* ======================================================================== * Copyright 1988-2006 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 * * * ======================================================================== */ .imaprc secrets revealed! Mark Crispin, June 17, 2002 The following information describes the format of the /etc/c-client.cf and ~/.imaprc file. The Columbia MM ~/.mminit file is also read by c-client; however, the only command that ~/.mminit has in common is set keywords. ********************************************************************** * DANGER! BEWARE! TAKE CARE! * ********************************************************************** * * * These files, and this documentation, are for internal UW usage * * only. This capability is for UW experimental tinkering, and most * * emphatically *not* for sorcerer's apprentices at other sites who * * feel that if a config file capability exists, they must write a * * config file whether or not there is any need for one. * * * * This information is subject to change without notice. Commands * * may be added, removed, or altered. The behavior of comamnds may * * change. Do not use any of this information without consulting me * * first. c-client's defaults have been carefully chosen to be right * * for general-purpose and most special-purpose configurations. If * * you tinker with these defaults, all hell may break loose. * * * * This is not an idle threat. There have been several instances of * * people who ignored these warnings and have gotten burned. * * * * Don't even trust this file to work. Many of the things which can * * be changed by this file can also be changed by the application, * * and it is totally unpredictable which will take precedence. It * * all depends upon how the application is coded. Not only that, you * * may cause the application to crash. * * * * In other words, keep your cotton-pickin' hands off my defaults. * * If it crashes and erases your mail, I don't want to hear about it. * * Consider 'em ``mandatory defaults''. Got a nice ring, eh? :-) If * * you must tinker with defaults, play with the .pinerc and pine.conf * * files in Pine. It's got options galore, all supported for you to * * have fun. They're also documented; so well documented, it takes * * two strong men to carry around all the documentation. ;-) ;-) * * * * Joking aside, you really shouldn't be fooling around with this * * capability. It's dangerous, and you can shoot yourself in the * * foot easily. If you need custom changes, you are better off with * * local source code modifications. Seriously. * * * * One last warning: don't believe anything that you read in this * * document. Every effort has been made to ensure that this document * * is incomplete and inaccurate, and I take no responsibility for any * * glimmers of correct information that may, by some fluke, be here. * * * ********************************************************************** The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc, and an entry in a later file overrides the setting of an earlier file except as noted below. This ordering and overriding behavior may change without notice. Almost all of these facilities can also be set via the mail_parameters() call in the program. Whether the file overrides mail_parameters(), or mail_parameters() overrides the file, is indeterminate. It will vary from program to program, and it may be one way in one version and the other way in the next version. It's completely unpredictable, and so anything you do with these files has to be in complete knowledge of what the version of each program you're running is going to do. This is because the files do something for testing, but the real capability for configurability is put in the program instead. Are you getting the feeling that you shouldn't be messing with these files yet? The very first line of the file MUST start with the exact string "I accept the risk". This ensures that you have checked the file for correctness against this version of the IMAP toolkit. This enable string may change without notice in future versions, and the new string may or may not be accurately described in an updated version of this file. So any time you install software that uses the IMAP toolkit, you need to check the new version against these files (if you have insisted upon creating them in spite of all warnings). If two pieces of software use different versions of the IMAP toolkit with incompatible requirements, one of them won't work. Re-read the warning above about why you should not use these files. Subsequent lines are read from the file one at a time. Case does not matter. Unrecognized commands are ignored. 1) set new-folder-format sets what format new mailboxes are created in. This also controls default delivery via tmail and dmail. a) set new-folder-format same-as-inbox Folder is created using the same mailbox format as INBOX. If INBOX is empty, it defaults to system standard. b) set new-folder-format system-standard This is the default. Folder is created using the wired-in system standard format, which on most UNIX systems is ordinary UNIX /bin/mail format. On SCO systems, this is MMDF. c) set new-folder-format Folder is created using the given driver name, e.g. mbx, unix, mmdf, etc. There is no protection against setting this to a silly value (e.g. news, nntp, dummy) and doing so is a great way to screw things up. Setting this to mh does not do what you think it does. Setting this to tenex or mtx isn't particularly useful. 2) set empty-folder-format sets what format data is written into an empty mailbox file using mail_copy() or mail_append(). This also controls default delivery via tmail. a) set empty-folder-format same-as-inbox Data is written using the same mailbox format as INBOX. If INBOX is empty, it defaults to system standard. b) set empty-folder-format system-standard This is the default. Data is written using the wired-in system standard format, which on most UNIX systems is ordinary UNIX /bin/mail format. On SCO systems, this is MMDF. c) set-empty-folder-format Data is written using the given driver name, e.g. tenex, unix, mmdf, etc. There is no protection against setting this to a silly value (e.g. news, nntp, dummy) and doing so is a great way to screw things up. Setting this to mh, mbx, or mx does not work. 3) set keywords , , ... Sets the list of keyword flags (supported by tenex and mtx) to the given list. Up to 30 flags may be given. Since these names correspond to numeric bits, the order of the keywords can not be changed, nor can keywords be removed or inserted (you can append new keywords, up to the limit of 30). Set keywords is a deprecated command. It may not appear in future versions, or it may appear in a changed form. It exists only for compatibility with MM, and should only appear in ~/.mminit and not in the other files. It is likely to disappear entirely in IMAP4. There is no protection against setting these to silly values, and doing so is a great way to cause a crash. 4) set from-widget header-only Sets smart insertion of the > character in front of lines that begin with ``From ''. Only such lines that are also in UNIX mbox header file format will have a > character inserted. The default is to insert the > character in front of all lines which begin with ``From '', for the benefit of legacy tools that get confused otherwise. 5) set black-box-directory Sets the directory in which the user's data can be found. A user's folders can be found in a subdirectory of the black box directory named with the user's username. For example, if the blackbox directory is /usr/spool/folders/, user jones' data can be found in /usr/spool/folders/jones/. The user's black-box directory is the location of folders, .mminit, .imaprc, .newsrc, and all other files used by c-client; internally, it sets c-client's idea of the user's ``home directory'', overriding /etc/passwd. This command may not appear in ~/.mminit or ~/.imaprc In black-box mode, it is not permitted to access any folders outside of the user's personal blackbox directory. The breakouts ``/'', ``~'', and ``..'' are not permitted. In order to make this work without crashing, you must set another option which is not listed in this document. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 6) set local-host Sets c-client's idea of the local host name. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 7) set news-active-file Sets the location of the news active file, if it is not in the standard place. It is recommended to use a courtesy symbolic link instead. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 8) set news-spool-directory Sets the location of the news spool, if it is not in the standard place. It is recommended to use a courtesy symbolic link instead. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 9) set news-state-file Sets the location of the news state file (normally $(USER)/.newsrc). This is not very useful in /etc/c-client.cf because it is a file name. Setting this in /etc/c-client.cf would set all users to the same file as their newsrc, which is probably not what you want. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 10) set system-inbox Sets the location of the "system inbox", if it is not in the standard place. This is the default location of INBOX, or the mail drop point from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats). This is not very useful in /etc/c-client.cf because it is a file name. Setting this in /etc/c-client.cf would set all users to the same file as their system inbox, which is probably not what you want. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 11) set tcp-open-timeout Sets the number of seconds that the TCP routines will block on opening a TCP connection before timing out. If a timeout occurs, the connection attempt is aborted. The default is zero, meaning use the operating system default (75 seconds on most UNIX systems). There is no protection against setting this to an excessively small value, such as 1, and doing so is a great way to cause users extreme grief. 12) set tcp-read-timeout Sets the number of seconds that the TCP routines will block on reading data before calling the timeout routine. If no timeout routine is set by the program, the connection will be aborted on a timeout. The default is zero, meaning infinite. There is no protection against setting this to an excessively small value, such as 1, and doing so is a great way to cause users extreme grief. 13) set tcp-write-timeout Sets the number of seconds that the TCP routines will block on sending data before calling the timeout routine. If no timeout routine is set by the program, the connection will be aborted on a timeout. The default is zero, meaning infinite. There is no protection against setting this to an excessively small value, such as 1, and doing so is a great way to cause users extreme grief. 14) set rsh-timeout Sets the number of seconds that the rsh routines will block on opening an rimapd connection before timing out. If a timeout occurs, the rsh connection attempt is aborted. A zero timeout will disable rsh. The default is 15 seconds. There is no protection against setting this to an excessively small value, such as 1, and doing so is a great way to cause users extreme grief. 15) set maximum-login-trials Sets the number of iterations of asking the user, via mm_login(), for a user name and password, before cancelling the attempt. The default is 3. There is no protection against setting this to zero, and doing so is a great way to cause users extreme grief. 16) set lookahead Sets the number of envelopes that are looked ahead in IMAP, in mail_fetchstructure(). This is based on the guess that in such operations as drawing browser lines, if you get data for message n you are likely to want it for message n+1, n+2,... in short order. Lookahead preloads the c-client cache and saves unnecessary RTTs. The default is 20, a good number for a browser on a 24x80 screen, and small enough to usually have no significant real-time difference from a single message fetch. Setting it to 0 turns off lookahead. There is no protection against setting this ridiculously high and incurring performance penalties as a result. 17) set prefetch Sets the number of envelops which are automatically fetched for the messages which match in a search. This is based on the guess that in a browser that is "zoomed" on the results of a search, you are likely to want the envelope data for each of those messages in short order. Prefetching reloads the c-client cache, saves unnecessary RTTs, and avoids loading undesired envelopes due to lookahead (see above). The default is 20. Setting it to 0 turns off prefetch. There is no protection against setting this ridiculously high and incurring performance penalties as a result. 18) set close-on-error If non-zero, IMAP connections are closed if an EXAMINE or SELECT command fails. Otherwise, they are left half-open, and can be used again to select some other mailbox. The mailbox name in the stream is set to {serverhost} The default is zero (do not close on error). 19) set imap-port Set the TCP/IP contact port to use for IMAP. This overrides the wired-in setting and the setting from /etc/services, and can in turn be overridden by an explicit user specification in the mailbox name, e.g. {serverhost:143}foo The default is zero (use setting from /etc/services or the wired-in setting (143). There is no protection against setting this to a silly value, and doing so is a great way to cause users extreme grief. 20) set pop3-port Set the TCP/IP contact port to use for POP3. This overrides the wired-in setting and the setting from /etc/services, and can in turn be overridden by an explicit user specification in the mailbox name, e.g. {serverhost:110/pop3} The default is zero (use setting from /etc/services or the wired-in setting (110). There is no protection against setting this to a silly value, and doing so is a great way to cause users extreme grief. 21) set uid-lookahead Sets the number of UIDs that are looked ahead in IMAP in mail_uid(). Lookahead preloads the c-client cache and saves unnecessary RTTs. The default is 1000, small enough to usually have no significant real-time difference from a single message UID fetch. Setting it to 0 turns off lookahead. There is no protection against setting this ridiculously high and incurring performance penalties as a result. 22) set mailbox-protection Set the default protection for newly-created mailbox files. The default is 384. There is no protection against setting this to a silly value, and doing so is a great way to screw things up massively. 23) set directory-protection Set the default protection for newly-created directories. The default is 448. There is no protection against setting this to a silly value, and doing so is a great way to screw things up massively. 24) set lock-protection Set the default protection for lock files The default is 438, which is necessary if locks are to be respected by processes running as other UIDs. There is no protection against setting this to a silly value, and contrary to what you may think just about any value other than 438 turns out to be a silly value. 25) set disable-fcntl-locking This only applies to SVR4 systems. If non-zero, fnctl() locking is not attempted. In the past, this was used to avoid locking NFS files. If NFS is involved, the evil lockd/statd daemons get invoked. These daemons supposedly work over NFS, but really don't. You probably don't really want to do this, though, because now the flock() emulator (which calls fcntl()) now checks to see if the file is accessed via NFS and no-ops the lock. This is compatible with BSD. Disabling fcntl() locking loses a great deal of locking protection on local files as well as NFS files (which now never have locking protection). The default is zero (fcntl() locking is enabled). 26) set lock-EACCES-error If non-zero, a warning message is given if an attempt to create a lock file fails. Otherwise, EACCES is treated as a "silent failure", and it proceeds without trying to use the lock file. This is for the benefit of users on systems with paranoid /usr/spool/mail protections which don't let users create /usr/spool/mail/$(USER).lock files; these unfortunate users would be harassed with a flood of error messages otherwise. The problem is that on SVR4, if EACCES remains disabled and fcntl() locking is also disabled, then there is no locking at all which is doubleplus-ungood. If the site is paranoid on /usr/spool/mail protections AND if there is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS), then there is no way to win. Find a different system to use. The default is non-zero (report EACCESS as an error). 27) set list-maximum-level Sets the maximum depth of recursion that a * wildcard list will go down the directory tree. 0 means that no recursion is permitted, and * becomes like %. The default is 20. There is no protection against setting this to a ridiculously high value. Since LIST will follow symbolic links, it can effectively recurse infinitely, until the name strings get large enough that some name limit is exceeded. 28) set anonymous-home-directory Sets the location of the anonymous home directory, if it is not in the standard place. It is recommended to use a courtesy symbolic link instead. There is no protection against setting this to a silly value, and doing so is a great way to cause a crash. 29) set chroot-server This option is for closed server systems only. If defined, a chroot() call to the user's home directory is done as part of the login process. This has the effect of preventing access to any files outside of the user's home directory (including shared mailboxes). Shared mailboxes with other users can't possibly work with this option, because there is no way to export lock information to other users. This should be done ONLY on systems which do not permit users to have shell access This option should NEVER(!!) be set if users are allowed shell access. Doing so actually makes the system *less* secure, since the user could create an etc subdirectory which would be treated as real /etc by such programs as /bin/su. The default is zero (don't do chroot). This option is strongly *NOT* recommended. 30) set disable-automatic-shared-namespaces Never look up the "ftp", "imappublic", and "imapshared" users as posssible home directories for the #ftp, #public, and #shared namespaces. On some systems (reportedly including AIX 4.3.3) getpwnam() of an unknown user name is horrendously slow. Note that this does not remove the #ftp, #public, and #shared namespaces, and they can still be set up by other means. The default is zero (shared namespaces are automatic). 31) set advertise-the-world Include the UNIX root as a shared namespace. This is generally a bad idea, since certain IMAP clients (names withheld to protect the guilty) will take this as license to download the entire filesystem tree. The default is zero (don't advertise the world). 32) set mail-subdirectory Change the default connected directory from the user's home directory to the named subdirectory of the user's home directory. For example, setting MAILSUBDIR="mail" will cause the POP2 and IMAP servers to connect to the user's ~/mail subdirectory. This is equivalent to the env_unix.c edit described in Example 2 of the CONFIG file. Note that if the subdirectory does not exist, the result is undefined. It is probably an extremely bad idea to set this unless you can guarantee that the subdirectory exists for all users. If you can not guarantee this, then you should leave the default as the user's home directory and allow them to configure a personal default in their IMAP client. The default is not to use any subdirectory. 33) set allow-user-config Allow users to use ~/.imaprc and ~/.mminit files. The default is zero (don't allow user config files). 34) set allow-reverse-dns By default, the servers (ipop[23]d and imapd) will do gethostbyaddr() on the local and remote sockets so that imapd can identify itself properly (this is important when the same CPU hosts multiple virtual hosts on different IP addresss) and also includes the client's name when it writes to the syslog. There are also client gethostbyaddr() calls, used primarily by authentication mechanisms. Setting this option to zero disables all gethostbyaddr() calls. The returned "host name" string for the socket is just the bracketed [12.34.56.78] form, as if the reverse DNS lookup failed. WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon the host names being right, and if you set this option, it won't work. You should only do this if you are encountering server performance problems due to a misconfigured DNS, e.g. long startup delays or client timeouts. The default is non-zero (allow reverse DNS). 35) set disable-plaintext Disable plaintext password authentication (LOGIN command, AUTH=LOGIN, and AUTH=PLAIN). The default is zero (allow plaintext authentication). 36) set trust-dns By default, host names are canonicalized via gethostbyname() for everything except for SSL certificate validation. This can represent a security bug due to DNS spoofing, but is more likely to deliver results that users expect. It also may be necessary for SASL authentication to work right (e.g. generating a correct name for a Kerberos service principal) if the name entered by the user is a CNAME or not a fully-qualified domain name. If trust-dns is set to zero, no host name canonicalization is done. The user's actual entered name is used for SASL authentication and will appear in the mailbox name of the open stream. The default is non-zero (do DNS canonicalization). 37) set sasl-uses-ptr-name By default, if trust-dns is set, the host names used in authentication (e.g. to generate a Kerberos service principal) are canonicalized via gethostbyaddr() instead of by gethostbyname(). If gethostbyaddr() fails the gethostbyname() canonicalization is used. This represents an additional security bug due to DNS spoofing, over and above trust-dns. It also adds an additional DNS query to starting a session. It is necessary for sites which implement a server cluster with multiple A records for a cluster name (instead of a CNAME) but each cluster member has a unique PTR record which it expects for a Kerberos service principal. If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the gethostbyname() canonicalized name is used for SASL authentication. The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to zero. The default is non-zero (use name from PTR record for SASL). 38) set network-filesystem-stat-bug By default, traditional UNIX mailbox files are only closed and reopened at checkpoint and expunge time. This ensures that, prior to rewriting the file, that any cached stat() data from a network filesystem is updated with current data. Very old versions of NFS, and reputedly also AFS, can get into a state in which the cached stat() data stays out-of-date, even across a close and reopen of the file. If network-filesystem-stat-bug is set non-zero, then the mailbox file is closed and reopened at ping time as a workaround for this bug in these network filesystems. This means that in imapd, the mailbox file is closed and reopened for every IMAP command. This is obviously something that should be avoided unless absolutely necessary. NFS and AFS are terrible ways to distribute mail. You use use IMAP servers with a local disk instead. The default is zero (only close/reopen at checkpoint and expunge time). Setting this option is a great way to ruin your system's performance. 39) set restrict-mailbox-access