Installing CuLy Mail


Welcome to CuLy Mail v1.0.5

Please take a few moments to read through this documentation, even if you have experience in setting up perl scripts. Many problems reported to us are caused by improper installations. We've tried to make things as easy as possible to set up - so if all goes well, you'll be logging in to CuLy Mail in no time!


1. Quick Installation Notes.
2. Detailed Installation Notes.
  a. Account Directory.
  b. CGI-BIN Directory.
  - 1. html Directory.
  c. Images Directory.
3. Customizing CuLy Mail.
  a. 999999 file.
  b. folders.start file.
  c. HTML Templates.
4. A Few Words on "Catchall" POP Mailboxes.
5. The Admin Utility.
6. Troubleshooting.
7. Release Notes.
8. Upgrade Notes.


1. Quick Installation Notes.

ASCII upload culymail directory to a directory OUTSIDE of your web directory. This is your $db_path directory.
chmod to 777

!!! Please manually select ASCII mode on your FTP client when uploading this directory. Because the files do not have a standard .txt (or other associated extension) most clients will upload these files in Binary mode by default. This WILL cause CuLy Mail not to work properly. !!!

ASCII upload cgi-bin/culymail into your cgi-bin directory.

ASCII upload cgi-bin/culymail/html.

BINARY upload images to a location accessable from the web.

Set the following parameters in setup.pl
my $dir_URL = "http://www.domainname.com/cgi-bin/culymail";
my $db_path = "/direct/path/to/culymail";
my $img_URL = "http://www.domainname.com/culymail/images";
@Admin_Users = ("admin1", "admin2");

Set all the rest of the parameters in setup.pl

Make all the files directly under cgi-bin/culymail executable (755).

** Be sure to create your admin account by running new_user.cgi before doing anything else!! **
That's it.


2. Detailed Installation Notes.

a. Account Directory
 
This is where the user directories are created. NOTE! There should not be web access to this directory! If you are unable to create a directory outside of your web directory, you will not have any security on your installation. The only tips we can offer would be to change the permissions on this directory to 733 so that nosey people can not browse this directory. This does not stop them from getting into account directories! If a person knows the name of an account, they can go directly to it and browse inside of this account.

This is also where the 999999, folders.start, and address_book files should be uploaded, and also the path listed in the setup.pl for $db_path=. Also, set the $Temp_Directory = variable in setup.pl to this location. Make sure you upload these files in ASCII Mode!! If you do not upload them in ASCII, CuLy Mail may not work!
 
b. CGI-BIN Directory
 
This is where the actual program files reside. This directory can have any name you would like, as long as $dir_URL = is set in the setup.pl. Again, make sure you upload all the files in ASCII format, and leave setup.pl a .pl file. Even if your server requires cgi executables to be set to .cgi, this is used by the other scripts and is only a parameter file. Also, varify that the first line of each file "#!/usr/bin/perl" is correct for your server. If it is not, change it to point to perl on your server for each file. Some servers use "#!/usr/local/bin/perl" instead. After uploading the files, set all the permissions to 755.
 
- 1. html Directory
 
This is where the html template files should be. They are discussed in the "Customizing CuLy Mail" section of this document.
 
c. Images Directory
 
This is where the images for CuLy Mail are. Depending on your server, this directory may be kept in your /cgi-bin/culymail directory. Some servers do not allow images to be served from within the cgi-bin directory, so you may need to put them in your web directory. You can make this directory anywhere with any name you like, as long as it is defined as $img_URL in the setup.pl and if it is where you are keeping your logo, it will need to be defined as $email_logo in setup.pl as well.

Here are some example location:

/cgi-bin/culymail/images - This is our default location.

/images/culymail - You can create a directory under your current images directory to help keep them seperate from your site images

/culymail/images - You can create a culymail/images directory in your web directory

/culymail - Or you can just put them in a culymail director created in your web directory


3. Customizing CuLy Mail


a. 999999 File.
 
NOTE: This is now editable from the Admin Utils!

This file is the first e-mail the a new user will receive. In this file, you want to put any information reguarding your service as well as helpfull hints in using your e-mail system. This file can have HTML incorporated in it. Below is an example e-mail with explination, but if you want to have images, add them like you would to a normal html page, but be sure to give the full path to the image file (EG: http://www.customlynx.com/images/welcome.jpg):

To: new user < welcome.to@culymail.com > - This is a non existant account but needs to be here for the header to display properly.
From: CuLy Mail < culymail@culymail.com > - Change this to who you want it to be from.
Subject: Welcome to CuLy Mail - Change this to your subject.
Date: Thu, 21 Sept 2000 02:23:59 -0400 - We suggest you change this to when you installed CuLy Mail, but you don't have to.
Content-type: text/html - This has to stay.
X-Mailer: "CuLy Mail Web Based Email Version 1.0" - This is written by CuLy Mail. You can change it, but all e-mail will have this.
- This space must be left here so CuLy Mail knows where the message begins.
Hello,< br >
Welcome to your new e-mail account.< br >
< br >
Thanks,< br >
Webmaster< br >

 
b. folders.start File.
 
The folders.start file is copied to the new user account as folders. Inside this file, CuLy Mail keeps track of all their e-mail as well as any folders they have created. You only need to edit 4 parts of this file as described below. Here is the default file info:

Inbox,1,1,6064
Trash,0,0,0
Sent,0,0,0

0|Inbox|Custom Lynx|Welcome to CLWebMail(click here to read email)|961395839|999999|0|6064


What does it mean?

Inbox - Folder name
1 - First 1 is the number of messages in this folder
1 - Second 1 is the number of unread messages in this folder
6064 - is the size of this folder

0 - Read message flag. 0 = unread, 1 = read
Inbox - Folder Name
Custom Lynx< clwebmail@customlynx.com > - From
Welcome to CLWebMail(click here to read email) - Subject
961395839 - Date. In epoch seconds
999999 - Filename of message
0 - File attachment flag. 0 = No, 1 = Yes
6064 - Message size in bytes

What to change?

Inbox - Folder name
1 - First 1 is the number of messages in this folder
1 - Second 1 is the number of unread messages in this folder
6064 - is the size of this folder - Change to file size of your 999999 file.

0 - Read message flag. 0 = unread, 1 = read
Inbox - Folder Name
Custom Lynx< clwebmail@customlynx.com > - From - Change to your liking (EG:webmaster@yourdomain.com)
Welcome to CLWebMail(click here to read email) - Subject - Change to your liking
961395839 - Date. In epoch seconds
999999 - Filename of message
0 - File attachment flag. 0 = No, 1 = Yes
6064 - Message size in bytes - Change to file size of your 999999 file.

Note on the file sizes. The actuall file size of 999999 and what is put in this file do not need to match. This is only used to keep track of how big a file is, and how big their folder is. Most users will delete this file anyway, so it will be deducted from the inbox size, making it = Inbox,0,0,0

 
c. HTML Templates
 
The template files can be modified in any way, as long as the parameters are kept in tact. Here is a list of parameters for each file that are required to keep the script working. If you do not want to use a parameter, put the HTML remark tags around it (IE <!-- and -->):

login.html requires the following-

- __TITLE__ = This is pulled from the setup.pl

- __email_ID__ = required to keep track of users

- __stat__ = Displays messages (eg: time out has expired, please log back in)

- __resubmit__ = Displays messages

- __email_logo__ = Displays logo defined in setup.pl
NOTE! if you do not want a logo display, comment it out as explained above.

- __BACKGROUND__ = Displays the background defined in setup.pl to keep it consistant.

main_frames.html requires the following-

- __TITLE__ = This is pulled from the setup.pl

- __email_ID__ = required to keep track of users

- __SID__ = required to keep track of users authentication

Must have a frame named "TOC" and a frame named "MAIN" in ALL CAPS.

new_user.html requires the following-

- __TITLE__ = This is pulled from the setup.pl

- __dir_URL__ = as defined in setup.pl

- __comp_name__ = Will Display parameter in setup.pl

- __problem__ = Displays message if a problem is found (EG: password not long enough)

- __POP_Server__ = Used to display domain name next to user account blank (EG: ________ @yourdomain.com)

- __BACKGROUND__ = Displays the background defined in setup.pl to keep it consistant.

start_message.html requires the following-

- __TITLE__ = This is pulled from the setup.pl

- __email_ID__ = required to keep track of users

- __SID__ = required to keep track of users authentication

- __comp_name__ = Will Display parameter in setup.pl

- __email_logo__ = Displays logo defined in setup.pl
NOTE! if you do not want a logo display, comment it out as explained above

- __imagedir__ = This is the path defined in setup.pl. - __BACKGROUND__ = Displays the background defined in setup.pl to keep it consistant.

- __qpercent__ = Displays users Quota limit usage.

toc.html requires the following-

- __BACKGROUND__ = Displays the background defined in setup.pl to keep it consistant.

- __img_URL__ = This is the path defined in setup.pl. - __dir_URL__ = as defined in setup.pl

- __email_ID__ = required to keep track of users

- __SID__ = required to keep track of users authentication

- __qpercent__ = Displays users Quota limit usage.

- __x_folder__ = Items between these should be the following:

   - __email_ID2__ = required to keep track of users

   - __SID2__ = required to keep track of users

   - __FolderName__ = Displays each foldername they have in their folders file

- __admin_text__ = Defined in setup.pl, will be displayed on the TOC if user is defined in @Admin_Users of setup.pl

- __admin_url__ = Will also be displayed if user is defined in setup.pl



4. A Few Words on "Catchall" POP Mailboxes.


Catchall POP3 Mailboxes by default will receive any e-mail sent to whatever@yourdomain.com. Please remember, if you have created additional accounts on your server that most likely they create a POP mailbox for that account as well. So if you create an account for someguy on your server, someguy@yourdomain.com will not work with CuLy Mail.

Why?

Well, because your server will redirect this mail to someguy@yourdomain.com's POP mailbox instead of your catchall mailbox. Also, if you have any forwarding turned on, CuLy Mail will not receive any e-mail for the forwarded accounts.

Forwarding

Forwading can be done in a few different ways.. We'll try to touch on the 3 most popular ways.

1. Forwarding by your Domain Name Registrar. Because there are so many different registrars today, and each have their own system, we'll give an overview of how it should work. Many registrars give users an online interface to manage their domain name. If your registrar has a forwarding feature, make sure you have it set to forward *@yourdomain.com to the POP mailbox that CuLy Mail is set to read.

2. Forwarding by your Hosting Provider. When your provider setup your domain name, they created your main account. All e-mail to yourdomain.com should have been set to forward to this address. Just set CuLy Mail to check this POP mailbox and your all set. If your provider has it set to forward to another e-mail account (Because they do not give you a POP mailbox) just set CuLy Mail to check that account instead.

3. Forwarding by you. Some hosting providers give you an online interface to manage your site. Make sure that you have not setup any forwarding for your domain. If you have, either remove the forwarding rule, or have CuLy Mail check the POP mailbox you are forwarding the mail to.


5. Admin Utility

The Admin Utility will show up if your account is listed under @Admin_Users in setup.pl By Default, ("admin1", "admin2") is listed. You can either create an admin1 or admin2 account using new_user.cgi or, create your own account (IE: Joe) and edit the setup.pl file so that joe is listed as an admin account ("joe", "admin2"). We suggest you create your own account, because if you leave the admin account named ("admin1","admin2"), you have a better chance of someone trying to "hack" into your admin account. We also suggest you change the admin2 name listed. If you do not create this account, anyone can sign up for a new account, create their username as "admin2" and have access to the admin utils. YOU MUST leave at least 2 names in this. If you need to add more, you can. Just keep adding ,"name" like this ("name1", "name2", "name3", "name4")

1. Account Management
To delete an account, just check next to the account name, and click on "Submit". To edit a user, click on their username. From here you can browse, reset their password, and edit the quota limit for their account.

2. Aliases
To delete an alias, just check next to the alias name, and click on "deletealiases". To add aliases, just type in an alias name, and the account you want it delivered to and click "savealiases".

3. System Config
This allows you to change most of the system setting in the setup.pl file.

4. Style Settings
This allows you to change the style settings in the setup.pl file

5. Edit Welcome Message
This will allow you to easily edit the welcome message for new users. PLEASE NOTE: this will not edit the folders.start file. Currently you will still need to manually edit the e-mail addresses in the folders.start file.


6. Troubleshooting

Here we will go over the popular issues that have come up during installation of CuLy Mail.

Problem: The Table Of Contents (TOC) is listing the contents of the Inbox or other folders.
Resolution: re-upload the folders.start file in ASCII mode. Then, do the same for the folders file of the account that has the issue. If you are still having problems, change the name to folders_start.txt and upload it that way (You may want to re-upload the address_book and 999999 files as well). This will tell your FTP client that it is an ASCII file and upload it in that mode. Then, just rename the file back to folders.start. This is cause by not having the proper or in the folders.start file. This file contains a space between the folders, and the content of all the folders. CuLy Mail is unable to find the blank line, and therefor is unable to tell where the folder list ends, and the folder contents begins. So it loads the whole file into the TOC.


7. Release Notes

V1.0.1 - Fixed deleted e-mail build up.
 
V1.0.2 - Fixed Checking of extrenal POP3 Mailboxes.
  - Fixed Sending mail with Qmail.
 
V1.0.3 - Fixed truncating on composing e-mails.
  - Fixed more deleted e-mail build up.
  - Added Universal Banner code to setup.pl
  - Added Admin Utils.
 
    - Account Management
    - Welcome Message Editor
 
V1.0.4 - Fixed duplicate folders bug
  - Fixed delete all accounts bug
  - Added File Attachment Area
 
V1.0.5 - Moved all virables to setup.pl
  - Added address_book incase touch command is restricted
  - Added Search option
  - Added Quota display on TOC
  - Added Admin Utils features.
 
    - Undeliverable Messages
    - Quotas
    - Sys Config editor
    - Style Settings editor
    - Reset Password
    - Aliases

8. Upgrade Notes

The easiest way to upgrade CuLy Mail is to delete all the files in the cgi-bin/culymail directory and upload the new ones. ONLY ADD any additional files to the data directory. Then log into CuLy Mail and verify all the screens work. If you get a red screen saying a variable has not been defined, edit the .html file that goes with that screen and add the variable described in the "Customizing CuLy Mail" section.


If you have any problems, please check the online support page
at http://www.culymail.com before e-mailing support@customlynx.com


Thanks,
Custom Lynx
www.customlynx.com

When customlynx.com reviewed the needs of it's clients, the company found that a low cost solution for providing web-based email addresses strangely lacking. In an effort to provide a solution, the CuLy Mail application borrows technology from many freeware applications. Customlynx.com would like to recognize the following authors for their contributions of freeware applications.

HTMLTMPL v1.21 - Ian Steel
upload.pl v1.0 - James K. Boutcher
amail v2.0 - Alex Hart