@Mail Webmail ( Client-mode ) Source Installation and Configuration Guide

1. @Mail Webmail Client Introduction and the Install Script

1.0 Pre-install and dependencies

1.1 Install Script

2. Manual Install

2.1 @Mail User and Apache

3. Troubleshooting

4. Contact Support

1. Pre-install and Dependencies

The Webmail Client source installation can be used to setup @Mail in the Webmail mode of @Mail. Use this method to setup @Mail as the WebMail interface for any existing POP3/IMAP servers.

This document will illustrate how to configure the @Mail Webmail software from source. If you want to setup @Mail as a complete mail-server, please refer to the Server installation guide.

1.0 Pre-install and Dependencies

@Mail requires the following to be existing before installation:

• MySQL Libraries - http://www.mysql.com/
  
• Apache Webserver - Usually installed by default with most Linux Distributions and Unix Variants - http://httpd.apache.org/
  
• Mod_perl - Mod_Perl is required to optimize the Perl code run in the @Mail application, it can produce a significant performance boost for your @Mail system. Depending on your Apache version ( 1.3 or 2.0 ), the Mod_Perl module can be installed and configured for your system. http://perl.apache.org/
  
• Perl
  • Perl 5.6+ recommended . Minimum Perl 5.005_03 tested - Perl is required and is usually installed by default with most Linux Distributions and Unix Variants.
  • Perl DBI module
  • Perl DBD::mysql module
  • Perl Apache::DBI module ( for Persistent database connections )
  • The above perl modules can be installed automatically using the installation script of @Mail
    
• A version of the gcc compiler and the make utility may be required if any system Perl libraries are missing

We strongly recommend using the RPM package for RPM compatible systems ( Redhat, Fedora, Mandrake ) as the RPM can be used to identify missing dependencies and automatically setup the software for your selected platform. For more information on the RPM install, please view:

http://support.atmail.com/webmail-rpm.html

We are always working towards making the installation of @Mail as easy and quick as possible, if you have any comments or suggestions, please feel free to email us at support@calacode.com

1.1 Install Script

It is recommended that you use the install.pl script to configure your @Mail system.

The purpose of this script is to configure the @Mail application for Webmail access, and to save the runtime settings to the main Configuration file (Config.pm).

You run the installation script by running the following commands:

# tar xvfz atmail4.tgz -C /usr/local/

# cd /usr/local/atmail/webmail/

# perl install.pl

@Mail must be installed under the default pathname of /usr/local/atmail/ - The atmail4.tgz archive has the directory structure pre-setup. Using the tar command extract the archive into the /usr/local directory.

If hard-disk space is an issue of the selected partition, the @Mail directory can be moved to another volume so long as the /usr/local/atmail directory is symbolically linked to the new directory.

Below is a walk through of the command-line installation script install.pl:

@Mail Configuration

@Mail can run in two different configurations. Email-Server or WebMail Client. Please select the mode which you would like to setup the software as.

1) @Mail Server Mode + WebMail

Select this mode if you want to setup @Mail as the Email-Server. This
allows you to manage user-accounts via the @Mail Web-Admin interface and the ability for users to sign up for an email account via the web.

2) @Mail POP3 / IMAP WebMail

Select this mode if you want to setup @Mail as a WebMail client for
existing POP3/IMAP accounts.

Enter @Mail Mode: [2]: 2

Selecting the installation mode

When first running the installation script, you must select which mode to install the @Mail software with. For the WebMail client installation select '2' for the WebMail installation.

Enter the full pathname to the Webserver configuration directory. Changes are required for the Webserver to recognize and run the @Mail application.

Enter Apache Configuration Directory: [/etc/httpd/conf/]:

Specifying the Webserver configuration directory

Next, @Mail will prompt for the directory of the Webserver httpd.conf . This is required to analyze the Webserver configuration and setup the runtime settings for Apache to run @Mail.

The installation script will prompt to edit the Webserver httpd.conf if the file does not contain the settings required to run @Mail. Reference the Webserver configuration chapter for further information.

@Mail sends outgoing messages via an SMTP server. Please specify the local SMTP server ( 127.0.0.1 ) on the machine or an external address to relay messages. The installation script will test the SMTP server you specify.

Enter SMTP Host: [127.0.0.1]:

SMTP Configuration

Next, the installation script will prompt for the outgoing SMTP server address. This is required to send messages via the WebMail interface of @Mail. It is recommended you use a local SMTP server to deliver outgoing messages. Otherwise, specify the hostname of your SMTP server and verify the @Mail server has permission to relay messages.

@Mail Configuration

Provide the following information to compile an libs/Atmail/Config.pm
file based on your servers unique configuration.

Enter the admin email for the system.

Admin Email: [admin@yourdomain.net]:

Entering the Admin Email

You will be first asked to add the Email Administrator account. The purpose of this is to allow any @Mail error or notification emails to be sent to this account.

SQL Database Configuration

@Mail can be installed to use an SQL database backend to store user emails and account information. We recommend the use of mySQL for the Database backend for @Mail, which can be freely obtained at http://www.mysql.com/

Select the database name to store email/account information
Select Database Name: [atmail]:

Enter which user to connect to the database server. The users needs
full permissions over the table to modify/read/write
Enter Username: [root]:

Enter the password for root to connect
Enter Password for root: []:

Next, specify the hostname / IP address of the MySQL server.

Using @Mail you can scale the software solution by storing user email/account information on a separate machine from the webserver.

It is recommended to use @Mail and mySQL on the same machine for userbases under < 10,000 accounts.

If the MySQL server is setup on the same machine leave the 'Hostname' field blank. This will make @Mail communicate with the database server directly rather then opening a TCP/IP connection.
Enter Hostname: []:

MySQL Database system configuration for @Mail

After this step you will have the option of creating the tables for the @Mail database you have specified and
testing the MySQL configuration and updating the my.cnf file to optimize MySQL for @Mail.

Next, the installation utility will check any missing Perl dependencies ( DBI, DBD::mysql modules ) and install the modules as required.

Apache and Mod_Perl Support

Mod_Perl supported on WebServer: Detected

Your Webserver is enabled with Mod_Perl support. It is highly recommended to configure Apache to run the @Mail application with Mod_Perl for faster performance.

Edit httpd.conf automatically? [Y/n] [Y]:

Mod_Perl detection

If your Webserver has been detected with Mod_Perl support, the installation script will prompt to automatically configure the Webserver to execute @Mail under Mod_Perl. For more details on the Mod_Perl installation of @Mail consult the online tutorial.

Once the installation is complete, the Webserver will be reset with the new changes and @Mail can be accessed via the address:

http://youraddress.com/mail/

Here you can access the WebMail interface of @Mail and login to any existing POP3/IMAP account. To begin using the WebAdmin interface of @Mail visit the URL:

http://youraddress.com/mail/webadmin/

After visiting the Webadmin you must enable a password for the access using the Webadmin -> Security -> Admin Password menu

2. @Mail and Apache

The following changes are required to the Webserver configuration to execute @Mail.

AddHandler cgi-script .pl

<Directory "/usr/local/atmail/webmail">
Options ExecCGI
AllowOverride All
Order allow,deny
Allow from all
</Directory>

<Files ~ ".pm$">
order allow,deny
deny from all
</Files>

Alias /mail/ /usr/local/atmail/webmail/
Alias /mail /usr/local/atmail/webmail/

These are required to allow the Webserver to execute .pl files as Perl scripts, grant permissions over the @Mail directory to be executable and deny .pm files to be viewable ( to avoid accessing the @Mail configuration module ) . The Alias command is required to access @Mail via the URL http://yourserver.com/mail or http://yourserver.com/mail/ with a leading slash. The installation script will automatically append these changes to the Webserver configuration file.

It is highly recommended to run @Mail under Mod_Perl with Apache. This increases the performance 3-5X over traditional CGI mode and creates a persistent environment for the script to run. For details see the Mod_Perl configuration page.

For the @Mail Application to be viewable with a browser - the @Mail directory located in /usr/local/atmail/webmail need to be owned by the username the Webserver runs as. If you are using @Mail within a VirtualHost, the directory must be owned by the username defined in the VirtualHost container.

The default username Apache runs as is nobody, apache or wwwuser. View the httpd.conf and locate which user the Webserver runs as. Change the permissions by running the command:

# chown -R atmail /usr/local/atmail

If the directory is not owned by the Webserver user, you can receive the message "Internal Server Error" when visiting the URL of @Mail, or the Webadmin page cannot save settings to the Config.pm file due to permissions.

3. Troubleshooting

1. I can't access the @Mail URL
   
   Check that your @Mail directory is owned by the user that runs the Webserver. This is usually the username nobody, apache, or wwwuser. Change the directory by using the command: chown -R [webserveruser] /path/to/atmail/
   
   
2. Webadmin Interface appears to be unsecured
   
   Access the Webadmin and go to the Security menu item, select Admin Password and enter a new password: this will update the .htpasswd file, any subsequent action in the Webadmin Interface will bring up the authentication for the Webadmin Interface.
   
   
3. I can't access the Webadmin Interface
   
   On the command line, cd to the Webadmin Folder and delete the existing .htpasswd and .htaccess files:
   
   # cd /usr/local/atmail/webmail/webadmin/
   
   # rm .ht*
   
   and perform the Admin Password change in the solution above to secure the Webadmin Interface.
   
   
4. Can't access POP3 / IMAP externally
   
   Review your firewall to allow the following ports:
   
   25 ( SMTP )
   80 ( Web )
   110 ( POP3 )
   143 ( IMAP )

4. Contact Details

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