diff --git a/CONTENTS b/CONTENTS new file mode 100644 index 0000000..73a54f6 --- /dev/null +++ b/CONTENTS @@ -0,0 +1,75 @@ +/* ======================================================================== + * 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 + * + * + * ======================================================================== + */ + + TOOLKIT DIRECTORY CONTENTS + +Documentation: + . CONTENTS this file + . LICENSE.txt software license + . NOTICE copyright notice + . README read this file first + . SUPPORT where to go to ask questions and/or report bugs + . docs/BUILD build and installation instructions + . docs/CONFIG detailed configuration notes + . docs/FAQ.html frequently asked questions and answers + . docs/FAQ.txt text version of FAQ.HTML + . docs/RELNOTES release notes + . docs/SSLBUILD build and installation instructions using SSL + . docs/Y2K information relating to Y2K issues + . docs/bugs.txt known bugs and deficiencies in this software + . docs/calendar.txt information relating to the calendar + . docs/commndmt.txt "ten commandments" on how to write a good IMAP client + . docs/draft/ Internet protocol documentation drafts + . docs/drivers.txt how various mailbox format drivers interact, and + comparable features and performance + . docs/formats.txt mailbox formats + . docs/internal.txt programming interfaces + . docs/locking.txt how file locking works + . docs/md5.txt CRAM-MD5 authentication setup instructions + . docs/mixfmt.txt specification of new mix format + . docs/naming.txt mailbox naming conventions + . docs/rfc/ Internet protocol documentation + +Sources: + . Makefile master makefile for UNIX + . makefile.nt master makefile for NT/Win32 + . makefile.ntk master makefile for NT/Win32 using Kerberos V + . makefile.os2 master makefile for OS/2 + . makefile.w2k master makefile for Windows 2000 + . makefile.wce master makefile for Windows CE + . src/ansilib pre-processed ANSI library routines + . src/c-client pre-processed c-client sources + . src/charset pre-processed character set conversion tables + . src/dmail pre-processed user mail delivery sources + . src/ipopd pre-processed POP2/POP3 daemon sources + . src/imapd pre-processed IMAP4rev1 daemon sources + . src/mailutil pre-processed mailbox utility sources + . src/mlock pre-processed mailbox locking sources + . src/mtest pre-processed c-client testbed sources + . src/osdep/amiga pre-processed Amiga-specific sources + . src/osdep/dos pre-processed DOS-specific sources + . src/osdep/mac pre-processed Mac-specific sources + . src/osdep/nt pre-processed NT-specific sources + . src/osdep/os2 pre-processed OS/2-specific sources (incomplete) + . src/osdep/tops-20 pre-processed TOPS-20 specific sources + . src/osdep/unix pre-processed UNIX-specific sources + . src/osdep/vms pre-processed VAX/VMS specific sources + . src/osdep/wce pre-processed Windows CE-specific sources (incomplete) + . src/tmail pre-processed system mail delivery sources + . tools internal tools needed as part of the build process + +Directories created at build time on UNIX and NT/Win32: + . c-client post-processed c-client sources and binary + . ipopd post-processed POP2/POP3 daemon sources and binaries + . imapd post-processed IMAP4rev1 daemon sources and binaries + . mtest post-processed c-client testbed sources and binaries diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..349bd53 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..e6e4987 --- /dev/null +++ b/Makefile @@ -0,0 +1,736 @@ +# ======================================================================== +# 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 +# +# +# ======================================================================== + +# Program: IMAP Toolkit Makefile +# +# Author: Mark Crispin +# UW Technology +# Seattle, WA 98195 +# Internet: MRC@Washington.EDU +# +# Date: 7 December 1989 +# Last Edited: 12 May 2008 + + +# Normal command to build IMAP toolkit: +# make [EXTRAAUTHENTICATORS=xxx] [EXTRADRIVERS=xxx] [EXTRACFLAGS=xxx] +# [PASSWDTYPE=xxx] [SSLTYPE=xxx] [IP=n] + + +# Port name. These refer to the *standard* compiler on the given system. +# This means, for example, that the hpx port is for HP's compiler and not for +# a non-standard compiler such as gcc. +# +# If you are using gcc and it is not the standard compiler on your system, try +# using an ANSI port that is close to what you have. For example, if your +# system is SVR4ish, try a32 or lnx; if it's more BSDish, try nxt, mct, or bsi. +# +# The following ports are bundled: +# a32 AIX 3.2 for RS/6000 +# a41 AIX 4.1 for RS/6000 +# aix AIX/370 (not RS/6000!!) +# ami AmigaDOS +# am2 AmigaDOS with a 68020+ +# ama AmigaDOS using AS225R2 +# amn AmigaDOS with a 680x0 using "new" socket library +# aos AOS for RT +# art AIX 2.2.1 for RT +# asv Altos SVR4 +# aux A/UX +# bs3 BSD/i386 3.0 and higher +# bsd generic BSD 4.3 (as in ancient 1980s version) +# bsf FreeBSD +# bsi BSD/i386 +# bso OpenBSD (yes, yet another one...) +# cvx Convex +# cyg Cygwin +# d-g Data General DG/UX prior to 5.4 (d41 port no longer exists) +# d54 Data General DG/UX 5.4 +# do4 Apollo Domain/OS sr10.4 +# dpx Bull DPX/2 B.O.S. +# drs ICL DRS/NX +# dyn Dynix +# epx EP/IX +# ga4 GCC AIX 4.x for RS/6000 +# gas GCC Altos SVR4 +# gcs GCC Solaris with Blastwave Community Open Source Software +# gh9 GCC HP-UX 9.x +# ghp GCC HP-UX 10.x +# ghs GCC HP-UX 10.x with Trusted Computer Base +# go5 GCC 2.7.1 (95q4 from Skunkware _not_ 98q2!) SCO Open Server 5.0.x +# gsc GCC Santa Cruz Operation +# gsg GCC SGI +# gso GCC Solaris +# gsu GCC SUN-OS +# gul GCC RISC Ultrix (DEC-5000) +# h11 HP-UX 11i +# hpp HP-UX 9.x (see gh9) +# hpx HP-UX 10.x (see ghp, ghs, hxd, and shp) +# hxd HP-UX 10.x with DCE security (see shp) +# isc Interactive Systems +# ldb Debian Linux +# lfd Fedora Core 4 +# ln8 Linux for Nokia N800 +# lnx Linux with traditional passwords and crypt() in the C library +# (see lnp, sl4, sl5, and slx) +# lnp Linux with Pluggable Authentication Modules (PAM) +# lmd Mandrake Linux +# lr5 RedHat Enterprise 5 and later (same as lfd) +# lrh RedHat Linux 7.2 and later +# lsu SuSE Linux (same as lrh) +# lyn LynxOS +# mct MachTen +# mnt Atari ST Mint (not MacMint) +# neb NetBSD +# nec NEC UX +# nto QNX Neutrine RTP +# nxt NEXTSTEP +# nx3 NEXTSTEP 3.x +# osf OSF/1 (see sos, os4) +# os4 OSF/1 (Digital UNIX) 4 +# osi Apple iPhone and iPod Touch +# osx Mac OS X +# oxp Mac OS X with Pluggable Authentication Modules (PAM) +# ptx PTX +# pyr Pyramid +# qnx QNX 4 +# s40 SUN-OS 4.0 (*not* Solaris) +# sc5 SCO Open Server 5.0.x (see go5) +# sco Santa Cruz Operation (see sc5, go5) +# shp HP-UX with Trusted Computer Base +# sgi Silicon Graphics IRIX +# sg6 Silicon Graphics IRIX 6.5 +# sl4 Linux using -lshadow to get the crypt() function +# sl5 Linux with shadow passwords, no extra libraries +# slx Linux using -lcrypt to get the crypt() function +# snx Siemens Nixdorf SININX or Reliant UNIX +# soc Solaris with /opt/SUNWspro/bin/cc +# sol Solaris (won't work unless "ucbcc" works -- use gso instead) +# sos OSF/1 with SecureWare +# ssn SUN-OS with shadow password security +# sua Windows Vista (Enterprise or Ultima) Subsystem for Unix Applications +# sun SUN-OS 4.1 or better (*not* Solaris) (see ssn) +# sv2 SVR2 on AT&T PC-7300 (incomplete port) +# sv4 generic SVR4 +# ult RISC Ultrix (DEC-5000) +# uw2 UnixWare SVR4.2 +# vul VAX Ultrix +# vu2 VAX Ultrix 2.3 (e.g. for VAXstation-2000 or similar old version) + + +# Extra authenticators (e.g. OTP, Kerberos, etc.). Adds linkage for +# auth_xxx.c and executes Makefile.xxx, where xxx is the name of the +# authenticator. Some authenticators are only available from third parties. +# +# The following extra authenticators are bundled: +# gss Kerberos V + +EXTRAAUTHENTICATORS= + + +# Additional mailbox drivers. Add linkage for xxxdriver. Some drivers are +# only available from third parties. +# +# The following extra drivers are bundled: +# mbox if file "mbox" exists on the home directory, automatically moves mail +# from the spool directory to "mbox" and uses "mbox" as INBOX. + +EXTRADRIVERS=mbox + + +# Plaintext password type. Defines how plaintext password authentication is +# done on this system. +# +# The following plaintext login types are bundled: +# afs AFS authentication database +# dce DCE authentication database +# gss Kerberos V +# nul plaintext authentication never permitted +# pam PAM authentication (note: for Linux, you should use the "lnp" port +# instead of setting this...also, you may have to modify PAMLDFLAGS +# in the imap-[]/src/osdep/unix/Makefile +# pmb PAM authentication for broken implementations such as Solaris. +# you may have to modify PAMLDFLAGS +# std system standard (typically passwd file), determined by port +# two try alternative (defined by CHECKPWALT), then std + +PASSWDTYPE=std + + +# SSL type. Defines whether or not SSL support is on this system +# +# The following SSL types are bundled: +# none no SSL support +# unix SSL support using OpenSSL +# nopwd SSL support using OpenSSL, and plaintext authentication permitted only +# in SSL/TLS sessions +# sco link SSL before other libraries (for SCO systems) +# unix.nopwd same as nopwd +# sco.nopwd same as nopwd, plaintext authentication in SSL/TLS only +# +# SSLTYPE=nopwd is now the default as required by RFC 3501 + +SSLTYPE=nopwd + + +# IP protocol version +# +# The following IP protocol versions are defined: +# o IPv4 support, no DNS (truly ancient systems) +# 4 (default) IPv4 support only +# 6 IPv6 and IPv4 support + +IP=4 +IP6=6 + + +# The following extra compilation flags are defined. None of these flags are +# recommended. If you use these, include them in the EXTRACFLAGS. +# +# -DDISABLE_POP_PROXY +# By default, the ipop[23]d servers offer POP->IMAP proxy access, +# which allow a POP client to access mail on an IMAP server by using the +# POP server as a go-between. Setting this option disables this +# facility. +# +# -DOLDFILESUFFIX=\"xxx\" +# Change the default suffix appended to the backup .newsrc file from +# "old". +# +# -DSTRICT_RFC822_TIMEZONES +# Disable recognition of the non-standard UTC (0000), MET (+0100), +# EET (+0200), JST (+0900), ADT (-0300), AST (-0400), YDT (-0800), +# YST (-0900), and HST (-1000) symbolic timezones. +# +# -DBRITISH_SUMMER_TIME +# Enables recognition of non-standard symbolic timezone BST as +0100. +# +# -DBERING_STANDARD_TIME +# Enables recognition of non-standard symbolic timezone BST as -1100. +# +# -DNEWFOUNDLAND_STANDARD_TIME +# Enables recognition of non-standard symbolic timezone NST as -0330. +# +# -DNOME_STANDARD_TIME +# Enables recognition of non-standard symbolic timezone NST as -1100. +# +# -DSAMOA_STANDARD_TIME +# Enables recognition of non-standard symbolic timezone SST as -1100. +# +# -DY4KBUGFIX +# Turn on the Y4K bugfix (yes, that's year 4000). It isn't well-known, +# but century years evenly divisible by 4000 are *not* leap years in the +# Gregorian calendar. A lot of "Y2K compilant" software does not know +# about this rule. Remember to turn this on sometime in the next 2000 +# years. +# +# -DUSEORTHODOXCALENDAR +# Use the more accurate Eastern Orthodox calendar instead of the +# Gregorian calendar. The century years which are leap years happen +# at alternating 400 and 500 year intervals without shifts every 4000 +# years. The Orthodox and Gregorian calendars diverge by 1 day for +# gradually-increasing intervals, starting at 2800-2900, and becoming +# permanent at 48,300. +# +# -DUSEJULIANCALENDAR +# Use the less accurate Julian calendar instead of the Gregorian +# calendar. Leap years are every 4 years, including century years. +# My apologies to those in the English-speaking world who object to +# the reform of September 2, 1752 -> September 14, 1752, since this +# code still uses January 1 (which Julius Ceasar decreed as the start +# of the year, which since 153 BCE was the day that Roman consuls +# took office), rather than the traditional March 25 used by the +# British. As of 2005, the Julian calendar and the Gregorian calendar +# diverge by 15 days. + +EXTRACFLAGS= + + +# Extra linker flags (additional/alternative libraries, etc.) + +EXTRALDFLAGS= + + +# Special make flags (e.g. to override make environment variables) + +EXTRASPECIALS= +SPECIALS= + + +# Normal commands + +CAT=cat +CD=cd +LN=ln -s +MAKE=make +MKDIR=mkdir +BUILDTYPE=rebuild +RM=rm -rf +SH=sh +SYSTEM=unix +TOOLS=tools +TOUCH=touch + + +# Primary build command + +BUILD=$(MAKE) build EXTRACFLAGS='$(EXTRACFLAGS)'\ + EXTRALDFLAGS='$(EXTRALDFLAGS)'\ + EXTRADRIVERS='$(EXTRADRIVERS)'\ + EXTRAAUTHENTICATORS='$(EXTRAAUTHENTICATORS)'\ + PASSWDTYPE=$(PASSWDTYPE) SSLTYPE=$(SSLTYPE) IP=$(IP)\ + EXTRASPECIALS='$(EXTRASPECIALS)' + + +# Make the IMAP Toolkit + +all: c-client SPECIALS rebuild bundled + +c-client: + @echo Not processed yet. In a first-time build, you must specify + @echo the system type so that the sources are properly processed. + @false + + +SPECIALS: + echo $(SPECIALS) > SPECIALS + +# Note on SCO you may have to set LN to "ln". + +a32 a41 aix bs3 bsi d-g d54 do4 drs epx ga4 gas gh9 ghp ghs go5 gsc gsg gso gul h11 hpp hpx lnp lyn mct mnt nec nto nxt nx3 osf os4 ptx qnx sc5 sco sgi sg6 shp sl4 sl5 slx snx soc sol sos uw2: an + $(BUILD) BUILDTYPE=$@ + +# If you use sv4, you may find that it works to move it to use the an process. +# If so, you probably will want to delete the "-Dconst=" from the sv4 CFLAGS in +# the c-client Makefile. + +aos art asv aux bsd cvx dpx dyn isc pyr sv4 ult vul vu2: ua + $(BUILD) BUILDTYPE=$@ + + +# Knotheads moved Kerberos and SSL locations on these platforms + +# Paul Vixie claims that all FreeBSD versions have working IPv6 + +bsf: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=$@ IP=$(IP6) \ + PASSWDTYPE=pam \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl/certs SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMLDFLAGS=-lpam" + +# I assume that Theo did the right thing for IPv6. OpenBSD does not have PAM. + +bso: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=$@ IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib" + +# Info from Joel Reicher about NetBSD SSL paths. I assume it has PAM because pam is in NetBSD sources... + +neb: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=$@ IP=$(IP6) \ + PASSWDTYPE=pam \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/openssl/certs SSLKEYS=/etc/openssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMLDFLAGS=-lpam" + +cyg: an + $(BUILD) BUILDTYPE=cyg \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/ssl/certs SSLKEYS=/usr/ssl/certs" + +gcs: an + $(BUILD) BUILDTYPE=gso \ + SPECIALS="SSLINCLUDE=/opt/csw/include/openssl SSLLIB=/opt/csw/lib SSLCERTS=/opt/csw/ssl/certs SSLKEYS=/opt/csw/ssl/certs" + +ldb: an + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl/certs SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib MAILSPOOL=/var/mail" + +lfd: an + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/pki/tls/certs SSLKEYS=/etc/pki/tls/private GSSDIR=/usr/kerberos" + +ln8: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=slx IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/lib/ssl/certs MAILSPOOL=/var/mail" + + +# RHE5 does not have the IPv6 bug + +lr5: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/pki/tls/certs SSLKEYS=/etc/pki/tls/private GSSDIR=/usr/kerberos" + +lmd: an + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/lib/ssl/certs SSLKEYS=/usr/lib/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib" + +# RHE3 definitely has the IPv6 bug + +lrh: lrhok an + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/share/ssl/certs SSLKEYS=/usr/share/ssl/private GSSDIR=/usr/kerberos" + +lrhok: + @$(SH) -c '(test ! -d /etc/pki/tls ) || make lrhwarn' + @$(TOUCH) lrhok + +lrhwarn: + @echo You are building for OLD versions of RedHat Linux. This build + @echo is NOT suitable for RedHat Enterprise 5, which stores SSL/TLS + @echo certificates and keys in /etc/pki/tls rather than /usr/share/ssl. + @echo If you want to build for modern RedHat Linux, you should use + @echo make lr5 instead. + @echo Do you want to continue this build? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac' + @echo OK, I will remember that you really want to build for old + @echo RedHat Linux. You will not see this message again. + @echo If you realize that you really wanted to build for modern + @echo RedHat Linux, then do the following commands: + @echo % rm lrhok + @echo % make clean + @echo % make lr5 + +lsu: an + $(BUILD) BUILDTYPE=lnp IP=$(IP6) \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/share/ssl/certs SSLKEYS=/usr/share/ssl/private GSSDIR=/usr/kerberos" + +# iToy does not have Kerberos or PAM. It doesn't have a +# /System/Library/OpenSSL directory either, but the libcrypto shared library +# has these locations so this is what we will use. + +osi: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=osx IP=$(IP6) CC=arm-apple-darwin-gcc \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private" + +oxp: an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=osx IP=$(IP6) EXTRAAUTHENTICATORS="$(EXTRAAUTHENTICATORS) gss" \ + PASSWDTYPE=pam \ + EXTRACFLAGS="$(EXTRACFLAGS) -DMAC_OSX_KLUDGE=1" \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMDLFLAGS=-lpam" + +osx: osxok an + $(TOUCH) ip6 + $(BUILD) BUILDTYPE=$@ IP=$(IP6) EXTRAAUTHENTICATORS="$(EXTRAAUTHENTICATORS) gss" \ + SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib" + +osxok: + @$(SH) -c '(test ! -f /usr/include/pam/pam_appl.h ) || make osxwarn' + @$(TOUCH) osxok + +osxwarn: + @echo You are building for OLD versions of Mac OS X. This build is + @echo NOT suitable for modern versions of Mac OS X, such as Tiger, + @echo which use PAM-based authentication. If you want to build for + @echo modern Mac OS X, you should use make oxp instead. + @echo Do you want to continue this build? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac' + @echo OK, I will remember that you really want to build for old + @echo Mac OS X. You will not see this message again. + @echo If you realize that you really wanted to build for modern + @echo Mac OS X, then do the following commands: + @echo % rm osxok + @echo % make clean + @echo % make oxp + + +# Linux shadow password support doesn't build on traditional systems, but most +# Linux systems are shadow these days. + +lnx: lnxnul an + $(BUILD) BUILDTYPE=$@ + +lnxnul: + @$(SH) -c '(test $(PASSWDTYPE) = nul) || make lnxok' + +lnxok: + @echo You are building for traditional Linux. Most modern Linux + @echo systems require that you build using make slx. + @echo Do you want to continue this build? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac' + @echo OK, I will remember that you really want to build for + @echo traditional Linux. You will not see this message again. + @echo If you discover that you can not log in to the POP and IMAP + @echo servers, then do the following commands: + @echo % rm lnxok + @echo % make clean + @echo % make slx + @echo If slx does not work, try sl4 or sl5. Be sure to do a + @echo make clean between each try! + @$(TOUCH) lnxok + + +# SUN-OS C compiler makes you load libdl by hand... + +ssn sun: sunok suntools ua + $(BUILD) BUILDTYPE=$@ + +suntools: + $(CD) tools;$(MAKE) LDFLAGS=-ldl + +gsu: sunok an + $(BUILD) BUILDTYPE=$@ + +s40: sunok ua + $(BUILD) BUILDTYPE=$@ + +sunok: + @echo You are building for the old BSD-based SUN-OS. This is NOT + @echo the modern SVR4-based Solaris. If you want to build for + @echo Solaris, you should use make gso or make sol or make soc. Do + @echo you want to continue this build? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac' + @echo OK, I will remember that you really want to build for the old + @echo BSD-based SUN-OS. You will not see this message again. + @echo If the build fails and you realize that you really wanted to + @echo build for Solaris, then do the following commands: + @echo % rm sunok + @echo % make clean + @echo % make gso + @echo If gso does not work, try sol. Be sure to do a make clean + @echo between each try! + @$(TOUCH) sunok + + +# SVR2 doesn't have symbolic links (at least my SVR2 system doesn't) + +sv2: + $(MAKE) ua LN=ln + $(BUILD) BUILDTYPE=$@ LN=ln + +# Hard links don't quite work right in SUA, and there don't seem to be any +# SSL includes. However, IPv6 works. + +sua: + $(TOUCH) ip6 sslnone + $(MAKE) an LN=cp SSLTYPE=none + $(BUILD) BUILDTYPE=$@ LN=cp IP=$(IP6) SSLTYPE=none + + +# Pine port names, not distinguished in c-client + +bs2: an + $(BUILD) BUILDTYPE=bsi + +pt1: an + $(BUILD) BUILDTYPE=ptx + + +# Compatibility + +hxd: + $(BUILD) BUILDTYPE=hpx PASSWDTYPE=dce + +# Amiga + +ami am2 ama amn: + $(MAKE) an LN=cp SYSTEM=amiga + $(BUILD) BUILDTYPE=$@ LN=cp + + +# Courtesy entries for Microsoft systems + +nt: + nmake /nologo /f makefile.nt + +ntk: + nmake /nologo /f makefile.ntk + +w2k: + nmake /nologo /f makefile.w2k + +wce: + nmake /nologo /f makefile.wce + + +# SSL build choices + +sslnopwd sslunix.nopwd sslsco.nopwd: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Building in full compliance with RFC 3501 security + @echo + requirements: + @echo ++ TLS/SSL encryption is supported + @echo ++ Unencrypted plaintext passwords are prohibited + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +sslunix sslsco: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Building in PARTIAL compliance with RFC 3501 security + @echo + requirements: + @echo + Compliant: + @echo ++ TLS/SSL encryption is supported + @echo + Non-compliant: + @echo ++ Unencrypted plaintext passwords are permitted + @echo + + @echo + In order to rectify this problem, you MUST build with: + @echo ++ SSLTYPE=$(SSLTYPE).nopwd + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + @echo Do you want to continue this build anyway? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make nounenc;exit 1);; esac' + +nounenc: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + At your request, this build with unencrypted authentication has + @echo + been CANCELLED. + @echo + You must start over with a new make command. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +sslnone: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Building in NON-COMPLIANCE with RFC 3501 security requirements: + @echo + Non-compliant: + @echo ++ TLS/SSL encryption is NOT supported + @echo ++ Unencrypted plaintext passwords are permitted + @echo + + @echo + In order to rectify this problem, you MUST build with: + @echo ++ SSLTYPE=nopwd + @echo + You must also have OpenSSL or equivalent installed. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + @echo Do you want to continue this build anyway? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make nonossl;exit 1);; esac' + +nonossl: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + At your request, this build with no TLS/SSL support has been + @echo + CANCELLED. + @echo + You must start over with a new make command. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +# IP build choices + +ip4: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Building with IPv4 support + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +ip6: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Building with IPv6 support + @echo + + @echo + NOTE: Some versions of glibc have a bug in the getaddrinfo + @echo + call which does DNS name resolution. This bug causes host + @echo + names to be canonicalized incorrectly, as well as doing an + @echo + unnecessary and performance-sapping reverse DNS call. This + @echo + problem does not affect the IPv4 gethostbyname call. + @echo + + @echo + getaddrinfo works properly on Mac OS X and Windows. However, + @echo + the problem has been observed on some Linux systems. + @echo + + @echo + If you answer n to the following question the build will be + @echo + cancelled and you must rebuild. If you did not specify IPv6 + @echo + yourself, try adding IP6=4 to the make command line. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + @echo Do you want to build with IPv6 anyway? Type y or n please: + @$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make noip6;exit 1);; esac' + @echo OK, I will remember that you really want to build with IPv6. + @echo You will not see this message again. + @$(TOUCH) ip6 + +noip6: + $(MAKE) clean + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + At your request, this build with IPv6 has been CANCELLED. + @echo + You must start over with a new make command. + @echo + + @echo + If you wish to rebuild without IPv6 support, do one of the + @echo + following: + @echo + + @echo + 1. If you specified IP=6 on the make command line, omit it. + @echo + + @echo + 2. Some of the Linux builds automatically select IPv6. If + @echo + you choose one of those builds, add IP6=4 to the make command + @echo + line. Note that this is IP6=4, not IP=4. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +# C compiler types + +an ua: + @$(MAKE) ssl$(SSLTYPE) + @echo Applying $@ process to sources... + $(TOOLS)/$@ "$(LN)" src/c-client c-client + $(TOOLS)/$@ "$(LN)" src/ansilib c-client + $(TOOLS)/$@ "$(LN)" src/charset c-client + $(TOOLS)/$@ "$(LN)" src/osdep/$(SYSTEM) c-client + $(TOOLS)/$@ "$(LN)" src/mtest mtest + $(TOOLS)/$@ "$(LN)" src/ipopd ipopd + $(TOOLS)/$@ "$(LN)" src/imapd imapd + $(TOOLS)/$@ "$(LN)" src/mailutil mailutil + $(TOOLS)/$@ "$(LN)" src/mlock mlock + $(TOOLS)/$@ "$(LN)" src/dmail dmail + $(TOOLS)/$@ "$(LN)" src/tmail tmail + $(LN) $(TOOLS)/$@ . + +build: OSTYPE rebuild rebuildclean bundled + +OSTYPE: + @$(MAKE) ip$(IP) + @echo Building c-client for $(BUILDTYPE)... + @$(TOUCH) SPECIALS + echo `$(CAT) SPECIALS` $(EXTRASPECIALS) > c-client/SPECIALS + $(CD) c-client;$(MAKE) $(BUILDTYPE) EXTRACFLAGS='$(EXTRACFLAGS)'\ + EXTRALDFLAGS='$(EXTRALDFLAGS)'\ + EXTRADRIVERS='$(EXTRADRIVERS)'\ + EXTRAAUTHENTICATORS='$(EXTRAAUTHENTICATORS)'\ + PASSWDTYPE=$(PASSWDTYPE) SSLTYPE=$(SSLTYPE) IP=$(IP)\ + $(SPECIALS) $(EXTRASPECIALS) + echo $(BUILDTYPE) > OSTYPE + $(TOUCH) rebuild + +rebuild: + @$(SH) -c '(test $(BUILDTYPE) = rebuild -o $(BUILDTYPE) = `$(CAT) OSTYPE`) || (echo Already built for `$(CAT) OSTYPE` -- you must do \"make clean\" first && exit 1)' + @echo Rebuilding c-client for `$(CAT) OSTYPE`... + @$(TOUCH) SPECIALS + $(CD) c-client;$(MAKE) all CC=`$(CAT) CCTYPE` \ + CFLAGS="`$(CAT) CFLAGS`" `$(CAT) SPECIALS` + +rebuildclean: + $(SH) -c '$(RM) rebuild || true' + +bundled: + @echo Building bundled tools... + $(CD) mtest;$(MAKE) + $(CD) ipopd;$(MAKE) + $(CD) imapd;$(MAKE) + $(CD) mailutil;$(MAKE) + @$(SH) -c '(test -f /usr/include/sysexits.h ) || make sysexitwarn' + $(CD) mlock;$(MAKE) || true + $(CD) dmail;$(MAKE) || true + $(CD) tmail;$(MAKE) || true + + +sysexitwarn: + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + @echo + Hmm...it does not look like /usr/include/sysexits.h exists. + @echo + Either your system is too ancient to have the sysexits.h + @echo + include, or your C compiler gets it from some other location + @echo + than /usr/include. If your system is too old to have the + @echo + sysexits.h include, you will not be able to build the + @echo + following programs. + @echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +clean: + @echo Removing old processed sources and binaries... + $(SH) -c '$(RM) an ua OSTYPE SPECIALS c-client mtest imapd ipopd mailutil mlock dmail tmail || true' + $(CD) tools;$(MAKE) clean + + +# A monument to a hack of long ago and far away... +love: + @echo not war? diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..a8f5136 --- /dev/null +++ b/NOTICE @@ -0,0 +1,17 @@ +UW IMAP toolkit notices: + +This software was developed by the University of Washington +(http://www.washington.edu/). + +The Univerity of Washington IMAP Toolkit (c-client API, dmail, imapd, +ipop2d, ipop3d, mailutil, mlock, mtest, and tmail software; and its +included text) is Copyright 1988-2007 by the University of Washington. + +The c-client library and mtest software are in part based upon code +developed by Mark Crispin at Stanford University, and is + + * Copyright 1988 Stanford University and was developed in the + * Symbolic Systems Resources Group of the Knowledge Systems Laboratory + * at Stanford University in 1987-88, and was funded by the + * Biomedical Research Technology Program of the National Institutes of + * Health under grant number RR-00785. diff --git a/README b/README new file mode 100644 index 0000000..d412d5b --- /dev/null +++ b/README @@ -0,0 +1,74 @@ +/* ======================================================================== + * 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 Environment + 4 April 2007 + Mark Crispin + + + UNIX QUICK BUILD NOTES + +These quick build notes assume that you have installed OpenSSL before +attempting to build this software, and that you do not have any non-default +configuration parameters. + +If you need additional information in building this software with OpenSSL, +please refer to the docs/SSLBUILD file for more information. + +If you intend to build this software with a non-default configuration +(including building a non-compliant server without SSL support), please +refer to the docs/BUILD file for more information. + +1) Look in the top-level Makefile and find your system type code. For example, + modern versions of Linux will use either "slx", "lnp", or one of the + lnp-variants (such as "lrh"). + +2) Type "make" followed by the system type, e.g. "make slx". + +3) Install the POP2 daemon (ipopd/ipop2d), the POP3 daemon (ipopd/ipop3d), and + the IMAP daemon (imapd/imapd) on a system directory of your choosing. + +4) Update /etc/services to register the pop2 service on TCP port 109, the + pop3 service on TCP port 110, and the imap service on TCP port 143. Also + update Yellow Pages/NIS/NetInfo/etc. if appropriate on your system. + +5) Update /etc/inetd.conf (or install files on /etc/xinetd.d) to invoke the + POP2, POP3, and IMAP daemons on their associated services. + +6) If your system uses PAM authentication, be sure to set up /etc/pam.d/imap + (*not* /etc/pam.d/imapd) and /etc/pam.d/pop (*not* /etc/pam.d/ipop3d or + /etc/pam.d/pop3d or /etc/pam.d/popd or /etc/pam.d/pop3). + +7) Unless you built your system without SSL support, you will need to set + up SSL server certificates as described in docs/SSLBUILD. + +6) That's all! + +Read the file docs/BUILD and docs/SSLBUILD if you need more detailed +information and/or you don't understand these quick build instructions. + + MISCELLANEOUS NOTES + + mtest has been run under UNIX, DOS, Windows, NT, Macintosh, TOPS-20, and +VMS. It is a very primitive interface, however, and is suited mainly as a +model of how to write a main program for c-client. You should take a look at +the source to figure out how to use it. Briefly, it first asks for a mailbox +name (either a local file path or an IMAP mailbox in the form +"{hostname}mailbox") and then puts you in a command mode where "?" will give +you a list of commands. + + Pine is available separately on the FTP.CAC.Washington.EDU archives. + + The focus of development and support is for UNIX and Win32 (including +Windows 95/98/Millenium, Windows NT, and Windows 2000). The other ports are +not frequently used or tested, and may be incomplete. diff --git a/SUPPORT b/SUPPORT new file mode 100644 index 0000000..562f51e --- /dev/null +++ b/SUPPORT @@ -0,0 +1,22 @@ +/* ======================================================================== + * 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. diff --git a/docs/BUILD b/docs/BUILD new file mode 100644 index 0000000..e094e06 --- /dev/null +++ b/docs/BUILD @@ -0,0 +1,491 @@ +/* ======================================================================== + * Copyright 1988-2007 University of Washington + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * + * ======================================================================== + */ + + BUILD AND INSTALLATION NOTES + Last Updated: 15 November 2007 + +Table of Contents: +1. UNIX Build Notes +2. UNIX Installation Notes +3. Win32 Build Notes +4. Win32 Installation Notes +5. Inactive Ports (TOPS-20, VMS) +6. Other ports (Macintosh, DOS/Win16, Windows CE, Amiga, OS/2) + + + UNIX BUILD NOTES + + The default build on many systems with IPv4 only. To build with IPv6, +add "IP=6" to the make command line, e.g. + make lnp IP=6 + + The default build is to build with SSL and disabling plaintext passwords +unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This means that +OpenSSL MUST be installed before building the IMAP toolkit. Please refer to +the SSLBUILD file for more information. + + To build without SSL, add "SSLTYPE=none" to the make command line. +Note that doing so will produce an IMAP server which is NON-COMPLIANT with +RFC 3501. + + You must build through the top-level imap-2007/Makefile, which will run +a "process" step the first time and create the imap-2007/c-client, +imap-2007/ipopd, and imap-2007/imapd directories in which building actually +takes place. + + Before doing a make on UNIX, you should read imap-2007/Makefile and see +if your system type is known. The various system types are three-letter codes. +If your system type is known, then use this as the make option. After the +first time you do a make, this option is remembered in a file called OSTYPE, +so just typing "make" suffices. + + For example, if you are using a more or less modern Linux system, your +system type is probably one of the specific distribution types (such as lrh for +RedHat). For more generic builds, try slx (shadow passwords only) or lnp (PAM). +To build for RedHat, do: + make lrh + + There are other make options, described in imap-2007/src/osdep/Makefile. + + It's probably best to see if an existing port will work on your system +before inventing a new port. Try: + sv4 generic SVR4, non-ANSI compiler + a32 modern SVR4 + bsd basic 4.3 BSD, non-ANSI compiler + bsf modern BSD + + If you must invent a new port, you need to create an entry in +imap-2007/Makefile and imap-2007/src/osdep/Makefile for your new port, as +well as osdep/os_???.h and osdep/os_???.c files with the appropriate +OS-dependent support for that system. You also need to determine which setup +process to use. You should use the ua process unless you are sure that your +compiler supports *ALL* aspects of ANSI C prototyping. Note that some +compilers, such as Ultrix, support some aspects of ANSI C but not others; +c-client really beats on the full prototyping capability of ANSI C so you +have to use the non-ANSI source tree for such systems. + + If you send a new port back to us, we will make it available for others +who use your particular system type. + + The mbox driver is now enabled by default. If the file "mbox" exists on +the user's home directory and is in UNIX mailbox format, then when INBOX is +opened this file will be selected as INBOX instead of the mail spool file. +Messages will be automatically transferred from the mail spool file into the +mbox file. To disable this behavior, delete "mbox" from the EXTRADRIVERS list +in the top-level Makefile and rebuild. + + WARNING: The SVR2 (sv2) port is *incomplete*. SVR2 does not appear to +have any way to do ftruncate(), which is needed by the mbox, mbx, mmdf, mtx, +tenex, and unix drivers. + + UNIX INSTALLATION NOTES + + Binaries from the build are: + imap-2007/mtest/mtest c-client testbed program + imap-2007/ipopd/ipop2d POP2 daemon + imap-2007/ipopd/ipop3d POP3 daemon + imap-2007/imapd/imapd IMAP4rev1 daemon + + mtest is normally not used except by c-client developers. + +STEP 1: [x]inetd setup + + The ipop2d, ipop3d, and imapd daemons should be installed in a system +daemon directory and invoked by a listener such as xinetd or inetd. In the +following examples, /usr/local/etc is used). + +STEP 1(A): xinetd-specific setup + + If your system uses xinetd, the daemons are invoked by files in your +/etc/xinetd.d directory with names corresponding to the service names (that +is: imap, pop2, pop3). You will need to consult your local xinetd +documentation to see what should go into these files. Here is a a sample +/etc/xinetd.d/imap file: + +service imap +{ + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/etc/imapd + groups = yes + flags = REUSE IPv6 +} + +STEP 1(B): inetd-specific setup + + If your system still uses inetd, the daemons are invoked by your +/etc/inetd.conf file with lines such as: + +pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d +pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d +imap stream tcp nowait root /usr/local/etc/imapd imapd + + Note that different variants of UNIX have different versions of inetd, +so you should verify the precise form of these commands (for example, some +versions of inetd do not require the "nowait"). + + IMPORTANT NOTE: inetd has a limit of how many new connections it will +allow in a certain interval, and when this limit is exceeded, it shuts down +the server. If you have anything beyond a small-scale server, you are +probably going to run up against this limit. You'll know when it happens; +your syslog will give the misleading message "imap/tcp server failing +(looping), service terminated" and users will complain that IMAP service is +unavailable for the next 10 minutes. Similarly with "pop3/tcp server +failing"... + + It must be emphasized that this is *NOT* a bug in the IMAP or POP +servers, nor is it anything that I can "fix". It is an inetd problem, and +the only way to fix it is to change inetd's behavior. + + By default, the parameters of this limit are (from inetd.c source code): + +#define TOOMANY 40 /* don't start more than TOOMANY */ +#define CNT_INTVL 60 /* servers in CNT_INTVL sec. */ +#define RETRYTIME (60*10) /* retry after bind or server fail */ + +That is, no more than 40 connections (TOOMANY) in 60 seconds (CNT_INTL), and +if exceeded, shut down the server for 10 minutes (RETRYTIME). This was a +good setting in the 1980s ARPAnet, but is much too small today. + + Some versions of inetd allow you to see a higher maximum in the +/etc/inetd.conf file. Read "man inetd" and see if you see something like +this in the text: + + The wait/nowait entry is applicable to datagram sockets only [...] + [...] The optional ``max'' suffix (separated from + ``wait'' or ``nowait'' by a dot) specifies the maximum number of server + instances that may be spawned from inetd within an interval of 60 sec- + onds. When omitted, ``max'' defaults to 40. + +If you see this, then edit the /etc/inetd.conf entry for imapd to be +something like: + +imap stream tcp nowait.100 root /usr/local/etc/imapd imapd + (or, if you use TCP wrappers) +imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd + + Otherwise, you'll need to edit the inetd source code to set TOOMANY to a +higher value, then rebuild inetd. + + +STEP 2: services setup + + You may also have to edit your /etc/services (or Yellow Pages, +NetInfo, etc. equivalent) to register these services, such as: + +pop 109/tcp +pop3 110/tcp +imap 143/tcp + + +STEP 3: PAM setup + + If your system has PAM (Pluggable Authentication Modules -- most +modern systems do) then you need to set up PAM authenticators for imap and +pop. The correct file names are + /etc/pam.d/imap +and + /etc/pam.d/pop + + It probably works to copy your /etc/pam.d/ftpd file to the above two +names. + + Many people get these file names wrong, and then spend a lot of time +trying to figure out why it doesn't work. Common mistakes are: + /etc/pam.d/imapd + /etc/pam.d/imap4 + /etc/pam.d/imap4rev1 + /etc/pam.d/ipop3d + /etc/pam.d/pop3d + /etc/pam.d/popd + /etc/pam.d/pop3 + + +STEP 4: optional rimap setup + + If you want to enable the rimap capability, which allows users with a +suitable client and .rhosts file on the server to access IMAP services +without transmitting her password in the clear over the network, you need +to have /etc/rimapd as a link to the real copy of imapd. Assuming you have +imapd installed on /usr/local/etc as above: + % ln -s /usr/local/etc/imapd /etc/rimapd + + Technical note: rimap works by having the client routine tcp_aopen() +invoke `rsh _host_ exec /etc/rimapd' in an child process, and then returning +pipes to that process' standard I/O instead of a TCP socket. You can set up +`e-mail only accounts' by making the shell be something which accepts only +that string and not ordinary UNIX shell commands. + + +STEP 4: notes on privileges + + Neither user "root", not any other UID 0 account, can log in via IMAP or +POP. "That's not a bug, it's a feature!" + + This software is designed to run without privileges. The mail spool +directory must be protected 1777; that is, with world write and the sticky +bit. Of course, mail *files* should be protected 600! + + An alternative to having the mail spool directory protected 1777, at the +cost of some performance, is to use the external "mlock" program, available +as part of the imap-utils package. With mlock installed as /etc/mlock and +setgid mail, the spool directory can be protected 775 with group mail. +Please disregard this paragraph if you don't understand it COMPLETELY, and +know EXACTLY what to do without question. + + +STEP 5: SVR4 specific setup + + There is one "gotcha" on System V Release 4 based systems such as +Solaris. These systems do not use the standard UNIX mail format, but rather a +variant of that format that depends upon a bogus "Content-Length:" message +header. This is widely recognized to have been a terrible mistake. One +symptom of the problem is that under certain circumstances, a message may get +broken up into several messages. I'm also aware of security bugs caused by +programs that foolishly trust "Content-Length:" headers with evil values. + + To fix your system, edit your sendmail.cf to change the Mlocal line to +have the -E flag. A typical entry will lool like: + +Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, A=mail.local -d $u + + WIN32 BUILD NOTES + + Visual C++ 6.0 along with the current Microsoft Platform SDK +(specifically the CORE SDK and the Internet Development SDK) is required +to build on Windows 9x/Me/NT/2K/XP. If you do not have the Platform SDK +installed or in your path properly, you'll get errors when building os_nt.c, +typically in env_nt.c, ssl_nt.c, ssl_w2k.c, or gss_shim.c. You can download +the Microsoft Platform SDK from Microsoft's web site. + + There is also considerable debate about how new mail is to be snarfed. +I am currently using something that seems to work with WinSMTP. Look at +the definition of MAILFILE in imap-2007/src/osdep/nt/mailfile.h and at the +sysinbox() function in imap-2007/src/osdep/nt/env_nt.c to see what's there +now, so you have a clue about how to hack it. + + To build under Windows 95/98/NT, connect to the imap-2007 directory +and do: + nmake -f makefile.nt +The resulting binaries will support SSL if either schannel.dll or +security.dll is installed in Windows, using the old, undocumented, SSL +interfaces. You can also use this to build under Me/2000/XP, but it is +not the preferred build on this platform. + + To build with MIT Kerberos support, connect to the imap-2007 directory +and do: + nmake -f makefile.ntk +The resulting binaries will support SSL if either schannel.dll or +security.dll is installed in Windows, using the old, undocumented SSL +interfaces. They will also support MIT Kerberos. Note, however, that +these binaries will only run on systems which have the MIT Kerberos DLLs +installed, and will not run otherwise. + + To build under Windows Me/2000/XP, connect to the imap-2007 directory +and do: + nmake -f makefile.w2k +The resulting binaries will support SSL and Microsoft Kerberos, using the +official, documented, Microsoft interfaces. Note, however, that these +binaries will not run under Windows 95, Windows 98, or Windows NT4. + + WIN32 INSTALLATION NOTES + + The resulting binaries will be: + imap-2007\mtest\mtest.exe (testbed client) + imap-2007\ipopd\ipop2d.exe POP2 server + imap-2007\ipopd\ipop3d.exe POP3 server + imap-2007\imapd\imapd.exe IMAP4rev1 server + + These servers are stdio servers. I wrote a simple network listener +for NT called inetlisn; currently it is available as: + ftp://ftp.cac.washington.edu/mail/nt/inetlisn.tar +To build this, use "nmake" after connecting to the inetlisn directory. +inetlisn takes two arguments, the first being the port number and the second +being the binary to run to serve a connection on that port, e.g. + c:\bin\inetlisn 143 c:\mail_daemons\imapd + + Note that NT imapd must be started as SYSTEM in order to be recognized as +being "not logged in"; otherwise it will preauth as whatever user it is +running as which is probably not what you want. One way to have it run as +system is to have inetlisn run by an AT command, e.g. if the time now is +2:05PM, try something like: + AT 14:06 "c:\bin\inetlisn 143 c:\mail_daemons\imapd" + + A more advanced network listener called wsinetd is available on: + http://wsinetd.sourceforge.net +It is based on inetlisn, and essentially is a "completed" version of inetlisn. + + Bottom line: this is not plug-and-play. If you're not a hacker and/or +are unwilling to invest the time to do some programming, you probably want to +buy a commercial server product. + + INACTIVE PORTS + + The TOPS-20 and VMS ports were developed at one time or another, but are +no longer actively developed. However, from time to time I test build both +of these to make sure that they compile without errors and that mtest runs, +and will continue doing so as long as I have access to systems running these +operating systems. + + + TOPS-20 BUILD NOTES + + I have provided a c-client port for TOPS-20 systems, but you're on your +own in terms of a nice TOPS-20 like main program. Maybe someday some nice +person will try porting Pine to TOPS-20. This assumes the use of KCC 6, and +probably will not build with other compilers or older versions of KCC. + + You do not use imap-2007/Makefile under TOPS-20, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/tops-20 onto a single directory on TOPS-20 and build from +that. The command: + DO BUILD.CTL +will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let +BATCON execute it. + + + VMS BUILD NOTES + + The VMS port has been tested with imap-2007, but as I am soon going +to lose access to a VMS system I will no longer be able able to test and +this port will be moved to the "other ports" category". + + You do not use imap-2007/Makefile under VMS, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/vms onto a single directory on VMS and build from that. +The command to build it is: + @BUILD MULTINET +or @BUILD NETLIB +If you just do @BUILD it will build with dummy TCP code, and since only TCP +based drivers are provided here this isn't too useful. + + If you aren't on the Pacific coast of the US or Canada, you probably will +need to change the wired-in timezone in the BUILD.COM file. Apparently, the +wonderful VMS system that DEC loves so much doesn't maintain any concept of +time zone; the VMS C compiler returns a null pointer from gmtime()! + + Otherwise you're pretty much on your own here. + + OTHER PORTS + + The following ports were developed at one time or another, but are no +longer actively developed or tested. It is not known if they still work or +not. + + Port Status + ---- ------ +Macintosh Obsolete; Mac OS X uses UNIX port +DOS/Win16 Obsolete; modern PCs use Win32 port +Windows CE Never completed +Amiga Unknown +OS/2 Unknown + + MACINTOSH BUILD NOTES + + This port is for the old Mac OS system, not Mac OS X. + + If you are building a Macintosh client, you will need MacTCP installed on +your system as well as the MacTCP C includes and libraries. + + You do not use imap-2007/Makefile on the Mac, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/mac onto a single directory on the Mac and build from +that. mtext.sit.hqx is a THINK C project file and cute icon for building +mtest, encoded with Binhex and StuffIt. + + THINK C is a truly wretched product which help make me understand why +Macintosh has lost most of its market share. Not only does it do cretinous +things such as barf about a cast in front of an lvalue, it also limits the size +of code *or* data in a single file to 32K! So much for having large character +set tables. Symantec says that "MacOS requires it, break up your files into +smaller pieces" yet somehow gcc under MachTen contrives to compile C programs +without subjecting the programmer to this idiocy. + + As a result of this, I found myself obliged to comment out the #includes +of the East Asian character sets in utf8.c in order to get it to build. It's +also necessary to break up some of the files, at least mail.c and imap4r1.c. +Maybe you don't have to do this in CodeWarrior or whatever the new compiler is +called, but I've pretty much given up on Macintosh. + + If you use precompiled headers, you may get some compilation errors since +some Apple symbols need to be redefined in order to get it to build under all +versions of MacOS. Try turning off the precompiled headers (so it will +re-read the .h files) and see if it builds any better. + + If you use a Mac C compiler with 2-byte ints (such as THINK C's normal +mode) you will need to fix some bugs in the MacTCP C includes and libraries to +prevent it from generating bad code, since those MacTCP files violate Apple's +standards of always using explicit shorts or longs, never ints. You could +avoid this if you set 4-byte ints in THINK C; however, the ANSI and UNIX +libraries in THINK C use 2-byte ints so you will also need to build 4-byte int +versions of these. c-client itself is 2-byte int or 4-byte int clean; it can +be used in either mode. + + The most important bug in the MacTCP files that you need to fix is in the +file AddressXlation.h, you need to change the definition of the rtnCode member +of the hostInfo structure to be long instead of int. There are several other +changes you need to make if you decide to compile dnr.c under THINK C instead +of using the Apple-supplied object file; see me for details if you decide to +undertake such an effort. This is fixed in newer versions from Apple. + + + DOS/WIN16 BUILD NOTES + + If you are building a DOS client, you will need a TCP/IP stack installed +on your DOS system along with its development environment. The currently +supported stacks are Beame & Whiteside, PC-NFS, Novell, PC/IP, Waterloo, and +Winsock. mtest and a version of Pine called PC Pine run under DOS. + + You do not use imap-2007/Makefile under DOS, nor do you build any +components other than c-client and mtest. Merge the contents of +imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and +imap-2007/src/osdep/dos onto a single directory on DOS and build from that. +The MAKE command on DOS takes an argument identifying the TCP/IP stack in use. +For example, do: + MAKE MAKEFILE OS=WSK (or MAKE -F MAKEFILE OS=WSK) +to build for Winsock. + + If you write a program for DOS/Win16, you will probably have to write a +replacement cache manager (look at mm_cache()) and otherwise disable most of +c-client's caching. Even so, memory limitations will be an ongoing problem, +particularly with DOS, and you will have some severe performance problems. +It's a bit better on Win16, but in my opinion you are better off writing a +32-bit program and telling your Win16 customers to upgrade to Windows 95 or at +least install Win32s. + + + WINDOWS CE BUILD NOTES + + I build using Visual C++ 6.0 with the WCE extensions. The current code +has SH3 wired in for the compiler building. + + To build under NT, connect to the imap-2007 directory and do: + nmake -f makefile.wce + + The only binary produced is a cclient.lib file. I haven't gotten as far +as building mtest on WCE, mainly because I don't have a stdlib library. + + + AMIGA BUILD AND INSTALLATION NOTES + + The Amiga port was contributed. Maybe the UNIX notes will help. + + + OS2 BUILD NOTES + + The OS2 port was contributed. Maybe the Win32 Build Notes will help. diff --git a/docs/CONFIG b/docs/CONFIG new file mode 100644 index 0000000..01ae71f --- /dev/null +++ b/docs/CONFIG @@ -0,0 +1,181 @@ +/* ======================================================================== + * 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. diff --git a/docs/FAQ.html b/docs/FAQ.html new file mode 100644 index 0000000..12a9fea --- /dev/null +++ b/docs/FAQ.html @@ -0,0 +1,4226 @@ + + + + + +

Table of Contents

+ + +
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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 "/".

+
+
+ +

Back to top

+
+ +

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".

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

1.13 Can I use SSL?

+ +
+
Yes. See the answer to the How do I configure SSL? + question.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

1.15 Can I use CRAM-MD5 + authentication?

+ +
+
Yes. See the answer to the How do I configure CRAM-MD5 + authentication? question.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

1.17 Can I use Kerberos V5?

+ +
+
Yes. See the answer to the How do I configure + Kerberos V5? question.
+
+ +

Back to top

+
+ +

1.18 Can I use PAM for plaintext + passwords?

+ +
+
Yes. See the answer to the How do I configure PAM for + plaintext passwords? question.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

1.20 Can I use AFS for plaintext + passwords?

+ +
+
Yes. See the answer to the How do I configure AFS for + plaintext passwords? question.
+
+ +

Back to top

+
+ +

1.21 Can I use DCE for plaintext + passwords?

+ +
+
Yes. See the answer to the How do I configure DCE for + plaintext passwords? question.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

1.23 Can I disable plaintext + passwords?

+ +
+
Yes. See the answer to the How do I disable plaintext + passwords? question.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

1.25 Can I use virtual hosts?

+ +
+
Yes. See the answer to the How do I configure virtual + hosts? question.
+
+ +

Back to top

+
+ +

1.26 Can I use RPOP authentication?

+ +
+
There is no support for RPOP authentication.
+
+ +

Back to top

+
+ +

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. +
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

1.32 Is there support for the Cyrus mailbox + format?

+ +
+
No.
+
+ +

Back to top

+
+ +

1.33 Is this software Y2K compliant?

+ +
+
Please read the files Y2K and calendar.txt.
+
+ +

Back to top

+
+ +


+ +

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.
+
+ +

Back to top

+
+ +

2.2 What do I need to build this software with Kerberos + V on UNIX?

+ +
+
You need to build and install MIT Kerberos first.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

2.9 What do I need to build this software on + TOPS-20?

+ +
+
You need the TOPS-20 KCC compiler.
+
+ +

Back to top

+
+ +

2.10 What do I need to build this software on Amiga or + OS/2?

+ +
+
We don't know.
+
+ +

Back to top

+
+ +

2.11 What do I need to build this software on Windows + CE?

+ +
+
This port is incomplete. Someone needs to finish it.
+
+ +

Back to top

+
+ +


+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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
+
+
+
+ +

Back to top

+
+ +

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. +
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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. +
+
+ +

Back to top

+
+ +

3.14 How do I configure AFS for plaintext + passwords?

+ +
+
+ Build with PASSWDTYPE=afs, e.g + 
+ make sol PASSWDTYPE=afs
+
+
+
+
+ +

Back to top

+
+ +

3.15 How do I configure DCE for plaintext + passwords?

+ +
+
+ Build with PASSWDTYPE=dce, e.g + 
+ make sol PASSWDTYPE=dce
+
+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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 allowed.
+ 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. +
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +


+ +

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.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
    • +
+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +


+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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!

+
+
+ +

Back to top

+
+ +


+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

6.4 Why don't you use iconv() for internationalization + support?

+ +
+
iconv() is not ubiquitous enough.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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().

+
+
+ +

Back to top

+
+ +

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. +
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
    • +
+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +


+ +

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
+
+
+
+ +

Back to top

+
+ +

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
+
+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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".
    • +
+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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?

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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: + +
      +
    • setting an explicit port number in the mailbox name, e.g. + 
      + {imapserver.foo.com:143}INBOX
+
      +
      • + +
    • 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);
+
    +
    • +
+
+
+ +

Back to top

+
+ +

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. +
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+
+ +


+ +

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.

+
+
+ +

Back to top

+
+ +

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.
+
+ +

Back to top

+
+ +

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.

+
+
+ +

Back to top

+ +

Last Updated: 15 November 2007

+ + + diff --git a/docs/FAQ.txt b/docs/FAQ.txt new file mode 100644 index 0000000..797bed0 --- /dev/null +++ b/docs/FAQ.txt @@ -0,0 +1,2993 @@ +/* ======================================================================== + * 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 diff --git a/docs/IPv6.txt b/docs/IPv6.txt new file mode 100644 index 0000000..5b1af62 --- /dev/null +++ b/docs/IPv6.txt @@ -0,0 +1,131 @@ +/* ======================================================================== + * 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"). diff --git a/docs/RELNOTES b/docs/RELNOTES new file mode 100644 index 0000000..5cfd913 --- /dev/null +++ b/docs/RELNOTES @@ -0,0 +1,787 @@ +/* ======================================================================== + * 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: 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. diff --git a/docs/SSLBUILD b/docs/SSLBUILD new file mode 100644 index 0000000..962e8b2 --- /dev/null +++ b/docs/SSLBUILD @@ -0,0 +1,267 @@ +/* ======================================================================== + * 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----- diff --git a/docs/Y2K b/docs/Y2K new file mode 100644 index 0000000..12b8428 --- /dev/null +++ b/docs/Y2K @@ -0,0 +1,145 @@ +/* ======================================================================== + * 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 + * + * + * ======================================================================== + */ + +QUESTION: Is c-client Y2K compliant? + +ANSWER: + + There are no known Y2K issues in c-client; nor have there ever +been any known Y2K issues in c-client from its inception. + + Some older versions of c-client don't like the two-digit year +"00", although the only impact of this is that messages with that year +will sort before any other messages. Nobody should be using two-digit +years in email messages any more (use "2000" instead of "00"). + + You may wish to read the document calendar.txt for more +information about the Y3.3K/Y4K, Y20K, and Y4)K issues. Assuming that +c-client is still around in 2000-40,000 years, someone will have to +deal with these. + + Within the plausible lifetimes of people today, there are three +known date-related issues in c-client which will have to be addressed +in the future. If I am still alive when the first problem hits, I +will be nearly 82 years old, and won't be maintaining c-client any +more. + + +Y2038: + + c-client, like most UNIX software, has Y2038 issues. On Tuesday, +January 19, 2038 at 03:14:08 Coordinated Universal Time (also known as +UTC, UT, or historically GMT), the clock on 32-bit UNIX systems will +wrap around to a negative number; that is, from 0x7fffffff to +0x80000000. + + c-client uses an unsigned long for its 32-bit time; however the C +library on most UNIX systems uses a signed long and will interpret +that time as being Friday, December 13, 1901 at 20:45:52 UTC. + + Fixing this problem will require changing the C library to use +either unsigned longs or a wider (e.g. 64-bit) value for time. Lots +of work will need to be done on 32-bit UNIX systems as 2038 +approaches. History suggests that most of the work will be done in +the autumn of 2037... ;-) It's not known if anything is necessary to +do to c-client other than just rebuild it with the new C library. + + Going to 32-bit unsigned longs means that there will be a Y2106 +bug that someone will have to fix. Hopefully nobody will even think +of using 32-bit systems by then. + + +Y2070: + + c-client assumes that 2-digit years with values of 70 or greater +are in the 20th century, and that 2-digit years with values of 69 or +less are in the 21st century. Time for UNIX began on January 1, 1970 +and email on ARPAnet happened between the first TENEX systems shortly +after that; consequently there is no ambiguity with email data with +2-digit years prior to the year 2070. This is used only when parsing +a 2-digit year. c-client never generates one. + + Fixing this problem requires convincing people not to use 2-digit +years. This is a lesson that people should have figured out 70 years +earlier with Y2K. Consequently, this may be a "non-problem." +Otherwise, look in mail_parse_date() for the comment "two digit year" +and change the statement as desired. [Note: do not change the +definition of BASEYEAR since the UNIX port assumes that this matches +when time began in the operating system.] + + +Y2098: + + On January 1, 2098, the year in per-message internal dates will +expire, since a 7-bit field is allocated for the year. c-client will +mistakenly think that the day is January 1, 1970. + + Fortunately, it is easy to fix this problem. Just increase the +width of "year" in MESSAGECACHE in mail.h. If you make it 8 bits, +it'll be good until January 1, 2216; 9 bits makes it good until 2482. +10 bits will push it back that you'd worry about the Y2800 question +before having to increase it again. If you ignore Y2800, 11 bits will +push it it back to having to worry about Y4K first. + + +Y2800: + + At this year, you will need to decide whether to keep the Gregorian +calendar, which is one day slow every 20,000 years, or go to the more +accurate Eastern Orthodox calendar which is one day slow every 45,000 +years. The Gregorian and Eastern Orthodox calendars diverge at this +year. + + There hasn't been any statement about how the international +community will deal with the situation of the Orthodox calendar being +one day ahead of the Gregorian calendar between 2800 and 2900. This +will happen again between 3200 and 3300, and at gradually increasing +intervals until 48,300 when the shift becomes permanent (assuming no +Y20K or Y40K fixes). + + If you wish to make the transition to the Eastern Orthodox calendar, +rebuild c-client with -DUSEORTHODOXCALENDAR=1. You can then ignore Y4K +and Y20K! + + +Y3.3K/Y4K: + + Some time around the year 3300, the calendar has gotten one day +behind. To remedy this, a little-known rule in the Gregorian calendar +is that years that are evenly divisible by 4000 are not leap years. +Unlike the other rules, this rule hasn't had effect yet, and won't for +another 2000 years. + + To fix the Y4K problem, just rebuild c-client with -DY4KBUGFIX=1. + + +Y20K: + + Those of you who stuck with the Gregorian calendar have a +problem; the calendar is now one day slow. The Pope has not made any +statement about how this problem will be fixed. Maybe they'll declare +that 20,004 is also not a leap year or something. + + There is no fix for this problem in c-client. + + +Y40K: + + Greeks, Serbs, Russians, and other Eastern Orthodox have spent +the past 38,000 years laughing at westerners' increasingly futile +efforts to keep the Gregorian calendar in order. The day of reckoning +has come; the Orthodox calendar is now one day slow. The Patriarch of +Istanbul (nee Constantinople) has not made any statement about how this +will be fixed. + + There is no fix for this problem in c-client. diff --git a/docs/bugs.txt b/docs/bugs.txt new file mode 100644 index 0000000..5f87b3e --- /dev/null +++ b/docs/bugs.txt @@ -0,0 +1,234 @@ +/* ======================================================================== + * 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 diff --git a/docs/calendar.txt b/docs/calendar.txt new file mode 100644 index 0000000..c100907 --- /dev/null +++ b/docs/calendar.txt @@ -0,0 +1,332 @@ +/* ======================================================================== + * 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. diff --git a/docs/commndmt.txt b/docs/commndmt.txt new file mode 100644 index 0000000..7fd9707 --- /dev/null +++ b/docs/commndmt.txt @@ -0,0 +1,101 @@ +/* ======================================================================== + * 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. + diff --git a/docs/draft/README b/docs/draft/README new file mode 100644 index 0000000..9aec471 --- /dev/null +++ b/docs/draft/README @@ -0,0 +1,19 @@ +Last Updated: 6 March 2008 + +This directory contains Internet Drafts which, at the time of release of +this software, were not yet been published as RFCs. These documents are +expected to be released as RFCs in the near future. + +This software adheres to the specification in these documents, which +are included for informational purposes. Note, however, that these +documents must be considered preliminary in nature and will be superceded +by the successor RFC. + +File Name I-D Name +--------- -------- +sort.txt draft-ietf-imapext-sort-20.txt + ;; SORT and THREAD commands + ;; Status: approved, blocked waiting for i18n + +i18n.txt draft-ietf-imapext-i18n-15.txt + ;; internationalization in IMAP diff --git a/docs/draft/i18n.txt b/docs/draft/i18n.txt new file mode 100644 index 0000000..f47c6cc --- /dev/null +++ b/docs/draft/i18n.txt @@ -0,0 +1,1140 @@ + + + + + + +Network Working Group Chris Newman +Internet-Draft Sun Microsystems +Intended Status: Proposed Standard Arnt Gulbrandsen + Oryx Mail Systems GmhH + Alexey Melnikov + Isode Limited + February 1, 2008 + + Internet Message Access Protocol Internationalization + draft-ietf-imapext-i18n-15.txt + + +Status of this Memo + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other documents + at any time. It is inappropriate to use Internet-Drafts as + reference material or to cite them other than as "work in progress". + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet- + Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft expires in August 2008. + + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + + +Abstract + + Internet Message Access Protocol (IMAP) version 4rev1 has basic + support for non-ASCII characters in mailbox names and search + substrings. It also supports non-ASCII message headers and content + encoded as specified by Multipurpose Internet Mail Extensions + (MIME). This specification defines a collection of IMAP extensions + + + +Newman & Co Expires August 2008 FF[Page 1] + + + + + +Internet-draft February 2008 + + + which improve international support including comparator negotiation + for search, sort and thread, language negotiation for international + error text, and translations for namespace prefixes. + + +Table of Contents + + 1. Conventions Used in this Document . . . . . . . . . . . . . . 2 + 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. LANGUAGE Extension . . . . . . . . . . . . . . . . . . . . . 3 + 3.1 LANGUAGE Extension Requirements . . . . . . . . . . . . . . . 3 + 3.2 LANGUAGE Command . . . . . . . . . . . . . . . . . . . . . . 4 + 3.3 LANGUAGE Response . . . . . . . . . . . . . . . . . . . . . . 6 + 3.4 TRANSLATION Extension to the NAMESPACE Response . . . . . . . 6 + 3.5 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. I18NLEVEL=1 and I18NLEVEL=2 Extensions . . . . . . . . . . . 7 + 4.1 Introduction and Overview . . . . . . . . . . . . . . . . . . 8 + 4.2 Requirements common to both I18NLEVEL=1 and I18NLEVEL=2 . . . + 4.3 I18NLEVEL=1 Extension Requirements . . . . . . . . . . . . . 8 + 4.4 I18NLEVEL=2 Extension Requirements . . . . . . . . . . . . . 8 + 4.5 Compatibility Notes + 4.6 Comparators and Charsets . . . . . . . . . . . . . . . . . . 9 + 4.7 COMPARATOR Command . . . . . . . . . . . . . . . . . . . . . 9 + 4.8 COMPARATOR Response . . . . . . . . . . . . . . . . . . . . . 10 + 4.9 BADCOMPARATOR Response Code . . . . . . . . . . . . . . . . . + 4.10 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 10 + 5. Other IMAP Internationalization Issues . . . . . . . . . . . 11 + 5.1 UTF-8 Userids and Passwords . . . . . . . . . . . . . . . . . 11 + 5.2 UTF-8 Mailbox Names . . . . . . . . . . . . . . . . . . . . . 11 + 5.3 UTF-8 Domains, Addresses and Mail Headers . . . . . . . . . . 11 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 + 9. Relevant Standards for i18n IMAP Implementations . . . . . . 13 + Normative References . . . . . . . . . . . . . . . . . . . . 13 + Informative References . . . . . . . . . . . . . . . . . . . 14 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 15 + Intellectual Property and Copyright Statements . . . . . . . 16 + + +Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The formal syntax use the Augmented Backus-Naur Form (ABNF) + [RFC4234] notation including the core rules defined in Appendix A. + + + +Newman & Co Expires August 2008 FF[Page 2] + + + + + +Internet-draft February 2008 + + + The UTF8-related productions are defined in [RFC3629]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + + +2. Introduction + + This specification defines two IMAP4rev1 [RFC3501] extensions to + enhance international support. These extensions can be advertised + and implemented separately. + + The LANGUAGE extension allows the client to request a suitable + language for protocol error messages and in combination with the + NAMESPACE extension [RFC2342] enables namespace translations. + + The I18NLEVEL=2 extension allows the client to request a suitable + collation which will modify the behavior of the base specification's + SEARCH command as well as the SORT and THREAD extensions [SORT]. + This leverages the collation registry [RFC4790]. + + +3. LANGUAGE Extension + + IMAP allows server responses to include human-readable text that in + many cases needs to be presented to the user. But that text is + limited to US-ASCII by the IMAP specification [RFC3501] in order to + preserve backwards compatibility with deployed IMAP implementations. + This section specifies a way for an IMAP client to negotiate which + language the server should use when sending human-readable text. + + The LANGUAGE extension only provides a mechanism for altering fixed + server strings such as response text and NAMESPACE folder names. + Assigning localized language aliases to shared mailboxes would be + done with a separate mechanism such as the proposed METADATA + extension (see [METADATA]). + + +3.1 LANGUAGE Extension Requirements + + IMAP servers that support this extension MUST list the keyword + LANGUAGE in their CAPABILITY response as well as in the greeting + CAPABILITY data. + + A server that advertises this extension MUST use the language "i- + + + +Newman & Co Expires August 2008 FF[Page 3] + + + + + +Internet-draft February 2008 + + + default" as described in [RFC2277] as its default language until + another supported language is negotiated by the client. A server + MUST include "i-default" as one of its supported languages. + + Clients and servers that support this extension MUST also support + the NAMESPACE extension [RFC2342]. + + The LANGUAGE command is valid in all states. Clients are urged to + issue LANGUAGE before authentication, since some servers send + valuable user information as part of authentication (e.g. "password + is correct, but expired"). If a security layer (such as SASL or + TLS) is subsequently negotiated by the client, it MUST re-issue the + LANGUAGE command in order to make sure that no previous active + attack (if any) on LANGUAGE negotiation has effect on subsequent + error messages. (See Section 7 for a more detailed explanation of + the attack.) + + + +3.2 LANGUAGE Command + + Arguments: Optional language range arguments. + + Response: A possible LANGUAGE response (see section 3.3). + A possible NAMESPACE response (see section 3.4). + + Result: OK - Command completed + NO - Could not complete command + BAD - arguments invalid + + The LANGUAGE command requests that human-readable text emitted by + the server be localized to a language matching one of the language + range argument as described by section 2 of [RFC4647]. + + If the command succeeds, the server will return human-readable + responses in the first supported language specified. These + responses will be in UTF-8 [RFC3629]. The server MUST send a + LANGUAGE response specifying the language used, and the change takes + effect immediately after the LANGUAGE response. + + If the command fails, the server continues to return human-readable + responses in the language it was previously using. + + The special "default" language range argument indicates a request to + use a language designated as preferred by the server administrator. + The preferred language MAY vary based on the currently active user. + + If a language range does not match a known language tag exactly but + + + +Newman & Co Expires August 2008 FF[Page 4] + + + + + +Internet-draft February 2008 + + + does match a language by the rules of [RFC4647], the server MUST + send an untagged LANGUAGE response indicating the language selected. + + If there aren't any arguments, the server SHOULD send an untagged + LANGUAGE response listing the languages it supports. If the server + is unable to enumerate the list of languages it supports it MAY + return a tagged NO response to the enumeration request. + + < The server defaults to using English i-default responses until + the user explicitly changes the language. > + + C: A001 LOGIN KAREN PASSWORD + S: A001 OK LOGIN completed + + < Client requested MUL language, which no server supports. > + + C: A002 LANGUAGE MUL + S: A002 NO Unsupported language MUL + + < A LANGUAGE command with no arguments is a request to enumerate + the list of languages the server supports. > + + C: A003 LANGUAGE + S: * LANGUAGE (EN DE IT i-default) + S: A003 OK Supported languages have been enumerated + + C: B001 LANGUAGE + S: B001 NO Server is unable to enumerate supported languages + + < Once the client changes the language, all responses will be in + that language starting after the LANGUAGE response. Note that + this includes the NAMESPACE response. Because RFCs are in US- + ASCII, this document uses an ASCII transcription rather than + UTF-8 text, e.g. ue in the word "ausgefuehrt" > + + C: C001 LANGUAGE DE + S: * LANGUAGE (DE) + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: C001 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < If a server does not support the requested primary language, + responses will continue to be returned in the current language + the server is using. > + + C: D001 LANGUAGE FR + S: D001 NO Diese Sprache ist nicht unterstuetzt + + + +Newman & Co Expires August 2008 FF[Page 5] + + + + + +Internet-draft February 2008 + + + C: D002 LANGUAGE DE-IT + S: * LANGUAGE (DE-IT) + S: * NAMESPACE (("" "/"))(("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: D002 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + C: D003 LANGUAGE "default" + S: * LANGUAGE (DE) + S: D003 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < Server does not speak French, but does speak English. User + speaks Canadian French and Canadian English. > + + C: E001 LANGUAGE FR-CA EN-CA + S: * LANGUAGE (EN) + S: E001 OK Now speaking English + + + +3.3 LANGUAGE Response + + Contents: A list of one or more language tags. + + The LANGUAGE response occurs as a result of a LANGUAGE command. A + LANGUAGE response with a list containing a single language tag + indicates that the server is now using that language. A LANGUAGE + response with a list containing multiple language tags indicates the + server is communicating a list of available languages to the client, + and no change in the active language has been made. + + +3.4 TRANSLATION Extension to the NAMESPACE Response + + If localized representations of the namespace prefixes are available + in the selected language, the server SHOULD include these in the + TRANSLATION extension to the NAMESPACE response. + + The TRANSLATION extension to the NAMESPACE response returns a single + string, containing the modified UTF-7 [RFC3501] encoded translation + of the namespace prefix. It is the responsibility of the client to + convert between the namespace prefix and the translation of the + namespace prefix when presenting mailbox names to the user. + + In this example a server supports the IMAP4 NAMESPACE command. It + uses no prefix to the user's Personal Namespace, a prefix of "Other + Users" to its Other Users' Namespace and a prefix of "Public + Folders" to its only Shared Namespace. Since a client will often + display these prefixes to the user, the server includes a + + + +Newman & Co Expires August 2008 FF[Page 6] + + + + + +Internet-draft February 2008 + + + translation of them that can be presented to the user. + + C: A001 LANGUAGE DE-IT + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: A001 OK LANGUAGE-Befehl ausgefuehrt + + +3.5 Formal Syntax + + The following syntax specification inherits ABNF [RFC4234] rules + from IMAP4rev1 [RFC3501], IMAP4 Namespace [RFC2342], Tags for the + Identifying Languages [RFC4646], UTF-8 [RFC3629] and Collected + Extensions to IMAP4 ABNF [RFC4466]. + + command-any =/ language-cmd + ; LANGUAGE command is valid in all states + + language-cmd = "LANGUAGE" *(SP lang-range-quoted) + + response-payload =/ language-data + + language-data = "LANGUAGE" SP "(" lang-tag-quoted *(SP + lang-tag-quoted) ")" + + namespace-trans = SP DQUOTE "TRANSLATION" DQUOTE SP "(" string ")" + ; the string is encoded in Modified UTF-7. + ; this is a subset of the syntax permitted by + ; the Namespace-Response-Extension rule in [RFC4466] + + lang-range-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the language-range rule in [RFC4647] + + lang-tag-quoted = astring + ; Once any literal wrapper or quoting is removed, this follows + ; the Language-Tag rule in [RFC4646] + + resp-text = ["[" resp-text-code "]" SP ] UTF8-TEXT-CHAR + *(UTF8-TEXT-CHAR / "[") + ; After the server is changed to a language other than + ; i-default, this resp-text rule replaces the resp-text + ; rule from [RFC3501]. + + UTF8-TEXT-CHAR = %x20-5A / %x5C-7E / UTF8-2 / UTF8-3 / UTF8-4 + ; UTF-8 excluding 7-bit control characters and "[" + + + + +Newman & Co Expires August 2008 FF[Page 7] + + + + + +Internet-draft February 2008 + + +4. I18NLEVEL=1 and I18NLEVEL=2 Extensions + + +4.1 Introduction and Overview + + IMAP4rev1 [RFC3501] includes the SEARCH command which can be used to + locate messages matching criteria including human-readable text. + The SORT extension [SORT] to IMAP allows the client to ask the + server to determine the order of messages based on criteria + including human-readable text. These mechanisms require the ability + to support non-English search and sort functions. + + Section 4 defines two IMAP extensions for internationalizing IMAP + SEARCH, SORT and THREAD [SORT] using the comparator framework + [RFC4790]. + + The I18NLEVEL=1 extension updates SEARCH/SORT/THREAD to use + i;unicode-casemap comparator, as defined in [UCM]. See Sections 4.2 + and 4.3 for more details. + + The I18NLEVEL=2 extension is a superset of the I18NLEVEL=1 + extension. It adds to I18NLEVEL=1 extension the ability to determine + the active comparator (see definition below) and negotiate use of + comparators using the COMPARATOR command. It also adds the + COMPARATOR response that indicates the active comparator and + possibly other available comparators. See Sections 4.2 and 4.4 for + more details. + + +4.2 Requirements common to both I18NLEVEL=1 and I18NLEVEL=2 + + The term "default comparator" refers to the comparator which is used + by SEARCH and SORT absent any negotiation using the COMPARATOR (see + Section 4.7) command. The term "active comparator" refers to the + comparator which will be used within a session e.g. by SEARCH and + SORT. The COMPARATOR command is used to change the active + comparator. + + The active comparator applies to the following SEARCH keys: "BCC", + "BODY", "CC", "FROM", "SUBJECT", "TEXT", "TO" and "HEADER". If the + server also advertises the "SORT" extension, then the active + comparator applies to the following SORT keys: "CC", "FROM", + "SUBJECT" and "TO". If the server advertises THREAD=ORDEREDSUBJECT, + then the active comparator applies to the ORDEREDSUBJECT threading + algorithm. If the server advertises THREAD=REFERENCES, then the + active comparator applies to the subject field comparisons done by + REFERENCES threading algorithm. Future extensions may choose to + apply the active comparator to their SEARCH keys. + + + +Newman & Co Expires August 2008 FF[Page 8] + + + + + +Internet-draft February 2008 + + + For SORT and THREAD, the pre-processing necessary to extract the + base subject text from a Subject header occurs prior to the + application of a comparator. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + implement the i;unicode-casemap comparator, as defined in [UCM]. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + support UTF-8 as a SEARCH charset. + + +4.3 I18NLEVEL=1 Extension Requirements + + An IMAP server that satisfies all requirements specified in sections + 4.2 and 4.6 (and doesn't support/advertise any other I18NLEVEL= + extension, where n > 1) MUST list the keyword I18NLEVEL=1 in its + CAPABILITY data once IMAP enters the authenticated state, and MAY + list that keyword in other states. + + + +4.4 I18NLEVEL=2 Extension Requirements + + IMAP server that satisfies all requirements specified in sections + 4.2, 4.4, 4.6-4.10 (and doesn't support/advertise any other + I18NLEVEL= extension, where n > 2) MUST list the keyword + I18NLEVEL=2 in its CAPABILITY data once IMAP enters the + authenticated state, and MAY list that keyword in other states. + + A server that advertises this extension MUST implement the + i;unicode-casemap comparator, as defined in [UCM]. It MAY implement + other comparators from the IANA registry established by [RFC4790]. + See also section 4.5 of this document. + + A server that advertises this extension SHOULD use i;unicode-casemap + as the default comparator. (Note that i;unicode-casemap is the + default comparator for I18NLEVEL=1, but not necessarily the default + for I18NLEVEL=2.) The selection of the default comparator MAY be + adjustable by the server administrator, and MAY be sensitive to the + current user. Once the IMAP connection enters authenticated state, + the default comparator MUST remain static for the remainder of that + connection. + + Note that since SEARCH uses the substring operation, IMAP servers + can only implement collations that offer the substring operation + (see [RFC4790 section 4.2.2). Since SORT uses ordering operation + (and by implication equality), IMAP servers which advertise the SORT + extension can only implement collations that offer all three + + + +Newman & Co Expires August 2008 FF[Page 9] + + + + + +Internet-draft February 2008 + + + operations (see [RFC4790] sections 4.2.2-4). + + If the active collation does not provide the operations needed by an + IMAP command, the server MUST respond with a tagged BAD. + + +4.5 Compatibility Notes + + Several server implementations deployed prior to the publication of + this specification comply with I18NLEVEL=1 (see section 4.3), but do + not advertise that. Other legacy servers use the i;ascii-casemap + (see [RFC4790]) comparator. + + There is no good way for a client to know which comparator that a + legacy server uses. If the client has to assume the worst, it may + end up doing expensive local operations to obtain i;unicode-casemap + comparisons even though the server implements it. + + Legacy server implementations which comply with I18NLEVEL=1 should + be updated to advertise I18NLEVEL=1. All server implementations + should eventually be updated to comply with the I18NLEVEL=2 + extension. + + +4.6 Comparators and Character Encodings + + RFC 3501, section 6.4.4 says: + + In all search keys that use strings, a message matches + the key if the string is a substring of the field. The + matching is case-insensitive. + + When performing the SEARCH operation, the active comparator is + applied instead of the case-insensitive matching specified above. + + An IMAP server which performs collation operations (e.g., as part of + commands such as SEARCH, SORT, THREAD) does so according to the + following procedure: + + (a) MIME encoding (for example see [RFC2047] for headers and + [RFC2045] for body parts) MUST be removed in the texts being + collated. + + If MIME encoding removal fails for a message (e.g., a body part + of the message has an unsupported Content-Transfer-Encoding, + uses characters not allowed by the Content-Transfer-Encoding, + etc.), the collation of this message is undefined by this + specification, and is handled in an implementation-dependent + + + +Newman & Co Expires August 2008 FF[Page 10] + + + + + +Internet-draft February 2008 + + + manner. + + (b) The decoded text from (a) MUST be converted to the charset + expected by the active comparator. + + (c) For the substring operation: + If step (b) failed (e.g., the text is in an unknown charset, + contains a sequence which is not valid according in that + charset, etc.), the original decoded text from (a) (i.e., + before the charset conversion attempt) is collated using the + i;octet comparator (see [RFC4790]). + + If step (b) was successful, the converted text from (b) is + collated according to the active comparator. + + + For the ordering operation: + + All strings that were successfully converted by step (b) are + separated from all strings that failed step (b). Strings in + each group are collated independently. All strings successfully + converted by step (b) are then validated by the active + comparator. Strings that pass validation are collated using the + active comparator. All strings that either fail step (b) or fail + the active collation's validity operation are collated (after + applying step (a)) using the i;octet comparator (see [RFC4790]). + The resulting sorted list is produced by appending all collated + "failed" strings after all strings collated using the active + comparator. + + + Example: The following example demonstrates ordering of 4 + different strings using i;unicode-casemap [UCM] comparator. + Strings are represented using hexadecimal notation used by + ABNF [RFC4234]. + + (1) %xD0 %xC0 %xD0 %xBD %xD0 %xB4 %xD1 %x80 %xD0 %xB5 + %xD0 %xB9 (labeled with charset=UTF-8) + (2) %xD1 %x81 %xD0 %x95 %xD0 %xA0 %xD0 %x93 %xD0 %x95 + %xD0 %x99 (labeled with charset=UTF-8) + (3) %xD0 %x92 %xD0 %xB0 %xD1 %x81 %xD0 %xB8 %xD0 %xBB + %xD0 %xB8 %xFF %xB9 (labeled with charset=UTF-8) + (4) %xE1 %xCC %xC5 %xCB %xD3 %xC5 %xCA (labeled with + charset=KOI8-R) + + Step (b) will convert string # 4 to the following + sequence of octets (in UTF-8): + + + + +Newman & Co Expires August 2008 FF[Page 11] + + + + + +Internet-draft February 2008 + + + %xD0 %x90 %xD0 %xBB %xD0 %xB5 %xD0 %xBA %xD1 %x81 %xD0 + %xB5 %xD0 %xB9 + + and will reject strings (1) and (3), as they contain + octets not allowed in charset=UTF-8. + After that, using the i;unicode-casemap collation, + string (4) will collate before string (2). Using the + i;octet collation on the original strings, string (3) + will collate before string (1). So the final ordering + is as follows: (4) (2) (3) (1). + + If the substring operation (e.g., IMAP SEARCH) of the active + comparator returns the "undefined" result (see section 4.2.3 of + [RFC4790]) for either the text specified in the SEARCH command or + the message text, then the operation is repeated on the result of + step (a) using the i;octet comparator. + + The ordering operation (e.g., IMAP SORT and THREAD) SHOULD collate + the following together: strings encoded using unknown or invalid + character encodings, strings in unrecognized charsets, and invalid + input (as defined by the active collation). + + + +4.7 COMPARATOR Command + + Arguments: Optional comparator order arguments. + + Response: A possible COMPARATOR response (see Section 4.8). + + Result: OK - Command completed + NO - No matching comparator found + BAD - arguments invalid + + The COMPARATOR command is valid in authenticated and selected + states. + + The COMPARATOR command is used to determine or change the active + comparator. When issued with no arguments, it results in a + COMPARATOR response indicating the currently active comparator. + + When issued with one or more comparator argument, it changes the + active comparator as directed. (If more than one installed + comparator is matched by an argument, the first argument wins.) The + COMPARATOR response lists all matching comparators if more than one + matches the specified patterns. + + The argument "default" refers to the server's default comparator. + + + +Newman & Co Expires August 2008 FF[Page 12] + + + + + +Internet-draft February 2008 + + + Otherwise each argument is an collation specification as defined in + the Internet Application Protocol Comparator Registry [RFC4790]. + + < The client requests activating a Czech comparator if possible, + or else a generic international comparator which it considers + suitable for Czech. The server picks the first supported + comparator. > + + C: A001 COMPARATOR "cz;*" i;basic + S: * COMPARATOR i;basic + S: A001 OK Will use i;basic for collation + + +4.8 COMPARATOR Response + + Contents: The active comparator. + An optional list of available matching comparators + + The COMPARATOR response occurs as a result of a COMPARATOR command. + The first argument in the comparator response is the name of the + active comparator. The second argument is a list of comparators + which matched any of the arguments to the COMPARATOR command and is + present only if more than one match is found. + + +4.9 BADCOMPARATOR response code + + This response code SHOULD be returned as a result of server failing + an IMAP command (returning NO), when the server knows that none of + the specified comparators match the requested comparator(s). + + +4.10 Formal Syntax + + The following syntax specification inherits ABNF [RFC4234] rules + from IMAP4rev1 [RFC3501], and Internet Application Protocol + Comparator Registry [RFC4790]. + + command-auth =/ comparator-cmd + + resp-text-code =/ "BADCOMPARATOR" + + comparator-cmd = "COMPARATOR" *(SP comp-order-quoted) + + response-payload =/ comparator-data + + comparator-data = "COMPARATOR" SP comp-sel-quoted [SP "(" + comp-id-quoted *(SP comp-id-quoted) ")"] + + + +Newman & Co Expires August 2008 FF[Page 13] + + + + + +Internet-draft February 2008 + + + comp-id-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-id rule from [RFC4790] + + comp-order-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-order rule from [RFC4790] + + comp-sel-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-selected rule from [RFC4790] + + +5. Other IMAP Internationalization Issues + + The following sections provide an overview of various other IMAP + internationalization issues. These issues are not resolved by this + specification, but could be resolved by other standards work, such + as that being done by the EAI group (see [IMAP-EAI]). + + +5.1 Unicode Userids and Passwords + + IMAP4rev1 currently restricts the userid and password fields of the + LOGIN command to US-ASCII. The "userid" and "password" fields of the + IMAP LOGIN command are restricted to US-ASCII only until a future + standards track RFC states otherwise. Servers are encouraged to + validate both fields to make sure they conform to the formal syntax + of UTF-8 and to reject the LOGIN command if that syntax is violated. + Servers MAY reject the use of any 8-bit in the "userid" or + "password" field. + + When AUTHENTICATE is used, some servers may support userids and + passwords in Unicode [RFC3490] since SASL (see [RFC4422]) allows + that. However, such userids cannot be used as part of email + addresses. + + +5.2 UTF-8 Mailbox Names + + The modified UTF-7 mailbox naming convention described in section + 5.1.3 of RFC 3501 is best viewed as an transition from the status + quo in 1996 when modified UTF-7 was first specified. At that time, + there was widespread unofficial use of local character sets such as + ISO-8859-1 and Shift-JIS for non-ASCII mailbox names, with resultant + non-interoperability. + + The requirements in section 5.1 of RFC 3501 are very important if + + + +Newman & Co Expires August 2008 FF[Page 14] + + + + + +Internet-draft February 2008 + + + we're ever going to be able to deploy UTF-8 mailbox names. Servers + are encouraged to enforce them. + + +5.3 UTF-8 Domains, Addresses and Mail Headers + + There is now an IETF standard for Internationalizing Domain Names in + Applications [RFC3490]. While IMAP clients are free to support this + standard, an argument can be made that it would be helpful to simple + clients if the IMAP server could perform this conversion (the same + argument would apply to MIME header encoding [RFC2047]). However, + it would be unwise to move forward with such work until the work in + progress to define the format of international email addresses is + complete. + + +6. IANA Considerations + + The IANA is requested to add LANGUAGE, I18NLEVEL=1 and I18NLEVEL=2 + to the IMAP4 Capabilities Registry. [Note to IANA: + http://www.iana.org/assignments/imap4-capabilities] + + +7. Security Considerations + + The LANGUAGE extension makes a new command available in "Not + Authenticated" state in IMAP. Some IMAP implementations run with + root privilege when the server is in "Not Authenticated" state and + do not revoke that privilege until after authentication is complete. + Such implementations are particularly vulnerable to buffer overflow + security errors at this stage and need to implement parsing of this + command with extra care. + + A LANGUAGE command issued prior to activation of a security layer is + subject to an active attack which suppresses or modifies the + negotiation and thus makes STARTTLS or authentication error messages + more difficult to interpret. This is not a new attack as the error + messages themselves are subject to active attack. Clients MUST re- + issue the LANGUAGE command once a security layer is active, so this + does not impact subsequent protocol operations. + + LANGUAGE, I18NLEVEL=1 and I18NLEVEL=2 extensions use the UTF-8 + charset, thus the security considerations for UTF-8 [RFC3629] are + relevent. However, neither uses UTF-8 for identifiers so the most + serious concerns do not apply. + + +8. Acknowledgements + + + +Newman & Co Expires August 2008 FF[Page 15] + + + + + +Internet-draft February 2008 + + + The LANGUAGE extension is based on a previous Internet draft by Mike + Gahrns, a substantial portion of the text in that section was + written by him. Many people have participated in discussions about + an IMAP Language extension in the various fora of the IETF and + Internet working groups, so any list of contributors is bound to be + incomplete. However, the authors would like to thank Andrew McCown + for early work on the original proposal, John Myers for suggestions + regarding the namespace issue, along with Jutta Degener, Mark + Crispin, Mark Pustilnik, Larry Osterman, Cyrus Daboo, Martin Duerst, + Timo Sirainen, Ben Campbell and Magnus Nystrom for their many + suggestions that have been incorporated into this document. + + Initial discussion of the I18NLEVEL=2 extension involved input from + Mark Crispin and other participants of the IMAP Extensions WG. + + +9. Relevant Standards for i18n IMAP Implementations + + This is a non-normative list of standards to consider when + implementing i18n aware IMAP software. + + o The LANGUAGE and I18NLEVEL=2 extensions to IMAP (this + specification). + o The 8-bit rules for mailbox naming in section 5.1 of RFC 3501. + o The Mailbox International Naming Convention in section 5.1.3 of + RFC 3501. + o MIME [RFC2045] for message bodies. + o MIME header encoding [RFC2047] for message headers. + o The IETF EAI working group. + o MIME Parameter Value and Encoded Word Extensions [RFC2231] for + filenames. Quality IMAP server implementations will + automatically combine multipart parameters when generating the + BODYSTRUCTURE. There is also some deployed non-standard use of + MIME header encoding inside double-quotes for filenames. + o IDNA [RFC3490] and punycode [RFC3492] for domain names + (currently only relevant to IMAP clients). + o The UTF-8 charset [RFC3629]. + o The IETF policy on Character Sets and Languages [RFC2277]. + + +Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2277] Alvestrand, "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + + + +Newman & Co Expires August 2008 FF[Page 16] + + + + + +Internet-draft February 2008 + + + [RFC2342] Gahrns, Newman, "IMAP4 Namespace", RFC 2342, May 1998. + + [RFC3501] Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC3629] Yergeau, "UTF-8, a transformation format of ISO 10646", + STD 63, RFC 3629, November 2003. + + [RFC4234] Crocker, Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, Brandenburg + Internetworking, Demon Internet Ltd, October 2005. + + [RFC4422] Melnikov, Zeilenga, "Simple Authentication and Security + Layer (SASL)", RFC 4422, June 2006. + + [RFC4466] Melnikov, Daboo, "Collected Extensions to IMAP4 ABNF", + RFC 4466, Isode Ltd., April 2006. + + [RFC4646] Philips, Davis, "Tags for Identifying Languages", BCP 47, + RFC 4646, September 2006. + + [RFC4647] Philips, Davis, "Matching of Language Tags", BCP 47, RFC + 4647, September 2006. + + [RFC4790] Newman, Duerst, Gulbrandsen, "Internet Application + Protocol Comparator Registry", RFC 4790, February 2007. + + [SORT] Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS + PROTOCOL - SORT AND THREAD EXTENSION", draft-ietf- + imapext-sort-19 (work in progress), November 2006. + + [UCM] Crispin, "i;unicode-casemap - Simple Unicode Collation + Algorithm", RFC 5051, October 2007. + + [RFC2045] Freed, Borenstein, "Multipurpose Internet Mail Extensions + (MIME) Part One: Format of Internet Message Bodies", RFC + 2045, November 1996. + + [RFC2047] Moore, "MIME (Multipurpose Internet Mail Extensions) Part + Three: Message Header Extensions for Non-ASCII Text", RFC + 2047, November 1996. + + +Informative References + + + [RFC2231] Freed, Moore, "MIME Parameter Value and Encoded Word + Extensions: Character Sets, Languages, and + + + +Newman & Co Expires August 2008 FF[Page 17] + + + + + +Internet-draft February 2008 + + + Continuations", RFC 2231, November 1997. + + [RFC3490] Faltstrom, Hoffman, Costello, "Internationalizing Domain + Names in Applications (IDNA)", RFC 3490, March 2003. + + [RFC3492] Costello, "Punycode: A Bootstring encoding of Unicode for + Internationalized Domain Names in Applications (IDNA)", + RFC 3492, March 2003. + + [METADATA] Daboo, C., "IMAP METADATA Extension", draft-daboo-imap- + annotatemore-12 (work in progress), December 2007. + + [IMAP-EAI] Resnick, Newman, "IMAP Support for UTF-8", draft-ietf- + eai-imap-utf8 (work in progress), May 2006. + + + +Authors' Addresses + + Chris Newman + Sun Microsystems + 3401 Centrelake Dr., Suite 410 + Ontario, CA 91761 + US + + Email: chris.newman@sun.com + + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Email: arnt@oryx.com + + Fax: +49 89 4502 9758 + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village, 36 Station Road, + Hampton, Middlesex, TW12 2BX, UK + + Email: Alexey.Melnikov@isode.com + + + + + + +Newman & Co Expires August 2008 FF[Page 18] + + + + + +Internet-draft February 2008 + + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be found + in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this specification + can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). This document is subject to + the rights, licenses and restrictions contained in BCP 78, and + except as set forth therein, the authors retain all their rights. + + This document and the information contained herein are provided on + an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE + IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL + WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY + WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE + ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS + FOR A PARTICULAR PURPOSE. + + +Acknowledgment + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Newman & Co Expires August 2008 FF[Page 19] + + diff --git a/docs/draft/sort.txt b/docs/draft/sort.txt new file mode 100644 index 0000000..4453bb4 --- /dev/null +++ b/docs/draft/sort.txt @@ -0,0 +1,885 @@ +IMAP Extensions Working Group M. Crispin +Internet-Draft K. Murchison +Intended status: Proposed Standard March 10, 2008 +Expires: September 10, 2008 +Document: internet-drafts/draft-ietf-imapext-sort-20.txt + + INTERNET MESSAGE ACCESS PROTOCOL - SORT AND THREAD EXTENSIONS + +Status of this Memo + + By submitting this Internet-Draft, each author represents that + any applicable patent or other IPR claims of which he or she is + aware have been or will be disclosed, and any of which he or she + becomes aware will be disclosed, in accordance with Section 6 of + BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as + Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + A revised version of this draft document will be submitted to the RFC + editor as a Proposed Standard for the Internet Community. Discussion + and suggestions for improvement are requested, and should be sent to + ietf-imapext@IMC.ORG. + + Distribution of this memo is unlimited. + +Abstract + + This document describes the base-level server-based sorting and + threading extensions to the [IMAP] protocol. These extensions + provide substantial performance improvements for IMAP clients which + offer sorted and threaded views. + +1. Introduction + + The SORT and THREAD extensions to the [IMAP] protocol provide a means + of server-based sorting and threading of messages, without requiring + that the client download the necessary data to do so itself. This is + particularly useful for online clients as described in [IMAP-MODELS]. + + A server which supports the base-level SORT extension indicates this + with a capability name which starts with "SORT". Future, + upwards-compatible extensions to the SORT extension will all start + with "SORT", indicating support for this base level. + + A server which supports the THREAD extension indicates this with one + or more capability names consisting of "THREAD=" followed by a + supported threading algorithm name as described in this document. + This provides for future upwards-compatible extensions. + + A server which implements the SORT and/or THREAD extensions MUST + collate strings in accordance with the requirements of I18NLEVEL=1, + as described in [IMAP-I18N], and SHOULD implement and advertise the + I18NLEVEL=1 extension. Alternatively, a server MAY implement + I18NLEVEL=2 (or higher) and comply with the rules of that level. + + Discussion: the SORT and THREAD extensions predate [IMAP-I18N] by + several years. At the time of this writing, all known server + implementations of SORT and THREAD comply with the rules of + I18NLEVEL=1, but do not necessarily advertise it. As discussed + in [IMAP-I18N] section 4.5, all server implementations should + eventually be updated to comply with the I18NLEVEL=2 extension. + + Historical note: the REFERENCES threading algorithm is based on the + [THREADING] algorithm written used in "Netscape Mail and News" + versions 2.0 through 3.0. + +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + The word "can" (not "may") is used to refer to a possible + circumstance or situation, as opposed to an optional facility of the + protocol. + + "User" is used to refer to a human user, whereas "client" refers to + the software being run by the user. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + +2.1 Base Subject + + Subject sorting and threading use the "base subject," which has + specific subject artifacts removed. Due to the complexity of these + artifacts, the formal syntax for the subject extraction rules is + ambiguous. The following procedure is followed to determine the + "base subject", using the [ABNF] formal syntax rules described in + section 5: + + (1) Convert any RFC 2047 encoded-words in the subject to + UTF-8 as described in "internationalization + considerations." Convert all tabs and continuations to + space. Convert all multiple spaces to a single space. + + (2) Remove all trailing text of the subject that matches + the subj-trailer ABNF, repeat until no more matches are + possible. + + (3) Remove all prefix text of the subject that matches the + subj-leader ABNF. + + (4) If there is prefix text of the subject that matches the + subj-blob ABNF, and removing that prefix leaves a non-empty + subj-base, then remove the prefix text. + + (5) Repeat (3) and (4) until no matches remain. + + Note: it is possible to defer step (2) until step (6), but this + requires checking for subj-trailer in step (4). + + (6) If the resulting text begins with the subj-fwd-hdr ABNF + and ends with the subj-fwd-trl ABNF, remove the + subj-fwd-hdr and subj-fwd-trl and repeat from step (2). + + (7) The resulting text is the "base subject" used in the + SORT. + + All servers and disconnected (as described in [IMAP-MODELS]) clients + MUST use exactly this algorithm to determine the "base subject". + Otherwise there is potential for a user to get inconsistent results + based on whether they are running in connected or disconnected mode. + +2.2 Sent Date + + As used in this document, the term "sent date" refers to the date and + time from the Date: header, adjusted by time zone to normalize to + UTC. For example, "31 Dec 2000 16:01:33 -0800" is equivalent to the + UTC date and time of "1 Jan 2001 00:01:33 +0000". + + If the time zone is invalid, the date and time SHOULD be treated as + UTC. If the time is also invalid, the time SHOULD be treated as + 00:00:00. If there is no valid date or time, the date and time + SHOULD be treated as 00:00:00 on the earliest possible date. + + This differs from the date-related criteria in the SEARCH command + (described in [IMAP] section 6.4.4), which use just the date and not + the time, and are not adjusted by time zone. + + If the sent date can not be determined (a Date: header is missing or + can not be parsed), the INTERNALDATE for that message is used as the + sent date. + + When comparing two sent dates that match exactly, the order in which + the two messages appear in the mailbox (that is, by sequence number) + is used as a tie-breaker to determine the order. + +3. Additional Commands + + These commands are extension to the [IMAP] base protocol. + + The section headings are intended to correspond with where they would + be located in the main document if they were part of the base + specification. + +BASE.6.4.SORT. SORT Command + + Arguments: sort program + charset specification + searching criteria (one or more) + + Data: untagged responses: SORT + + Result: OK - sort completed + NO - sort error: can't sort that charset or + criteria + BAD - command unknown or arguments invalid + + The SORT command is a variant of SEARCH with sorting semantics for + the results. Sort has two arguments before the searching criteria + argument; a parenthesized list of sort criteria, and the searching + charset. + + The charset argument is mandatory (unlike SEARCH) and indicates + the [CHARSET] of the strings that appear in the searching + criteria. The US-ASCII and UTF-8 charsets MUST be implemented. + All other charsets are optional. + + There is also a UID SORT command which returns unique identifiers + instead of message sequence numbers. Note that there are separate + searching criteria for message sequence numbers and UIDs; thus the + arguments to UID SORT are interpreted the same as in SORT. This + is analogous to the behavior of UID SEARCH, as opposed to UID + COPY, UID FETCH, or UID STORE. + + The SORT command first searches the mailbox for messages that + match the given searching criteria using the charset argument for + the interpretation of strings in the searching criteria. It then + returns the matching messages in an untagged SORT response, sorted + according to one or more sort criteria. + + Sorting is in ascending order. Earlier dates sort before later + dates; smaller sizes sort before larger sizes; and strings are + sorted according to ascending values established by their + collation algorithm (see under "Internationalization + Considerations"). + + If two or more messages exactly match according to the sorting + criteria, these messages are sorted according to the order in + which they appear in the mailbox. In other words, there is an + implicit sort criterion of "sequence number". + + When multiple sort criteria are specified, the result is sorted in + the priority order that the criteria appear. For example, + (SUBJECT DATE) will sort messages in order by their base subject + text; and for messages with the same base subject text will sort + by their sent date. + + Untagged EXPUNGE responses are not permitted while the server is + responding to a SORT command, but are permitted during a UID SORT + command. + + The defined sort criteria are as follows. Refer to the Formal + Syntax section for the precise syntactic definitions of the + arguments. If the associated RFC-822 header for a particular + criterion is absent, it is treated as the empty string. The empty + string always collates before non-empty strings. + + ARRIVAL + Internal date and time of the message. This differs from the + ON criteria in SEARCH, which uses just the internal date. + + CC + [IMAP] addr-mailbox of the first "cc" address. + + DATE + Sent date and time, as described in section 2.2. + + FROM + [IMAP] addr-mailbox of the first "From" address. + + REVERSE + Followed by another sort criterion, has the effect of that + criterion but in reverse (descending) order. + Note: REVERSE only reverses a single criterion, and does not + affect the implicit "sequence number" sort criterion if all + other criteria are identicial. Consequently, a sort of + REVERSE SUBJECT is not the same as a reverse ordering of a + SUBJECT sort. This can be avoided by use of additional + criteria, e.g. SUBJECT DATE vs. REVERSE SUBJECT REVERSE + DATE. In general, however, it's better (and faster, if the + client has a "reverse current ordering" command) to reverse + the results in the client instead of issuing a new SORT. + + SIZE + Size of the message in octets. + + SUBJECT + Base subject text. + + TO + [IMAP] addr-mailbox of the first "To" address. + + Example: C: A282 SORT (SUBJECT) UTF-8 SINCE 1-Feb-1994 + S: * SORT 2 84 882 + S: A282 OK SORT completed + C: A283 SORT (SUBJECT REVERSE DATE) UTF-8 ALL + S: * SORT 5 3 4 1 2 + S: A283 OK SORT completed + C: A284 SORT (SUBJECT) US-ASCII TEXT "not in mailbox" + S: * SORT + S: A284 OK SORT completed + +BASE.6.4.THREAD. THREAD Command + +Arguments: threading algorithm + charset specification + searching criteria (one or more) + +Data: untagged responses: THREAD + +Result: OK - thread completed + NO - thread error: can't thread that charset or + criteria + BAD - command unknown or arguments invalid + + The THREAD command is a variant of SEARCH with threading semantics + for the results. Thread has two arguments before the searching + criteria argument; a threading algorithm, and the searching + charset. + + The charset argument is mandatory (unlike SEARCH) and indicates + the [CHARSET] of the strings that appear in the searching + criteria. The US-ASCII and UTF-8 charsets MUST be implemented. + All other charsets are optional. + + There is also a UID THREAD command which returns unique + identifiers instead of message sequence numbers. Note that there + are separate searching criteria for message sequence numbers and + UIDs; thus the arguments to UID THREAD are interpreted the same as + in THREAD. This is analogous to the behavior of UID SEARCH, as + opposed to UID COPY, UID FETCH, or UID STORE. + + The THREAD command first searches the mailbox for messages that + match the given searching criteria using the charset argument for + the interpretation of strings in the searching criteria. It then + returns the matching messages in an untagged THREAD response, + threaded according to the specified threading algorithm. + + All collation is in ascending order. Earlier dates collate before + later dates and strings are collated according to ascending values + established by their collation algorithm (see under + "Internationalization Considerations"). + + Untagged EXPUNGE responses are not permitted while the server is + responding to a THREAD command, but are permitted during a UID + THREAD command. + + The defined threading algorithms are as follows: + + ORDEREDSUBJECT + + The ORDEREDSUBJECT threading algorithm is also referred to as + "poor man's threading." The searched messages are sorted by + base subject and then by the sent date. The messages are then + split into separate threads, with each thread containing + messages with the same base subject text. Finally, the threads + are sorted by the sent date of the first message in the thread. + + The first message of each thread are siblings of each other + (the "root"). The second message of a thread is the child of + the first message, and subsequent messages of the thread are + siblings of the second message and hence children of the + message at the root. Hence, there are no grandchildren in + ORDEREDSUBJECT threading. + + Children in ORDEREDSUBJECT threading do not have descendents. + Client implementations SHOULD treat descendents of a child in + a server response as being siblings of that child. + + REFERENCES + + The REFERENCES threading algorithm threads the searched + messages by grouping them together in parent/child + relationships based on which messages are replies to others. + The parent/child relationships are built using two methods: + reconstructing a message's ancestry using the references + contained within it; and checking the original (not base) + subject of a message to see if it is a reply to (or forward of) + another message. + + Note: "Message ID" in the following description refers to a + normalized form of the msg-id in [RFC-2822]. The actual + text in an RFC 2822 may use quoting, resulting in multiple + ways of expressing the same Message ID. Implementations of + the REFERENCES threading algorithm MUST normalize any msg-id + in order to avoid false non-matches due to differences in + quoting. + + For example, the msg-id + <"01KF8JCEOCBS0045PS"@xxx.yyy.com> + and the msg-id + <01KF8JCEOCBS0045PS@xxx.yyy.com> + MUST be interpreted as being the same Message ID. + + The references used for reconstructing a message's ancestry are + found using the following rules: + + If a message contains a References header line, then use the + Message IDs in the References header line as the references. + + If a message does not contain a References header line, or + the References header line does not contain any valid + Message IDs, then use the first (if any) valid Message ID + found in the In-Reply-To header line as the only reference + (parent) for this message. + + Note: Although [RFC-2822] permits multiple Message IDs in + the In-Reply-To header, in actual practice this + discipline has not been followed. For example, + In-Reply-To headers have been observed with message + addresses after the Message ID, and there are no good + heuristics for software to determine the difference. + This is not a problem with the References header however. + + If a message does not contain an In-Reply-To header line, or + the In-Reply-To header line does not contain a valid Message + ID, then the message does not have any references (NIL). + + A message is considered to be a reply or forward if the base + subject extraction rules, applied to the original subject, + remove any of the following: a subj-refwd, a "(fwd)" + subj-trailer, or a subj-fwd-hdr and subj-fwd-trl. + + The REFERENCES algorithm is significantly more complex than + ORDEREDSUBJECT and consists of six main steps. These steps are + outlined in detail below. + + (1) For each searched message: + + (A) Using the Message IDs in the message's references, link + the corresponding messages (those whose Message-ID header + line contains the given reference Message ID) together as + parent/child. Make the first reference the parent of the + second (and the second a child of the first), the second the + parent of the third (and the third a child of the second), + etc. The following rules govern the creation of these + links: + + If a message does not contain a Message-ID header line, + or the Message-ID header line does not contain a valid + Message ID, then assign a unique Message ID to this + message. + + If two or more messages have the same Message ID, then + only use that Message ID in the first (lowest sequence + number) message, and assign a unique Message ID to each + of the subsequent messages with a duplicate of that + Message ID. + + If no message can be found with a given Message ID, + create a dummy message with this ID. Use this dummy + message for all subsequent references to this ID. + + If a message already has a parent, don't change the + existing link. This is done because the References + header line may have been truncated by a MUA. As a + result, there is no guarantee that the messages + corresponding to adjacent Message IDs in the References + header line are parent and child. + + Do not create a parent/child link if creating that link + would introduce a loop. For example, before making + message A the parent of B, make sure that A is not a + descendent of B. + + Note: Message ID comparisons are case-sensitive. + + (B) Create a parent/child link between the last reference + (or NIL if there are no references) and the current message. + If the current message already has a parent, it is probably + the result of a truncated References header line, so break + the current parent/child link before creating the new + correct one. As in step 1.A, do not create the parent/child + link if creating that link would introduce a loop. Note + that if this message has no references, that it will now + have no parent. + + Note: The parent/child links created in steps 1.A and 1.B + MUST be kept consistent with one another at ALL times. + + (2) Gather together all of the messages that have no parents + and make them all children (siblings of one another) of a dummy + parent (the "root"). These messages constitute the first + (head) message of the threads created thus far. + + (3) Prune dummy messages from the thread tree. Traverse each + thread under the root, and for each message: + + If it is a dummy message with NO children, delete it. + + If it is a dummy message with children, delete it, but + promote its children to the current level. In other words, + splice them in with the dummy's siblings. + + Do not promote the children if doing so would make them + children of the root, unless there is only one child. + + (4) Sort the messages under the root (top-level siblings only) + by sent date as described in section 2.2. In the case of a + dummy message, sort its children by sent date and then use the + first child for the top-level sort. + + (5) Gather together messages under the root that have the same + base subject text. + + (A) Create a table for associating base subjects with + messages, called the subject table. + + (B) Populate the subject table with one message per each + base subject. For each child of the root: + + (i) Find the subject of this thread, by using the base + subject from either the current message or its first + child if the current message is a dummy. This is the + thread subject. + + (ii) If the thread subject is empty, skip this message. + + (iii) Look up the message associated with the thread + subject in the subject table. + + (iv) If there is no message in the subject table with the + thread subject, add the current message and the thread + subject to the subject table. + + Otherwise, if the message in the subject table is not a + dummy, AND either of the following criteria are true: + + The current message is a dummy, OR + + The message in the subject table is a reply or forward + and the current message is not. + + then replace the message in the subject table with the + current message. + + (C) Merge threads with the same thread subject. For each + child of the root: + + (i) Find the message's thread subject as in step 5.B.i + above. + + (ii) If the thread subject is empty, skip this message. + + (iii) Lookup the message associated with this thread + subject in the subject table. + + (iv) If the message in the subject table is the current + message, skip this message. + + Otherwise, merge the current message with the one in the + subject table using the following rules: + + If both messages are dummies, append the current + message's children to the children of the message in + the subject table (the children of both messages + become siblings), and then delete the current message. + + If the message in the subject table is a dummy and the + current message is not, make the current message a + child of the message in the subject table (a sibling + of its children). + + If the current message is a reply or forward and the + message in the subject table is not, make the current + message a child of the message in the subject table (a + sibling of its children). + + Otherwise, create a new dummy message and make both + the current message and the message in the subject + table children of the dummy. Then replace the message + in the subject table with the dummy message. + + Note: Subject comparisons are case-insensitive, as + described under "Internationalization + Considerations." + + (6) Traverse the messages under the root and sort each set of + siblings by sent date as described in section 2.2. Traverse + the messages in such a way that the "youngest" set of siblings + are sorted first, and the "oldest" set of siblings are sorted + last (grandchildren are sorted before children, etc). In the + case of a dummy message (which can only occur with top-level + siblings), use its first child for sorting. + + Example: C: A283 THREAD ORDEREDSUBJECT UTF-8 SINCE 5-MAR-2000 + S: * THREAD (166)(167)(168)(169)(172)(170)(171) + (173)(174 (175)(176)(178)(181)(180))(179)(177 + (183)(182)(188)(184)(185)(186)(187)(189))(190) + (191)(192)(193)(194 195)(196 (197)(198))(199) + (200 202)(201)(203)(204)(205)(206 207)(208) + S: A283 OK THREAD completed + C: A284 THREAD ORDEREDSUBJECT US-ASCII TEXT "gewp" + S: * THREAD + S: A284 OK THREAD completed + C: A285 THREAD REFERENCES UTF-8 SINCE 5-MAR-2000 + S: * THREAD (166)(167)(168)(169)(172)((170)(179)) + (171)(173)((174)(175)(176)(178)(181)(180)) + ((177)(183)(182)(188 (184)(189))(185 186)(187)) + (190)(191)(192)(193)((194)(195 196))(197 198) + (199)(200 202)(201)(203)(204)(205 206 207)(208) + S: A285 OK THREAD completed + + Note: The line breaks in the first and third server + responses are for editorial clarity and do not appear in + real THREAD responses. + +4. Additional Responses + + These responses are extensions to the [IMAP] base protocol. + + The section headings of these responses are intended to correspond + with where they would be located in the main document. + +BASE.7.2.SORT. SORT Response + + Data: zero or more numbers + + The SORT response occurs as a result of a SORT or UID SORT + command. The number(s) refer to those messages that match the + search criteria. For SORT, these are message sequence numbers; + for UID SORT, these are unique identifiers. Each number is + delimited by a space. + + Example: S: * SORT 2 3 6 + +BASE.7.2.THREAD. THREAD Response + + Data: zero or more threads + + The THREAD response occurs as a result of a THREAD or UID THREAD + command. It contains zero or more threads. A thread consists of + a parenthesized list of thread members. + + Thread members consist of zero or more message numbers, delimited + by spaces, indicating successive parent and child. This continues + until the thread splits into multiple sub-threads, at which point + the thread nests into multiple sub-threads with the first member + of each subthread being siblings at this level. There is no limit + to the nesting of threads. + + The messages numbers refer to those messages that match the search + criteria. For THREAD, these are message sequence numbers; for UID + THREAD, these are unique identifiers. + + Example: S: * THREAD (2)(3 6 (4 23)(44 7 96)) + + The first thread consists only of message 2. The second thread + consists of the messages 3 (parent) and 6 (child), after which it + splits into two subthreads; the first of which contains messages 4 + (child of 6, sibling of 44) and 23 (child of 4), and the second of + which contains messages 44 (child of 6, sibling of 4), 7 (child of + 44), and 96 (child of 7). Since some later messages are parents + of earlier messages, the messages were probably moved from some + other mailbox at different times. + + -- 2 + + -- 3 + \-- 6 + |-- 4 + | \-- 23 + | + \-- 44 + \-- 7 + \-- 96 + + Example: S: * THREAD ((3)(5)) + + In this example, 3 and 5 are siblings of a parent which does not + match the search criteria (and/or does not exist in the mailbox); + however they are members of the same thread. + +5. Formal Syntax of SORT and THREAD Commands and Responses + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. It also uses [ABNF] + rules defined in [IMAP]. + +sort = ["UID" SP] "SORT" SP sort-criteria SP search-criteria + +sort-criteria = "(" sort-criterion *(SP sort-criterion) ")" + +sort-criterion = ["REVERSE" SP] sort-key + +sort-key = "ARRIVAL" / "CC" / "DATE" / "FROM" / "SIZE" / + "SUBJECT" / "TO" + +thread = ["UID" SP] "THREAD" SP thread-alg SP search-criteria + +thread-alg = "ORDEREDSUBJECT" / "REFERENCES" / thread-alg-ext + +thread-alg-ext = atom + ; New algorithms MUST be registered with IANA + +search-criteria = charset 1*(SP search-key) + +charset = atom / quoted + ; CHARSET values MUST be registered with IANA + +sort-data = "SORT" *(SP nz-number) + +thread-data = "THREAD" [SP 1*thread-list] + +thread-list = "(" (thread-members / thread-nested) ")" + +thread-members = nz-number *(SP nz-number) [SP thread-nested] + +thread-nested = 2*thread-list + + The following syntax describes base subject extraction rules (2)-(6): + +subject = *subj-leader [subj-middle] *subj-trailer + +subj-refwd = ("re" / ("fw" ["d"])) *WSP [subj-blob] ":" + +subj-blob = "[" *BLOBCHAR "]" *WSP + +subj-fwd = subj-fwd-hdr subject subj-fwd-trl + +subj-fwd-hdr = "[fwd:" + +subj-fwd-trl = "]" + +subj-leader = (*subj-blob subj-refwd) / WSP + +subj-middle = *subj-blob (subj-base / subj-fwd) + ; last subj-blob is subj-base if subj-base would + ; otherwise be empty + +subj-trailer = "(fwd)" / WSP + +subj-base = NONWSP *(*WSP NONWSP) + ; can be a subj-blob + +BLOBCHAR = %x01-5a / %x5c / %x5e-ff + ; any CHAR8 except '[' and ']' + +NONWSP = %x01-08 / %x0a-1f / %x21-ff + ; any CHAR8 other than WSP + +6. Security Considerations + + The SORT and THREAD extensions do not raise any security + considerations that are not present in the base [IMAP] protocol, and + these issues are discussed in [IMAP]. Nevertheless, it is important + to remember that [IMAP] protocol transactions, including message + data, are sent in the clear over the network unless protection from + snooping is negotiated, either by the use of STARTTLS, privacy + protection is negotiated in the AUTHENTICATE command, or some other + protection mechanism. + + Although not a security consideration, it is important to recognize + that sorting by REFERENCES can lead to misleading threading trees. + For example, a message with false References: header data will cause + a thread to be incorporated into another thread. + + The process of extracting the base subject may lead to incorrect + collation if the extracted data was significant text as opposed to + a subject artifact. + +7. Internationalization Considerations + + As stated in the introduction, the rules of I18NLEVEL=1 as described + in [IMAP-I18N] MUST be followed; that is, the SORT and THREAD + extensions MUST collate strings according to the i;unicode-casemap + collation described in [UNICASEMAP]. Servers SHOULD also advertise + the I18NLEVEL=1 extension. Alternatively, a server MAY implement + I18NLEVEL=2 (or higher) and comply with the rules of that level. + + As discussed in [IMAP-I18N] section 4.5, all server implementations + should eventually be updated to support the [IMAP-I18N] I18NLEVEL=2 + extension. + + Translations of the "re" or "fw"/"fwd" tokens are not specified for + removal in the base subject extraction process. An attempt to add + such translated tokens would result in a geometrically complex, and + ultimately unimplementable, task. + + Instead, note that [RFC-2822] section 3.6.5 recommends that "re:" + (from the Latin "res", in the matter of) be used to identify a reply. + Although it is evident that, from the multiple forms of token to + identify a forwarded message, there is considerable variation found + in the wild, the variations are (still) manageable. Consequently, it + is suggested that "re:" and one of the variations of the tokens for + forward supported by the base subject extraction rules be adopted for + Internet mail messages, since doing so makes it a simple display time + task to localize the token language for the user. + +8. IANA Considerations + + [IMAP] capabilities are registered by publishing a standards track or + IESG approved experimental RFC. This document constitutes + registration of the SORT and THREAD capabilities in the [IMAP] + capabilities registry. + + This document creates a new [IMAP] threading algorithms registry, + which registers threading algorithms by publishing a standards track + or IESG approved experimental RFC. This document constitutes + registration of the ORDEREDSUBJECT and REFERENCES algorithms in that + registry. + +9. Normative References + + The following documents are normative to this document: + + [ABNF] Crocker, D. and Overell, P. "Augmented BNF + for Syntax Specifications: ABNF", RFC 5234 + January 2008 + + [CHARSET] Freed, N. and Postel, J. "IANA Character Set + Registration Procedures", RFC 2978, October + 2000. + + [IMAP] Crispin, M. "Internet Message Access Protocol - + Version 4rev1", RFC 3501, March 2003. + + [IMAP-I18N] Newman, C. and Gulbrandsen, A. "Internet + Message Access Protocol Internationalization", + Work in Progress. + + [KEYWORDS] Bradner, S. "Key words for use in RFCs to + Indicate Requirement Levels", BCP 14, RFC 2119, + March 1997. + + [RFC-2822] Resnick, P. "Internet Message Format", RFC + 2822, April 2001. + + [UNICASEMAP] Crispin, M. "i;unicode-casemap - Simple Unicode + Collation Algorithm", RFC 5051. + +10. Informative References + + The following documents are informative to this document: + + [IMAP-MODELS] Crispin, M. "Distributed Electronic Mail Models + in IMAP4", RFC 1733, December 1994. + + [THREADING] Zawinski, J. "Message Threading", + http://www.jwz.org/doc/threading.html, + 1997-2002. + +Appendices + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: +1 (206) 543-5762 + + EMail: MRC@CAC.Washington.EDU + + Kenneth Murchison + Carnegie Mellon University + 5000 Forbes Avenue + Cyert Hall 285 + Pittsburgh, PA 15213 + + Phone: +1 (412) 268-2638 + Email: murch@andrew.cmu.edu + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. diff --git a/docs/drivers.txt b/docs/drivers.txt new file mode 100644 index 0000000..de91aa5 --- /dev/null +++ b/docs/drivers.txt @@ -0,0 +1,189 @@ +/* ======================================================================== + * 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. diff --git a/docs/formats.txt b/docs/formats.txt new file mode 100644 index 0000000..8dfb9da --- /dev/null +++ b/docs/formats.txt @@ -0,0 +1,217 @@ +/* ======================================================================== + * 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. diff --git a/docs/imaprc.txt b/docs/imaprc.txt new file mode 100644 index 0000000..cda153a --- /dev/null +++ b/docs/imaprc.txt @@ -0,0 +1,613 @@ +/* ======================================================================== + * 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