Mod_Perl Setup for @Mail

@Mail System Documentation : v 3.4
The latest version of this file can be found at:
http://atmail.nl/docs/

@Mail Mod_Perl Setup

1 Introduction to Mod_Perl
2 How to setup Apache with Mod_Perl
3 How @Mail works with Mod_Perl
4 Test Mod_Perl is running with @Mail
5 Troubleshooting Mod_Perl

1 Introduction to Mod_Perl

Mod_Perl gives you a persistent Perl interpreter embedded in your web server. This lets you avoid the overhead of starting an external interpreter and avoids the penalty of Perl start-up time, giving you super-fast dynamic content.

The standard Apache::Registry module can provide 5x speedups for your existing @Mail installation and reduce the load on your server at the same time. A few changes to the web server's config is all that is required to run your @Mail application at lightning speed.

For up-to-date information on Mod_Perl visit the project site at : http://perl.apache.org/

This document assumes you have an existing knowledge of Apache, and basic Perl understanding.

Note: @Mail for Windows users can skip this tutorial. Mod_Perl is pre-configured on the installation of @Mail.

2 How to setup Apache with Mod_Perl

To start you must pre-configure your Webserver with the Mod_Perl module. You can obtain a version of Mod_Perl for Apache at http://perl.apache.org/ . Mod_Perl support is only available under the commercial version of @Mail, the demo version does not include support.
You can run the install.pl script via the command-line to modify your httpd.conf with support for Mod_Perl with @Mail . Before running the install.pl script, your webserver must be pre-configured with Mod_Perl.
You can also configure your httpd.conf manually with Mod_Perl and @Mail. Below is an example configuration to enable @Mail with Mod_Perl support.

# Optional; your Webserver should already include lines similar to these:
<IfDefine HAVE_PERL>
LoadModule perl_module modules/libperl.so
</IfDefine>

# Optional; your Webserver should already include lines similar to these:
<IfDefine HAVE_PERL>
AddModule mod_perl.c
</IfDefine>

# @Mail Mod_Perl Conf
# If the perl module is installed, this will be enabled.
<IfModule mod_perl.c>

# Optional, only for the SQL version of @Mail
PerlModule Apache::DBI

# For Mod_Perl 1.X
PerlInitHandler Apache::StatINC

# For Mod_Perl 2.X
#PerlInitHandler Apache::Reload

# For SQL version of @Mail
PerlRequire "/www/atmail3/modperldb.pl"

# For Flat-file version of @Mail
#PerlRequire "/www/atmail3/modperlfile.pl"

<Directory "/path/to/atmail/">

<Files ~ ".pl$">
SetHandler perl-script

# For Mod_Perl 1.X
PerlHandler Apache::Registry

# For Mod_Perl 2.X
# PerlHandler ModPerl::Registry

Options +ExecCGI
PerlSendHeader On
</Files>

<Files ~ "spell.pl$">
SetHandler cgi-script
</Files>

# Disable Mod_Perl for the WAP feature (not supported)
<Files ~ "wap.pl$">
SetHandler cgi-script
</Files>
</Directory>

<Directory "/www/atmail3/webadmin">

<Files ~ ".pl$">
SetHandler cgi-script
Options +ExecCGI
</Files>

</Directory>
</IfModule>

Before simply copy and pasting the above into the httpd.conf you must have a basic understanding what the configuration does.
Each configuration line is described below.
<IfDefine HAVE_PERL>
LoadModule perl_module modules/libperl.so
</IfDefine>


<IfDefine HAVE_PERL>
AddModule mod_perl.c
</IfDefine>
By default the above lines should be already defined in your httpd.conf when Mod_Perl was installed. The configuration will load the libperl.so module (created by the Mod_Perl installation) into the Webserver. This combines the Perl interpreter into the Webserver increasing the performance of @Mail.

The IfDefine HAVE_PERL definition will activate if the Webserver was launched with the -DHAVE_PERL argument. You can safely remove the <IfDefine></IfDefine> if you certain Apache is correctly installed with Mod_Perl
# If the perl module is installed, this will be enabled.
<IfModule mod_perl.c>

...

</IfModule>
The next step begins to configure Apache to use Mod_Perl for the @Mail application. The <IfModule> tag encapsulates the commands and will only run if the Mod_Perl library was successfully loaded.
PerlModule Apache::DBI
PerlInitHandler Apache::StatINC
The Apache::DBI line is required only if you are running the SQL version of @Mail. The module creates a persistent database connection, and avoids creating a new database handle for each process in @Mail.

The Apache::StatINC will automatically restart the Webserver if a library in @Mail is modified ( for Mod_Perl 1.X) . Using Mod_Perl 2.X you must use the definition Apache::Reload

Since Mod_Perl will cache all the @Mail scripts / modules it will not recognize any changes to the runtime modules until the Webserver is restarted (For example, changing the configuration of @Mail via the WebAdmin).

By using Apache::StatINC / Apache::Reload any configuration modules changed in @Mail will be automatically reloaded.
# For the SQL version of @Mail
PerlRequire "/www/atmail3/modperldb.pl"
Or
# For the Flat file version of @Mail
PerlRequire "/www/atmail3/modperlflat.pl"
This will pre-load the modperldb.pl or modperlflat.pl script into the parent process in Apache. Depending on your setup choose the corresponding PerlRequire line. These scripts pre-loaded common library's shared in @Mail to reduce files re-loading each Apache process.

For running the SQL version of @Mail, each Apache process will open a mySQL connection to the server. This is required to create a persistent database connection and speed-up Web-requests from users. By default mySQL is installed with a limit of the number of open connections (usually around 50-100) . It is highly recommended you increase this value in the /etc/my.cnf file to avoid the mySQL server denying new connections.

If you are using Mod_Perl 2.X , the above PerlRequire file must be modified to include the following module at the top of the document.

use Apache::compat;

This will allow the new Mod_Perl version to correctly run with the backwards compatability of Mod_Perl 1.X
/etc/my.cnf:
           
[mysqld]
set-variable = max_user_connections=500
set-variable = max_connections=500
The modperldb.pl or modperlflat.pl script will setup the library path for Apache::StatINC to recognize the module path in @Mail. The script will also create the persistent database connection to the SQL server.
<Directory "/www/atmail3/">

<Files ~ ".pl$"> 
           SetHandler perl-script
           PerlHandler Apache::Registry
           Options +ExecCGI
           PerlSendHeader On
</Files>

<Files ~ "spell.pl$">
           SetHandler cgi-script
</Files>

</Directory>
The configuration above sets up the /www/atmail3/ directory with Mod_Perl. Replace the directory with the full pathname to @Mail installed on your server.

Any files with the .pl extension in the /www/atmail3/ directory will be enabled to use Mod_Perl. The webserver will cache the script contents and setup the Apache::Registry environment to handle the requests.

The spell.pl file is excluded from Mod_Perl since it is not supported. The script uses an external binary that is not compatible with Mod_perl.
<Directory "/www/atmail3/webadmin">
<Files ~ ".pl$">
SetHandler cgi-script
Options +ExecCGI
</Files>
</Directory>
</IfModule>
The above will disable Mod_Perl from the @Mail WebAdmin. The WebAdmin is not compatible with Mod_Perl, and can safely be run under normal CGI mode.

The next step is to configure the @Mail scripts with Mod_Perl support. Via the command line run the change-lib.pl script with the pathname to the atmail/libs directory and modperl as the second argument. For example:
           server# cd /path/to/atmail/
           server# perl change-lib.pl /path/to/atmail/libs/ modperl

3 How @Mail works with Mod_Perl

Apache loads the Perl interpreter once into memory and never needs to load it again. Each @Mail script is only compiled once. The compiled version is then kept into memory and used each time the program is run. In this way there is no extra overhead when accessing a page within @Mail.

4 Test @Mail is working with Mod_Perl

On you have included the Mod_Perl configuration to httpd.conf you can restart the Webserver using:

apachectl restart

Or kill -HUP the httpd processes on the server.

Once restarted verify the Webserver is starting. Check the Apache ErrorLog contains the following string:

[notice] Apache/1.3.12 (Unix) (Red Hat/Linux) mod_perl/1.24 configured -- resuming normal operations

If you see the mod_perl/1.XX configured you have successfully setup the Webserver with Mod_Perl

The next step is to run the atmail/change-lib.pl script via the command line to enable Mod_Perl support in the @Mail scripts.

To test the @Mail pages are loading with Mod_Perl visit the index page within @Mail. For example http://localhost/atmail/index.pl

Once the login page is loaded click View Source in your web-browser. Towards the end of the HTML file you should see the following comment:



If you see the text above, congratulations you have successfully installed Mod_Perl on your webserver with @Mail.

5 Troubleshooting

While Mod_Perl is easy to setup there are several pitfalls along the way.

This section of the Mod_Perl document will cover common errors that can occur during setup of @Mail with Mod_Perl
Mod Perl installed but the @Mail performance does not improve
Check you have correctly edited the correct httpd.conf for your system. Verify you have followed the steps in Section 4.

Check the Mod_Perl definition points to the correct @Mail Directory.

For example of an incorrect Webserver configuration:

@Mail is installed at:
/usr/home/httpd/html/atmail3/
The WebServer httpd.conf specify's the DocumentRoot for the Webserver is at:
DocumentRoot /www/
# Mod Perl setup for @Mail

<Directory "/usr/home/httpd/html/atmail3/"> .. </Directory>
Since the DocumentRoot does not match the installation of @Mail the directory Mod_Perl will not be correctly enabled.

Solution:

Change the atmail installation directory to:
/www/atmail3/
Which is contained in the DocumentRoot of your Webserver. Change all references to the old installation directory to the new pathname in httpd.conf.

Follow the steps in Section 4 to test Mod_Perl is enabled.
Apache will not start , error 'Apache::DBI could not be found ...'
If you are running the SQL version of @Mail you must install the Apache::DBI module for Mod_Perl. The install.pl script will automatically install this module if missing.

To manually install:
prompt# cd atmail/libs/src/Apache-DBI/
prompt# perl Makefile.PL ; make ; make install
I cannot install @Mail with Mod_Perl correctly. Even though the Webserver is installed with Mod_Perl, the inital login page of @Mail does not show the MOD_PERL footer in the source.

Just double check the definition for Mod_Perl points to the real location of the directory, not an alias/symlink ( This is a common error )

I am running Mod_Perl 2.X and I receive the following in the WebServer error_log : failed to resolve handler `Apache::Registry'

Mod_Perl 2.X uses the ModPerl::[module] namespace for Apache. You must change the Apache::Registry line in the httpd.conf to read ModPerl::Registry . See the example httpd.conf at the top of the document for steps on how to configure.

After installing @Mail for Mod_Perl 2.X I receive the following in the Webserver error_log : ModPerl::Registry: Can't locate Apache/Constants.pm

The PerlRequire file defined in the httpd.conf ( /path/to/atmail/modperldb.pl or /path/to/atmail/modperlfile.pl ) must have the following defined at the top of the script:

use Apache::compat;

This will allow the Mod_Perl 2.X to correctly run with the backwards compatability of Mod_Perl 1.X

After installing @Mail for Mod_Perl 2.X I receive the following in the Webserver error_log : Can't locate Apache/StatINC.pm

The Apache::StatINC module is used to reload scripts in the Webserver cache that have changed on disk. The Apache::StatINC definition in the httpd.conf must be replaced to Apache::Reload for the new Mod_Perl 2.X branch.