TRex version 2.1.2

User's Guide

DIRECTORY STRUCTURE AND FILE DESCRIPTIONS

User_area directory
folders.start file
999999 file
User_name directory
www directory
images directory
Mail_program directory
Perl_lib directory

User_area directory : All user data is stored here. There should be no web access to this area. Permissions of all files under this are need to be readable and writeable (600) by the web server. Users each have their own directory. The folders.start file needs to be in here. The full system path to this directory should be reflected in the $db_path variable of Common.pm.

folders.start : Initial folders file each user is given upon creation of an account. Contains Inbox, Trash, and Sent folders, and the fact that each contains no messages, no unread messages, and has a size of 0Kb.

999999 : This is the initial mail message that is automatically included in each new user account. This file can be easily changed, but the folders.start should be updated to reflect an relevant changes.

User_name directory : One directory per user containing all messages and user data.
The files in this directory are as follows:
-- ###### (any filename consisting of only numbers is a complete email including headers. As of Version 2, filenames starting with 1 are sent mails, while filanames starting with 2 are incoming message.)
-- ######.deleted ( messages permanently deleted from Trash, should be cleaned up periodically)
-- uploads (dir for user file storage. Contains files users saved from emails, or uploaded using upload script.)
-- folders (stores incoming and outgoing message and folder information inlcuding header details for each message) see below
-- folders.undo (last copy of folders, unless checked mail backup)
-- folders.undo2 (another backup, it sucks to lose folders)
-- address_book (all contact and group information) see below
-- pass (stores TRex password encrypted)
-- sessID (stores unique session ID which is a randomly generated number created upon TRex login, time session started(perl epoch time), and number of seconds user is off from server time)
-- user_info.db (perl hash file containing user's personal data (name, email, server info, time zone, etc.)

address_book contents:

The first line of address_book keeps track of the highest index number assigned to a contact in your address book. Each contact is identified by an index number. The next contact added should have an index one higher than this number. All contact numbers are not necessarily present in the file since contacts can be deleted.

The second line of address_book, through the first blank line, store all individual contact information.
The contact information is comma delimited.
The contact fields stored, in this order are :
[0]Nickname
[1]Last Name
[2]First Name
[3]email address
[4]index number.
Any of these fields except for index number can be blank.

All lines after the blank line contain the group information.
The group info is '|' delimited.
The three fields for groups are :
[0]Group Name
[1]Number of contacts in group
[2]contacts in group, comma delimited
The group contacts can be stored as the index numbers of the contacts or as email addresses. Index numbers are preceded by an '@'.

Sample address_book
<--
<-- Start sample address_book
7
al,Hart,Alex,alex@hart.net,3
atp,althepal,,althepal@althepal.com,4

First|2|@4,@3
--> End sample address_book
-->

This example is explained as follows:
7 contacts have been added so far, so the next new entry will have an index number of 8.

Only 2 contacts are now present. The first one has a nickname of 'al', full name is 'Alex Hart', email address is 'alex@hart.net, and the index number is 3. The second entry has the same format, but no First Name was entered.

There is one group in address_book. The group is named 'First', it has 2 contacts stored in it, and the contacts are those entries with index numbers 3 and 4.

folders contents:

The file folders stores several details about all mail messages, including which folder each is in, whether or not the message was read, and some static information about the message.

The first part of "folders", up to the blank line, contains information about the folders themselves.
This information is comma delimited. Folder information is updated during any operation which changes the folder contents or state.
The folder fields are :
[0] - Folder Name
[1] - Number Of Messages
[2] - Number of Unread messages
[3] - Size Of Folder (bytes).

The second part of "folders", after the blank line, contains details about the messages.
These fields are delimited by '|'. All '|' and '%' are encoded to avoid confusion.
The message field are :
[0] - message has been read or not 0/1 - this always starts as 0, then changed to 1 when read
[1] - folder name
[2] - from (if message was sent by user then this is the 'to' field instead
[3] - the subject sent in the message ('- none -' if no subject is given)
[4] - date - in epoch seconds (perl lingo for the number of seconds since a long time ago)
[5] - message filename - filenames are also the Message ID (MID)
[6] - whether or not message has an attachment 0/1
[7] - message size (bytes)

www directory : this directory is not actually necessary, but seems to be a common convention for an area with web access. All directories below this should be web accessible.

images directory : stores all images used by scripts. Directory should be readable and executable(500) while images should be readable(400) by the web server. You can name it anything you like, but the $img_URL variable in the Common.pm script needs to reflect the location.

Programs directory : All scripts used by TRex are stored in here. Directory and all contents should be readable and executable(500) by the web server. Again, any name works here, just update $dir_URL accordingly in Common.pm.

This is a very basic overview of what each script does. You'll just have to read the code to figure out what's really going on.

TOC.pl -- Table of Contents for TRex. The main purpose of this script is for showing the main options available to TRex users. This script is called by amail.pl as the top frame of the mail screen (the top 25 pixels). Calling Check Mail, Compose, Folders, Address Book, Search, user Info, Your Files, and Logout are all done here. In addition, much of the javascript used in the mail program is put here since TOC is usually just loaded once. Since this screen is never reloaded, several forms are stored here to keep track of state information.

address.pl -- This is the Address book script. It handles all input and editting of address_book, where all contacts and groups are stored. Can be called by TOC, compose, read_mess, whenever the address_book is needed.

amail.pl -- This script checks user name and password and sets up a session if they check out. If all is well, this sets up the frames for TRex and loads in TOC, functions, pop, and read_mess.

change_pass.pl -- Used to change user password. Called by user_info.

compose.pl -- Sets up input screen for composing mail. Also sends mail. Reply, Fwd, resend are all part of compose. Also does attachment handling, both inserting files and other attachments from other emails.

download.pl -- Short script. Opens a file and sends it for downloading to client side disk.

drive.pl -- Manages uploads directory for user. Stores and lists files in the directory.

dump.pl -- handy script for debugging. Sends all form data to browser. NOT USED in any script except for debugging.

folders.pl -- Shows folders, and their information. All folder operations (rename, delete, etc) are done here. Adding folders can be done here, but may also occur in pop or read_mess.

functions.pl -- This is the screen with the folder list as well as the move, delete, and go buttons. Very little is actually done in this script. Most of the information gathered by this script is sent to pop or read_mess. There is a good amount of javascript here.

line.pl -- This is sorta dumb, but this script loads a black page. This is the line between the folder contents screen and the message screen. It's a script because some cgi directories only run scripts and do not accept html. This is called by amail.pl to fill in the middle frame.

login.pl -- This is the login screen. It can give some status info, but mainly sends login data on to amail.pl.

new_account.pl -- Creates a new account.

pop.pl -- This script fills the upper main window showing the folder contents. In addition, this script checks for new mail and moves and deletes messages.

read_mess.pl -- This script fills in the lower main window showing the message contents. Move, delete, mark-as-read, is also done in this script.

search.pl -- Displays search form and performs search operation. Results are then sent to pop.pl for listing. Once the search is complete, a list of the results is saved and altered as necessary by pop.pl and read_mess.pl.

show_attach.pl -- Decodes and displays attachments for viewing or downloading.

start_message.pl -- Simple script which fills in the message window by default until a message is loaded. There is a form included in the html which is needed for some of the javascripts.

user_info.pl -- Edit user information.

wait_reply.pl -- Displays a message to the user that a mail is being sent. This is only used when resending a message.

lib directory : Well, don't forget our core scripts, the perl modules ... These are located the surrounding services around TRex core, and permits anyone to extend TRex to the infinite and beyond !!!

These are located in the program/lib directory from the distribution.

Common.pm -- This is the TRex perl Module with many of the common functions used by the scripts. If you can't find a function, it's probably in here. Customization of TRex(listing your server name, time_zone, etc) is done in here.

L10N.pm -- This name is a short one for Localization ('L' letter, 10 characters and 'N' letter), and contains the basis for allowing TRex to be used in various languages (the translation modules for each language are located in the L10N directory).

Sec.pm -- The security module involves all tasks related to TRex secure programming. If you try to make a task, such as openning a file, it must be surrounded by a lot of code to make it safe (check the file existence, proper permissions, porper filename, etc.) with disturb the code reading. If a safe_open function is made and contained inside it, then the specific code for security can be put there making it more maintainable (all the code is in one place), cleaner and easier for use.