Atmail ActiveSync 2.2.10 Installation Guide

PROBLEM

I need to install atmail ActiveSync.

ENVIRONMENT

• On-Premise Server + WebMail Installations: Version 7.4+
• Webmail Only Installations: Version 7.4+

CAUSE

ActiveSync requirement.

RESOLUTION

Since atmail 7.4, atmail requires an extra package for ActiveSync. With the release of atmail 7.8.0, a newer version of atmail ActiveSync is also available. This package is available for download via the "Downloads" section of your Atmail Customer Portal.

Requirements

• atmail 7.4.0+
• POSIX (php-process) Extension for PHP
• atmail 7.4.0+ must be already installed
• Valid license to use ActiveSync with atmail
• Operating System

  Since Atmail ActiveSync is based on PHP, it can be ported into any platform that supports and/or compiles PHP. Currently, Atmail supports the following environments:

  • Redhat Enterprise 6.x and 7.x only
  • CentOS 6.x and 7.x only
  • Ubuntu 14.x only

How to install

Download

You will first need to download the atmail ActiveSync package from within your Atmail Customer Portal. Login at https://atmail.com/portal2/ and go to the "Downloads" page. Here you will find a link to download the Atmail ActiveSync package.

Installation

1. Create /usr/share/push/ directory.

   mkdir /usr/share/push

2. Place the downloaded file any where on your server and extract as follows.

   tar xfvz atmail7.push.xxx.tgz -C /usr/share/push/

   Change the file name to match the file you downloaded. Each customer will be provided with a unique file name.

3. Ensure correct permissions for the /usr/share/push/ directory.

   chown -R atmail:apache /usr/share/push/

4. Run atmail ActiveSync installation.

   php /usr/share/push/install.php

5. Example Installation

   [root@mail195 share]# mkdir /usr/share/push
   [root@mail195 share]# tar xvzf atmail7.push.aaa7f54fb0e2d419bd0b11556d41f1e2.tgz -C /usr/share/push/
   INSTALL
   LICENSE
   README
   autodiscover/
   autodiscover/INSTALL
   autodiscover/autodiscover.php
   autodiscover/config.php
   autodiscover/response.xml
   backend/
   backend/imap/
   backend/imap/imap.php
   tar: backend/imap/imap.php: time stamp 2016-07-29 10:45:31 is 7370.93892324 s in the future
   backend/README.IMAP
   backend/caldav.php
   backend/combined/
   backend/combined/importer.php
   backend/combined/config.php
   backend/combined/combined.php
   backend/combined/exporter.php
   backend/README.CardDAV
   backend/THANKS
   backend/carddav.php
   backend/AUTHOR
   backend/.htaccess
   config.ini.default
   config.php
   include/
   include/mimeDecode.php
   include/mimePart.php
   include/iCalendar.php
   include/TinyRedisClient.php
   include/Net/
   include/Net/Socket.php
   include/Net/SMTP.php
   include/stringstreamwrapper.php
   include/z_RTF.php
   include/Mail/
   include/Mail/smtp.php
   include/Mail/mail.php
   include/Mail/sendmail.php
   include/Translation.php
   include/AWLUtilities.php
   include/z_RFC822.php
   include/RFC822.php
   include/XMLDocument.php
   include/Auth/
   include/Auth/SASL/
   include/Auth/SASL/Login.php
   include/Auth/SASL/Anonymous.php
   include/Auth/SASL/CramMD5.php
   include/Auth/SASL/External.php
   include/Auth/SASL/Plain.php
   include/Auth/SASL/DigestMD5.php
   include/Auth/SASL/Common.php
   include/Auth/SASL/SCRAM.php
   include/Auth/SASL.php
   include/Mail.php
   include/z_carddav.php
   include/caldav-client-v2.php
   include/.htaccess
   include/XMLElement.php
   index.php
   install.php
   lib/
   lib/z-push/
   lib/z-push/.htaccess
   lib/utils/
   lib/utils/compat.php
   lib/utils/timezoneutil.php
   lib/utils/zpushadmin.php
   lib/utils/utils.php
   lib/utils/stringstreamwrapper.php
   lib/webservice/
   lib/webservice/webserviceusers.php
   lib/webservice/webservice.php
   lib/webservice/webservicedevice.php
   lib/default/
   lib/default/redisstatemachine.php
   lib/default/sqlstatemachine.php
   lib/default/searchprovider.php
   lib/default/filestatemachine.php
   lib/default/backend.php
   lib/default/diffbackend/
   lib/default/diffbackend/exportchangesdiff.php
   lib/default/diffbackend/diffbackend.php
   lib/default/diffbackend/diffstate.php
   lib/default/diffbackend/importchangesdiff.php
   lib/default/filestatemachine.php.bak
   lib/default/simplemutex.php
   lib/core/
   lib/core/interprocessdata.php
   lib/core/pingtracking.php
   lib/core/changesmemorywrapper.php
   lib/core/devicemanager.php
   lib/core/paddingfilter.php
   lib/core/zpush.php
   lib/core/hierarchycache.php
   lib/core/statemanager.php
   lib/core/zlog.php
   lib/core/contentparameters.php
   lib/core/bodypreference.php
   lib/core/streamimporter.php
   lib/core/synccollections.php
   lib/core/asdevice.php
   lib/core/stateobject.php
   lib/core/zpushdefs.php
   lib/core/loopdetection.php
   lib/core/topcollector.php
   lib/core/streamer.php
   lib/core/syncparameters.php
   lib/exceptions/
   lib/exceptions/httpreturncodeexception.php
   lib/exceptions/statenotyetavailableexception.php
   lib/exceptions/provisioningrequiredexception.php
   lib/exceptions/syncobjectbrokenexception.php
   lib/exceptions/wbxmlexception.php
   lib/exceptions/exceptions.php
   lib/exceptions/fatalmisconfigurationexception.php
   lib/exceptions/statenotfoundexception.php
   lib/exceptions/authenticationrequiredexception.php
   lib/exceptions/fatalnotimplementedexception.php
   lib/exceptions/notimplementedexception.php
   lib/exceptions/stateinvalidexception.php
   lib/exceptions/zpushexception.php
   lib/exceptions/fatalexception.php
   lib/exceptions/nopostrequestexception.php
   lib/exceptions/nohierarchycacheavailableexception.php
   lib/exceptions/statusexception.php
   lib/wbxml/
   lib/wbxml/replacenullcharfilter.php
   lib/wbxml/wbxmldecoder.php
   lib/wbxml/wbxmldefs.php
   lib/wbxml/wbxmlencoder.php
   lib/interface/
   lib/interface/ichanges.php
   lib/interface/isearchprovider.php
   lib/interface/ibackend.php
   lib/interface/iimportchanges.php
   lib/interface/istatemachine.php
   lib/interface/iexportchanges.php
   lib/syncobjects/
   lib/syncobjects/syncmailflags.php
   lib/syncobjects/syncmail.php
   lib/syncobjects/synctaskrecurrence.php
   lib/syncobjects/syncappointment.php
   lib/syncobjects/syncbasebody.php
   lib/syncobjects/syncdeviceinformation.php
   lib/syncobjects/syncmeetingrequestrecurrence.php
   lib/syncobjects/synccontact.php
   lib/syncobjects/syncresolverecipientsoptions.php
   lib/syncobjects/synctask.php
   lib/syncobjects/syncuserinformation.php
   lib/syncobjects/syncresolverecipients.php
   lib/syncobjects/syncattachment.php
   lib/syncobjects/syncresolverecipientscertificates.php
   lib/syncobjects/syncappointmentexception.php
   lib/syncobjects/syncresolverecipientsavailability.php
   lib/syncobjects/syncobject.php
   lib/syncobjects/syncresolverecipient.php
   lib/syncobjects/syncresolverecipientspicture.php
   lib/syncobjects/syncoofmessage.php
   lib/syncobjects/syncprovisioning.php
   lib/syncobjects/syncsendmailsource.php
   lib/syncobjects/syncmeetingrequest.php
   lib/syncobjects/syncsendmail.php
   lib/syncobjects/syncattendee.php
   lib/syncobjects/syncbaseattachment.php
   lib/syncobjects/syncrecurrence.php
   lib/syncobjects/syncoof.php
   lib/syncobjects/syncfolder.php
   lib/syncobjects/syncitemoperationsattachment.php
   lib/syncobjects/syncnote.php
   lib/syncobjects/syncdevicepassword.php
   lib/syncobjects/syncvalidatecert.php
   lib/request/
   lib/request/folderchange.php
   lib/request/search.php
   lib/request/getattachment.php
   lib/request/getitemestimate.php
   lib/request/requestprocessor.php
   lib/request/validatecert.php
   lib/request/provisioning.php
   lib/request/meetingresponse.php
   lib/request/itemoperations.php
   lib/request/ping.php
   lib/request/resolverecipients.php
   lib/request/settings.php
   lib/request/notify.php
   lib/request/sync.php
   lib/request/foldersync.php
   lib/request/moveitems.php
   lib/request/request.php
   lib/request/sendmail.php
   lib/request/gethierarchy.php
   lib/.htaccess
   log/
   log/.htaccess
   sql/
   sql/.htaccess
   sql/push.sql
   version.php
   [root@mail195 share]# chown -R atmail:apache /usr/share/push/
   
   [root@mail195 share]# php /usr/share/push/install.php
   Welcome to Push Installation
   ----------------------------------
   
   PHP Version: 5.4.45
   
   This script will setup the Push Service for your system
   
   When requesting your input during the installation the default values are
   presented within square brackets -- to choose the default value, hit "Enter"
   
   [Press Enter to Continue]
   
   Install Prerequisites
   ---------------------
   
   The installer will check your system has the required PHP runtime settings.
   You can install the optional PHP extensions via your system package manager or
   via the PHP pecl system. The installer will also scan your php.ini
   configuration file and make the required adjustments for Push.
   
   
   Required Extensions:
    * POSIX (php-process) Extension for PHP: OK
    * IMAP (php-imap) Extension for PHP: OK
    * MySQL (php-mysql) Extension for PHP: OK
    * MBString (php-mbstring) Extension for PHP: OK
    * DOM (php-xml) Extension for PHP: OK
   
   [Press Enter to Continue with installation]
   
   IMAP Backend Setup 
   --------------------
   
   The following few prompts will set up your Imap Backend for Push.
   You will need to supply a valid IMAP Hostname.
   
   Enter your Push IMAP server's hostname or IP address [127.0.0.1]: 
   
   Enter your Push IMAP server's protocol 
   1- No SSL 
   2- SSL [1]: 
   
   Enter your Push IMAP server's port  [143]: 
   
   CalDav Backend Setup 
   --------------------
   
   The following few prompts will set up your CalDav Backend for Push.
   You will need to supply a valid CalDav Hostname.
   
   Enter your Push CalDav server's hostname or IP address  [127.0.0.1]: 
   
   Enter your Push CalDav server's protocol
   1-http 
   2-https  [1]: 
   
   Enter your Push CalDav server's port  [8008]: 
   
   CalDav Backend Setup 
   --------------------
   
   The following few prompts will set up your CardDav Backend for Push.
   You will need to supply a valid CardDav Hostname.
   
   Enter your Push CardDav server's hostname or IP address [127.0.0.1]: 
   
   Enter your Push CardDav server's protocol
   1-http 
   2-https [1]: 
   
   Enter your Push CardDav server's port  [8008]: 
   
   MySQL Database Setup 
   --------------------
   
   The following few prompts will set up your MySQL Database for Push.
   You will need to supply an MySQL user that has permission to create databases.
   
   Enter your Push MySQL server's hostname or IP address [127.0.0.1]: 
   
   Enter username for database [root]: 
   
   Enter password for root: 
   
   Connected to MySQL Server!
   
   Select the database to use or enter the name of a new database to create:
   
   [1] information_schema
   [2] atmail7
   [3] mysql
   [4] test
   
   Choose the name you would like to use for the MySQL database for the Push system. Databases already present are listed above, if you want to choose one of those as the Push database then select the appropriate number from the list. Otherwise, enter the name that you would like to use. A typical name for the Push database is 'push' but you can choose any database name that is appropriate for your system (choose a number from the list or enter a name for a new database): atmail7push
   
   The database atmail7push was created for Push
   
   Creating Push database tables on atmail7push...
   Push tables successfully created.
   
   
   Redis State Machine Setup 
   --------------------
   
   An optional Redis state machine can be installed to improve performances on large infrastructures.
   
   Do you want to use Redis state machine [No]: 
   
   WebServer Configuration
   -----------------------
   An Alias tag is required to enable Microsoft Exchange ActiveSync Push services on your server.
   
   -> Add the following to the apache conf file. You must do this manually (for advanced
   httpd.conf configurations) or select to automatically edit the configuration
   file below.
   
   Append the following to the httpd.conf:
   
   Alias /Microsoft-Server-ActiveSync /usr/share/push/index.php
   
   Edit webserver configuration automatically? [Y]: 
   
   
   The installer has edited your httpd.conf.
   
   For changes to take effect, you are required to restart  Apache.
   The installer can attempt to restart Apache (if this fails, restart the
   Apache service manually).
   
   Restart HTTPD automatically? [Y]: 
   Stopping httpd:                                            [  OK  ]
   Starting httpd:                                            [  OK  ]
   
   
   Install completed

Troubleshooting

Ubuntu Permissions

If you are installting atmail ActiveSync onto an Ubuntu machine, you will find the following error at the end of the installation.

Edit webserver configuration automatically? [Y]: 
chown: invalid group: 'atmail:apache'
chown: invalid group: 'atmail:apache'

To resolve, set permisions as follows.

Atmail Server + Webmail Installation

root@ubuntu:# chown -R atmail:atmail /usr/share/push

Atmail WebMail Client Only Installation

root@ubuntu:# chown -R [webserveruser]:[webserveruser] /usr/share/push

Where [webserveruser] is the user which runs Apache

Apache 2.4.X

With Apache 2.4.X, you may have a 403 forbiden error. To resolve, you need to add the following into your Apache configuration file.

<Directory /usr/share/push>
Require all granted
</Directory>

Extra Information

Atmail ActiveSync 2.2.10 has been tested and confirmed working with the following devices, using the default mail applications available on them.

• Samsung Galaxy s5 with Android 5.0
• Samsung Galaxy s5 with Android 6.0.1
• Samsung Galaxy Note 5 with Android 6.0.1
• LG Nexus 5 with Android 6.0.1
• Sony Xperia Z3  with Android 5.1.1
• Apple iPhone 6 with iOS 9.3.4
• Apple iPod 2 with iOS 6.1.6 (10B500) (Notes: Does not support unicode/utf8 characters)