I decided to set myself a little challenge to get ActiveSync working for free for a project I am working on. Most ActiveSync clients on the market are licensed directly from Microsoft.
I have an email service from the excellent MXRoute http://www.mxroute.com and I am not using the service much, they don’t currently offer a mobile solution so I thought I would see if it is possible to use a small virtual private server (VPS) to connect to IMAP and pass it to my mobile, turns out you can! I am using MXRoutes London servers, you will need to change the config if you are using any other locations.
Using Z-PUSH (2.3.5) to connect to MX Route
Known Issues:
Z-push syncs the shared address book, I haven’t worked out how to stop this, it’s a minor issue, but you do need to be aware of it.
Z-push fails to get the name of the calendar, so on an activesync device the calendar name shows up as unknown, but it works.
Z-push pulls the tasks through as a calendar, I have turned off syncing tasks.
Z-push itself isn’t the most reliable platform. This isn’t an issue per se, but it is something you need to be aware of.
Pre-Reqs
A VPS or server, I am running Ubuntu 16.04 LTS A MXRoute account Apache installed with an SSL cert (I’m using letencrypt) PHP7 with php-cli and php-soap Instructions
Add the z-push repo by creating /etc/apt/sources.list.d/z-push.list with the content
deb http://repo.z-hub.io/z-push:/final/Ubuntu_16.04/ /
Download and add the repo key to the keychain
wget -qO – http://repo.z-hub.io/z-push:/final/Debian_8.0/Release.key | sudo apt-key add –
Run apt-get update
We then need to install the z-push packages that we need
apt-get install z-push-common z-push-config-apache z-push-backend-caldav z-push-backend-carddav z-push-backend-combined z-push-backup-imap z-push-ipc-sharedmemory
This will install and configure z-push ready to go, we now need to edit the config files to tell it where to get the contacts, calendar and email from.
Start by editing /usr/share/z-push/config.php
Change the section “Default Settings” to match your timezone and ensure that the define(‘USE_FULLEMAIL_FOR_LOGIN’,true); is set to true.
Under the logging settings there is a specialLogUsers value, this is really useful to put a user in here when you need to troubleshoot, this generates debug logs for the named user and which can be found in the /var/log/z-push directory, but remember to remove them when you have done your testing as they can generate massive log files.
The only other setting we need to change is the Backend settings.
Change the backend provider setting to:
define(‘BACKEND_PROVIDER’,’BackendCombined’);
Save and exit the file
Next edit the /usr/share/z-push/backend/combined/config.php
Update it to match the following values
‘backends’ => array(
‘i’ => array(
‘name’ => ‘BackendIMAP’,
),
‘d’ => array(
‘name’ => ‘BackendCardDAV’,
),
‘c’ => array(
‘name’ => ‘BackendCalDAV’,
),
),
‘delimiter’ => ‘/’,
//force one type of folder to one backend
//it must match one of the above defined backends
‘folderbackend’ => array(
SYNC_FOLDER_TYPE_INBOX => ‘i’,
SYNC_FOLDER_TYPE_DRAFTS => ‘i’,
SYNC_FOLDER_TYPE_WASTEBASKET => ‘i’,
SYNC_FOLDER_TYPE_SENTMAIL => ‘i’,
SYNC_FOLDER_TYPE_OUTBOX => ‘i’,
// SYNC_FOLDER_TYPE_TASK => ‘c’,
SYNC_FOLDER_TYPE_APPOINTMENT => ‘c’,
SYNC_FOLDER_TYPE_CONTACT => ‘d’,
SYNC_FOLDER_TYPE_NOTE => ‘c’,
SYNC_FOLDER_TYPE_JOURNAL => ‘c’,
SYNC_FOLDER_TYPE_OTHER => ‘i’,
SYNC_FOLDER_TYPE_USER_MAIL => ‘i’,
SYNC_FOLDER_TYPE_USER_APPOINTMENT => ‘c’,
SYNC_FOLDER_TYPE_USER_CONTACT => ‘d’,
SYNC_FOLDER_TYPE_USER_TASK => ‘c’,
SYNC_FOLDER_TYPE_USER_JOURNAL => ‘c’,
SYNC_FOLDER_TYPE_USER_NOTE => ‘c’,
SYNC_FOLDER_TYPE_UNKNOWN => ‘i’,
),
//creating a new folder in the root folder should create a folder in one backend
‘rootcreatefolderbackend’ => ‘i’,
);
}
}
This tells z-push which backend is responsible for which function.
Next we need to edit the individual service files we will start with email.
Edit the file /usr/share/z-push/backend/imap/config.php
Update the following values, this is assuming you are using MXRoute’s London servers.
// Defines the server to which we want to connect
define(‘IMAP_SERVER’, ‘london.mxroute.com’);
// connecting to default port (143)
define(‘IMAP_PORT’, 993);
// best cross-platform compatibility (see http://php.net/imap_open for options)
define(‘IMAP_OPTIONS’, ‘/ssl/norsh’);
// Mark messages as read when moving to Trash.
// BE AWARE that you will lose the unread flag, but some mail clients do this so the Trash folder doesn’t get boldened
define(‘IMAP_AUTOSEEN_ON_DELETE’, false);
// Since I know you won’t configure this, I will raise an error unless you do.
// When configured set this to true to remove the error
define(‘IMAP_FOLDER_CONFIGURED’, true);
// Folder prefix is the common part in your names (3, 4)
define(‘IMAP_FOLDER_PREFIX’, ”);
// Inbox will have the preffix preppend (3 & 4 to true)
define(‘IMAP_FOLDER_PREFIX_IN_INBOX’, false);
// Inbox folder name (case doesn’t matter) – (empty in 4)
define(‘IMAP_FOLDER_INBOX’, ‘INBOX’);
// Sent folder name (case doesn’t matter)
define(‘IMAP_FOLDER_SENT’, ‘inbox.SENT’);
// Draft folder name (case doesn’t matter)
define(‘IMAP_FOLDER_DRAFT’, ‘inbox.DRAFTS’);
// Trash folder name (case doesn’t matter)
define(‘IMAP_FOLDER_TRASH’, ‘inbox.TRASH’);
// Spam folder name (case doesn’t matter). Only showed as special by iOS devices
define(‘IMAP_FOLDER_SPAM’, ‘inbox.junk’);
// Archive folder name (case doesn’t matter). Only showed as special by iOS devices
define(‘IMAP_FOLDER_ARCHIVE’, ‘ARCHIVE’);
You also want to update the method used for sending emails (I am using an SSL connection to MXRoute)
define(‘IMAP_SMTP_METHOD’, ‘smtp’);
global $imap_smtp_params;
$imap_smtp_params = array(‘host’ => ‘ssl://london.mxroute.com’, ‘port’ => 465, ‘auth’ => true, ‘username’ => ‘imap_username’, ‘password’ => ‘imap_password’ );
The above ‘imap_username’ and ‘imap_password’ are variables and do not need changing to the actual username and password.
Save and close the file.
Next we will setup syncing contacts
Edit /usr/share/z-push/backend/carddav/config.php update the following
// Server protocol: http or https
define(‘CARDDAV_PROTOCOL’, ‘https’);
// Server name
define(‘CARDDAV_SERVER’, ‘london.mxroute.com’);
// Server port
define(‘CARDDAV_PORT’, ‘2080’);
// Address book path
define(‘CARDDAV_PATH’, ‘/rpc/addressbooks/%u/’);
// Server path to the default address book
define(‘CARDDAV_DEFAULT_PATH’, ‘contacts/’);
// Support sync-collection
define(‘CARDDAV_SUPPORTS_SYNC’, false);
Save and close the file
Finally the calendar sync
Edit /usr/share/z-push/backend/caldav/config.php
// Server protocol: http or https
define(‘CALDAV_PROTOCOL’, ‘https’);
// Server name
define(‘CALDAV_SERVER’, ‘london.mxroute.com’);
// Server port
define(‘CALDAV_PORT’, ‘2080’);
// Path
define(‘CALDAV_PATH’, ‘/rpc/calendars/%u/’);
// Default CalDAV folder (calendar folder/principal). This will be marked as the default calendar in the mobile
define(‘CALDAV_PERSONAL’, ‘calendar’);
// If the CalDAV server supports the sync-collection operation
// DAViCal, SOGo and SabreDav support it
// SabreDav version must be at least 1.9.0, otherwise set this to false
// Setting this to false will work with most servers, but it will be slower
define(‘CALDAV_SUPPORTS_SYNC’, false);
// Maximum period to sync.
// Some servers don’t support more than 10 years so you will need to change this
define(‘CALDAV_MAX_SYNC_PERIOD’, 2147483647);
Save and close the file
Although not necessarily I restart apache at this point.
service apache2 restart
On your client device (iOS / Android / Outlook 2013+)
As there is no autodiscovery function you will need to enter the settings manually.
Username: Full email address
Password: Users MXRoute Password
Server: Your VPS address (i.e. z-push.yourdomain.com)
Basic Troubleshooting
Check the apache and z-push logs, both of which can be found in /usr/var/log/
Turn on debugging for a single user (see above for details)
Check you can access activesync on your server https://z-push.yourdomain.com/Microsoft-Server-ActiveSync, you should be promoted for a username and password use the email address and the users mxroute password, you should see a page that gives you the activesync information and tell you that “GET is not supported”.
You should now be good to go!
