Z-Push configuration manual

This document describes how to install and configure the Z-Push software to synchronize PDA's and Smartphones with a server based solution Z-Push is available as an opensource pro!ect on Sourceforge - http"##z-push sourceforge net

Introduction
The Z-Push software allows users with PDA's and Smartphones to synchronize their email$ contacts$ calendar items and tas%s directly from a compatible server over &'TS$ (P)S$ *i+i or (S' data connections The following devices are native supported by Z-Push"

Poc%etPc ,--, and ,--. *indows 'obile / and 0 1o%ia 2-series Sony 2ricsson P33-$ *3/- and '0-All other ActiveSync compatible devices

The devices can be synchronised because the Z-Push module emulates a 'S 24change server on the server side$ allowing users to synchronize without installing specialized synchronisation software on their devices Z-Push is supports the following bac%ends' server technologies"

Zarafa Zarafa is a wor%group sharing solution based on the loo%-and-feel of 'icrosoft 5utloo%$ which enables sharing of mail and appointments from 5utloo% and a web based interface IMAP 6 is a widely used mail protocol with folder support maildir 6 'aildir is a simple mailsolution available on almost every 7inu4 system All mails are stored in specific directories on the server vCard 6 8mplementation used to synchronize v9ard files with contacts on the PDA

p. 1

Security
:ou can use the SS7 feature of the PDA only when you have setup SS7 on your server and your server has an acceptable certificate This means that you either need an official SS7 certificate from a commercial certificate authority$ or you need to install the certificate on your PDA 8nstalling SS7 certificates is beyond the scope of this document$ but many ;5*T5s can be found on the internet

Installation
Download the latest Z-Push software on the following website" http"##z-push sourceforge net To 8nstall Z-Push$ simply untar the Z-Push tar to your webroot$ e g with tar zxvf z-push-<version>.tar.gz -C /var/www The -9 option is the destination where the files need to be installed 8n the following overview you'll see the default webroot directories of where your distribution lets the Apache webserver search for files

Distribution SuS2 )ed;at and clones <eg +edora$ 9ent5S= Debian and &buntu

Default webroot #srv#www#htdocs #var#www#html #var#www

This documents continues the /var/www directory as e4ample 1ow$ edit the config php file in the directory to reflect your local system +or 'AP8 use with Zarafa$ you needn't change any settings and should wor% as-is Set the BACKEND_ !"#$DE! value to suit your needs %BACKEND_ !"#$DE! & 'Ba()en*$C+', %BACKEND_ !"#$DE! & 'Ba()en*$/A ', %BACKEND_ !"#$DE! & 'Ba()en*/ai0*ir', %BACKEND_ !"#$DE! & 'Ba()en*#CDir', // -arafa $C+ .a()en* // $/A .a()en* // 1ai0*ir .a()en* // vCar* .a()en*

2ach bac%end have own custom variables to be defined Please chec% these in the config php file 'a%e sure that the 'state' directory is writeable for your webserver process$ so either change the owner of the 'state' directory to the &8D of your apache process$ or ma%e the directory world writeable" (h1o* 222 /var/www/z-push/state

p. 2

:ou can also rela4 the permissions a bit$ and correct the user and#or group of the directory$ so only Apache can write in the directory" (h1o* 233 /var/www/z-push/state (hown www-*ata4www-*ata /var/www/z-push/state The user and group name of Apache will differ per 7inu4 distribution >elow you will find a table with an overview of the correct username and groupname for Apache" Distribution SuS2 )ed;at and clones <eg +edora$ 9ent5S= Debian and &buntu Apache username wwwrun apache www-data Groupname www apache www-data

1ow$ you must configure Apache to redirect the &)7 ''icrosoft-Server-ActiveSync' to the inde4 php file in the z-push directory This can be done by adding the line"
A0ias //i(rosoft-+erver-A(tive+5n( /var/www/z-push/in*ex.php

to your httpd conf file 'a%e sure that you are adding the line to the correct part of your Apache configuration$ ta%ing care of virtual hosts and other Apache configurations ?*A)181(? :ou 9A115T simply rename the Z-Push directory to 'icrosoft-Server-ActiveSync This will cause Apache to send redirects to the PDA$ which will definitely brea% your PDA synchronisation 7astly$ ma%e sure that P;P has the following settings" php_f0ag php_f0ag php_f0ag php_f0ag 1agi(_6uotes_gp( off register_g0o.a0s off 1agi(_6uotes_runti1e off short_open_tag on

:ou can set this in the httpd conf$ in php ini or in an htaccess file in the root of Z-Push 8f you don't set this up correctly$ you will not be able to login correctly via Z-Push After doing this$ you should be able to synchronize from your PDA

Setting up your PocketPC

This is simply a case of adding an 'e4change server' to your activesync server list$ specifying the 8P address of the Z-Push apache server$ disabling SS7$ unless you have already setup SS7 on your Apache server$ setting the correct username @ password <the domain is ignored$ you can simply specify 'domain' or some other random string=$ and then going through the standard activesync settings 5nce you have done this$ you should be able to synchronise your Poc%etP9 simply by clic%ing the 'Sync' button in ActiveSync on your Poc%etP9

p. 3

8n steps" A 5pen ActiveSync and select 'set up your device to sync with it'

Type your server address <without http or other &)7 parts=

p. 4

Specify your username and password$ you must specify a domain but it is not used within Z-Push$ so you can specify simply 'domain' or some other random te4t Select 'save password' if you wish to automatically sync

Select which items you wish to synchronize

Press '+inish'

:ou can now synchronize your PDA by pressing 'Sync'

p. 5

Troubleshooting
'ost problems will be caused by incorrect Apache settings To test whether your Apache setup is wor%ing correctly$ you can simply type the Z-Push &)7 in your browser$ to see if apache is correctly redirecting your reCuest to Z-Push :ou can simply use" http4//<serverip>//i(rosoft-+erver-A(tive+5n( 8f correctly configured$ you should see a username#password reCuest$ and when you specify a valid username @ password$ you should see a string li%e D:our device reCuested the Z-Push &)7 without the reCuired (2T parametersD 8f not$ then chec% your P;P and Apache settings 8f you have other synchronisation problems$ you can create the file 'debug t4t' in the root directory of Z-Push$ which should also be world-writable" tou(h /var/www/z-push/*e.ug.txt (h1o* 222 /var/www/z-push/*e.ug.txt The debug t4t file will then collect debug information from your synchronisation

Using Z-Push via SSL

To synchronise your PDA or Smartphone remote via SS7$ you will need SS7 support on your Apache webserver >y default the PDA only support SS7 certificates that are signed by the following 9ertified Authorities <9A=" E FeriSign E 9ybertrust E Thawte E 2ntrust E (lobalSign E 2Cuifa4 To buy an official certificate from one of these vendors cost around between ,-- and ,--- euro :ou can also get a free certificate at www cacert org *ith 9acert certificates you still need to install the 9A certificate on the PDA 8f the server certificate doesn't match with the server name or the 9A certificate isn't installed$ the remote synchronisation cannot be established

p. 6

Generate official SSL certificate

To get an official SS7 certificate you first need to create 9ertificate Signing )eCuests <9S)= To generate a 9S) file$ you will first need to create private )SA %ey This private %ey should be %ept absolutely personal openss0 genrsa -out host.)e5 789: (h1o* :88 host.)e5 openss0 re6 -new -no*es -)e5 host.)e5 -out host.(sr *hen prompted for the x38; Co11on Na1e attribute information$ enter the fully Cualified hostname the certificate will be used on The e-mail address will li%ely be used by the 9A to contact you 7eave any subseCuent attributes blan%$ unless the 9A reCuests something be set in them The csr file must be submitted to a 9A The 9A will finally return the certificate Save the certificate in the file host crt To see how you can enable your SS7 certificate in your Apache$ please see G9onfigure Apache with SS7H

Generate a self-signed certificate

To create a self signed certificate you first need to setup your own 9A by the following commands" openss0 genrsa -*es< -out (a.)e5 :8;= openss0 re6 -new -x38; -*a5s <=3 -)e5 (a.)e5 -out (a.(rt After your 9A is ready$ you need to create a 9ertificate Signing )eCuests <9S)= openss0 genrsa -out host.)e5 789: (h1o* :88 host.)e5 openss0 re6 -new -no*es -)e5 host.)e5 -out host.(sr *hen prompted for the x38; Co11on Na1e attribute information$ enter the fully Cualified hostname the certificate will be used on 1ow you have to certify your 9S) file by your own 9A openss0 x38; -re6 -*a5s <=3 -in host.(sr -CA (a.(rt -CA)e5 (a.)e5 -set_seria0 87 -out host.(rt To add the generated certificate and the private %ey to your Apache webserver$ see the following chapter

p. 7

Configure

pache !ith SSL

To use the certificate in your Apache webserver$ ma%e sure the modIssl pac%age is installed and loaded Depending on your distribution the default Apache SS7 configuration settings are available in a different file See the list below for your distribution" )edhat" #etc#httpd#conf d#ssl conf Debian" #etc#apache,#ssl conf Suse" #etc apache,#vhosts d#ssl-server conf To load your new certificate$ change the following options in the ssl configuration file" SS79ertificate+ile host crt SS79ertificateJey+ile host %ey 8f you have a self signed certificate$ please add also the following option to the ssl configuration file" SS79A9ertificate+ile #root#ssl#ca crt

Configure P"

for SSL

8n *indows 'obile-based PDA's you also need to add the 9A 9ertificate to the Trusted )oot 9ertificates store if you don't have a certificate of one of the 9ertified Authorities describe in the first chapter The certificates should be in D2) format to install it on the PDA >y default the generated SS7 certificates on 7inu4 are in P2' format The D2) certificate is a base0B encoded P2' certificate :ou can convert the certificate type by the following commands" openss0 x38; -in (a.(rt -infor1 openss0 x38; -in host.(rt -infor1 E/ -out (a.(er -outfor1 DE! E/ -out host.(er -outfor1 DE!

After converting both certificates you need to copy them to the PDA >y selecting the certificates on your PDA they will be stored in the Trusted )oot 9ertificates store of your PDA The PDA is now ready to use Activesync via SS7

p. 8

#eferences

Z-push website http"##z-push sourceforge org Setup G'ail for 24changeH to synchronize your 1o%ia phone http"##www businesssoftware no%ia com#mailIforIe4changeIdownloads php 5penssl manuals" http"##www openssl org#docs#;5*T5#%eys t4t http"##www openssl org#docs#;5*T5#certificates t4t

'icrosoft tool to disable certificate verification" http"##www microsoft com#downloads#details asp4K+amily8dLDMMN/.>M-M>.A-B+AD-M23B/.-A0N0ABD+A@displaylangLen 'anual how to add a root certificate to your PDA http"##support microsoft com#%b#MBA-0-#en

p. 9