| This manual is deprecated. Please visit https://groupoffice.readthedocs.io for the latest documentation. |
Difference between revisions of "Z-push"
(→Manual) |
(→Manual) |
||
| (16 intermediate revisions by 2 users not shown) | |||
| Line 11: | Line 11: | ||
=Requirements= | =Requirements= | ||
| − | + | #Works on a Linux or Mac (POSIX) server only. It does not work on a Windows server. | |
| − | + | =Installation= | |
==Automatic== | ==Automatic== | ||
| Line 23: | Line 23: | ||
==Manual== | ==Manual== | ||
| − | ActiveSync support does not work out of the box. To add support of ActiveSync | + | ActiveSync support does not work out of the box. We use the third party library z-push. To add support of ActiveSync take the following steps (Step 1 to 5 can be done with modules/sync/z-push/install.sh too): |
| − | take the following steps (Step 1 to 5 can be done with modules/sync/z- | + | |
| − | 1. Download z-push from http:// | + | 1. Download z-push from http://download.z-push.org/final/. We've tested up to version 2.3.4beta. |
2. Unpack the archive and put it in the "modules" directory of Group-Office. | 2. Unpack the archive and put it in the "modules" directory of Group-Office. | ||
| Line 32: | Line 31: | ||
3. rename the folder to "z-push" | 3. rename the folder to "z-push" | ||
| − | 4. Copy the | + | 4. Copy the folder modules/'''sync'''/z-push/backend/go/ to modules/z-push/backend/ |
| − | 5. Copy | + | 5. Copy modules/'''sync'''/z-push/config.php to modules/z-push/config.php |
6. Now, you must configure Apache to redirect the URL 'Microsoft-Server-ActiveSync' to the index.php file in the modules/z-push/ directory.<br />This can be done by adding the line: | 6. Now, you must configure Apache to redirect the URL 'Microsoft-Server-ActiveSync' to the index.php file in the modules/z-push/ directory.<br />This can be done by adding the line: | ||
| Line 43: | Line 42: | ||
7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync! | 7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync! | ||
| + | |||
| + | ===Known issues per device=== | ||
| + | {| class="wikitable" style="width:100%;" | ||
| + | |- | ||
| + | ! Device !! OS !! Issue | ||
| + | |- | ||
| + | | Iphone || All IOS versions || Removing participant from a recurring event on the phone that will be saved as an exception event will also delete the participants on the main event | ||
| + | |- | ||
| + | | || IOS 7 || New tasklists that are created on the device will not be synced to Group-Office. The list will be kept on the phone but the tasks itself will also be added to the main tasklist. | ||
| + | |- | ||
| + | | HTC || HERO (maybe more) || Contacts that are synced to the phone and then marked as favorite on the phone will add HTC xml data to the comments field. | ||
| + | |} | ||
==CGI mode== | ==CGI mode== | ||
By default z-push only works when PHP is loaded as an Apache module. If you use | By default z-push only works when PHP is loaded as an Apache module. If you use | ||
| − | PHP in CGI mode you'll have to | + | PHP in CGI mode you'll have to add 2 .htaccess files |
| − | + | One you have to put in /modules/z-push/.htaccess: | |
| − | + | ||
| − | + | ||
<pre> | <pre> | ||
| − | + | RewriteEngine on | |
| − | RewriteEngine | + | RewriteRule .* - [E=HTTP_MS_ASPROTOCOLVERSION:%{HTTP:Ms-Asprotocolversion}] |
| − | RewriteRule | + | RewriteRule .* - [E=HTTP_X_MS_POLICYKEY:%{HTTP:X-Ms-Policykey}] |
| + | RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L] | ||
</pre> | </pre> | ||
| − | + | Below you can find an example .htaccess file that needs to be placed in the Group-Office document root(next to the index.php file): | |
<pre> | <pre> | ||
| − | + | Options +FollowSymLinks | |
| − | + | RewriteEngine On | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | #Mind the absolute path to index.php here. On shared hosts you can often find it in config.php ($config['root_path']). | |
| − | + | RewriteRule Microsoft-Server-ActiveSync(.*) /var/www/groupoffice/modules/z-push/index.php$1 [E=ACTIVESYNC:true,E=REMOTE_USER:%{HTTP:Authorization}] | |
| − | + | ||
| − | + | ||
| − | + | ||
</pre> | </pre> | ||
| + | |||
| + | '''Note:''' Change the path to Group-Office to the correct absolute path for your server. | ||
=Uninstall= | =Uninstall= | ||
| − | Remove the z-push folder from the modules directory of Group-Office. | + | Remove the z-push folder from the modules directory of Group-Office and remove the apache alias that is described above. |
=User Manual= | =User Manual= | ||
| − | + | Visit the following page for client instructions: | |
| + | |||
| + | [[Synchronization]] | ||
=Additional Notes= | =Additional Notes= | ||
| Line 91: | Line 98: | ||
A log will be generated in /home/groupoffice/log/ | A log will be generated in /home/groupoffice/log/ | ||
| − | + | Z-Push can only sync email when running on a default HTTP port eg. 80 or 443 | |
| + | =Debugging= | ||
Sometimes it can happen that an item is not synced to the device. | Sometimes it can happen that an item is not synced to the device. | ||
| − | + | ==Creating a synchronisation log file== | |
| + | When the synchronisation is not working anymore for a user, then you can create a logfile of the synchronisation of that particular user. | ||
| + | |||
| + | You can enable this by adding the following configuration variable to the Group-Office config.php file. | ||
| + | <pre> | ||
| + | $config['zpush2_special_log_users']=array('username','username2'); | ||
| + | </pre> | ||
| + | |||
| + | After you have done that, a log file with the name: {username}.log will be created on the following location: {go_file_storage_path}/log/z-push/ | ||
| + | |||
| + | Sometimes you can find more information about the synchronisation problem in that log. | ||
| + | |||
| + | If you don't understand what's happening then you can create a ticket at our ticketsystem. Please add the generated logfile to the ticket so we have some debug information. | ||
| + | |||
| + | * Don't forget to remove the users from the GO configuration variable after the log is created so the logfiles will not grow to huge files anymore. | ||
| + | |||
| + | ==Z-Push admin commandline tool== | ||
| + | |||
| + | When you get an error in the "z-push-error.log" file that is located in the {go_file_storage_path}/log/z-push/ folder. | ||
The error can look like this: | The error can look like this: | ||
| Line 107: | Line 133: | ||
When this happens you can usually find more info on this error by using the "z-push-admin.php" file that is located in the z-push folder. | When this happens you can usually find more info on this error by using the "z-push-admin.php" file that is located in the z-push folder. | ||
| − | This is a commandline tool that is shipped with the z-push2 package. | + | This is a commandline tool that is shipped with the z-push2.1 package. |
You can use it like this: | You can use it like this: | ||
<pre> | <pre> | ||
| − | cd /usr/share/groupoffice/modules/z- | + | cd /usr/share/groupoffice/modules/z-push |
php z-push-admin.php -a list -u {go_username} | php z-push-admin.php -a list -u {go_username} | ||
</pre> | </pre> | ||
| − | *Note: You need to go to the directory of z- | + | *Note: You need to go to the directory of z-push first because otherwise the GO config file cannot be loaded. |
| + | If the config file still cannot be found then add this line directly after the <?php open tag in the z-push-admin.php file: | ||
| + | <pre> | ||
| + | define('GO_CONFIG_FILE',{absolute_path_to_config_file}); | ||
| + | </pre> | ||
| + | |||
| + | When you have ran the z-push-admin tool then you can find a better error description for each device in the result of the "list" command. | ||
| + | |||
| + | ==Ignored broken message== | ||
| + | |||
| + | When this happens there could be 3 reasons. | ||
| + | |||
| + | #the object is broken in whatever reason (detected by Z-Push, semantic error, like appointments end date is before the start date) | ||
| + | #there is a connection issue between the server and the mobile (bad reception, network instabilities etc.) | ||
| + | #the mobile can (for whatever reason) not process the received data | ||
| − | + | Check Start menu -> ActiveSync management and select your device to find more information. It might help to resync your device. Double click the device and click the "Resync" button. If the problem persists then submit a support ticket and include a complete log file (see [[Z-push_2.1#Creating_a_synchronisation_log_file]]). | |
Latest revision as of 13:57, 20 December 2016
Contents
Overview
This module can be used to synchronize Emails, Contacts, Tasks and Calendars to a mobile device/tablet.
Dependencies
Apache modules
Some apache modules cannot be enabled because Z-Push is NOT working when they are enabled.
- mod_pagespeed (source: http://z-push.sourceforge.net/phpbb/viewtopic.php?f=2&t=2286&p=8480&hilit=pagespeed#p8480)
Requirements
- Works on a Linux or Mac (POSIX) server only. It does not work on a Windows server.
Installation
Automatic
To install the z-push module automatically, you can use the script that is provided with the "Sync" module. (install.sh)
The script is located in the "modules/sync/z-push" folder.
Manual
ActiveSync support does not work out of the box. We use the third party library z-push. To add support of ActiveSync take the following steps (Step 1 to 5 can be done with modules/sync/z-push/install.sh too):
1. Download z-push from http://download.z-push.org/final/. We've tested up to version 2.3.4beta.
2. Unpack the archive and put it in the "modules" directory of Group-Office.
3. rename the folder to "z-push"
4. Copy the folder modules/sync/z-push/backend/go/ to modules/z-push/backend/
5. Copy modules/sync/z-push/config.php to modules/z-push/config.php
6. Now, you must configure Apache to redirect the URL 'Microsoft-Server-ActiveSync' to the index.php file in the modules/z-push/ directory.
This can be done by adding the line:
Alias /Microsoft-Server-ActiveSync /path/to/groupoffice/modules/z-push/index.php
Don't use a symlink, this won't work.
7. Restart apache2 and configure your mobile device with the servername, username and password and you should be in sync!
Known issues per device
| Device | OS | Issue |
|---|---|---|
| Iphone | All IOS versions | Removing participant from a recurring event on the phone that will be saved as an exception event will also delete the participants on the main event |
| IOS 7 | New tasklists that are created on the device will not be synced to Group-Office. The list will be kept on the phone but the tasks itself will also be added to the main tasklist. | |
| HTC | HERO (maybe more) | Contacts that are synced to the phone and then marked as favorite on the phone will add HTC xml data to the comments field. |
CGI mode
By default z-push only works when PHP is loaded as an Apache module. If you use PHP in CGI mode you'll have to add 2 .htaccess files
One you have to put in /modules/z-push/.htaccess:
RewriteEngine on
RewriteRule .* - [E=HTTP_MS_ASPROTOCOLVERSION:%{HTTP:Ms-Asprotocolversion}]
RewriteRule .* - [E=HTTP_X_MS_POLICYKEY:%{HTTP:X-Ms-Policykey}]
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
Below you can find an example .htaccess file that needs to be placed in the Group-Office document root(next to the index.php file):
Options +FollowSymLinks
RewriteEngine On
#Mind the absolute path to index.php here. On shared hosts you can often find it in config.php ($config['root_path']).
RewriteRule Microsoft-Server-ActiveSync(.*) /var/www/groupoffice/modules/z-push/index.php$1 [E=ACTIVESYNC:true,E=REMOTE_USER:%{HTTP:Authorization}]
Note: Change the path to Group-Office to the correct absolute path for your server.
Uninstall
Remove the z-push folder from the modules directory of Group-Office and remove the apache alias that is described above.
User Manual
Visit the following page for client instructions:
Additional Notes
For debugging change modules/z-push/config.php:
define('LOGLEVEL', LOGLEVEL_ALL);
A log will be generated in /home/groupoffice/log/
Z-Push can only sync email when running on a default HTTP port eg. 80 or 443
Debugging
Sometimes it can happen that an item is not synced to the device.
Creating a synchronisation log file
When the synchronisation is not working anymore for a user, then you can create a logfile of the synchronisation of that particular user.
You can enable this by adding the following configuration variable to the Group-Office config.php file.
$config['zpush2_special_log_users']=array('username','username2');
After you have done that, a log file with the name: {username}.log will be created on the following location: {go_file_storage_path}/log/z-push/
Sometimes you can find more information about the synchronisation problem in that log.
If you don't understand what's happening then you can create a ticket at our ticketsystem. Please add the generated logfile to the ticket so we have some debug information.
- Don't forget to remove the users from the GO configuration variable after the log is created so the logfiles will not grow to huge files anymore.
Z-Push admin commandline tool
When you get an error in the "z-push-error.log" file that is located in the {go_file_storage_path}/log/z-push/ folder.
The error can look like this:
01/02/2013 12:22:31 [24372] [ERROR] [john@doe.com] Ignored broken message (SyncAppointment). Reason: '4' Folderid: 'a/GroupOfficeCalendar' message id '25' 01/02/2013 12:33:53 [28717] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674' 01/02/2013 12:34:02 [28717] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674' 01/02/2013 12:36:35 [13733] [ERROR] [john@doe.com] Ignored broken message (SyncMail). Reason: '2' Folderid: 'm/INBOX' message id '1674'
When this happens you can usually find more info on this error by using the "z-push-admin.php" file that is located in the z-push folder.
This is a commandline tool that is shipped with the z-push2.1 package.
You can use it like this:
cd /usr/share/groupoffice/modules/z-push
php z-push-admin.php -a list -u {go_username}
- Note: You need to go to the directory of z-push first because otherwise the GO config file cannot be loaded.
If the config file still cannot be found then add this line directly after the <?php open tag in the z-push-admin.php file:
define('GO_CONFIG_FILE',{absolute_path_to_config_file});
When you have ran the z-push-admin tool then you can find a better error description for each device in the result of the "list" command.
Ignored broken message
When this happens there could be 3 reasons.
- the object is broken in whatever reason (detected by Z-Push, semantic error, like appointments end date is before the start date)
- there is a connection issue between the server and the mobile (bad reception, network instabilities etc.)
- the mobile can (for whatever reason) not process the received data
Check Start menu -> ActiveSync management and select your device to find more information. It might help to resync your device. Double click the device and click the "Resync" button. If the problem persists then submit a support ticket and include a complete log file (see Z-push_2.1#Creating_a_synchronisation_log_file).
