------------
Contents
------------
Copyright
Notices
Authors
Acknowledgements
Synopsis
Notes
History
Files
Making IUPOP3
Install IUPOP3
Runtime Options
Configuring IUPOP3
Configuring APOP for IUPOP3
POP3 Extensions
RFC 822 header generation
Comments


------------
Copyright 
------------

  (C) Copyright 1997,1998 Michael Stenns

   Permission to use, copy, modify, and distribute this program for
   non-commercial use and without fee is hereby granted. 

   This software is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 

   -------------------------------------------------------------------------------

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

   -------------------------------------------------------------------------------

   This software uses the MD5 message-digest algorithm from RSA Data Security, Inc.
   Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.

------------
Notices
------------

The Indiana University has dropped the development of this software
after version 1.8-1. 

This version (2.0-2) was made to add support for newer POP3 internet standards
(STD 53, RFC 1939), including support for the UIDL and APOP commands described 
there. It contains additional bug fixes and many enhancements from suggestions 
made by people on the IUPOP3 mailing list <iupop3-users@indiana.edu>.


------------
Authors
------------
Version 1.8:

Indiana University
University Computing Services
Network Applications Group

Jacob Levanon - Manager, Network Applications
Larry Hughes  - Principal Software Engineer

Version 2.0-x:

University of Hanover, Germany
Institute of Technical Chemistry

Michael Stenns  <stenns@vw.tci.uni-hannover.de>


----------------
Acknowledgements
----------------

The author wish to thank everyone who has contributed fixes, 
enhancements, and/or assistance in debugging IUPOP3.  There are 
many such people, notably Alberto Meregalli,  Andy Harper, Ian Miller, 
Karol Zielonko and some other.

The author also thanks Jacob Levanon and Larry Hughes for writing the
original version and the Indiana University for maintaining the
iupop3-users mailing list.

------------
Synopsis
------------

The IUPOP3 server is a VMS implementation of the Post Office Protocol
Version 3, based on RFC 1939 (STD 53), which supersedes RFC's 1081, 
1225, 1460 and 1725.

IUPOP3 is a multithreaded server which supports up to 30 simultanous
connections. Once started it listens permanent on the POP3 network port
(normally 110) for new connections. 

IUPOP3 was developed and tested on OpenVMS VAX 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), Process Software's MultiNet, TCPware 
and Madgoat's Netlib (>v2.0). 

------------
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, 
Netscape Mail, Internet Explorer Mail, AK-Mail and others. 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).  

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.

On OpenVMS versions >= 6.x (x=1 for vax and x=2 for alpha) this server can
use the $scan_intrusion system service. This makes it much harder to hack
user passwords using the IUPOP3 server.

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.


------------
History
------------

Version      : 2.0-1 (supersedes all 1.9-beta releases)
Release Date : Dec 10, 1997
Comments     : This version is not made at Indiana University.

Some highlights:
Adding support for long records (up to 64 kb).
Adding support for mixed cluster enviroments.
Adding support for gcc 2.7.1 on vax.
Adding support for NETLIB TCP/IP.
Adding the UIDL, the APOP and some XTND commands.
Using the  scan_intrusion system service to enhance security on newer
OpenVMS versions.
Prototyping all functions, made the files full ANSI-C compatible.
(Compile with DECC without the /standard=vaxc qualifier).

   See file changes.txt for a complete list of changes.

Version      : 1.8-1 (supersedes all 1.8-beta releases)
Release Date : May 11, 1994
Comments     : 

   See file readme_18.txt for changes in 1.8-1

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
RFC1939.TXT         - RFC 1939 describing POP3 protocol
RFC1734.TXT         - RFC 1734 POP3 AUTHentication command

IUPOP3.COM          - Runs the IUPOP3 server 
IUPOP3_LOGICALS.COM - defines logicals used by IUPOP3 and startup procedure (must be configured!)
IUPOP3_STARTUP.COM  - Starts IUPOP3.COM as a detached job 

MAKE.COM            - The required mechanism for building IUPOP3
IUPOP3.MMS          - The MMS makefile invoked by MAKE.COM, if MMS or MMK is installed

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
MD5C.C            - RSA Data Security, Inc., MD5 message-digest algorithm

IUPOP3_GENERAL.H  - Includes files...
IUPOP3_GLOBAL.H
IUPOP3_VMS.H
DESCR.H
INETIODEF.H
VERSION.H
MAILMSGDEF.H
SECSRVMSGDEF.H
MD5.H

POP_XTND.DAT      - An example authorization file for XTND commands

POP3.COM          - A VMS DCL/C-Kermit script for executing POP3 commands
XTND.COM          - A VMS DCL/C-Kermit script for executing XTND commands
XTND.SH           - A UNIX Bourne Shell/Kermit script for executing XTND commands


-------------
Making IUPOP3
-------------

 Note for TCPware and Multinet: 
 Normally these stacks should uses the UCX compatibility mode to avoid problems 
 with newer OS/Compiler versions. To compile against the native multinet 
 libraries, use the MULTINET_NATIVE make command line parameter 
 (but this is not preferred).

 Note for clusters with mixed ip stacks: 
 The NETLIB or UCX version can either be used.
 Netlib is free and available for most (all?) stacks on OpenVMS, including 
 OpenCMU. Many stacks have a UCX compatibility mode.

To build IUPOP3, type this command in your IUPOP3 distribution directory:

   $ @MAKE ?

which gives an overview about available options.

The MAKE.COM accepts five optional (non-positional) kinds of paramters:

   $ @make stack make-utility make-options mms-options compiler

stack:            UCX, MULTINET, TCPWARE, WINS or NETLIB
make-utility:     MMS, MMK or NOMMS
compiler:         DECC, VAXC or GNUC
mms-options:      all parameters starting with a slash (see mms/mmk documentaion)
make-options:     all other parameters (see chapter "Make Options")

The recommended make command is:

   $ @make

All parameters can be specified alone, as comma-separated list or mixed.
Remark: DCL accepts only up to eight parameters, but parameters concatenated 
        with a comma counts only for one.

-------------
Install IUPOP3
-------------

1) Create the following directory structure:
   dev:[somewhere]
   dev:[somewhere.bin]
   dev:[somewhere.log]

2) copy IUPOP3_LOGICALS.COM to dev:[somewhere]     !**! you must edit this file! !**!
   copy IUPOP3_STARTUP.COM to  dev:[somewhere]
   copy IUPOP3.COM         to  dev:[somewhere.bin]
   copy IUPOP3_*.EXE       to  dev:[somewhere.bin]
   copy POP_XTND.DAT       to  dev:[somewhere.bin] !**! you must edit this file! !**!

3) execute IUPOP3_LOGICALS.COM if not at same location as IUPOP3_STARTUP.COM
     This defines logicals used by IUPOP3 or the startup procedure.
   execute IUPOP3_STARTUP.COM
     This executes IUPOP3_LOGICALS.COM if in same directory and
     starts IUPOP3 as a detached process. The following
     logicals will be defined in the system logical table:

    iupop3_root:[000000]         Root of IUPOP3 tree
    iupop3_root:[bin]            IUPOP3 binaries.
    iupop3_root:[log]            Directory for log files
    iupop3_exe                   points to iupop3_root:[bin]
    iupop3_log                   points to iupop3_root:[log]


Example installation (executed from source code directory):

    $@make
    $create/dir sys$sysdevice:[iupop3]
    $create/dir sys$sysdevice:[iupop3.bin]
    $create/dir sys$sysdevice:[iupop3.log]
    $copy IUPOP3_LOGICALS.COM sys$sysdevice:[iupop3]
    $copy IUPOP3_STARTUP.COM sys$sysdevice:[iupop3]
    $copy IUPOP3.COM, POP_XTND.DAT, IUPOP3_alpha.EXE sys$sysdevice:[iupop3.bin]
    $edit/tpu sys$sysdevice:[iupop3]IUPOP3_LOGICALS.COM
    $edit/tpu sys$sysdevice:[iupop3.bin]POP_XTND.DAT
    $!
    $! insert the following line in SYSTARTUP_VMS.COM:
    $@sys$sysdevice:[iupop3]IUPOP3_STARTUP

------------
Runtime Options
------------

There are several options that you may enable when building IUPOP3.

Note that these options are disabled by default.

PERSONAL_NAME                     <bool>
   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" <hughes@indiana.edu> 
    From: <hughes@indiana.edu>

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

USE_BOTTOM_HEADERS                <bool>
   This option controls wether IUPOP3 grabs the RFC 822 headres from the 
   bottom of a mail11 message rather than from the top.
   Specify this option *only* 
      - if you have UCX
      - if you have SMTP configured to put the RFC 822 headers at the
        bottom of the message
      - and you have specified the IGNORE_MAIL11_HEADERS option.
   Remark:
      Most other POP3 servers for OpenVMS rely on RFC 822 headers being
      at the top of a message. Also the PINE email client expects
      these headers at the top for interpreting MIME messages.

USE_MAIL_FOLDER                   <bool>
   Moves all new mail to the MAIL folder and displays this folder
   instead of the NEWMAIL folder. 
   Normally the NEWMAIL folder is shown and the messages are moved 
   to the MAIL folder when read. This makes it impossible to download 
   a message previously read with VMS Mail or to receive messages
   with more than one POP client.
   If the option is used, the maximum allowed messages should be set to
   a high value and the FAST_SCAN option should be used, too.

FAST_SCAN                         <bool>
   With this option enabled a maildrop selection is significant faster.
   The size of each message is estimated only from the number of 
   records (available from callable mail api) rather than checking
   the size of each mail file. The result is used in the "LIST" pop3
   command. Most clients do not rely on good values here.
 
IGNORE_EXPIRED_PASSWORDS          <bool>
   With this option enabled the maildrop access is granted even
   if the specified password has been expired. This is normal
   behavior for network processes.

SCAN_INTRUSION                    <bool>
NOSCAN_INTRUSION           ! make option only
   After password validation the $scan_intrusion system service
   is checked for intruders. 
   Each unsuccessful authentication attempt increments the intrusion
   count. If the intrusion type has changed from "SUSPECT" to "INTRUDER"
   every access from the offending source will be rejected. This makes
   it nearly impossible to hack for passwords by misusing the POP3 
   protocol.

   $ show intrusion
   Intrusion       Type       Count        Expiration         Source
   NETWORK      SUSPECT       1    7-AUG-1997 20:07:54.15  IUPOP3::127.0.0.1:stenns

   The last field contains the source of the suspect intrusion.
   At least OpenVMS/VAX 6.1 or OpenVMS/Alpha 6.2 is required. The IUPOP3
   process needs the security privilege.


DEFAULT_TO_SMTP                    <bool>
   Sets the default message type where IUPOP3 can't detect the 
   right one. Same as the -default_type commandline option.

APOP_CHECK_DUPLICATE               <bool>
   Disables access if APOP and interactive passwords are identical.
   The APOP shared secred must be known as clear text both to
   client and server. Using identical passwords may be considered
   as security risk.

ENABLE_LONG_LINES                  <bool>
   Enables passing of lines longer than 256 bytes to the client
   using undocumented features of the callable mail routines.
   AFAIK only MX creates messages with long lines.

PURGE_MAILBOXES                    <bool>
   Enables purging of mailboxes. Mailboxes are purged only if this
   option is set and the user has enabled autopurging in VMS mail. 
   If this option is set to false, deleted messages are only moved 
   to the wastebasket folder. The PURGE_RECLAIM_THRESHOLD option 
   is ignored in this case.

PURGE_RECLAIM_THRESHOLD            <numerical>
   Defines the number of deleted message bytes required for a 
   purge/reclaim operation. During normal purge external message
   files are deleted, but some data within mail.mai remains 
   unavailable. Purge/reclaim needes mail.mai be locked, so no mail
   can be received during this operation. The default value is
   32176 if the -purge_reclaim commandline option is set. A value
   of 0 inhibits purge/reclaim.

READ_DIRECT_THRESHOLD           <numerical>
   Defines the maximum file size in bytes where the callable mail
   routines are used to process the file. Larger files are read
   with ANSI-C functions. Default is zero, which means no threshold.
   The callable mail routines read the whole file into memory, 
   even if it contains a lot of megabytes of stuff.
   Because of additional required buffers values less than 64 kb
   makes no sense.

DEFAULT_SENDBUFFER_SIZE          <numerical>
   Defines the default buffer size in bytes which is allocated for
   each active thread. Use a value between 1 kb and 
   512 kb (defined in iupop3_general.h). Default is 4 kb.
   On sending large messages the send buffer is filled and queued to
   the network driver. While the driver sends the content of the buffer, 
   other threads can be processed.
   Up to 64 kb are queued in a single I/O to the network driver.
  
MAX_MESSAGES                       <numerical>
   Defines the maximum number of message in a maildrop which are
   shown to the client. 
   Same as the -maxmsg commandline switch.

CLIENT_TIMEOUT                      <numerical>
   Defines the client timeout in minutes. RFC 1939 recommends a
   minimum value of 10 minutes.

AUTH_COMMANDS                       <string>
   RFC 1939 makes the user/pass and apop authorization commands optional.
   A value of "user" means only the user/pass combination is allowed,
   "apop" means only the apop command is recognized, and any other value
   means both commands are allowed (this is the default).

FOREIGN_FOLDER                      <string>
   IUPOP3 ignores delete operations on foreign mails because they
   can only be handled locally. Only a informational message is send
   to the client. With this logical defined IUPOP3 moves the foreign
   mail to the specified folder instead of just ignoring the delete 
   operation.
   Example:
   $DEFINE/SYSTEM IUPOP3_FOREIGN_FOLDER "FOREIGN-MAIL"

NODE_xxx                            <string>
   Maps decnet node xxx to specified domain.
   This is very useful for building meaningful reply addresses.
   Example:
   Mapping without this logical defined:
         nodename::username   --->  username@nodename
   Mapping with this logical defined:
   define /system IUPOP3_NODE_nodename  "node.sub.top"
         nodename::username   --->  username@node.sub.top


Overview of available options:

           logicals                : commandline 
       (run-time options)          :   options
 ----------------------------------:----------------
                                   :
 IUPOP3_IGNORE_MAIL11_HEADERS      :
 IUPOP3_DEFAULT_TO_SMTP            : -default_type 
 IUPOP3_USE_BOTTOM_HEADERS         :
 IUPOP3_PERSONAL_NAME              :
 IUPOP3_USE_MAIL_FOLDER            :
 IUPOP3_FAST_SCAN                  :
 IUPOP3_SCAN_INTRUSION             :
 IUPOP3_ENABLE_LONG_LINES          :
 IUPOP3_APOP_CHECK_DUPLICATE       :
 IUPOP3_IGNORE_EXPIRED_PASSWORDS   :
 IUPOP3_PURGE_MAILBOXES            : 
 IUPOP3_READ_DIRECT_THRESHOLD      :
 IUPOP3_DEFAULT_SENDBUFFER_SIZE    :
 IUPOP3_PURGE_RECLAIM_THRESHOLD    : -purge_reclaim
 IUPOP3_MAX_MESSAGES               : -maxmsg
 IUPOP3_CLIENT_TIMEOUT             : -timeout
 IUPOP3_AUTH_COMMANDS              :
                                   : -logfile
                                   : -loglevel
                                   : -xtnd
                                   : -port
                                   : UCX, MULTINET, TCPWARE, NETLIB 1)
                                   : VAX, ALPHA 1)
 IUPOP3_FOREIGN_FOLDER
 IUPOP3_NODE_xxx


1)  This options are automatically generated by the make.com build 
    command procedure. MULTINET and TCPWARE uses UCX emulation.

These logical are defined in iupop3_startup.com.

 Additional logicals needed:
 SYS$TIMEZONE_DIFFERENTIAL  <offset to utc in seconds>
 This logical should already be defined on newer OpenVMS versions.
 It is used to supply timezone informations with decnet messages. It
 is converted to a string like "-0500". Always the current value is
 used.

------------------
Configuring IUPOP3
------------------

After you execute the MAKE.COM procedure, you'll have to edit the
IUPOP3_LOGICALS.COM file.
See the comments within this file.


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. You need to edit IUPOP3.COM in this case.

Format:  iupop3 [-port n] [-xtnd file] [-loglevel level] 
                [-logfile file] [-maxmsg N] [-purge_reclaim]
                [-default_type type] [-timeout N]

  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.

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

  default_type - type of messages which type can not be determined.
      Choices are decnet or smtp.

  timeout - client timeout in minutes. RFC 1939 request a value
      of at least 10 minutes.

Example: iupop3 -port 2000 -xtnd pop_xtnd.dat -loglevel debug -
             -logfile iupop3_log:iupop3.log -maxmsg 50 -purge_reclaim -
             -default_type decnet -timeout 10

------------------
Configuring APOP for IUPOP3
------------------

APOP is an authorization mechanism which uses the username/digest 
instead of the username/password combination.

The digest is a cryptographic checksum created from a shared secret 
and a timestamp sent by the server during connect. The digest is different
on each connect, but both server and client must know the shared secret
as clear text. It should be different from the interactive login password,
and with IUPOP3_APOP_CHECK_DUPLICATE logical set to true a shared secret
identical to the login password is not accepted.

To enable APOP for an user a file named POP_SECRET.DAT must exist in the
user's mail directory with the shared secret in the first line. The 
secret may not exceed 512 characters and is case sensitive.
This file might be protected like

$ set protection=(o:rwd,s,g,w) POP_SECRET.DAT

---------------
POP3 Extensions
---------------

IUPOP3 implements none of the optional 'XTND' commands discussed in
RFC 1082.  

However, IUPOP3 does implement some custom XTND commands.  They are:

     XTND CLIENT    - log POP3 client info (if client supplies it)
     XTND HELP      - display XTND commands summary
   * XTND LOGLEVEL  - dynamically adjust IUPOP3 logging level
   * XTND STATS     - display IUPOP3 threads statistics
   * XTND NETSTATS  - display network i/o statistics
   * XTND INFO      - display resource usage statistics
   * XTND OPTIONS   - show/set runtime options
   * XTND KILL      - stop client
   * XTND RESTART   - restart the IUPOP3 image 
   * 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 four 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.

METHOD 4: Get the POPrequest utility. This is a small C program probably
available from the same site you get IUPOP3 from. 

   -> $ poprequest /pass=* /xtnd=log=thread /noapop
      +OK IUPOP3 server <V2.0-1/UCX@vw.tci.uni-han.de at 21-MAY-1997 18:56:18.15>
   -> Enter password>**********
      +OK Password required for "stenns"
      +OK Username/password combination ok
      xtnd loglevel thread
      +OK logging level changed to thread
      +OK IUPOP3 server at vw.tci.uni-hannover.de signing off.


--------------------------------------------------------------------------
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 KILL n" - (requires special validation) - Generates a output like this:

Kills the specified thread immediatly.

XTND KILL 7
+OK thread 7 will be disconnected

--------------------------------------------------------------------------
"XTND HELP"  - Generates a output like this:
 XTND command  | min. arg. | max. arg. | validation
===============+===========+===========+============
 client        |      1    |     10    | (none)
 stats         |      0    |      0    | stats
 netstats      |      0    |      0    | stats
 info          |      0    |      0    | stats
 loglevel      |      1    |      1    | loglevel
 options       |      0    |      1    | shutdown
 shutdown      |      0    |      0    | shutdown
 restart       |      0    |      0    | shutdown
 kill          |      1    |      1    | shutdown
 help          |      0    |      0    | (none)

--------------------------------------------------------------------------
"XTND STATS" - (requires special validation) - Generates a report like this:

+OK Statistics follow
  Version Number       : 2.0-1/UCX
  Logging Level        : THREAD
  Current Time         : 1997-05-21 19:01:12
  Start Time           : 1997-05-07 10:00:39
  CPU Seconds          : 183.78   (3 mins, 3 secs)
  Current Threads      : 2
  Total Threads        : 113
  Max Threads          : 2
  Too Many Threads     : 0
  Normal Disconnects   : 90
  Abnormal Disconnects : 1
  Client Timeouts      : 0
  Retrieved Messages   : 589
  Retrieved Octets     : 4495513
  Average Octets       : 7632
  Minimum Octets       : 376
  Maximum Octets       : 485286
  Auth Failures        : 44
  Current Users        : 2
     0. stenns        , since 21-MAY-1997 19:00:41 , timeouts 19:11:10.40
     1. postmaster    , since 21-MAY-1997 19:01:12

--------------------------------------------------------------------------
"XTND NETSTATS" - (requires special validation) - Generates a report like this:

+OK Statistics follow
  Current Time         : 1997-05-21 19:03:24
  Start Time           : 1997-05-07 10:00:39
  CPU Seconds          : 185.36   (3 mins, 5 secs)
  Main loop count      : 46594
  Hibernation count    : 44054
  Connections accepted : 114
  Commands processed   : 1237
  Network bytes written: 5310929
  Network bytes read   : 14508
  Network write count  : 2513
  Write AST count      : 1161
  Network read count   : 1264

--------------------------------------------------------------------------
"XTND INFO" - (requires special validation) - Generates a report like this:

+OK Displaying process informations after 3957 measurements
 description                              |    cur   |    min   |   max
==========================================+==========+==========+==========
 remaining AST quota                      |       96 |       96 |       99
 remaining buffered I/O quota             |      100 |       99 |      100
 remaining buffered I/O byte count quota  |    95968 |    95776 |    99296
 remaining direct I/O quota               |      100 |       99 |      100
 remaining lock request quota             |      293 |      292 |      300
 remaining open file quota                |       93 |       92 |       97
 process's global page count in the ws    |     1072 |       16 |     1312
 remaining paging file quota              |    40768 |    40768 |    47280
 number of working set pages or pagelets  |     3776 |      304 |     6144

  CPU Seconds (image)   : 187.18   (3 mins, 7 secs)
  CPU Seconds (process) : 187.79   (3 mins, 7 secs)

--------------------------------------------------------------------------
"XTND OPTIONS SHOW" - (requires special validation) - Generates a report 
like this:

+OK Displaying current options
  Current Options:
=============================+===========================
  RUN_TIME_OPTIONS           : TRUE
  IGNORE_MAIL11_HEADERS      : TRUE
  DEFAULT_TO_SMTP            : TRUE
  USE_BOTTOM_HEADERS         : FALSE
  PERSONAL_NAME              : TRUE
  USE_MAIL_FOLDER            : TRUE
  FAST_SCAN                  : TRUE
  SCAN_INTRUSION             : FALSE
  APOP_CHECK_DUPLICATE       : TRUE
  IGNORE_EXPIRED_PASSWORDS   : TRUE
  PURGE_MAILBOXES            : TRUE
  PURGE_RECLAIM_THRESHOLD    : 16000
  MAX_MESSAGES               : 2048
  CLIENT_TIMEOUT             :    0 00:10:00.00

--------------------------------------------------------------------------
"XTND OPTIONS SET" - (requires special validation) - Generates ouput
like this:

+OK will reset options when no threads are connected

--------------------------------------------------------------------------
"XTND RESTART" - (requires special validation) - Commands IUPOP3 to
shutdown with the SS$_OPRABORT exit status.  It will wait for current 
client connections to disconnect, etc.  The IUPOP3.COM will loop
after this return status and restart the IUPOP3 image within the same
process context. Resets the restart counter within IUPOP3.COM.

--------------------------------------------------------------------------
"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    *
   loglevel hughes levanon

A "*" as username means no restriction for this command.
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.


------------
RFC 822 header generation
------------
For DECNET mails IUPOP3 generates some RFC 822 compliant headers on the
fly regarding on the header informations supplied by MAIL11.


Example:

MAIL> READ 1
    #1        18-JUL-1997 18:53:58.84                            MAIL
From:   HAL::STENNS       "MICHAEL STENNS"
To:     VW::STENNS
CC:     STENNS
Subj:   Test

would be converted to

Received: by vw.tci.uni-hannover.de (OpenVMS MAIL)
        with DECNET; Fri, 18 Jul 1997 18:53:58 +0200
Message-ID: <199707181853588464685@vw.tci.uni-hannover.de>
Date: Fri, 18 Jul 1997 18:53:58 +0200
From: "MICHAEL STENNS" <stenns@hal.tci.uni-hannover.de>
Subject: Test
To: vw::stenns
Cc: stenns
X-VMS-From: HAL::STENNS       "MICHAEL STENNS"
X-POP3-Server: vw.tci.uni-hannover.de IUPOP3 V2.0-1/UCX
X-POP3-ID: 1997-07-18.19:00:15.0

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

Enjoy!
