help centre
For more info visit status.atmail.com

How can we help?


Search our knowledge base for answers to
common questions and latest updates.



My activities New request

Follow

atmail ActiveSync 2.3.2 Upgrade Guide

Stewart -

PROBLEM

I need to install atmail ActiveSync.

ENVIRONMENT

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

CAUSE

ActiveSync requirement.

RESOLUTION

Since atmail 7.4, atmail requires an extra package for ActiveSync. With the release of atmail 7.8.0.1, 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.8.0.1
  • apache 2.4 only
  • POSIX (php-process) Extension for PHP
  • atmail 7.8.0.1+ 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 upgrade

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.

Note: The atmail ActiveSync download will only be shown in your atmail Customer Portal if your license allows the use of ActiveSync.

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. Ubuntu Requirement:
    apt-get install php5-xsl php5-curl php5-imap
    sudo php5enmod imap
    sudo php5enmod curl
    sudo php5enmod xsl
    sudo apachectl restart
  4. Run atmail ActiveSync installation.

    cd /usr/share/push
    php install.php
  5. At the MySQL Database Setup section, create a new database. A new database is required for the newer verion of ActiveSync.
  6. Example Installation

    [root@localhost /]# mkdir /usr/share/push
    [root@localhost /]# tar xvzf push.xxx.tgz -C /usr/share/push/
    DEVELOPMENT
    INSTALL
    LICENSE
    README
    autodiscover/
    autodiscover/INSTALL
    autodiscover/autodiscover.php
    autodiscover/config.php
    autodiscover/response.xml
    backend/
    backend/imap/
    backend/imap/mime_encode.php
    backend/imap/mimePart.php
    backend/imap/Net/
    backend/imap/Net/Socket.php
    backend/imap/Net/SMTP.php
    backend/imap/config.php
    backend/imap/Mail/
    backend/imap/Mail/smtp.php
    backend/imap/Mail/mail.php
    backend/imap/Mail/sendmail.php
    backend/imap/REQUIREMENTS
    backend/imap/user_identity.php
    backend/imap/Auth/
    backend/imap/Auth/SASL/
    backend/imap/Auth/SASL/Login.php
    backend/imap/Auth/SASL/Anonymous.php
    backend/imap/Auth/SASL/CramMD5.php
    backend/imap/Auth/SASL/External.php
    backend/imap/Auth/SASL/Plain.php
    backend/imap/Auth/SASL/DigestMD5.php
    backend/imap/Auth/SASL/Common.php
    backend/imap/Auth/SASL/SCRAM.php
    backend/imap/Auth/SASL.php
    backend/imap/Mail.php
    backend/imap/THANKS
    backend/imap/README
    backend/imap/imap.php
    backend/imap/mime_calendar.php
    backend/caldav/
    backend/caldav/config.php
    backend/caldav/REQUIREMENTS
    backend/caldav/caldav.php
    backend/caldav/AUTHOR
    backend/ipcmemcached/
    backend/ipcmemcached/ipcmemcachedprovider.php
    backend/ipcmemcached/config.php
    backend/carddav/
    backend/carddav/config.php
    backend/carddav/REQUIREMENTS
    backend/carddav/THANKS
    backend/carddav/README
    backend/carddav/carddav.php
    backend/combined/
    backend/combined/importer.php
    backend/combined/config.php
    backend/combined/combined.php
    backend/combined/exporter.php
    backend/ipcsharedmemory/
    backend/ipcsharedmemory/ipcsharedmemoryprovider.php
    backend/.htaccess
    backend/sqlstatemachine/
    backend/sqlstatemachine/sqlstatemachine.php
    backend/sqlstatemachine/config.php
    composer.json
    config.php
    cron/
    cron/fixstates.sh
    include/
    include/mimeDecode.php
    include/iCalendar.php
    include/z_RTF.php
    include/Translation.php
    include/AWLUtilities.php
    include/z_RFC822.php
    include/XMLDocument.php
    include/z_carddav.php
    include/z_caldav.php
    include/.htaccess
    include/XMLElement.php
    index.php
    install.php
    lib/
    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/webserviceinfo.php
    lib/webservice/webserviceusers.php
    lib/webservice/webservice.php
    lib/webservice/webservicedevice.php
    lib/log/
    lib/log/log.php
    lib/log/filelog.php
    lib/log/syslog.php
    lib/default/
    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/simplemutex.php
    lib/core/
    lib/core/interprocessdata.php
    lib/core/pingtracking.php
    lib/core/changesmemorywrapper.php
    lib/core/devicemanager.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/unavailableexception.php
    lib/exceptions/statenotyetavailableexception.php
    lib/exceptions/provisioningrequiredexception.php
    lib/exceptions/syncobjectbrokenexception.php
    lib/exceptions/wbxmlexception.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/interface/iipcprovider.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/syncobjects/syncresolverecipientsresponse.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
    policies.ini
    vendor/
    vendor/composer/
    vendor/composer/autoload_classmap.php
    vendor/composer/LICENSE
    vendor/composer/autoload_psr4.php
    vendor/composer/ClassLoader.php
    vendor/composer/autoload_static.php
    vendor/composer/autoload_files.php
    vendor/composer/autoload_namespaces.php
    vendor/composer/autoload_real.php
    vendor/autoload.php
    version.php
    z-push-admin.php
    z-push-top.php
    [root@localhost atmail]# cd /usr/share/push
    [root@localhost push]# php install.php
    Welcome to the push installer
    ----------------------------------

    PHP Version: 5.4.16

    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]

    SELinux Configuration
    ---------------------

    SELinux support is detected as active on your server. The SELinux architecture
    enforces many kinds of mandatory access control policies. Setup of this module is not provided
    in this installer and you must either disable SELinux or configure it correctly to run the application.

    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 IMAP connection options
    The default will provided the best cross-platform compatibility.
     Please see http://php.net/imap_open for all options. [/notls/norsh]:

    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]:

    Enter your Push CalDav root path  [/calendars/%u/]:

    CardDav 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]:

    Enter your Push CardDav root path  [/addressbooks/%u/]:

    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 your Push MySQL server's port [3306]:

    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:

    PHP Deprecated:  Function mysql_list_dbs() is deprecated in /usr/share/push/install.php on line 542
    PHP Deprecated:  mysql_list_dbs(): This function is deprecated; use mysql_query() with SHOW DATABASES instead in /usr/share/push/install.php on line 542
    [1] information_schema
    [2] atmail7
    [3] atmail7logs
    [4] mysql
    [5] performance_schema
    [6] 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

    Table creation will be automatically triggered on first login.
    Writing configuration to ./config.php
    Setting LOGFILEDIR to /usr/share/push/log/
    Writing configuration to ./backend/sqlstatemachine/config.php
    Setting STATE_SQL_SERVER to 127.0.0.1
    Setting STATE_SQL_PORT to 3306
    Setting STATE_SQL_PASSWORD to
    Setting STATE_SQL_DATABASE to atmail7push
    Writing configuration to ./backend/imap/config.php
    Setting IMAP_SERVER to 127.0.0.1
    Setting IMAP_OPTIONS to /notls/norsh
    Setting IMAP_PORT to 143
    Writing configuration to ./backend/caldav/config.php
    Setting CALDAV_SERVER to 127.0.0.1
    Setting CALDAV_PROTOCOL to http
    Setting CALDAV_PORT to 8008
    Setting CALDAV_PATH to /calendars/%u/
    Writing configuration to ./backend/carddav/config.php
    Setting CARDDAV_SERVER to 127.0.0.1
    Setting CARDDAV_PROTOCOL to http
    Setting CARDDAV_PORT to 8008
    Setting CARDDAV_PATH to /addressbooks/%u/
    Configuration written!

    WebServer Configuration
    -----------------------
    An Alias tag is required to enable Microsoft Exchange ActiveSync Push services on your server.

    -> Add the following to the apache 2.4+ conf file. You must do this manually for advanced
    httpd.conf configurations, or select to automatically edit the configuration
    file below.

    To manually install:
    * Create atmail-activesync.conf with the contents below.
       - OR -
    * Append httpd.conf with the contents below.

    Alias /Microsoft-Server-ActiveSync /usr/share/push/index.php

    Make sure that PHP has the following settings for the directory:
        <Directory /usr/share/push>
            php_flag magic_quotes_gpc off
            php_flag register_globals off
            php_flag magic_quotes_runtime off
            php_flag short_open_tag on
            Require all granted
        </Directory>
    Create atmail-activesync.conf 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]:


    It is recommended to add a CRON job that periodically ensures stale states are removed (~weekly) :
    ./cron/fixstates.sh

    Install completed

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.3.2 has been tested and confirmed working with the following devices, using the default mail applications available on them. Alternate devices that support ActiveSync should work without issue, however untested.

  • Samsung Galaxy s5 with Android 6.0.1
  • Samsung Galaxy s7 Edge with Android 6.0.1
  • Samsung Galaxy Tab 3 with Android 4.4.2
  • LG Nexus 5 with Android 6.0.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)
  • Nokia Lumia 635 with Windows OS 8.10.12397.895 [CYAN]
Have more questions? Submit a request

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com