IAn Webmail	(c) 2004 Adrian Irimescu (adrian_irimescu@yahoo.com)
don't forget to write...

Please read the entire file !

-----------------------------
WARNING ! WARNING ! WARNING !
-----------------------------

    Please read the following carefully !
    
    The scripts used in this program only perform a session check after user has logged in.
    Passwords and user names are sent via POST method, and are not encrypted before sending. 
    These are high security risks ! I am not a security expert but you might want to run this
    program over secure http (https). My advice is not to use it in a production environment
    (if you do, you do it at your own risks !). 
    You should also protect the *.inc.php files. Set the proper permissions with the help of
    Apache configuration files. There are various ways to exploit the program via editing the 
    configuration files. Go figure !
    When using the preferences make sure you give the proper permission for the database user !
    TAKE ANY SECURITY PRECAUTION YOU CONSIDER, AND THOSE MAY INCLUDE, BUT ARE NOT LIMITED TO,
    THOSE ABOVE !!! YOU HAVE BEEN WARNED !
    See the Q&A section.
    

------------------------------------
INSTALLATION - Please read carefully
------------------------------------

    What you need to install IAn Webmail:
    
     - A Web Server - mandatory ! ( I use Apache 2.0.48, but it should work with Apache 1.3 and I
        think other web servers would do just fine )    
     - PHP - mandatory ! ( I use PHP 4.3.4, but it should work with any PHP 4.x )
     - MySQL - optional, but highly recommended ( if you use the preferences ). I personally use
        version 4.0.8, but almost any version will do.
     - a server running an MTA of some sort and the IMAP protocol ( mandatory :) ). I personally use
       sendmail on my server.
	
    What you need to run IAn Webmail:
	
     - Any browser with cookies ENABLED should do. It was tested with lynx, links, Mozilla 1.6, 
     Internet Explorer 5, Internet Explorer 6, Konqueror 3.2.0 and it behaved really FINE.

    I assume you have some basic Linux / Apache / MySQL knowledge, so I won't cover that.
    
    Now, you got the zip archive. Go to your document root (mine is "/var/www/html/")
    and make a new folder (mkdir ...  name it as you like). Let's call this the installation folder.
    Unpack the zip archive into the instalation folder then open the file config.inc.php
    with your favourite text editor. There are some options you should change and although
    sometimes it's possible for the application to work with the defaults, that is certainly
    NOT recommended !
    
    We'll take them one at a time: 
    
    
    IMAP server options
    -------------------
    
    $CONFIG["IMAP_SERVER_NAME"] is defaulted to "localhost". You might want to change that to your 
    actual IMAP server, something like "imap.company.com"
    
    $CONFIG["IMAP_SERVER_PORT"] is defaulted to 143, change it if your IMAP server runs on a different
    port (but probably it's not the case)
    
    $CONFIG["IMAP_SERVER_OPTIONS"] is defaulted to "notls". You should leave it that way, unless you know
    what you are doing.
    
    $imap_srv - if you know what you are doing and you really need to change it, go ahead.

    
    MAIL related options
    --------------------
    
    $CONFIG["MAIL_DOMAIN"] defaults to "localhost". Change this to the domain name you'll be using, for
    example "mail.server.net"
        
    $CONFIG["MAIL_PATH"] defaults to "", which means "user's home directory". You should check and set the mail
    directory properly, as sometimes mail is delivered directly to the user's home directory. Do not forget to
    add a slash ( / ) at the end of the path, e.g. "mail/"
    
    $CONFIG["MAIL_LIST_PATTERN"] is defaulted to "%". I think you should leave that enabled, or you'll be flooded with 
    all subdirectories contents starting from your home directory
    
    $mail_list - don't need to change that, but if you know what you are doing, and you really need to change it,
    go ahead.
    
    
    MySQL server options
    --------------------
    
    $CONFIG["DBF_USE_SERVER"] defaults to "no". Change this to "yes" if you are going to use preferences. 
    PLEASE NOTE: do not set this to "yes" if you do not have a database server. Doing so will result in using
    all the default preferences listed in the `config.inc.php' file for all users or worse, those will be set
    to blank ("") and used as such.

    $CONFIG["DBF_SERVER_NAME"] defaults to "localhost". If the server running MySQL is located elsewhere, change
    this setting to the name of the actual server, e.g. "mysql.server.com"
    
    $CONFIG["DBF_SERVER_PORT"] defaults to "". If you know your MySQL server runs on another port, change this.

    $CONFIG["DBF_SERVER_OPTIONS"] defaults to "". If you want to pass options to your MySQL server, change this
    to the actual options.
    
    $CONFIG["DBF_SERVER_USER"] defaults to "". Change this to the actual user you'll be using to connect to the
    MySQL server.
    
    $CONFIG["DBF_SERVER_PASS"] defaults to "". You should change this.
    
    $CONFIG["DBF_DATABASE"] defaults to "test". Change this to the name of database you'll be using.
    
    $CONFIG["DBF_TABLE"] defaults to "preferences". You may change this to the name of your choice.
    
    $dbf_srv - don't need to change that, but if you know what you are doing, and you really need to change it,
    go ahead.
    
    
    Default user preferences
    ------------------------ 
    
    ( * marks the preferences that will be read regardless of the  $CONFIG["DBF_USE_SERVER"] setting ! )    
    
    $PREF["FULL_NAME"] defaults to "". Don't change it, unless you want all users to have the same full name.
    
*   $PREF["EXPUNGE_NOW"] defaults to "no". This means that messages will not be purged after you delete them.
			 WARNING ! This is one of the options that will be read by the program regardless of the
			 $CONFIG["DBF_USE_SERVER"] setting. Use this with care, as it can wipe your deleted mails,
			 making them unrecoverable, no questions asked.

    $PREF["SIGNATURE"] defaults to "". You should leave this unchanged. When using the preferences, the signature
		       is saved in a database, never read from here.

*   $PREF["SAVE_SENT"] defaults to "yes". This allows you to control the behaviour of the mail system when sending
		       messages. "yes" means the message will be saved in a mailbox of your choice.

*   $PREF["SAVE_FOLDER"] defaults to "sent-mail". This is the default folder to save messages in after sending.
 
*   $PREF["DRAFT_FOLDER"] defaults to "drafts". This is the default folder to save drafts in.
    
*   $PREF["VIEW_TEXT_ATTACH"] defaults to "no". Set to "yes" if you want the text attachments to be embedded in 
			      the message body. This may cause text files to be embedded in the message body 
			      when forwarding a message.

*   $PREF["SORT_BY"] defaults to "SORTARRIVAL". This is the messages sort criteria. Note that you can specify only one.
		    Available options: "SORTDATE","SORTARRIVAL","SORTFROM","SORTSUBJECT","SORTTO","SORTCC","SORTSIZE".
		    I think these are self-explanatory.

*   $PREF["SORT_ORDER"] defaults to 1. This specifies the sort order: 1 "for reversed sorting", 0 for "normal" sorting

*   $PREF["PAGE_SIZE"] defaults to 10. This specifies the number of messages to view at a time.


    Administrative options
    ----------------------
    
    $CONFIG["ADMIN_TEXT"] defaults to "". This is the text to display when the user logs in. NOT YET IMPLEMENTED.
    
    $CONFIG["ADMIN_DISPLAY_TEXT"] defaults to "no". Change if you want the $CONFIG["ADMIN_TEXT"] displayed when 
    user logs in. NOT YET IMPLEMENTED.
    
    $CONFIG["ADMIN_MIN_PAGE_SIZE"] defaults to 3. This is the minimum allowed $PREF["PAGE_SIZE"] setting.

    $CONFIG["ADMIN_MAX_PAGE_SIZE"] defaults to 20. This is the maximum allowed $PREF["PAGE_SIZE"] setting.

    $CONFIG["ADMIN_MAX_ATTACH"] defaults to 3. This is the maximum number of allowed attachments per message.
    
    $CONFIG["ADMIN_TIMEOUT"] defaults to 0. This is the session expiry time. NOT YET IMPLEMENTED.
    
    $CONFIG["ADMIN_IMAGE_DIR"] defaults to "images/". This will be implemented in a future version.
    

    This should take care of the settings. Now for the next step:

-----------------------
Setting up the database
-----------------------
        
    The database you specify as $DBF_DATABASE should exist. The table is created by the "configure.php"
    script, so don't bother too much. If you have done everything until here, you should point a browser to 
    
	http://your_server/install_folder/configure.php
	
    Follow the instructions there. ( Enter the name and password of a user with administrative privileges ) 
    If your MySQL server is properly configured and you have specified the correct settings for $DBF_ entries
    you should get a message stating that the table was created. 

    If you get an error stating that:
	- it can't connect to the server: check if you have specified a valid user and that the server is up
	- it is unable to select the database: check if it exists, if not, then manually CREATE IT.
	- it is unable to create the table: check if user has permissions to create tables.
    
    If it still fails, you have to create the table manually. Open the "configure.php" and look for the line
    containing "$sql" (without quotes). Copy that down replacing $PREF[] with the actual values. DON'T COPY
    the quotes ( " ) ! That's the command you should give to MySQL.

    Now give the right permissions on the freshly created table to the user specified in $DBF_SERVER_USER. You
    should give at least: SELECT, INSERT, UPDATE permissions on the table you've just created, otherwise errors
    will occur when using the preferences. And don't forget to set $DBF_USE_SERVER to "yes" in order for the
    preferences to work.
    
    Once you have created the table, you should DELETE (yes, DELETE) the "configure.php" file or at least RENAME
    it (yes, RENAME) to something like "configure.inc.php". Remember to protect the "*.inc.php" files !!!

    Sorry, but that's all I could do for now.


-------
All set
-------
    
    This should be the final test: point your browser to http://your_server/install_folder/
    A login screen should appear. Enter the user name and password and click "Login". If the
    user exists and the password is valid, you should be able to read the mail. Test the installation
    by composing a message and sending it to yourself (or to any mail address you own). If you can
    read it, it works.

    If login fails: 
	- check your user name and password
	- check if cookies are enabled
	- check the "config.inc.php" to see if the name, port and options of the server are correct.
	
    Note that you should make sure the files in the installation folder are owned by root, and have 
    read (and ONLY read) permission from others. 

    	PLEASE TAKE ALL THE SECURITY PRECAUTIONS YOU CONSIDER TO PROTECT YOUR SERVER !
	    	DO NOT RUN THIS APPLICATION IN A PRODUCTION ENVIRONMENT !
	
-----
Q & A
-----

    Q1. What security precautions should I take ?
    A1. Whatever you consider. I am no security expert, and as my installation of IAn Webmail runs
	only on a small, closed intranet, I have only protected the "*.inc.php" files. DON'T TAKE
	ME FOR A MODEL, FOR WHAT I HAVE DONE IS NOT GOOD ENOUGH FOR SECURITY !!!
	
    Q2. Your security recommendations are crap !
    A2. As I have said, I am no security expert, can't stress that enough. Read Those Friendly Manuals
	or ask somebody who knows better. If you know better, tell me, too.
	
    Q3. I have found a bug. Now what ?
    A3. You can mail me ( adrian_irimescu@yahoo.com ) and tell me about it: when, what were you doing, 
	and how did it occur. A copy of your "config.inc.php" would help.
	
    Q4. Your program sucks.
    A4. Delete it.
    
    Q5. I have a suggestion / comment / complaint.
    A5. Mail it to adrian_irimescu@yahoo.com. If you have a complaint, read the COPYING file before mailing me.
    
    Q6. I want to use your code in my application. May I ?
    A6. Yes, providing you also distribute the original code with your application. Read the COPYING file, and
	please let me know if you use my code. Thanks.

    Q7. I like your program, but it lacks ...
    A7. See Q5 & A5.
    
    Q8. What does IAn stand for ?
    A8. That's easy: [I]rimescu [A]dria[n].
    
    Q9. What languages are supported ?
    A9. Currently only English is supported. Sorry. But I am working on it.
    
---EOF---