@Mail Installation and Configuration Guide

1 Introduction: What is @Mail?
     1.1 'HotMail' Mode
     1.2 Web Email Client Mode

2 Installing @Mail
    2.1 System Requirements
        < 1000 users
        1000 - 10 000 users
        10 000 - 50 000 users
        1 000 000 users
2.2 UNIX Installation Instructions
    2.2.0 How to upgrade an existing @Mail installation install
    2.2.1 Gathering information about your server
    2.2.2 Instructions for Tar file install
2.3 Windows Installation Instructions
2.4 Identifying the Web Server User name
2.5 Multiple Domain Name configuration
2.6 Configuring SQL Database back end

4 Configuring @Mail

5 Large user base information

6 Additional Support
    6.1 The document root of your web server
    6.2 Location of Perl
    6.3 Contact Support

1 Introduction: What is @Mail?

@Mail is a total Web Email solution, allowing universal Email access to your users via their web browser. @Mail can run in two modes:

    1.1 As a 'Hotmail' Style system.

This allows users to sign-up online and instantly have access to their Email. @Mail users also have full POP access, allowing them to read and send Email via an 'Outlook' or 'Eudora' style client if they wish. Email can be stored in an SQL database for speed and scalability.

    1.2 As a POP3/IMAP Access Client.

@Mail can be used as a client for other external Email accounts. This means that you can use @Mail as a replacement for 'Outlook' style programs. This allows you to have a totally mobile (including wireless) solution for Clients.

2. Installing @Mail under UNIX

This will assist you in installing the @Mail software on your server. Installation is different for UNIX and Windows, so follow the guide for your platform. Once installed, follow through to the Configuration section to learn how to fine-tune your @Mail server.

    2.x Windows NT Install Instructions

Please see the Windows Installation Guide for information regarding installation of @Mail for Windows.

    2.1 System Requirements

The following is a hardware requirement chart, based on the expected number of users.

Users	Recommended CPU	RAM	Disk Space
<1,000	1 Server - Pentium II > 800Mhz+	256MB+	5 GB (5MB per User)
<5,000	1 Server - Pentium III > 1ghz+	512MB+	25 GB (5MB per User)
<10,000	1 Multi Processor Server - Pentium III 1.5ghz+ x 2	1GB+	50 GB (5MB per User)
50,000	2 Multi Processor Servers - Pentium III 2.0ghz+	1GB+	250 GB+ (5MB per User)
1,000,000	See Large User Documentation

Less than 1000 User Mail Boxes, 10 Simultaneous Requests*
Pentium II 800mhz+
256MB RAM
5GB (5MB user quota)
This setup does not require installation and configuration of the SQL Database

1,000 - 5,000 User Mail Boxes, 30 Simultaneous Requests
Pentium class 1Ghz
256MB RAM
50GB (5MB user quota)

5,000 - 10,000 User Mail Boxes, 50 Simultaneous Requests
Recommended:
Multi Processor 2.0 Ghz
1GB RAM
50GB (5MB user quota)

Minimal:
Single Processor 2.0Ghz
256MB RAM
50GB (5MB user quota)

10 000 - 50 000 User Mail Boxes, 200 Simultaneous Requests
Two of the Following Servers:

MultiProcessor Pentium class 2.0Ghz
1GB RAM+

The first server handles all the web requests. The second is a dedicated SQL server storing and retrieving user data and mail.

The Database Server must in addition have:
250GB (5MB user quota) RAID

mySQL Database Server or Oracle

These two Servers should be located within the same LAN for fast connectivity

1 000 000 User Mail Boxes.
Please see Large User Base Information

*Simultaneous requests is defined in this context as the number of users accessing @Mail within the same 100ms (milliseconds). Simultaneous requests are not based on the number of users logged into @Mail.

Software Requirements:
Perl 5+
Perl executable web server (ISS, Apache)
Sendmail / Qmail / Postfix or Exim **
Unix, Linux, FreeBSD, Solaris (and most other UNIX flavors)
WinNT, Win2k / XP also supported

** SMTP configuration required

    2.2 UNIX Install Instructions

This section will guide you through installation of @Mail on a UNIX platform. It is recommended that you install @Mail as root.

2.2.0 Upgrading an existing @Mail installation:

To upgrade from an existing version of @Mail, follow the steps below:

1. Move your existing @Mail directory to a new folder. This will temporarily disable @Mail.
2. Extract the tarball, and copy the new @Mail files to the original @Mail directory.
3. Run the install.pl script in the @Mail directory.
4. Once configured, visit the WebAdmin utility to define the system settings.
5. If you are running the SQL version of @Mail, you may need to update your database table. See the scripts in the atmail/dbpatch/ directory for instructions on updating the database.
6. Verify that email delivery works and users can successfully login via the Web.

        2.2.1 Gathering information about your server:

Before you install @Mail you will need to know the following about your server:

· The directory name under which you would like users to be able to access @Mail.
· The username under which the web server runs (usually 'apache' or 'nobody').
· The location of Sendmail and startup flags.
· The location of Perl.
· Your SMTP hostname.
· Your SQL server information (optional).

        2.2.2 Instructions for tar file install:

1. Gunzip / Untar atmail.tgz into your web server's document root.

Find the pathname of your web server's DocumentRoot. @Mail must be installed to a directory within the DocumentRoot so that it can be made available via the web.

Move the @Mail tarball you've downloaded to a location within your DocumentRoot.

root:/# mv atmail.tgz /www/

where /www is your DocumentRoot.

Now move to your /www directory.

root:/# cd /www/

You will need to enter the server details for your machine; the install utility (install.pl) will analyze your server setup and prompt for any configuration decisions.

Untar and decompress the @mail archive by typing the following:

root:/www# tar xfvz atmail.tgz

Then move to the @Mail directory:

root:/www# cd atmail

2. Automatic Configuration

Now you can run the @Mail install utility. This program will ask you questions about your server, and prompt for the appropriate configuration changes.

root:/www/atmail# perl install.pl

The @Mail install.pl script will attempt to configure your server for @Mail . The install.pl script may be used to modify your system's httpd.conf and sendmail.cf for @Mail (recommended, if modification is necessary).

Once the install.pl script is complete you can visit the WebAdmin of @Mail to finish the installation. Using the WebAdmin you can fine tune the installation and specify account preferences. The WebAdmin URL is:

http://yourdomainname.com/atmail/webadmin/

where yourdomainname.com is the domain name of your server, and atmail/ is the directory in which you installed @Mail.

3. Manual Configuration of @Mail

If you have difficulty running the install.pl script you can install @Mail manually. The steps required to complete the installation of @Mail are as follows:

• Change the ownership of the @Mail directory (to the owner of the webserver; see below).
• Configure your Webserver to execute @Mail (httpd.conf).
• Configure the SMTP server (sendmail.cf).
• Visit the @Mail WebAdmin to define @Mail's settings & preferences.
  

Changing the ownership of the @Mail directory:

Correct permissions must be set for @Mail to run on your server. Type the following (where 'username' is the owner of the web server):

root:/www/atmail# chown -R username /www/atmail

Configure your WebServer to execute @Mail

Your webserver must be configured to execute .pl files as scripts. Depending on the version of your web server, the following modifications will need to be made in either httpd.conf or srm.conf. Newer versions of Apache use httpd.conf. If your webserver is using Virtual Hosts, make these modifications only within the Virtual Host statement which represents your website. If you add the following lines outside the scope of your Virtual Host configuration, the changes will be made system wide. Check with your hosting provider if you are unsure.

# Allow .pl files to be executed as a perl script
AddHandler cgi-script .pl

<Directory "/www/atmail"> # Replace this with your @Mail directory
Options ExecCGI
AllowOverride All
Order allow,deny
Allow from all
</Directory>

<Files ~ ".pm > # Deny files ending in .pm
order allow,deny
deny from all
</Files>

You must now restart your web server.

Configure the SMTP Server:

*Note that @Mail running in POP3/IMAP Client Mode does not require any modification to your SMTP server.

If you use @Mail as the Email-Server, (i.e., Allowing users to automatically sign up for accounts; a Hotmail type system) you must modify your SMTP server to deliver email messages to @Mail.

@Mail supports a variety of MTA (Mail Transport Agents):

• Sendmail
• Postfix
• Exim
• And the @Mail SMTP server , written in Perl, located in atmaildir/modules/smtpserver/

*Note that MTA configurations will vary depending on OS type.

    2.4 Identifying the Web Server Account

The best way to find the username (owner) of your web server is to read it from the httpd.conf file.

To find your httpd.conf file type:

root:/# find / -name httpd.conf

Once you find the path, move to the appropriate directory

root:/# cd /dir

root:/# cat httpd.conf | grep User

The output should be similar to:

# User/Group: The name (or #number) of the user/group to run httpd as.
User nobody

This tells you that the httpd user is 'nobody'. This name is common for Apache web servers.

    2.5 Multiple Domains

To configure @Mail to receive email for more than one domain, use the WebAdmin utility in @Mail. Or consult the relevant SMTP configuration file for your system.

    2.6 Configuring SQL

If you expect to have more than 10,000 users, you should use an SQL Database for email storage.

With an SQL database, you can setup multiple web servers to host the webmail interface. Each machine can communicate with the SQL server to retrieve messages, allowing you to scale the webmail solution to suit your needs. We recommend using mySQL under a UNIX OS.

If using mySQL, verify that your mysqld startup flags include a larger max_allowed_packet . By default, mySQL supports a maximum query size of 1MB. You must increase this value, or large attachments will not be accepted.

You may set a higher max_allowed_packet by using a command line argument:

/usr/local/libexec/mysqld -O max_allowed_packet=9999999

OR by setting max_allowed_packet in your mySQL configuration file, 'my.cnf':

[mysqld]
set-variable = max_allowed_packet=16M

After editing the my.cnf you must restart the mySQL server for the changes to take effect.

For larger sites using @Mail and the SQL backend, the default number of mySQL connections must be set to a higher value. Each Webserver process running @Mail will connect to the mySQL server. If @Mail is configured to use Mod_Perl the Webserver will maintain a persistant database connection between Webserver threads.

The following can be appended to the /etc/my.cnf file to increase the number of mySQL connections:

[mysql]
....
set-variable = max_user_connections=500
set-variable = max_connections=500

Change the value of 500 to match the number of mySQL connections to be accepted.

        2.6.1 Setting up the SQL Environment

Start mySQL as user root, and create a new database called 'atmail'

user:/www/atmail# mysql -u root
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 113 to server version: 3.22.24

mysql> create database atmail;

Query OK, 1 row affected (0.06 sec)
Once your SQL database is setup, install the Perl DBI module for your database type if requested by the installation script.

See http://search.cpan.org and download the DBI module for your system and configure as per the README file. Once the Perl DBI module is loaded, install the DBD module for the type of SQL server you are using (e.g. DBD::Mysql for mySQL, DBD::Oracle for Oracle)

        2.6.2: Creating the SQL tables for @Mail

@Mail has two database table structures, one normal, and one large. You should use the Large table structure if your user base will be greater than 10,000 users.

@Mail stores user information in the database keyed by the first character in the username. This means that SQL can access requested information very quickly. If you have over 10,000 users @Mail stores the information by the first and second characters of the username.

If you have less than 10,000 users, use the following (replace database_name with the name of your database, e.g. 'atmail'):

mysql -u root database_name < atmail/docs/normal.sql

If you have more than 10,000 users:

mysql -u root database_name < atmail/docs/large.sql

This will create all the necessary database tables.

        2.6.3: Set Database Configuration via WebAdmin

Visit the Webadmin control panel and set the various database options for your OS. Via the Webadmin panel, select which SQL server you are using and provide the username/password required to login to the database server. Enter the hostname or IP address of the SQL server if it is on a different server than the @Mail software.

        2.6.4: Validate Setup

Check your setup and configuration files, and verify that the system is working by adding a new user. When the user receives email, the @Mail SQL installation is complete.

3 Configuring @Mail

Configuration of @Mail can be done exclusively via the /atmaildir/libs/Atmail/Config.pm file, although the primary configuration tool for @Mail is the WebAdmin. Once @Mail is installed, visit http://yourdomain.com/atmail/webadmin/    (you may be prompted for a password).

In the WebAdmin you'll find the following configuration options:

- System Configuration
- Sendmail Configuration
- Database Configuration
- Branding   (brand-specific configuration; personalize your version of @Mail)
- User Defaults   (default settings for new users)
- LDAP Settings
- Manage Domains
- Undeliverable   (return messages in case an email delivery fails)
- Reserved Usernames   (usernames that can't be created by users)
- Admin Password   (change the password to the Webadmin)
- @Mail Registration
- Backup @Mail
- And more...

 

4. Configuring @Mail

The @Mail configuration file is /atmaildir/libs/Atmail/Config.pm. It contains all of the configuration settings for @Mail. You can edit this file manually but we advise that you use the WebAdmin. If you plan to manually edit this file, please make a backup of it first!

 

5. Large User base Information

For information about serving 1,000,000 users, please see our case study.

6 Miscellaneous

    6.1 The document root of your web server

locate your httpd.conf:

root:/# locate httpd.conf

or

root:/# find / -name httpd.conf

Once you find the location of httpd.conf, cd to the directory and type the following:

cat httpd.conf | grep DocumentRoot
·
This will display the current document root.

When you type your domain name into the address bar of a web browser, you are shown the default document (usually index.html or default.html) which resides in the DocumentRoot of your web server.

    6.2 Location of Perl

To locate the Perl binary, type the following:

root:/# which perl

    6.3 Contact Support

For additional support, please visit our web site, http://webbasedemail.com
Or send us an Email : support@CalaCode.com