1. @Mail Source Introduction and the Install Script

1.0 Pre-install and dependencies

1.1 Install Script

2. Manual Install

2.1 Exim Binary

2.2 SpamAssassin

2.3 Courier-IMAP

2.4 @Mail User and Apache

2.5 Final Installation

3. Post-Install

4. Troubleshooting

5. Contact Support

1. @Mail Server Source Introduction and the Install Script

The source-installation can be used to setup the complete Mailserver/WebMail mode of @Mail. This document will illustrate how to configure the @Mail software from source. If you only want to setup the WebMail client, please refer to the WebMail-source installation guide.

1.0 Pre-install and Dependencies

@Mail requires the following software to be installed 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/
  
• A version of the gcc compiler and the make utility may be required to compile the SMTP and POP3/IMAP server modules
  
• PHP

• PHP 5.0+ recommended . Minimum PHP 4.3+ required - PHP is required and is usually installed by default with most Linux Distributions and Unix Variants.

• Additional libraries:

• openssl and openssl-devel
• zlib and zlib-devel (or libz for other distributions)
• db and db-devel
• gdbm and gdbm-devel (only if db libraries are not installed)
• gcc-c++ (G++)

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/server-rpm.html

1.1 Install Script

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

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

For non Linux systems ( FreeBSD, Solaris, etc ) before running the server-install.php script, the username 'atmail' must be created as a system account. Using the useradd/adduser utility depending on your OS. The UID of the new user must be UID 3000. For Linux systems the server-install.php script will automatically add the user-account to the system.

You run the installation script by running the following commands:

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

# cd /usr/local/atmail/

# php server-install.php

@Mail must be installed under the default pathname of /usr/local/atmail/ - The atmail5.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 server-install.php:

Welcome to @Mail 5.0 Mail-Server Installation
---------------------------------

PHP Version: <your php version>
@Mail Version: 5.0
Build Date: <date>
Operating System: Linux

This script will setup @Mail in Server Mode. This allows you to manage user accounts via the @Mail WebAdmin interface and provides the ability (optional) for users to sign up for an email account via the web.

@Mail is a complete mailserver solution. It will replace any existing SMTP, POP3 and IMAP services on your server.

If you are upgrading from another version of @Mail, please see the upgrade tutorial at: http://support.atmail.com/upgrade.html

When requesting your input during the installation the default values are presented within square brackets [] -- to choose the default, simply press Enter.

[Press Enter to Continue]

The following few prompts will set up your MySQL Database for @Mail. You will need to supply a MySQL user that has permission to create databases.

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 than opening a TCP/IP connection.

MySQL Database Setup

First, specify the IP or hostname of your mysql server:

Enter MySQL server's hostname [localhost]:

Enter which username to use when connecting to the database server. The user needs
full permissions over the table to modify/read/write

Enter username for creating database [root]:

Enter the password for root to connect

Enter password for root: []:

MySQL Database system configuration for @Mail

After this step you will have the option of creating the tables for the @Mail database, and test the MySQL configuration details are correct.

Then, continue:

Groupware Module
----------------

@Mail includes an optional Groupware module allowing users and groups on the system to share Calendar, Address-book and Task data.

Enable Groupware Support? [Y]:

WebServer Configuration
-----------------------

Select the location of your httpd.conf or enter the full path if not listed:

[1]/etc/httpd/conf/httpd.conf
...

Enter choice or the full path:

Choose from the list of detected configuration files or enter the full path to your httpd.conf to proceed. Next you will specify the location of your webserver binary (should be detected if apache is running):

Specify the binary location of your Webserver: [/usr/sbin/httpd]:

Next, the script will scan the webserver configuration and make any necessary changes. Choose yes when prompted to edit httpd.conf automatically (unless you have a specific reason not to, and intend to make the changes manually at a later time.

Reading /etc/httpd/conf/httpd.conf: Found expires-module support ...

@Mail is scanning your WebServer Configuration. The webserver
may require configuration to recognize @Mail.

DocumentRoot: /var/www/html

Htaccess files permitted: OK
Alias URL setup for @Mail: FAIL
Default Character Encoding: OK

Webserver permissions for atmail: FAIL

Solution:
The runtime Webserver user must be changed from apache
to the username 'atmail' . This is required for @Mail Server Mode.

-> Add the following to /etc/httpd/conf/httpd.conf. You must do this manually
(for advanced httpd.conf configurations) or select to automatically
edit the configuration file below.

Replace the following:

User apache

To read:

User atmail

Edit httpd.conf automatically? [Y]:

Groupware and Webserver Configuration

Next you must specify the domain names for which you wish to host email accounts:

Domain Configuration
--------------------

Please specify the domain names for which you wish to
configure @Mail. At least one domain name must be
specified to complete the installation.

Enter domain names for which you wish to host email accounts (separate multiple by a comma): [hostname]:

Domain Name Configuration

Continue to specify the Administrator email address and accept the configuration of Gzip compression and mod_deflate if they are detected as available.

In the next step of configuration, the installation utility will compile the SMTP server ( Exim ), POP3/IMAP server, Spamassassin and optionally the AV scanner from source.

Before installing these modules your system must have the gcc compiler installed with the relevant system libraries/headers ( gcc is installed as standard under common Unix platforms ) .

The mySQL header and library files are also required to be installed before installation. These library files should be installed by default with mysql, otherwise you can obtain the header/library files from the Mysql.com site ( Download the RPM or binary for your selected system, otherwise build the mySQL server from source )

SMTP Configuration

The installation utility can configure the Exim/@Mail SMTP server and automatically
setup the service for outgoing/incoming messages. Before installing the SMTP service
verify any existing SMTP servers have been manually disabled.

Install the SMTP server from source? : [Y]:

....[compile output]....

@Mail SMTP Server Installation: SUCCESSFUL

Installing the SMTP server

@Mail POP3/IMAP Server

By running @Mail as the Email-Server you can setup the additional POP3/IMAP module. This allows users to access their mail-account via any POP3/IMAP client ( Outlook, Eudora, etc) .

Install @Mail POP3/IMAP Server? : [Y]: y

@Mail can allow users to relay messages from your SMTP server using the POP before SMTP feature. When a user successfully authenticates using the POP3/IMAP server, their IP address is added to the SMTP access database.

By default @Mail is setup to allow SMTP-authentication. This allows users to authenticate to send messages via the SMTP server using a mail-client such as Outlook/Eudora.

Enable SMTP Relay for @Mail Users? : [Y]: y

....[compile output]....

@Mail POP3/IMAP Server Installation: SUCCESSFUL

Installing the POP3/IMAP Server

Spamassassin Anti-Spam

Optionally, the Spamassassin mail-filter can be installed to protect user-accounts from Spam messages.

Install Spamassassin from source? : [Y]: y

....[compile output]....

Spamassassin Installation: SUCCESSFUL

Anti-Virus Engine
-----------------

Optionally, the @Mail-Clam AntiVirus engine can be installed to protect user accounts from virus infection.

Install AV Engine from source? : [Y]:

Optional Spamassassin and Anti-Virus Installation

The next [optional] installation step is to run a diagnostic utility to verify local mail delivery for your @Mail system.

The following tests are performed: Account signup, message sending, message viewing via WebMail, and POP3 access. Note that the diagnostic utility can also be used via the graphical Webadmin to verify the installation.

@Mail Diagnostic utility

Testing @Mail for testuser@yourdomain.com...
Running Email-Server tests.

--- Creating account: OK

--- Testing Mail Send: Sendmail: OK - Waiting 7 seconds for mail delivery ...

--- Accessing Mail: Status: OK

--- Viewing Mail messages: OK

--- Checking remote POP3 for testuser@yourdomain.com , testing: Status: OK

--- Delete user: OK

5 tests passed out of 5 ( 100 % )

Successful result of the diagnostic utility

Once the installation is complete, @Mail will start the services via the atmailserver init script and the software can be accessed via the address:

http://youraddress.com/mail/

Here you can access the WebMail interface of @Mail and setup a new email-account at your selected domain. 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. Manual Installation

Begin by creating the atmail user, the account must be created with the UID 3000

# adduser -u 3000 atmail

Next, create the atmail directories and extract the @Mail install tarball:

# tar xvfz atmail4.tgz /usr/local/

2.1 Exim Binary

@Mail uses a modified Exim binary to provide the @Mail SMTP Server, this needs to be compiled before you are able to configure the @Mail Application.

To configure run the script provided in /usr/local/atmail/webmail/modules/buildexim.php

# cd /usr/local/atmail/webmail ; php modules/buildexim.php

This provides the necessary changes in the Makefile and compiles and installs the Exim binary.

Exim will then be installed in /usr/local/atmail/mailserver/*

2.2 SpamAssassin

SpamAssassin is used to provide Filtering and Spam Email Rules for the @Mail system and @Mail users.

Change your directory to the SpamAssassin-@Mail archive, located at /usr/local/atmail/server_source/sa-atmail/

# cd /usr/local/atmail/server_source/sa-atmail/

# export LANG=C

# php Makefile.PL INSTALLDIRS=vendor PREFIX=/usr/local/atmail/spamassassin/ CONFDIR=/usr/local/atmail/spamassassin/etc/ DATADIR=/usr/local/atmail/spamassassin/etc/

[[ this is on a single line ]].

# make install

# chown -R atmail /usr/local/atmail/spamassassin/

Commands for installing SpamAssassin for @Mail

SpamAssassin will then be installed in /usr/local/atmail/spamassassin/ . After installing you must change the ownership of the directory to the @Mail user.

 

2.3 Courier-IMAP

The Courier IMAP/POP3 server provides the email server functionality for the @Mail Server. To install, first extract the tarball to /tmp ( due to permission problems, this should not be in /root ).

# tar xvfz /usr/local/atmail/server_source/courier-atmail.tgz /tmp

# chown -R atmail /tmp

# su atmail

[atmail]$ ./configure --enable-workarounds-for-imap-client-bugs --with-trashquota --prefix=/usr/local/atmail/mailserver/ --without-authpgsql --without-authldap --without-authplain --with-authmysql

[atmail]$ make

[atmail]$ exit

[[back to the root user]]

# make install

# chown -R atmail /usr/local/atmail/mailserver/

# chown root /usr/local/atmail/mailserver/bin/exim*

# chmod 4555 /usr/local/atmail/mailserver/bin/exim

commands for installing Courier IMAP for @Mail

This will install the Courier-IMAP in /usr/local/atmail/mailserver/ . You must set the permissions on the directory as the 'atmail' username, and the Exim binary as root.

2.4 @Mail and Apache

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

AddHandler cgi-script .php

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

<Files ~ ".php$">
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 .php files as PHP scripts, grant permissions over the @Mail directory to be executable and deny .php 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.

For the @Mail Application to be viewable with a browser - the @Mail files located in /usr/local/atmail/webmail need to be owned by the Webserver user, in the Server mode, this requires changing the default User in the Apache Configuration:

# chown -R atmail /usr/local/atmail

Edit the Apache Configuration, httpd.conf - locate the 'User' references and change username to atmail. After editing the httpd.conf restart Apache to reload the configuration file.

2.5 Final Installation

To complete the installation of @Mail, you are required to run the atmail/server-install.php script to setup the runtime configuration and mySQL details.

# cd /usr/local/atmail/webmail/ ; php server-install.php

 

3. Post-Install

@Mail uses the SysV startup scheme, the atmailserver startup script will be located:

/etc/init.d/atmailserver

You can start, restart and stop the services for @Mail, by using these commands after the script, for example:

root# /etc/init.d/atmailserver start

root# /etc/init.d/atmailserver restart

root# /etc/init.d/atmailserver stop

4. Troubleshooting

1. SMTP server doesn't start / No Services are running
   
   Run the following command to start the necessary services for @Mail:
   
   # /etc/init.d/atmailserver start
   
   
2. I can't access the @Mail URL
   
   Check that your Apache Server is running under the atmail user.
   
   
3. Webadmin Interface appears does not prompt for a username/password
   
   Access the Webadmin and go to the Security -> Admin Password menu item and enter a new password: This script will update the /usr/local/atmail/webmail/webadmin/.htpasswd file, any subsequent action in the Webadmin Interface will bring up the authentication window.
   
   
4. I can't access the Webadmin Interface since I forget the username/password
   
   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.
   
   
5. Can't access POP3 / IMAP externally
   
   Review your firewall to allow the following ports:
   
   25 ( SMTP )
   80 ( Web )
   110 ( POP3 )
   143 ( IMAP )
   
   
6. Permission errors or messages can't be received
   
   Check that your @Mail directories are owned by the user atmail . This is required to run as the single user, since the POP3, SMTP, and IMAP daemons run under this username for read/write access. The Webserver must be running as the same username, otherwise the WebMail interface cannot read/modify the users mail-messages.
   
   
7. Can't IP relay or use the SMTP for outgoing messages
   
   Access the Webadmin to specify IP ranges for relay, or enable SMTP-authentication support under the WebAdmin -> Services -> SMTP Settings menu.
   
   
8. I receive the error message "./configure: cannot create /dev/null: permission denied" when compiling the POP3/IMAP server
   
   Verify the /dev/null has the correct permissions. Under some Unix systems, a non root user cannot use /dev/null - Use the following as the solution: chmod 644 /dev/null
   
   
9. When installing the POP3/IMAP server I receive the error: "No rule to make target `../gdbmobj/libgdbmobj.a', needed by `makedatprog'. Stop"
   
   This error can occur if the libgdbm module is missing on your server. This is required to compile database support into the POP3/IMAP server. Install the libgdbm and libgdbm-devel module from the installation CD of your Linux distribution or visit RPM-find to download a copy for your system. After installation of libgdbm, run the server-install.php script again to complete the installation.
   
10. When compiling the POP3/IMAP server I receive the following error "./configure: config.log: Permission denied"
    
    This error message can occur if you are compiling the source-tree, and the parent directory is not owned as the 'atmail' user. As a solution move the directory /usr/local/atmail/server_source/courier-imap to /tmp/courier-imap , then , chown -R /tmp/courier-imap/ and run the configure/make script within the /tmp/courier-imap/ directory
    
11. When compiling the POP3/IMAP server I receive the error "configure: error: --with-authmysql specified but no mysqlclient.so"
    
    @Mail requires the mySQL development library/header files to be correctly installed. Please verfiy you have installed the mySQL development library, and the libmysqlclient.so library exists in your system library path.
    
    You can optionally specify the pathname directly to the mySQL development library/header with the configure script below:
    
    ./configure --enable-workarounds-for-imap-client-bugs --with-trashquota --prefix=/usr/local/atmail/mailserver/ --without-authpgsql --without-authldap --without-authplain --with-authmysql --with-mysql-libs=/usr/local/mysql/lib/mysql/ --with-mysql-includes=/usr/local/mysql/include/mysql/
    
    Where /usr/local/mysql/ is the pathname to the mySQL installation directory
    
12. When compiling Exim, I get the error, "db.h - no such file or directory"
    
    @Mail requires the Berkeley Database libraries, in order to compile Exim with it. To fix, just download the source files from the Sleepycat site (http://www.sleepycat.com), or download the following RPMs:
    
    

    db4
    

    db4-devel

    
    Re-run the installation process, and Exim should compile prophpy.

5 Contact Support

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