TRex version 2.1.2

User's Guide

SECURITY

We are not security experts, but we're try to make this as secure as possible. (remember that security is not a product, is a process as Bruce Schneier and other pointed out. I make no guarantee how crack proof this program is. If you have any suggestions on how to increase security, or notice any flaws, please let us know.

All information sent to or by TRex can be seen by anyone who cares enough to look really hard. There is no encryption done by this program when sending or receiving information, including any passwords sent to the server (more security fetures will be added as this program evolves). Passwords are never sent in the html, so it is very hard to accidentally save a page with a password in it.

The user's TRex password is stored encrypted on the server in the user's pass file This is a very minor security precaution, since if someone can read the pass file, they can surely read any email stored in that directory as well. However, if the user directories are only readable and writable by the user name that the web server runs on, no one but the web server should be able to read the user's pass file, or any of the user's info. The user directories should also not be web accessible.

Each time a user logs in, a session ID is created and is stored in the user's sessID file. A new login will overwrite the old sessID file and the old ID will not work. The sessID file is removed on a logout. Every script that accesses a user's area first checks that a proper user name and session ID is given. This info is passed from script to script through forms. Each time the session ID is checked, a time check is done to see if the session is longer than the $time_til_expire variable specified in Common.pm. If the session has lasted longer than the number of seconds specified, the session ID will not work.

The user_info.db file stores all user inputted information except for user name and password. This includes pop server and password information. This information can be misused and should be protected from prying eyes.

User names and passwords are limited to certain characters but most other stuff is pretty liberal. We're really not sure what sort of input would screw up the server, but who knows. I think that server side includes are not generally run for script generated html, which, if true, should greatly limit the damage users can do.

Protecting from unwanted users: If you do not want anyone to be able to open an account without permission, there are two options. What we did is to put the new_acocunt.cgi script in a new directory which is password protected. The login.cgi script needs to point to this new directory. Directories can be made password protected by placing a .htaccess in the directory. New users will need to know the directory password to open a account. Once a user has the password, they can set up as many accounts as they wish.
The other option, which is more secure than the first, is to manually run new_account.cgi for each new user. This gives the site operator total control over new account.

TEST ACCOUNT

If the user name given is althepal, then no changes can be made to the folders file for this account except for marking messages as read. This was done to allow people to view TRex in operation without installing it and without creating an account. The name "althepal" is hardcoded in each of the scripts.

DIRECTORY SETUP

When you unpack your TRex tarbal (TRex-x.y.z.tar.gz) a bunch of directories are created, adn the each one has it reasons to be there (believe me !!). So pay attention and enjoy TRex !!

Documentation Directory : Inside it there's all the documentation provided with TRex in a few languages (only english and spanish at this time). By the way, you already have found it if you are reading this !!
You must copy the whole directory to the corresponding one that point where indicated by the $man_URL variable inside Common.pm file (if $man_URL points to the URL http://localhost/htdocs/TRex/man, then locate the directory that corresponds to it)

Image Directory : All language dependent images are here. Copy (or move) the whole directory to the corresponding one that points where indicated by the $img_URL variable inside Common.pm file.

Program Directory : Used to hold all perl programs. Any file ending in cgi or pm need to be placed in here. This directory needs web access and needs to be executable through the web. Depending on your setup, you may need to place it under your cgi-bin directory.
You must copy the whole directory to the corresponding one that point where indicated by the $dir_URL variable inside Common.pm file

Libraries directory : Inside your program directory there is a lib one that holds all the perl modules (pm files) that conform the TRex programming class. Make an 'TRex' directory in your site_perl directory inside the perl distribution (usually inside /usr/lib/perl5 or c:\perl\lib) and copy (or move) to it all the files inside the lib directory.

Mail Users Directory : Used to hold all users data THERE SHOULD BE NO WEB ACCESS TO THESE DIRECTORIES OR ANYONE CAN LOOK AT ANYONE'S MAIL. The only files you need in this directory is folders.start and 999999. Each user gets one directory with same name as the user name under this directory. The structure necessary for a new user is created in the new user process.

See detailed directory structure and file descriptions for more information.

Skins Directory : All images that conform the TRex skin are here. You can create new skins by generating new directories inside this one, with the name of your new skin, and generating 24x24 pixels images to for the skin. Copy (or move) the whole directory to the corresponding one that points where indicated by the $skin_URL variable inside Common.pm file.

PROGRAM CUSTOMIZATION

The only file that needs to be altered to get these programs to work is Common.pm.
There are five variables that should be changed to customize the script to a particular server.

o File location
Common.pm makes mention of the user directory and URLs for the program directory and the image directory. The user directory variable should be a file path on your system, but the references to the URLs should be in form of "http://your.domain/directory". Change the two URLs and one directory to the ones used on your system.

the following variables in Common.pm need to be set for your environment :
$dir_URL --- set to the url that the perl code is in (program directory in the distribution)
$db_path --- set to the directory path that the user files are in
$img_URL --- set to the url that the images are in (images directory in the distribution)
$man_URL --- set to the manual pages location, that must be web accessed (doc directory in the distribution)
$skin_URL --- set to the skin images location that must be web accessed (skins directory in the distribution)
$skin --- set to the skin to be used (this is one directory name of those in $skin_URL)
$lang --- Language preferred (at this time only English and Spanish are supported)
@reserved_files --- A list of filenames no to be shown when displaying the file list in the upload area. Actually its components are '.' and '..', but if you are using a platform that uses other ones (such as MacOS do it) the you should change it.

o Session time out
The number of seconds until a session expires can be set with the $time_til_expire variable. I have mine set to a high number, so I never really time out.

o Server time
$time_off_from_NY should be set to the number of seconds behind New York time that the server running this script is on. Each user can then set their local time in the user_info section. Currently, this program can only handle those users in the continental US, who observe daylight savings time. It would be a fairly trivial matter to adjust the program to fit more areas (is what we're trying to do !!).

Note for international users: This program was written mainly for people in the continental US. For this reason, users are asked to enter their time zone, but are only given 4 choices. To workaround this, set $time_off_from_NY to 0 and set the user to Eastern Time. Then the user will be on the same time as the server.

USER SETUP

Setting up an account is straight forward and entirely done by the user. First a user selects a user name and password using the new_accounts.cgi script, which can be accessed through the login page. The new_account.cgi script adds 2 directories for each user, a user directory named after the user and an uploads area beneath this directory. Inside the user directory should be the following files : folders, pass, address_book. To see detailed information on these files, click the following link.
See more information on user files

Once the user has an account, the user can login in through the login page. Once in the webmail program, the user should add server and other information which will be used to receive and send mail. This info added by clicking on the user_info button at the top of the screen. If everything is working properly the user should be able to access mail.

LOGGING

Logging is based on Log::Log4perl module, and basic logging capabilities (and configuration files) are derived from it. More information can be found at CPAN search site

The default TRex configuration reads the logging configuration file as indicated by the $logConfigFile scalar variable in each configuration script (default value /etc/TRex/log4perl.conf), which in turns reads the shipped (default) log config file:

log4perl.rootLogger=INFO, ErrorLog, AccessLog, DebugLog
log4perl.TRex.Storage.EMail=DEBUG, ErrorLog, AccessLog, DebugLog

log4perl.appender.DebugLog=Log::Dispatch::File           
log4perl.appender.DebugLog.filename=/var/log/TRex/debug.log       
log4perl.appender.DebugLog.mode=append
log4perl.appender.DebugLog.min_level=debug
log4perl.appender.DebugLog.max_level=debug
log4perl.appender.DebugLog.layout=PatternLayout           
log4perl.appender.DebugLog.layout.ConversionPattern=[%d] %L %c - %m (%M)%n 

log4perl.appender.AccessLog=Log::Dispatch::File
log4perl.appender.AccessLog.filename=/var/log/TRex/access.log
log4perl.appender.AccessLog.mode=append
log4perl.appender.AccessLog.min_level=info
log4perl.appender.AccessLog.max_level=notice
log4perl.appender.AccessLog.layout=PatternLayout
log4perl.appender.AccessLog.layout.ConversionPattern=[%d] %m (%M)%n

log4perl.appender.ErrorLog=Log::Dispatch::File
log4perl.appender.ErrorLog.filename=/var/log/TRex/error.log
log4perl.appender.ErrorLog.mode=append
log4perl.appender.ErrorLog.min_level=warning
log4perl.appender.ErrorLog.layout=PatternLayout
log4perl.appender.ErrorLog.layout.ConversionPattern=[%d] %m (%M)%n

This one divides the logging arena y three different logs :

debug.log : debugging log file, inactive by default, catches the DEBUG level only
access.log : access related logging, mainly to verify the results, and correct access, to each resource. Traps the INFO and NOTICE error levels
error.log: error colector, that tracks all anomalies in TRex, given by levels WARNING to FATAL

One point to notice is that when an error is logged it correspond to the underlying infrastructure (operating system) and not to logic derived from the module itself. i.e. if a file can't be locked it is logged in the error file and the access log will also store the failed attempt but if a folder needs to be renamed and it can't be found, then it's only a failed attempt (no underlying structure failure).

Of course this default config file, and so the file locations and other logging features, can be changed to fit into your installation.

SCREEN SHOTS

These screen shots are reduced by a factor of .75. Everything is actually much clearer.

Main Screen
Compose Message
Address Book
Folders
Personal Disk Space
Search Screen

This is the main amail screen.
The top tine is the table of contents, or TOC.cgi.
The orange box on the left, with the Go, Move, and Delete buttons is the function.cgi script. The functions work on the window to the right, if one or more messages are selected, or the message on the bottom otherwise.
The large window immediately under the table of contents contains brief information on all email messages in the folder being shown.
The bottom half of the window is used to read messages.
main amail page

This is the screen used to compose a message. Attachments are added using the form on the bottom. The link to the address book allows users to insert email addresses from their address book.
amail compose screen

This is the address book. The contacts are shown on the top, the groups on the bottom.

This is the folder information for the user.

This screen shows the users files that have been uploaded to the server.

This is the search screen.