Z push
From Kolab Wiki
Contents |
Z push
Z-push (zpush) is an emulation of Microsoft's activesync (Active Sync) protocol. This allows you to sync your pda or phone with a Kolab server, using the phone's support for Microsoft Exchange. Z-Push allows the server to appear like an Exchange Server to the client.
Z-push has a pluggable backend and one for Kolab is currently in development. It's home is: kolabzpush at sourceforge.
This allows 2-way syncing of Kolab's calendar, contacts and (soon) tasks with your Exchange-compliant phone. Email is probably better done using IMAP.
Versions
0.7.4: May 2011
- Corrections version (in push mode the connexions never dead that fall down in some case the server)
0.7.3: December 2010
- Released with Kolab 2.3 Alpha
- Correction for GAL
0.7.2: November 2010
- Improvement for compatibility with Symbian
- Improvement of performances
- Mails
- Zpush 1.5 beta 2
- Autoregistration for folder outside INBOX
- Compatibility for separator / in Shared space
0.6.4: September 2010
- some change for the compatibility with Z-push 1.5
0.6.3: August 2010
- LDAP bind with credentials (not anonymous)
0.6.2: July 2010
- Z-push 1.4
- Many corrections of 0.6.1
0.6.1: July 2010
- it is possible now to choose the folders who must be synchronized
- complete support of contacts ( with photo)
- complete support of "cut of date" for the basic reccurences
- ACL to manage the access to Zpush
- Support of Tasks
- support of emails
- support of Global address book ( Ldap search )
- support of Ipad
- RPMS installation
0.4: April 2010
- FlatMode
- Complete Subfolder Support
- Corrected bugs:
- Accents in folders
- Space in folders
- Memory leak
- Problems with email field with Android
- Alarms of user/* namepace ans shared was displayed
- Sensitivity Private events are shown for user/* namespace
- Sensitivity field support
- Some malformed field (in phone number) can block the synchronization
- Default folders : if default folder is missing the backend try to find one
0.3: March 2010
- First port for Z-push 1.3
- New cache files using 1 file by user in kolabindex
- Cut of Date first implementation
- Resolved Folders problems
- Resolved the default folder on the iphone (no need of the work arround now)
0.2: November 2009
- This version introduces for the I-phone the possibility to synchronize more than one contact folder. You can synchronize for example shared contacts folders
0.1: May 2009
- First release
Archive
Roadmap
- 0.8
- Invitation handling on the mobile phone
- 1.0 2011
- FIRST RELEASE
Installation
Install Z-Push with RPMS
Packages are available at http://files.kolab.org/server/release/kolab-server-2.3.1/
In order to install these packages, you need to have a working version of Kolab 2.2.4 or 2.3.1 installed from the Open-PKG packages. Kolab must be installed, bootstrapped up and running. For more information about installing Kolab see http://files.kolab.org/server/release/kolab-server-2.3.1/ix86-debian5.0/1st.README or http://files.kolab.org/server/release/kolab-server-2.3.1/ix86-debian6.0/1st.README
You need 3 (kolab 2.3) or 4 (kolab 2.2.4) packages :
- kolab-webclient-1.2.0-20100625+activesync3.noarch-debian5.0-kolab.rpm (not needed with Kolab 2.3 alpha) at http://files.kolab.org/incoming/wickert/z-push-testing/
- http://files.kolab.org/server/release/kolab-server-2.3.1/ix86-debian6.0/kolab-z-push-0.7.4-1.ix86-debian6.0-kolab.rpm
- http://files.kolab.org/server/release/kolab-server-2.3.1/ix86-debian6.0/PEAR-Kolab_Zpush-0.1.3-1.ix86-debian6.0-kolab.rpm
- http://files.kolab.org/server/release/kolab-server-2.3.1/ix86-debian6.0/z-push-1.5.2-1.ix86-debian6.0-kolab.rpm
The packages are noarch and thus will work both on Debian 4.0 and 5.0 as well as other distributions. Once you are done, cd into the folder with the packages and run
$ /kolab/bin/openpkg rpm -Uvh *.rpm
(for install with Z-push add the option --nodeps )
FOR 2.2.4 Only
Change this line in /kolab/etc/kolab/template/z-push-config.php.template
OWNERSHIP=@@@webserver_musr@@@:@@@webserver_grp@@@
by
OWNERSHIP=@@@kolab_musr@@@:@@@webserver_grp@@@
define('KOLAB_INDEX',"@@@localstatedir@@@/z-push/kolabindex");
by
define('KOLAB_INDEX',"/kolab/var/z-push/kolabindex");
Another way for 2.2.4
IS to add the Variables missing in /kolab/etc/kolab/kolab.globals webserver_musr :kolab webserver_grp :kolab-n localstatedir : /kolab/var/kolab/www
NB: running, eg debian 5.0.5, you may see an error "package xxxxx is intended for a debian5.0 operating system". You can override this by running
$ /kolab/bin/openpkg rpm -Uvh --ignoreos *.rpm
ATTENTION: You must reset the synchronization on certain mobile.
Test of the configuration
Point your browser to the URL http://kolab.example.com/Microsoft-Server-ActiveSync
You should get an authentication prompt. Try to log in as as known user. You should now see this message:
GET not supported This is the z-push location and can only be accessed by Microsoft ActiveSync-capable devices
If you cannot log in at the authentication prompt, please check that the file
/kolab/var/kolab/www/z-push/config.php is present and contains the correct
values for KOLAB_SERVER and KOLAB_LDAP_BASE. If the file is not present or
does not contain the correct values from /kolab/etc/kolab/kolab.conf,
run kolabconf and restart apache with
$ /kolab/bin/openpkg rc apache restart
Directory organization
Now Logs and kolabindex are moved.
- /kolab/var/kolab/www/z-push : Z-push core with the backend.
- /kolab/var/z-push/log : z-push log access.
- /kolab/var/z-push/kolabindex: backend cache. This directory contain the caches file. There are one cache file by user_serialnumber device .
How to Debug
in case of problems you can have a debug file. Create in z-push directory a file named debug.txt :
$ cd /kolab/var/kolab/www/z-push $ touch debug.txt $ chown kolab-n:kolab-n debug.txt
PLEASE TO HELP US TO DEBUG : Send us in case of problem
* Kolab Version * The Kind of instalation (openpkg, from sources ....) * The part of the access.log * The debug file * Phone type and OS Version
Send your comments , problems on kolab-users Forum
How to select the folders to be synchronized
With Horde Interface (kolab 2.2.4)
you can choose, by folder if you want to synchronize the folder or not
With command line utility ( kolab <= 2.2.4)
Make a first synchronization and retrieve your Mobile serial number :
$ getsyncdevice.php username
IMAP password: <password> serial: A601A162CB2ACD182B1DA04B4101C0CE Device:PocketPC Mode:-1 serial: Appl1E005NU675J Device:iPod Mode:-1 serial: validate Device:Android Mode:-1 serial: androidc259148960 Device:Android Mode:-1
the program display all the devices that have been synchronized for this account
Mark a folder to be synchronized or not for a specific device :
- setsync.php <action> <value> <serial> <folder> <username>
action : alarm to set or unset alarms for this folder. sync to marck or unmark this folder for the synchronization value : 0 to unset 1 to set serial : the device's serial number folder : the IMAP folder username: the kolab user
ex : #setsync.php sync 1 Appl1E005NU675J shared.clients username password : xxxxx
Appl1E005NU675J S:1, A:0 OK wrote the annotation in shared.clients
You can retrieve the setting for a folder with the command getsync.php
- getsync.php shared.clients username
password : xxxxxx Appl1E005NU675J S:1, A:0
S = sync bit A = Alarm bit
With Folder Autoregistration
Now you can tell to the backend to automatically add shared or users folder for the synchronization. to make that : Edit /kolab/etc/template/kolab/zpush-config.php.template add a line define('KOLAB_AUTOREGISTER',"shared.folder1:shared.folder2"); at each new mobile these folder will be automatically added.
ACL for Zpush Access
You could now create a LDAP group to restrict the access to zpush
Create a LDAP group (groupOfNames) or some group with member attribute Define this group in the template /kolab/etc/kolab/templates/zpush-config.php.template: define("KOLAB_LDAP_ACL","cn=myactivesync,ou=groupes,dc=demo,dc=com");
if this definition is blank or missing or if the group doesn't exist all accounts will be allowed to synchronize
Modes
Version 0.4 introduce two mode the FlatMode and the FolderMode.
Flat Mode
In this mode all folders (Calendar, Contacts ) are represented on the mobile as a single calendar or contact address book. this mode is very usual for mobile who doesn't support more than one calendar and contact.
Folder Mode
this mode display folders (Contacts, Calendar) as separed calendars or Contact address book on the mobile. For the moment i know just the iphone who has this capabilty (see the table below)
Automatic Mode
the backend will detect the device type and switchs in the best mode for this type.
Clients
Clients Folders capabilities (Contacts, Calendar)
- INBOX is INBOX namespace
- USER is USER shared space /user/username/.....
- SHARED is public folders shared.folders
- NO : not implemented
- YES : Implemented and tested
- ? : not tested
| Platform | INBOX Default folder | INBOX others folders | USER folders | SHARED | remarks | Tested on |
|---|---|---|---|---|---|---|
| Android | YES | NO | NO | NO | See: Google issue 4758 | HTC Droid Eris |
| Android 2.1,2.2 | YES | NO | NO | NO | Works very well | LG Optimus one P500 Samsung Galaxy |
| BlackBerry | YES | ? | ? | ? | BOLD 9000 (with NotifySync or AstraSync, see below) | |
| Iphone,ipad,ipod | YES | YES | YES | YES | Works really great (bugs in mails in mail's dates) | Iphone 3.0 iphone 3.0GS iphone 4.0 Ipod Touch Ipad |
| Maemo5 | YES | NO | NO | ? | Work with 0.7.3 (some bugs in mails) Also see: http://wiki.maemo.org/Mail_for_Exchange | N900 (see restrictions) |
| Symbian | YES | NO | NO | NO | Nokia 5800 ExpressMusic | |
| Symbian Mfe 3.0 | YES | NO | NO | NO | Nokia N97 some bugs due to Nokia | |
| Windows Mobile | YES | NO | NO | NO | Only default folders | HTC HD2 |
| Sony Ericsson | YES | ? | ? | ? | Most sony erricsson phones come with SE's own properitary OS. Some have exchange support and will work. | Sony Ericsson G705 |
| WebOS | YES | ? | ? | ? | calendar, contacts and mail syncing appears to work on WebOS 1.4.5 using z-push 1.3 with Kolab-Backend 0.6.1 and kolab 2.2.4 (using FolderMode) | Palm Pre (WebOS 1.4.5) |
Android
Android 2.2 is required for Calendar support. Android 2.0 is required for ActiveSync support.
- Go to "Contacts" -> "Accounts" -> "Add Account" -> "Microsoft Exchange ActiveSync"
- Enter your "Email address", "Password" and press "Next"
- Enter "Domain\Username" in the format "dom.ain\<uid>"
- Please note in Kolab 2.3, the <uid> is often the primary email address.(i.e. doe@example.org).
- Please note in Kolab 2.4 and later, the <uid> is not qualified with a domain name space by default, and would thus simply be 'doe'.
- Ensure the "Server" matches your Kolab server. This may not be the same as the "Domain".
- Press "Next"
- Select your preferences and press "Next"
- Set "Your name" and press "Done"
Android 4.0 and higher uses a rewritten ActiveSync implementation.
- On needs to change Device Mode to "folder mode" for the initial sync. If not so, the Exchange2.apk will crash with a NullpointerExeption.
- It seems to work better if you set "day to synchronize" to a value instead of auto-config.
Blackberry
You must have third party software to sync contacts and calendar without using Blackberry Enterprise server, for example: NotifySync.
Feedback with NotifySync Tried with a BOLD 9000.
You have to download the application over the air then ask a trial key to the support. You can read the tutorial at notifysync.co.uk.
Follow this settings to enable the sync between your BB and z-pus :
Server address: fqdn Port: 443 Use https: Checked Username: youremailwith@domain.ext
Now you can set a tail on your debug.txt and normaly you will see your first sync.
iPhone, Ipod Touch, Ipad
Configuration mostly matches this Apple Support Page.
- Open "Settings", and go into "Mail, Contacts, Calendars"
- Choose "Add account" and "Microsoft Exchange"
- Key in an email address, mail domain, username, password.
- After a few seconds, you will also be asked for a server name, enter your mail server
- Ideally, leave SSL on.
- Choose Mail "off" and Contacts and Calendars "on".
Once this has worked, you should be able to go into contacts and click "Groups" in the top left corner to choose between "all contacts", those local on the iPhone and those synced from Kolab. The same logic should work in email, sms, calendars, phone, etc.
Maemo5 (N900)
With z-push-1.2.3 and kolabbackend 0.4 you are able to synchronize contacts and calendar entries. Developers are in the process of adding task functionality. Later versions of z-push seems to have problems. Use "foldermode" for kolabbackend 0.4 config file by doing editing /kolab/var/kolab/www/z-push/config-kolab.php and change define("KOLAB_MODE",1)
- Go to Settings -> Mail for Exchange
- Enter your e-mailaddress, username (with the domain), password and press Next
- Enter your servers location either as an ip-address or servername
- To start please use an unsecure connection on port 80 but feel free to change it later.
- Press Finish
More infos about Mail for Exchange (MfE)
Windows Mobile
Go in ActiveSync and create a sync. Domain must be not empty but this is not checked by the backend.
Windows Mobile will not sync if you have a non-trusted SSL certificate.
You either need to get a cert which your device trusts or disable SSL.
Your options are:
- Obtain a certification your device trusts
- Use a non-ssl connection (NOT RECOMMENDED: ALL CONTACTS AND CALENDAR WILL BE SENT OVER THE NETWORK IN CLEAR TEXT)
- Install your self signed root certificate on your mobile device (see below).
Adding a root certificate might work following:
Microsoft-Knowledgebase 915840 How to install root certificates on a Windows Mobile-based device
Bernhard 12:30, 18 March 2010 (CET) Tested on HTC Touch Pro2 (Model# T7373, ROM 1.86.407.5 (67102) GER 10/23/09), (zpush 1.2.2, backend 0.2): I could not enter something in the "domaine" setting, which was okay. I could see with IE of the device if my root certificate was properly entered before and after importing it. Sync of calender and contacts worked with SSL. Attention: With the version I was using, the contact of my device get synced up to the server, but if you reconfigure to not sync contacts, they will be removed from the device.
Adding a Root Certificate
On kolab server:
# mkdir /kolab/var/kolab/www/certs # cp cacert.pem /kolab/var/kolab/www/certs/cacert.cer #note the file extension change
In windows:
- Navigate to www.your.kolab.server/certs/cacert.cer
- Open the ca certificate and follow the windows prompts to install.
- This also has the advantage of getting rid of the Certificate Error in Internet Explorer and likely Outlook [not tested in Outlook]
- Install Microsoft SslChainSaver
- Open a command prompt and navigate to: C:\Program Files\Microsoft SSL ChainSaver
- execute: sslchainsaver your.kolab.server
- execute: copy your.kolab.server.wm6.xml _setup.xml
- execute: makecab _setup.xml rootcert-wm6.cab
- execute: copy your.kolab.server.wm5.xml _setup.xml
- execute: makecab _setup.xml rootcert-wm5.cab
- Copy rootcert-wm5.cab and rootcert-wm6.cab to your kolab server (/kolab/var/kolab/www/certs/).
- Navigate your Windows mobile phone to http://your.kolab.server/certs/rootcert-wm[5|6].cab depending on the os version of your windows mobile device.
- This will automatically install the root ca and allow your phone to sync with SSL and a self signed certificate.
- tested on a Samsung Blackjack II running Windows Mobile 6.1 Standard (Aug. 30, 2010)
Known Issues
- version 0.7.4 and before
- tasks : reccuring tasks don't work (z-push Bug).
- mails : Sentfolder is only detected by the annotations (mail.sentitems)
- mails : no support of Html mails, they are translated in Text format (Z-push limitation)
- version 0.7.3 and before
- core : in push mode performance problems and process loop (processes who are never killed )
- core : Android doesn't send the Serial number at the first synchronization
- tasks : reccuring tasks don't work (z-push Bug).
- mails : Sentfolder is only detected by the annotations (mail.sentitems)
- mails : no support of Html mails, they are translated in Text format (Z-push limitation)
- version 0.7.2
- contacts: only one email address is synchronized
- GAL : Global address book doesn t work with Z-push 1.5/0.7.2
- events : on iphone os >=4.1 the end of recurence is false ( -2 days)
- mails : dates are wrong (-1 hour) on iphone (iphone bug)
- S60 (Nokia) : some bugs with this OS
- tasks : reccuring tasks don't work (z-push Bug).
- mails : Sentfolder is only detected by the annotations (mail.sentitems)
- mails : no support of Html mails, they are translated in Text format (Z-push limitation)
- calendar: Exceptions in recurence appointments doesn t work
- core : if the logfile is too big the > 2GB the synchronization doesn't work
- version 0.6.1 - 0.6.4
- tasks : reccuring tasks don't work (z-push Bug).
- mails : Sentfolder is only detected by the annotations (mail.sentitems)
- mails : some html mails with attached images block the mail synchronization on the iphone
- mails : no support of Html mails, they are translated in Text format (Z-push limitation)
- calendar: Exceptions in recurence appointments doesn t work
- core : if the logfile is too big the > 2GB the zynchronization doesn't work
- phones : some problems with Nokia E serie
- Version 0.4
- Exceptions in recurence appointments doesn t work
- Version 0.3
- Memory consomption when Push is actived (button push on the iphone for exemple)(resolved 0.4)
- Private events are shown for a shared USER folder ( bit Private) (resolved 0.4)
- Some malformed fields in the contacts could block the sync (resolved 0.4)
- with Android problem in the mail address (Android send the mail address in a different form than pocketPC and the iphone (resolved 0.4)
- Exceptions in recurence appointments doesn t work
- reminders are shown for the others USER/.. calendars (resolved 0.4)
Developers
Z-push is developed in a Kolabsys repository.
