home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 35 Internet
/
35-Internet.zip
/
jpop100.zip
/
README.TXT
< prev
next >
Wrap
Text File
|
1997-08-04
|
33KB
|
911 lines
Page 1
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
ROSSI ENGINEERING
J-POP SERVER
for the Java(TM) platform
USER MANUAL
Table of Contents: Page
-------------------------------------------------------------------------------
1.0 Introduction..........................................................2
1.1 Features..............................................................2
1.2 Requirements..........................................................2
1.3 Installation..........................................................3
1.4 Configuration files...................................................4
1.5 Configuring Server Profile............................................6
1.6 Configuring Users.....................................................8
1.7 Configuring Allowed Hosts.............................................8
2.0 Mailboxes.............................................................9
2.1 Sendmail and local delivery agents...................................10
3.0 Notes for OS/2 users.................................................10
3.1 Notes for Unix users.................................................11
3.2 Operation on other platforms.........................................11
4.0 Optional POP3 commands...............................................11
5.0 Licence..............................................................12
5.1 Support..............................................................13
5.2 Disclamier...........................................................14
5.3 Copyright............................................................14
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 2
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
1.0 Introduction
-------------------------------------------------------------------------------
This POP3 server is entirely written in Java(TM). It is intended to be used on
any platform that supports Java.
1.1 Features
-------------------------------------------------------------------------------
* Complies with RFC1939, RFC1725, RFC1460, RFC1225, and RFC1081.
* Supports the following POP3 commands:
APOP, DELE, LAST, LIST, NOOP, PASS, QUIT, RETR, RSET, STAT,
TOP, UIDL, USER
* Built-in access control through an allowed hosts file.
* Fully Java Compatible, no native methods or system dependencies.
* Supports 2 styles of local mailboxes.
* Graphical user interface for routine management operations, such
as adding users, etc.
* The following optional POP3 commands can be enabled or disabled:
APOP, LAST, TOP, UIDL
* The USER and PASS commands can also be disabled to force users to use
the APOP authentification method.
* No need to restart the server after making configuration changes.
* Comprehensive logging.
* High Performance.
* Registered version supports an unlimited number of users.
1.2 Requirements
-------------------------------------------------------------------------------
* Java runtime version 1.0.2 or higher,
The Java runtime can be obtained at the following locations for
listed platforms:
OS/2 ver. 3.0, 4.0
ftp://ncc.hursley.ibm.com/pub/java/os2/102/runtime.exe
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 3
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Linux http://www.blackdown.org
Solaris http://java.sun.com
Windows NT and 95 http://java.sun.com
* Sendmail or some other mechanism to receive mail for the server
* TCP/IP networking software
* Filesystem capable of supporting long filenames (greater than 8.3) if
using Unix style mailboxes.
1.3 Installation
-------------------------------------------------------------------------------
1.) Unzip the archive into a temporary directory.
2.) Copy the Pop3d.pty file to the "Java Home" directory. This is
the directory that the Java runtime is installed in.
3.) Copy the rossi.zip file to some directory. The CLASSPATH environment
variable will be modified to tell Java where to find it. Under the
"Java Home" directory, there should be a directory called lib. This
is the recommended location. DO NOT UNZIP THIS FILE!!!
4.) Add to the CLASSPATH environment variable so that it contains the
rossi.zip file. A typical CLASSPATH might look like this:
Unix:
CLASSPATH=/java/lib/classes.zip:.:/java/lib/rossi.zip
Windows NT: (set in System Control Panel)
CLASSPATH=d:\java\lib\classes.zip;.;d:\java\lib\rossi.zip
OS/2: (set in CONFIG.SYS)
CLASSPATH=d:\javaos2\lib\classes.zip;.;d:\javaos2\lib\rossi.zip
On some systems it may be necessary to reboot after this change.
5.) You may wish to create a directory to store server configuration
information, such as the user database and the log file. Unix
users should make this files read/writeable by root only.
6.) From a command shell, execute the GUI setup utility by typing:
java rossi.Pop.Setup
Note that this command is case sensitive. On Unix systems, this
may require root privilege.
Or configure the server manually by editing and creating configuration
files by hand. See section 1.4 for details on how to do this.
A few error messages may be displayed during initial installation.
This is normal.
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 4
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
7.) Select Server profile on the Configure Menu. Enter valid file names
for the supplied fields. See section 1.5 for details
8.) Press the Apply button.
9.) If you had selected Restrict Access, then configure the allowed hosts
by selecting "Allowed Hosts" off the Configure menu. See section 1.7
for details.
10.) If you are using the UnixMailFactory, select MailFactory off of the
Configure menu and setup the parameters for the UnixMailFactory. You
don't have to do this for the OS2MailFactory because it doesn't have
any parameters.
11.) Select Users off of the Configure menu and setup user accounts.
See section 1.6 for details.
12.) Start the server with the command:
java rossi.Pop.Server
Note that this command is case sensitive.
On Unix, this should be done by the root user. The command:
java rossi.Pop.Server& can be put in one of the system initialization
scripts.
On OS/2, the following command may be added to STARTUP.CMD:
detach java rossi.Pop.Server
1.4 Configuration files
-------------------------------------------------------------------------------
THIS SECTION IS FOR HAND EDITING THE CONFIGURATION FILES. IF YOU ARE
USING THE GUI SETUP PROGRAM, YOU DO NOT NEED TO READ THIS.
1.4.1 Pop3d.pty: Server Properties file
Pop3d.pty is the main configuration file. It should be located in the
"Java Home" directory. This is the directory above where the java executable
is installed.
This file is a Java properties file, and contains a series of lines with
name and value pairs. The name of a property and its value are separated
with an equals sign (=). The backslash character (\) is used as an escape
character, so when specifing filenames on Windows NT or OS/2 it is necessary
to use double backslashes where one would normally put a single one.
For example: To specify the directory D:\MAIL, we would enter D:\\MAIL
Do not put any space or tab characters in the fields, and do not put any
blank lines in the file. Properties are case sensitive.
All properties listed below MUST be specified in the Pop3d.pty file.
Below is a description of each of the properties:
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 5
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
rossi.Pop.UserList Specifies the name of the user list file. This
file contains information on users.
rossi.Pop.TcpdConfig Specifies the name of the allowed hosts file.
rossi.Pop.LogFile Specifies the name of the server log file. If
this is blank, then logging is disabled.
rossi.Pop.MailFactory Set to either rossi.Pop.OS2MailFactory, or
rossi.Pop.UnixMailFactory. This specifies which
style of mailbox the server is using.
rossi.Pop.UseTcpd Set to "true" or "false". Enables or disables
restricting access to the server by using the
allowed hosts file specified by the property
rossi.Pop.TcpdConfig
rossi.Pop.HostName The fully qualified host name of the server
machine. This gets displayed in the POP banner
if APOP is enabled.
rossi.Pop.EnableAPOP Set to "true" or "false". Enables or disables
the APOP command.
rossi.Pop.EnableLAST Set to "true" or "false". Enables or disables
the LAST command.
rossi.Pop.EnableTOP Set to "true" or "false". Enables or disables
the TOP command.
rossi.Pop.EnableUIDL Set to "true" or "false". Enables or disables
the UIDL command.
rossi.Pop.EnableUSERPASS Set to "true" or "false". Enables or disables
the USER and PASS commands.
rossi.Pop.RegName Name of the person or organization the product
is registered to. Leave blank if unregistered.
rossi.Pop.RegKey The registration key for the specified registered
user. Leave blank if unregistered.
If using UnixMailFactory:
rossi.Pop.UnixMailFactory.TempDir The name of the directory where
temporary files can be stored.
Default is \tmp or /tmp.
rossi.Pop.UnixMailFactory.LockExt Extention on the Lock file.
Default is lock.
rossi.Pop.UnixMailFactory.UseIndex Enables/disables using indexes.
Example Pop3d.pty file:
rossi.Pop.UserList=d:\\Pop\\popuser.cfg
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 6
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
rossi.Pop.TcpdConfig=d:\\Pop\\poptcpd.cfg
rossi.Pop.LogFile=d:\\Pop\\pop3.log
rossi.Pop.MailFactory=rossi.Pop.UnixMailFactory
rossi.Pop.UseTcpd=false
rossi.Pop.HostName=rossi.com
rossi.Pop.EnableAPOP=true
rossi.Pop.EnableLAST=true
rossi.Pop.EnableTOP=true
rossi.Pop.EnableUIDL=true
rossi.Pop.EnableUSERPASS=true
rossi.Pop.RegName=
rossi.Pop.RegKey=
1.4.2 User list file
The user list file has the name specified in the rossi.Pop.Userlist property
in the server Properties file mentioned above. It has the format of 3
comma delimited fields per line. Each line specifies a user. Blank lines
spaces and tab characters are not allowed.
Each line is of the format:
<username>,<password>,<mailbox directory or file>
Example 1 (using OS2MailFactory on OS/2):
joe,joepass,d:\mail\joe
bob,bobpass,d:\mail\bob
Example 2 (using UnixMailFactory on Unix):
joe,joepass,/var/spool/mail/joe
bob,bobpass,/var/spool/mail/bob
1.4.3 Allowed hosts file
The allowed hosts file has the name specified in the rossi.Pop.TcpdConfig
property in the server Propteries file mentioned above. It has the format
of 3 space delimited fields per line. Each line specifies a block of IP
addresses. Blank lines and extra spaces between fields are not allowed.
Each line has the following format:
<base address of block> <net mask> <comment>
Example:
207.60.177.1 255.255.255.0 rossi.com
192.207.60.1 255.255.255.0 macross.com
1.5 Configuring Server Profile (with Setup program)
-------------------------------------------------------------------------------
Fill in the following information:
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 7
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
User List File: The name of the file to contain user specific
information. This must be a fully specified
file name. This file contains user passwords,
so be sure to set file access permissions
on this file appropriately after running Setup.
Log File Name: Location of the log file. This must be a fully
specified file name. The log file will contain
details of each POP3 transaction including user
passwords. Be sure to set file access permissions
on this file appropriately after running Setup.
Local Host Name: This is the name of the machine running the Server.
ex. mail.foo.com.
Allowed hosts File: This file contains information on which hosts and
networks are allowed to access the server. Use
of this file is enalbed by selecting the Restrict
Access checkbox. Even if you do not want to restrict
access to your server, you must still specifiy a
fully specified file name here.
MailFactory class This specifies the style of mailbox your server is
to user. Enter rossi.Pop.OS2MailFactory for OS/2
style mailboxes, and rossi.Pop.UnixMailFactory for
Unix style mailboxes. If you entered
rossi.Pop.UnixMailFactory, then the MailFactory
option on the Configure menu will become available
after you press the apply button.
Registration Name This is the name of the person or organization
the server is registered to. This is not required
for unregistered operation.
Registration Key This is the registration key associated with the
above registration name. These two items are
compared when the server runs and will grant
access to registered features if they match.
Restrict Access Checking this checkbox will allow the server to
restrict access to the server to only those hosts
and networks specified in the allowed hosts file.
Enable UIDL UIDL is an optional POP3 command. Checking this
box will permit its use. See section 4.0 for
details.
Enable APOP APOP is one of two user authentication mechanisms
available to the server. Checking this box will
permit its use. See section 4.0 for details.
Enable LAST LAST is an optional POP3 command. Checking this
box will permit its use. See section 4.0 for
details.
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 8
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Enable TOP TOP is an optional POP3 command. Checking this
box will permit its use. See section 4.0 for
details.
Enable USER|PASS USER|PASS is one of two user authentication
mechanisms available to the server. Checking
this box will permit its use. See section 4.0
for details.
Apply button Press the apply button when all changes are
completed. THIS DOES NOT SAVE THE SETTINGS,
to do that, select Save Changes off of the
File menu.
1.6 Configuring Users (with Setup program)
-------------------------------------------------------------------------------
To add a new user:
* Fill in the user's name in the Name field.
* Fill in the user's password in the Password field.
* Fill in the user's mailbox location in the mailbox location box.
If you are using the Unix style mail box, this is the location
of the mail spool file. If you are using the OS/2 style mailbox,
this is the name of the directory where mail is stored.
* Press the Add button.
* Select Save Changes off of the file menu to save these changes.
To modify a user:
* Select the user to be modified in the User Name list box.
* Change the information in the Name, Password, and/or Mailbox Location
fields.
* Press the Modify button.
* Select Save Changes off of the file menu to save these changes.
To delete a user:
* Select the user to be modified in the User Name list box.
* Press the Delete button.
* Select Save Changes off of the file menu to save these changes.
1.7 Configuring Allowed Hosts (with Setup program)
-------------------------------------------------------------------------------
To add an allowed host or network:
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 9
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
* Fill in the IP address of the host or a host on the network
in the Network field.
* Fill in the Net Mask for this host or network. The Net Mask for
a single host is 255.255.255.255. The Net Mask for a network
can be obtained from the network's administrator.
* Fill in a comment or name for this network in the Comment field.
* Press the Add button.
* Select Save Changes off of the file menu to save these changes.
To modify an allowed host or network:
* Select the host/network to be modified in the Allowed Hosts list box.
* Change the information in the Network, Net Mask, and/or Comment
fields.
* Press the Modify button.
* Select Save Changes off of the file menu to save these changes.
To delete an allowed host or network:
* Select the user to be modified in the User Name list box.
* Press the Delete button.
* Select Save Changes off of the file menu to save these changes.
2.0 Mailboxes
-------------------------------------------------------------------------------
The server currently supports 2 mailbox styles. The first is the standard
unix style mailbox in which all the messages for a particular user are in
one file. The second, which is commonly used on OS/2 systems, contains each
message in a separate file.
The Java classes that implement these mailbox styles are named
rossi.Pop.OS2MailFactory and rossi.Pop.UnixMailFactory. During installation
one of these must be selected. The OS2MailFactory implements the one message
per file system, and the UnixMailFactory implements the one file per user
system.
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 10
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Note that the OS2MailFactory can be used on Unix or other platforms, and the
UnixMailFactory can be used on OS/2 or other platforms. The choice of which
to use can be based upon how mail arrives in your system.
2.1 Sendmail and local delivery agents
-------------------------------------------------------------------------------
Most systems receive mail using the sendmail program. Sendmail is highly
configurable, and uses a program known as a local delivery agent to store
mail locally.
To find out (or change) what local delivery agent your sendmail is using,
look in the sendmail configuration file (named sendmail.cf) and look for
the line that starts with Mlocal. This is where the local delivery agent
is specified.
3.0 Notes for OS/2 users
-------------------------------------------------------------------------------
* The Java runtime that ships in the box with Warp version 4.0 is NOT
current enough to run this software. You must install version 1.0.2
or higher. The OS/2 Java runtime is available from:
ftp://ncc.hursley.ibm.com/pub/java/os2/102/runtime.exe
ftp://ftp.software.ibm.com/software/java/os2/102/runtime.exe
* Unix style mailboxes can be used on FAT, and will result in better
disk utilization. Be sure to change the lock file name extention
in Setup to be 3 character or less.
* OS/2 sytle mailboxes can be used on FAT, but will perform **MUCH** better
on HPFS.
* Recommended configuration:
Use OS/2 sytle mailboxes on HPFS.
Use the QYPMAIL local delivery agent with sendmail. QYPMAIL is included
in this archive for OS/2 users, and is also available on ftp-os2.cdrom.com.
* Using the OS/2 style mailboxes with a local delivery agent other than
QYPMAIL may produce erroneous results with the optional LAST and UIDL
commands. The OS2MailFactory class that implements the OS/2 sytle mailbox
makes some assumptions about the mail file names. These assumptions are
valid when using QYPMAIL, but may not be for other local delivery agents.
The assuptions are:
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 11
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
1.) The mail filename is unique through out the system for all time,
and is thus suitible to be used as a unique identifier for the message.
2.) The mail filename is in 8.3 format, and the extension is constant.
OS2MailFactory denotes which files have been read by changing the
extension on the mail files when the optional LAST command is
enabled.
If problems are encountered using another local delivery agent, you may
disable the UIDL and/or LAST commands.
3.1 Notes for Unix users
-------------------------------------------------------------------------------
* Server must run as root in order to have access to TCP/IP port 110.
* The UnixMailFactory class is known to interoperate with the procmail and
mail.local local delivery agents, and user programs like PINE. Enabling
the UseIndex option can produce great performance gains, however may
not work well if users read mail through a means other than POP3 as well.
* Configuration may be done by hand editing the various configuration files,
or by using the GUI tool.
* Change the permissions on the User List and Log files after running
Setup for the first time. Make them so that they are read/writable
by root only. These files contain sensitive information and could
pose a security risk if left world readable.
3.2 Operation on other platforms
-------------------------------------------------------------------------------
* The server "should" run on any platform that supports Java and can produce
one of the 2 supporte mailbox styles. Not all platforms have been tested,
however.
* The server has been developed on Linux and OS/2.
* The server will run on Windows NT, but something has to supply the mailboxes.
* Support for other mailbox styles may be added in the future.
4.0 Optional POP3 commands
-------------------------------------------------------------------------------
All of the optional POP3 commands can be enabled or disabled. This section
will guide you through deciding which to enable or disable.
APOP
APOP allows a user to log into the server without sending his/her password
in the clear. APOP was introduced to POP3 in RFC1460. RFC1460, RFC1725 and
RFC1939 recommend that either APOP or the USER and PASS commands be used
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 12
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
to log users into the server but not both. It is not a protocol violation
Disabling APOP and USER/PASS has the effect of preventing anyone from logging
in. At least one of the two must be enabled for useful operation.
Many POP3 clients currently do not support APOP.
The APOP facility uses the MD5 algorithm from RSA Data Security, Inc.
USER/PASS
The USER and PASS commands support the older style of logging into a POP3
server. This mechanism requires the client to send a password over the
network in the clear. This has possible security implications.
LAST
The LAST command was dropped from the POP3 specification as of RFC1725. In
the earlier RFCs, this command was required. Because of this ambiguity, the
command is optional in this implementation.
TOP and UIDL
The TOP command is inefficent at best. It is sometimes used by client programs
to determine which (if any) messages it has already read. The UIDL command
was added in RFC1725 for specifically this purpose. UIDL is more efficent
than TOP.
Disabling UIDL, TOP and LAST has the effect of making it difficult for a
client to determine if messages held on the server have been previously read
or not. These could be disabled to encourage users to delete messages off
the server after they have been retrived.
5.0 Licence
-------------------------------------------------------------------------------
This software is "shareware". This means that you are permitted to
freely redistrbute the software provide that:
1.) You distribute the complete package, including all documentation.
2.) You may not modifiy the package in any way.
3.) You may not distribute a registration key with the package.
Without a registration key, the server will support 5 users. If this
is sufficent to your needs, you may use the software at no charge.
Technical support will not be provided for unregistered software.
If you need more than 5 users, then you must register. Upon registration
you will be given a registration key. This key will enable the software
to support more users. You may not use this key on more than one computer
at a time, or disclose the key to any third party.
For information on how to register, see the ORDER.FRM file.
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 13
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
5.1 Support
-------------------------------------------------------------------------------
For technical support, fill out the following form and then email it to
support@rossi.com, or fax it to (508) 520-6996. Most of the requested
information can be found in the Setup utility, or by running
java rossi.Pop.BuildVer.
Your Name ______________________
Company Name ______________________
Address ______________________
City/State ______________________
Country/ZIP ______________________
Telephone
with area or
country code ______________________
Fax ______________________
Email ______________________
J-POP Server Version ______________________
Registration Name ______________________
Registration Key ______________________
MailFactory Used ______________________
Build Number ______________________
Build Date/Time ______________________
Java Version ______________________
Java Class Version ______________________
Java Vendor ______________________
Operating System ______________________
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
Page 14
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
5.3 Disclaimer
-------------------------------------------------------------------------------
Rossi Engineering shall not be held responsible for incidental or consequential
damages arising from the use of this software. This software is not
warrantied, either expessed or implied, to be suitable for any paritcular
purpose. Rossi Engineering shall not be held responsible for loss of data,
productivity, or network bandwidth resulting from the use of this software.
5.4 Copyright
-------------------------------------------------------------------------------
Unless otherwise stated, all software and documentation is Copyright (C) 1997
Rossi Engineering, Franklin MA.
This package contains the MD5 algorithm, which is Copyright (C) 1991, 1992
RSA Data Security.
Sendmail is Copyright (C) 1983 The Regents of the University of California,
and Copyright (C) 1983 Eric P. Allman.
Java and all Java-based marks are trademarks or registered trademarks
of Sun Microsystems, Inc. in the United States and other countries.
Rossi Engineering is independent of Sun Microsystems, Inc.
____ _ ___ _ _ ___ ___ ___ ___ ____
|___| |_______| |_| |___| |___| |_____| |___| |_____| |___|
