------------ Contents ------------ Copyright Notices Authors Acknowledgements Synopsis Notes VMS Related Bugs History Files Making IUPOP3 Make Options Configuring IUPOP3 POP3 Extensions Comments ------------ Copyright ------------ (C) Copyright 1991-1994 The Trustees of Indiana University Permission to use, copy, modify, and distribute this program for non-commercial use and without fee is hereby granted, provided that this copyright and permission notice appear on all copies and supporting documentation, the name of Indiana University not be used in advertising or publicity pertaining to distribution of the program without specific prior permission, and notice be given in supporting documentation that copying and distribution is by permission of Indiana University. Indiana University makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. ------------ Notices ------------ The authoritative distribution site for IUPOP3 is ftp.indiana.edu. This is where you will find the most up-to-date version. Other sites have been known to have copies a year or more old. ------------ Authors ------------ Indiana University University Computing Services Network Applications Group Jacob Levanon - Manager, Network Applications Larry Hughes - Principal Software Engineer ---------------- Acknowledgements ---------------- The authors wish to thank everyone who has contributed fixes, enhancements, and/or assistance in debugging IUPOP3. There are many such people, notably Andrew Greer, Charles Bailey, Jim Gaynor, and David E. Bellamy. We're sure we've missed at least a few names; please know that your efforts are appreciated. ------------ Synopsis ------------ The IUPOP3 server is a VMS implementation of the Post Office Protocol Version 3, based on RFC 1460 (which supersedes RFC 1081 and 1225). There are many differences between IUPOP3 and the BSD UNIX popper, partly due to the differences between VMS and UNIX as operating systems. Probably the most notable difference is that IUPOP3 is a permanent, multithreaded server. The server always listens on the network port for new connections, and can handle up to 31 simultaneous POP3 client connections. In this way, expensive VMS process creation overhead can be avoided. Note that this does not mean that IUPOP3 can serve only 31 clients; indeed, at IU it serves hundreds. The limitation is 31 concurrent connections from POP3 clients at any given moment in time. IUPOP3 was developed and tested on VMS 5.3 (and higher) systems, using the VMS callable mail (MAIL$) API. The current release is believed to be compatible with current versions of these TCP/IP network implemen- tations: Wollongong's Pathway (aka WIN/TCP for VMS), DEC's TCP/IP Services for OpenVMS (aka UCX), and TGV's MultiNet. IUPOP3 also runs on Process Software's TCPware, in UCX emulation mode (see the section titled "Making IUPOP3" below for details). *** NOTE: On AXP platforms, we have tested IUPOP3 only with MultiNet 3.2 *** and 3.3. A bug in AXP/UCX 3.0 prevents it from running correctly *** there, but we are told that it runs fine on AXP/UCX 3.1. ------------ Notes ------------ IUPOP3 has been tested with many POP3 clients: Eudora for the Macintosh, PC and Windows Eudora, FTP Software's POP3 for DOS, NuPOP for DOS, and IU's home grown POP3 client for DOS (sorry, it's not public domain). It works very well with all of these clients. If you test it with other clients, we would appreciate knowing the results. True to the POP3 protocol, IUPOP3 does not perform any mail delivery functions (notably, the optional "XTND XMIT" command). At IU, as most other sites, we rely on a UNIX host to act as an SMTP mail relay for POP3 clients. You can also use a VMS host as an SMTP relay, as long its SMTP server is configured to act as a relay. Due to a change in the password hashing algorithm in VMS 5.4 (and the introduction of the SYS$HASH_PASSWORD system service call), IUPOP3 includes both VMS 5.4 and pre-VMS 5.4 algorithms and password verification routines. The MAKE.COM procedure should automatically sense your VMS version and use the right algorithm when building IUPOP3. If you plan on running IUPOP3 with many clients, chances are you'll take advantage of its multi-threading capabilities. You should be sure that your PQL_DTQELM is set to at least 34; many systems have a default of 8, which means that IUPOP3 will hang when it gets more than 6 simultaneous threads. ---------------- VMS Related Bugs ---------------- If you are running CSCPAT_0180023 or CSCPAT_1123 on your system, any pre-V1.8 version of IUPOP3 is susceptible to crash at intermittent and unpredictable intervals, with this message: %CONV-F-OPENIN, error opening !AS as input -RMS-F-IFI, invalid internal file identifier (IFI) value %TRACE-F-TRACEBACK, symbolic stack dump follows where !AS is the full path to a user's MAIL.MAI file. This was due to a bug in the patches for CONVSHR.EXE. This affects pre-V1.8 versions of IUPOP3, which always performed the equivalent of a PURGE/RECLAIM after deleting messages. IUPOP3 V1.8 is still capable of performing the PURGE/RECLAIM, but does not do so by default; to enable this feature, see the description of command line options later in this document. DEC's callable mail API (MAIL$) has at least one memory leak that causes IUPOP3 to occasionally crash due to "insufficient virtual memory." This was reported to DEC in October of 1992. In April 1993, we were told that this bug had also crept into VMS 6.0, and may not be corrected until VMS 6.1. If we are able to obtain a patch before then, we will notify everyone on our mailing list. Meanwhile, you can lengthen the life of IUPOP3 between crashes by modifying its RUN/DETACH to include a /PAGE_FILE= parameter. To size this parameter, do a SHOW PROCESS/QUOTA on your IUPOP3 process, and look at the "Paging file quota:" field. Try doubling this number, and use it as the /PAGE_FILE= parameter. To join our mailing list, see the "Comments" section later in this file. ------------ History ------------ Version : 1.8-1 (supersedes all 1.8-beta releases) Release Date : May 11, 1994 Comments : Fixed various bugs in the MAKE procedure. (We're sure it's still not bulletproof, but it's better!) Fixed a bug which would occasionally cause IUPOP3 to crash with this error message: %MAIL-E-NOMORECTX, no more context blocks %SYSTEM-F-ACCVIO, access violation, reason mask=01, [...etc...] Minimal support for mail messages sent with MAIL/FOREIGN. Such messages are usually binary, and so are not transferred to the POP3 client. Instead, the message headers are transferred, along with a brief message body telling the user to login and EXTRACT the foreign message. Also, these foreign messages are never deleted, despite POP3 client directions to do so; they are always moved into the MAIL folder after the client retrieves them. In other words, to preserve both the POP3 protocol and the untransferred messages, IUPOP3 simply lies about having deleted them. The SO_REUSEADDR socket option is now being set correctly, permitting a fast restart of the server after it crashes or is stopped. Without prior IUPOP3 versions, too short of a wait would cause the error message "error binding initial socket" to appear in the log, before exiting. Fixed a bug in the way that the active logfile was being opened; now it should be correctly read-shared. (This bug only appeared on AXP systems, to our knowledge). Added a configurable option for the maximum number of mail messages a single client can download per connection. Prior versions had a hardcoded limit of 20 messages. (For details on this, see below where the command line parameters are described). Added a command line parameter for enabling PURGE/RECLAIM on user mailboxes when messages are deleted. This used to be a make option. You might want to run your server this way one day per week, for example, to keep tidy mailboxes. The XTND authorization database is now being closed. Prior versions opened it anew, never closing, each time it was accessed. (For more information on XTND, see the "POP3 Extentions" section below). Support for AXP architecture. We have tested only on OpenVMS AXP V1.5 with MultiNet V3.2 and 3.3. We have reports that it runs correctly on AXP/UCX 3.1, but not on 3.0 due to a UCX bug. Major changes to the way logging is implemented. Most notably, there are now 4 dynamically-adjustable logging levels: ERROR, INFO, THREAD, and DEBUG. ERROR is the least verbose, and logs only error messages. INFO is slightly more verbose than ERROR; it also reports some startup and shutdown messages, changes to logging levels, etc. THREAD (the default level) is informative about client/server interactions, without being overly verbose. At this level the client's IP address and username is logged, in addition to the client's half of the POP3 conversation, and unique message IDs for tracing downloaded messages. The DEBUG level is extremely verbose; it is how all logging was performed in pre-V1.8 versions. Logging now occurs by default to SYS$OUTPUT, or may optionally be directed to a log file of your choice. We recommend the latter approach, because with it IUPOP3 will initiate a new version of the log every day just after midnight (specifically, beteween 12:00 and 12:03 AM). This feature, in concert with adjustable logging levels, should help you manage IUPOP3's disk consumption. Note that when you log to a file rather than SYS$OUTPUT, IUPOP3 flushes the file to disk every 3 minutes. IUPOP3.EXE now supports command line parameters, to help you customize its behavior. See the section on "Configuring IUPOP3" later in this document. Patching of the VMS Mail "From:" lines is now done automatically, to facilitate replies from POP3 mail clients. The rules used are relative simple, and are checked in this order: 1. If the address is of the form FOO%"xxxxxx" or NODE::"xxxxxx", the text in quotes is used, without modification. 2. If the address is of the form NODE::USER, it is converted to user@node. 3. Since checks 1 and 2 failed, the address is assumed to be local, so "@localhostname" is appended to it. The value of "localhostname" depends on your local TCP/IP configuration. Examples: SMTP%"hughes@indiana.edu" -----> hughes@indiana.edu MYGATE::"hughes@indiana.edu" -----> hughes@indiana.edu MYVAX::HUGHES -----> hughes@myvax HUGHES -----> hughes@localhostname This feature obsoletes the need to define the PATCH_FROM_LINE macro in the build procedure, as prior versions required. Cases where a user has no MAIL.MAI is now handled correctly. Before this version, a new user that had not yet received any mail (and hence had no MAIL.MAI) would encounter a POP3 protocol error. IUPOP3 now pays closer attention to the "flags" field of the user's SYSUAF entry. Specifically, a user will not be able to access mail through IUPOP3 if any of these flags is set: DISUSER, DISMAIL, PWD_EXPIRED, or PWD2_EXPIRED. Such a user will receive a POP3 error like this: -ERR user account "jones" not accessible. To discourage hacking attempts, IUPOP3 now permits only 2 username/ password authentication attempts per TCP connection. After the second failure, IUPOP3 closes the connection. Also to discourage hacking, IUPOP3 no longer reports "invalid username" if the attempted username does not exist. If the username/password pair is invalid for any reason, the user should receive a POP3 error like this: -ERR user account "jones" not accessible. When downloading mail messages to POP3 clients, IUPOP3 adds a few extra lines to the mail header. These lines begin with "X-". They have changed slightly in this version. The new ones are "X-VMS-From:", "X-POP3-Server:", and "X-POP3-ID:". For example: X-VMS-From: SMTP%"hughes@indiana.edu" "larry hughes" X-POP3-Server: jade.ucs.indiana.edu IUPOP3 V1.8/UCX X-POP3-ID: 1993-05-12.11:39:23.167 The "X-POP3-ID" line indicates the date and time that the message was downloaded through IUPOP3, followed by a unique number. If IUPOP3 is logging at the THREAD or DEBUG level, this information can be used to locate that POP3 transaction in the log. Fixed a (never reported!) bug when IUPOP3 is used on UCX systems, whereby client connections are never timed out. IUPOP3 should have timed out connections after two minutes of client silence. Finally, this distribution includes a new utility (XTND) to help you administer IUPOP3 via its unique extions. For details on this, see the "POP3 Extensions" section below. Version : 1.7 Release Date : March 16, 1992 Version : 1.6a Release Date : June 6, 1991 Version : 1.6 Release Date : May 16, 1991 Version : 1.5 Release Date : April 2, 1991 ------------ Files ------------ README.TXT - This file COPYRIGHT.TXT - IUPOP3 copyright RFC1460.TXT - RFC 1460 describing POP3 protocol RFC1082.TXT - RFC 1082 describing optional POP3 extentions IUPOP3.COM - Runs the IUPOP3 server (must be configured!) START_IUPOP3.COM - Starts IUPOP3.COM as a detached job (must be configured!) MAKE.COM - The required mechanism for building IUPOP3 IUPOP3.MMS - The MMS makefile invoked by MAKE.COM, if MMS is installed UCX.OPT - Linker options file for UCX WINS.OPT - Linker options file for WIN/TCP MULTINET.OPT - Linker options file for MultiNet IUPOP3.C - Main source file IUPOP3_COMMANDS.C - Routines which process the POP3 server commands IUPOP3_VMS.C - MAIL$ and SYS$ routines IUPOP3_UTILITY.C - Various utility and support routines PASSWD_V54.C - VMS 5.4 password hashing and validation PASSWD_V53.C - Pre VMS 5.4 password hashing and validation UCX_IOCTL.C - A somewhat functional ioctl() function for UCX CHANGE_CASE.MAR - A few very fast string routines IUPOP3_GENERAL.H - Includes files... IUPOP3_GLOBAL.H IUPOP3_VMS.H DESCR.H INETIODEF.H ITMLST.H VERSION.H MAILMISCDEF.H MAILMSGDEF.H POP_XTND.DAT - An example authorization file for XTND commands XTND.COM - A VMS DCL/Kermit script for execting XTND commands XTND.SH - A UNIX Bourne Shell/Kermit script for execting XTND commands ------------- Making IUPOP3 ------------- (Note for TCPware: IUPOP3 can run on TCPware in UCX emulation mode. To do so first requires one minor modification. Edit the UCX.OPT file, and change "sys$library:ucx$ipc.olb/lib" to "tcpware:ucx$ipc.olb/lib". Then make IUPOP3 for UCX as instructed below.) To build IUPOP3, type this command in your IUPOP3 distribution directory: $ @MAKE The MAKE.COM accepts three optional (and positional) paramters: $ @MAKE [UCX | MULTINET | WINS] [MMS | NOMMS] "make options" *must be P1* *must be P2* *must be p3* Although MAKE.COM should be able to automatically detect your TCP/IP implementation and whether or not you have MMS, you may override the automatic detection by supplying either or both of the first two parameters. Specify "UCX" to force the build procedure to assume that you have TCP/IP Services for OpenVMS (aka UCX) installed, or if you are running IUPOP3 is UCX emulation mode. Specify "MULTINET" for TGV's MultiNet product, and "WINS" for Wollongong's Pathway (aka WIN/TCP) product. Specify "MMS" if you have MMS installed on your system, or "NOMMS" if you do not. If desired, you may specify one or more comma-separated Make Options contained in a single set of double quotes. See the section titled "Make Options" for details on each of them. Example: $ @MAKE UCX MMS "IGNORE_MAIL11_HEADERS, PERSONAL_NAME" ------------ Make Options ------------ There are several options that you may enable when building IUPOP3. Note that these options are disabled by default. PERSONAL_NAME This options controls whether or not IUPOP3 will provide your POP3 clients with "From:" lines that include the sender's personal name, if one appeared on the original VMS "From:" line. Below, the first example contains the sender's personal name, and the second does not: From: "larry hughes" From: Be warned that some POP3 clients get confused by the presence of personal names when you attempt to reply to a mail message. Others usually don't mind personal names, but get confused when the name contains commas and other special characters. If you enable this option, please test very carefully with your POP3 clients. IGNORE_MAIL11_HEADERS This option controls whether or not IUPOP3 will completely ignore the VMS Mail headers (From:, To:, etc.) for non-DECnet mail messages. This is something you'll want to do if all of your non-DECnet mail has valid SMTP mail headers beginning on line 1 of the mail message, or if you have users receiving MIME mail from the Internet. ------------------ Configuring IUPOP3 ------------------ After you execute the MAKE.COM procedure, you'll have to edit the IUPOP3.COM (which actually runs IUPOP3.EXE), and START_IUPOP3.COM (which starts IUPOP3.COM as a detached process). The only changes you'll have to make to these procedures are to correct the directory specifications like "SYS$NOWHERE:[NOBODY]". These unusual and probably invalid directory references are used to encourage you to correctly configure IUPOP3 for your individual site. You may also configure IUPOP3.EXE to run with one or more command line parameters. All parameters are optional and case insensitive. They may not be abbreviated. Format: iupop3 [-port n] [-xtnd file] [-loglevel level] [-logfile file] [-maxmsg N] [-purge_reclaim] logfile - specifies a log file other than SYS$OUTPUT. Be sure to use a full path. loglevel - sets the initial logging level: choices are ERROR, INFO, THREAD (the default), and DEBUG. maxmsg - specifies the maximum number of new mail messages a client may discover, per connection. The default is 20. Since IUPOP3 is multithreaded, defining a reasonable maximum prevents a single client from hogging a thread for long periods of time. port - runs IUPOP3 on a TCP port other than the standard port 110, for testing purposes. purge_reclaim - configures IUPOP3 to perform the equivalent of a PURGE/RECLAIM after deleting user's downloaded mail messages. Be warned that this can cause IUPOP3 to crash occasionally due to a bug in CSCPAT_0180023 and CSCPAT_1123. xtnd - specifies a path to a file that serves as an authorization database for privileged XTND commands. (See the "POP3 Extensions" section later in this document for more information). Example: iupop3 -port 2000 -xtnd pop_xtnd.dat -loglevel debug - -logfile somepath:iupop3.log -maxmsg 50 -purge_reclaim Finally, you might also wish to change START_IUPOP3.COM to submit IUPOP3.COM to a batch queue, instead of running it as a detached process. We prefer the latter approach, and also choose to run it at an elevated priority. --------------- POP3 Extensions --------------- IUPOP3 implements none of the optional 'XTND' commands discussed in RFC 1082. Nor does it (yet) implement the optional APOP extension described in RFC 1460. This might be implemented in a future release. However, IUPOP3 does implement four custom XTND commands. They are: XTND CLIENT - log POP3 client info (if client supplies it) * XTND LOGLEVEL - dynamically adjust IUPOP3 logging level * XTND STATS - display IUPOP3 statistics * XTND SHUTDOWN - cleanly shutdown IUPOP3 * = requires special validation (explanation below) Although you will surely not have a POP3 client that implements these IUPOP3-specific XTND commands, there are three methods to execute them. METHOD 1: If you have a current version of VMS Kermit that supports telnet (like C-Kermit 5A(189)), you can run the XTND.COM script that comes with this distribution. For example: $ @xtnd IUPOP3 Node(s) > vax1 vax2 vax3 Username > hughes Password > XTND command > loglevel debug You may also supply the parameters on the command line, for example: $ @xtnd "vax1 vax2 vax3" hughes mypassword "loglevel debug" Note: VMS versions of C-Kermit 5A(188) have a network timeout bug. Please obtain version 5A(189) for XTND.COM to work correctly. Look on watsun.cc.columbia.edu in /kermit/b/. METHOD 2: If you have a current version of UNIX Kermit that supports telnet (like C-Kermit 5A), you can run the xtnd.sh script that comes with this distribution. For example: % xtnd.sh IUPOP3 Node(s) > vax1 vax2 vax3 Username > hughes Password > XTND command > loglevel debug You may also supply the parameters on the command line, for example: % xtnd.sh "vax1 vax2 vax3" hughes mypassword "loglevel debug" METHOD 3: You can pretend to be a POP3 client by telnet'ing to the POP3 port (110) and typing some commands manually. For example, type the commands indicated below with "->", substituting the name of your IUPOP3 host for VAX1, and using your real username and password: -> $ TELNET VAX1 110 Connected to vax1. Escape character is '^]'. +OK IUPOP3 server V1.8/UCX at vax1, up since 1993-05-12 16:18:48 -> USER HUGHES +OK Password required for "hughes" -> PASS xxxxxx +OK Username/password combination ok -> XTND LOGLEVEL DEBUG +OK logging level changed to debug -> QUIT +OK IUPOP3 server at vax1 signing off. Connection closed by foreign host. Now, a brief description of each XTND command. "XTND LOGLEVEL level" - (requires special validation) - Causes IUPOP3 to immediately modify its logging level. Supported levels are ERROR, INFO, THREAD (the default), and DEBUG. For a brief description of these logging levels, and how to set the initial logging level, see the "Configuring IUPOP3" section earlier in this document. "XTND STATS - (requires special validation) - Generates a report like this: +OK Statistics follow Version Number : 1.8/UCX Logging Level : THREAD Current Time : 1992-02-13 17:44:11 Start Time : 1992-02-13 07:32:53 CPU Seconds : 113.80 (1 mins, 53 secs) Current Threads : 2 Total Threads : 218 Max Threads : 8 Too Many Threads : 0 Normal Disconnects : 215 Abnormal Disconnects : 2 Client Timeouts : 1 Blocked Socket Count : 3 Retrieved Messages : 127 Retrieved Octets : 52451 Average Octets : 413 Minimum Octets : 265 Maximum Octets : 1029 Auth Failures : 6 Current Users : 0. hughes 1. levanon . "XTND SHUTDOWN" - (requires special validation) - Commands IUPOP3 to cleanly shutdown at the nearest opportunity. It will wait for current client connections to disconnect, etc. This is strongly recommended over the DCL "STOP" command, which may not be graceful. "XTND CLIENT clientinfo" - (requires no validation) - IUPOP3 simply logs this client information when it is supplied by the POP3 client. Nothing else is done with it. This can be helpful for troubleshooting, if you use IUPOP3 with a variety of POP3 clients that identify themselves. Administrators of IUPOP3 can validate users for the "XTND LOGLEVEL", "XTND STATS" and "XTND SHUTDOWN" commands by modifying the example POP_XTND.DAT file that comes with the IUPOP3 distribution. An example: # # Format: # xtnd_command [valid_user ...] # shutdown system stats system levanon hughes loglevel hughes levanon Then, indicate the location of this XTND authentication database with the "-xtnd" parameter to IUPOP3 in IUPOP3.COM. For example: $ iupop3 -xtnd sys$somewhere:[somedir]pop_xtnd.dat Note that this is a generic mechanism for validating other XTND commands we (or you) might wish to implement in the future. ------------ Comments ------------ IUPOP3 is an unsupported program. If you decide to use it, do so only in strict adherence to the copyright/disclaimer shown at the top of this file, in the file COPYRIGHT.TXT, and throughout the source code. To self-subscribe to the IUPOP3 users list, send a mail message like this (the dashed delimiters are for visual purposes only, don't include them): ----------------------------------------- To: majordomo@indiana.edu Subject: (subjects are ignored) subscribe iupop3-users ----------------------------------------- You can also get help from IU's Majordomo by sending a message like this: ----------------------------------------- To: majordomo@indiana.edu Subject: (subjects are ignored) help ----------------------------------------- After subscribing, you can send email to "iupop3-users@indiana.edu". Your question or problem report will go to everyone on the list. Be warned that your message will go to HUNDREDS of people worldwide (including the authors). You can also contact the IUPOP3 authors privately by sending a message to "iupop3-authors@indiana.edu". We will respond on a time-available basis. We do appreciate hearing from you! Enjoy!