=============================================================================
POPPER (Version 1.4b7, 16. Feb. 2001)
=============================================================================

POPPER (or however it will be called :-) is a free web mail-reader written
with PHP 4. It's (more or less) MIME conformant.

=============================================================================
LICENSE
=============================================================================

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program 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.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Copyright (C) 21. November 2000 by Jean-Pierre Bergamin

=============================================================================
CONTACT
=============================================================================
If you have any questions, improvements, tips or anything else, don't
hesitate to contact me: 

Developers are always welcome to join the program. I set up a sourceforge
account with everything you need (CVS, ftp, mailinglists etc...)
at: http://sourceforge.net/projects/popper


E-Mail:				roytoo@roytoo.org
						james@ractive.ch (alternate contact)
Homepage:			http://www.ractive.ch
POPPER-Homepage:	http://popper.ractive.ch
POPPER-forum:		http://forum.ractive.ch
Mailinglist:		http://www.ractive.ch/gpl/mailinglist.html
Sourceforge:		http://sourceforge.net/projects/popper

=============================================================================
INTRODUCTION
=============================================================================
Popper is a web based mail-client which allows you to read mails from
different POP3 accounts.
Accessing a POP3 account from different computers is not always
easy. Web-based mail solutions like hotmail.com etc. are an option, but
not the best solution.

There are already PHP web interfaces to read POP3 mails, but most of them
require that PHP is compiled with the --with-imap options which is mostly not
the case.

Popper tries to fill this gap. It gives you the possibility to read and write
your mails from (almost ;-) any web-browser from any place.
It's MIME conformant. This means that you also can get and send attachments.

What browsers are supported?
============================
Popper is 100% Java(-script) FREE which eliminates problems on different
platforms and browsers (yes, you can even use lynx ;-)!

CSS is used heavily. Therefore browsers with a good CSS support are
recommended. This does not mean that popper is tuned to a certain browser.
Virtually every browser could be used.

Netscape 4.x should be avoided because the lacking CSS support. The result
looks awful :-(
Best reults are achieved with Internet Explorer 5.x, Mozilla and Netscape 6
(yuck!).
Opera 5.x has a small bug that doesn't stretch textareas to the full width.
Therefore it looks a bit odd, but does not cause any problems :-(

=============================================================================
INSTALLATION
=============================================================================
Popper needs a system running a webserver with PHP 4 support (NO, PHP3 won't
work) and a MySQL database system (other database systems may be supported
in the future).

I recommend the following configuration:

- Linux (your favorite brand :-)
- Apache webserver (www.apache.org)
- PHP 4.0.0 or newer (www.php.net)
- MySQL (www.mysql.com)
  (with some work you could port is to postgres or other DBMS)

All the above products are freely available!


1. Create a MySQL database (i.e. called popper) or let your provider create
   one for you.
   See the section MySQL below for further instructions.

2. Untar the file popper.tar.gz to a location under your webserver's
   document-root (i.e. /usr/local/httpd/htdocs/):
   
   tar -xzvf popper.tar.gz
   
   A new directory popper will be created. You can rename the directory
   to any name you want (i.e. mail):
   
   mv popper mail

3. Create the database structure with

   mysql popper --user=dbusername -p < popper.mysql

   Instead of popper, use the correct name of the database.

4. IMPORTANT!
   MOVE the file popper.inc.php to the directory above the document-root
   (i.e. /usr/local/httpd/). This gives you maximum security that the
   connection details are never revealed to anyone.
   
   This file contains the database connection information.
   Change the values according to your settings.
   
   MAKE SURE THAT popper.inc.php IS NOT IN THE DOCUMENT ROOT ANY MORE!
   
   If you don't have access to the directory above your document-root,
   put it in the document-root itself and change line 74
   of class.db_tool.inc.php to:
   
   		require("$doc_root/$this->db_data_inc");

5. Edit config.inc.php and change the settings to your needs.

6. Create a subdirectory called tmp (you must probably be root for this):
   mkdir tmp
   chmod 777 tmp

7. You may want to change the look and feel by changing the attributes
   in the stylesheet style.css

8. It should work now :-)

=============================================================================
UPDATE FROM PREVIOUS VERSIONS
=============================================================================

Untar the archive to the same directory.

Edit config.inc.php and set it to your needs. (New options in there)
(You may want to copy config.inc.php to i.e. config.inc.php.tmp before
untarring, to compare your settings)

Create a sub-directory in the directory popper, called tmp.
Make it accessible for all:
chmod 777 tmp


No updates to the database structure.


Update of PHP files:

If you are using V1.4, V1.41 or V1.41-p1:
Apply the class.pop3.inc.php-V1_41-r2-patch.diff to 
class.pop3.inc.php from your respective popper source:
patch class.pop3.inc.php class.pop3.inc.php.php-V1_41-r2-patch.diff

If you are using earlier versions:
Download the popper-1.41-r2.tar.gz package, then extract and copy it to 
the popper (or whatever you call it) folder on your webserver.  If you 
have already performed the mysql updates, everything should work just fine.




=============================================================================
MySQL
=============================================================================
To create a new database you need root privileges. Ask your system
administrator for help.

Some MySQL clients don't accept the syntax:
   mysql popper [commands here]
try this instead:
   mysql --database=popper [commands here]


As root:
========
1. Start the mysql console by typing "mysql -p". Enter the password to
   log in

2. Create the database with:

   create database popper;

3. Change the priviliges for the new database to a normal user account:

   GRANT insert, update, select, delete, alter, drop, create ON popper.*
   TO dbusername@localhost IDENTIFIED BY 'theuserpassword';

As normal user:
===============
1. Create the datbase structure:

   mysql popper --user=dbusername -p < popper.mysql 
      
2. Change the file popper.inc.php located above the documet root to 
   the settings you made.
   It should look something like this then:
	  $host = "localhost";       // Unlikely to be another host than localhost
	  $user = "dbusername"       // Or the user-name given in step 3
	  $pass = "theuserpassword"; // Or the password given in step 3
	  $dbname = "popper";        // Or the name given in step 2
	  
   Avoid using your root account to access the database!

=============================================================================
SECURITY ISSUES
=============================================================================
Web applications are not known to be secure!
I tried to make popper as secure as possible. But I'm sure someone will find
a hole somewhere. Please report ANY security-considerations to
roytoo@roytoo.org (alternate contact: james@ractive.ch) or post is to the 
mailinglist.

Some thoughts about security:
- ALL passwords of ALL POP-servers of ALL users are stored in plain-text
  in the database! I thought about encrypting them, but since it must
  be decrypted again to send it to the POP-server an attacker that knows
  the passwords wouldn't find it difficult to decrypt it, since he knows
  the way to do it.
  Another reason is that the POP password is sent to the POP-server in
  plain text any way.
  Do you have better ideas how to make this more secure?
  
- NEVER use your root MySQL account to access the database. If (for some
  reason) an attacker gets this password, he has FULL ACCESS to ALL
  of your databases!
  
- The reason why popper.inc.php is put above the document-root is that
  the web-server cannot (should not be able to) access it and reveal the
  access information of the database.
  But don't count on it ;-)

- If a user views a multipart/related mail with inbound objects (i.e.
  pictures) temporary files are created in the sub-directory tmp.
  These files are deleted after the user logs off or when he opens a new
  mail.
  If the user just closes the browser without logging off, the files stay
  there. Since everone has access to the tmp directory, the content of these
  tmp-files are open to everyone.
  Any ideas how to resolve that problem?

=============================================================================
BUGS
=============================================================================
There are probably still a lot of bugs in this program.     
Report them to roytoo@roytoo.org (alternate contact: james@ractive.ch) with 
a detailed description of the problem, including your PHP version and the 
used webserver.  Put them also in the bug-tracking system at sourceforge.net:
http://sourceforge.net/bugs/?func=addbug&group_id=15135

You may want to create a file phpinfo.php with this content:
<?php phpinfo(); ?>
Call this file with your webbrowser (i.e. http://somewhere.com/phpinfo.php)
This helps to gather information about your system.

Subscribe yourself to the mailinglist to discuss things about popper:
http://www.ractive.ch/gpl/mailinglist.html

=============================================================================
DEVELOPERS
=============================================================================
You are welcome to join the developement of popper. You find everyting you
need on sourceforge (including CVS access etc.):
http://sourceforge.net/projects/popper/

Visit http://popper.sourceforge.net for more infomation (under construction)

Contact me if you need more information: roytoo@roytoo.org (alternate 
contact: james@ractive.ch)

=============================================================================

                    Einmal gepoppt - nie mehr gestoppt ;-)

=============================================================================
