1 | Installing Z-Push |
---|
2 | ====================== |
---|
3 | |
---|
4 | Requirements |
---|
5 | ------------ |
---|
6 | |
---|
7 | Z-Push 2 runs only on PHP 5.1 or later |
---|
8 | A PEAR dependency as in previous versions does not exist in Z-Push 2. |
---|
9 | |
---|
10 | The PHP version requirement is met in these distributions and versions (or later). |
---|
11 | |
---|
12 | Debian 4.0 (etch) |
---|
13 | Ubuntu 8.04 (hardy heron) |
---|
14 | RHEL/CentOS 5.5 |
---|
15 | Fedora 5 (bordeaux) |
---|
16 | OpenSuse 10.1 |
---|
17 | Slackware 12.0 |
---|
18 | Gentoo 2006.1 |
---|
19 | FreeBSD 6.1 |
---|
20 | OpenBSD 4.0 |
---|
21 | Mandriva 2007 |
---|
22 | |
---|
23 | If your distribution is not listed here, you can check which PHP version |
---|
24 | is default for it at http://distrowatch.com/. |
---|
25 | |
---|
26 | Additional informations can be found in the Zarafa Administrator Manual: |
---|
27 | http://doc.zarafa.com/trunk/Administrator_Manual/en-US/html/_zpush.html |
---|
28 | |
---|
29 | |
---|
30 | Additioal php packages |
---|
31 | ---------------------- |
---|
32 | To use the full featureset of Z-Push 2 and the z-push-top command line utility, |
---|
33 | additional php packages are required. These provide SOAP support, access to |
---|
34 | process control and shared memory. |
---|
35 | |
---|
36 | These packages vary in names between the distributions. |
---|
37 | - Generally install the packages: php-cli php-soap |
---|
38 | - On Suse (SLES & OpenSuse) install the packages: php5 php5-soap php5-pcntl php5-sysvshm php5-sysvsem |
---|
39 | - On RHEL based systems install the package: php-cli php-soap php-process |
---|
40 | To install this package you need to add an extra channel subscription from the |
---|
41 | RHEL Server Optional channel. |
---|
42 | |
---|
43 | |
---|
44 | How to install |
---|
45 | -------------- |
---|
46 | |
---|
47 | To install Z-Push, simply untar the z-push archive, e.g. with: |
---|
48 | tar -xzvf z-push-[version]-{buildnr}.tar.gz |
---|
49 | |
---|
50 | The tar contains a folder which has the following structure: |
---|
51 | z-push-[version]-{buildnr} |
---|
52 | |
---|
53 | The contents of this folder should be copied to /usr/share/z-push. |
---|
54 | In a case that /usr/share/z-push does not exist yet, create it with: |
---|
55 | mkdir -p /usr/share/z-push |
---|
56 | |
---|
57 | cp -R z-push-[version]-{buildnr}/* /usr/share/z-push/ |
---|
58 | |
---|
59 | Edit the config.php file in the Z-Push directory to fit your needs. |
---|
60 | If you intend to use Z-Push with Zarafa backend and Zarafa is installed |
---|
61 | on the same server, it should work out of the box without changing anything. |
---|
62 | Please also set your timezone in the config.php file. |
---|
63 | |
---|
64 | The parameters and their roles are also explained in the config.php file. |
---|
65 | |
---|
66 | By default the state directory is /var/lib/z-push, the log directory /var/log/z-push. |
---|
67 | Make sure that these directories exist and are writeable for your webserver |
---|
68 | process, so either change the owner of these directories to the UID of |
---|
69 | your apache process or make the directories world writeable: |
---|
70 | |
---|
71 | chmod 777 /var/lib/z-push |
---|
72 | chmod 777 /var/log/z-push |
---|
73 | |
---|
74 | For the default webserver user please refer to your distribution's manual. |
---|
75 | |
---|
76 | Now, you must configure Apache to redirect the URL |
---|
77 | 'Microsoft-Server-ActiveSync' to the index.php file in the Z-Push |
---|
78 | directory. This can be done by adding the line: |
---|
79 | |
---|
80 | Alias /Microsoft-Server-ActiveSync /usr/share/z-push/index.php |
---|
81 | |
---|
82 | to your httpd.conf file. Make sure that you are adding the line to the |
---|
83 | correct part of your Apache configuration, taking care of virtual hosts and |
---|
84 | other Apache configurations. |
---|
85 | Another possibility is to add this line to z-push.conf file inside the directory |
---|
86 | which contents are automatically processed during the webserver start (by |
---|
87 | default it is conf.d inside the /etc/apache2 or /etc/httpd depending on your |
---|
88 | distribution). |
---|
89 | |
---|
90 | You have to reload your webserver after making these configurations. |
---|
91 | |
---|
92 | *WARNING* You CANNOT simply rename the z-push directory to |
---|
93 | Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the |
---|
94 | mobile device, which will definitely break your mobile device synchronisation. |
---|
95 | |
---|
96 | Lastly, make sure that PHP has the following settings: |
---|
97 | |
---|
98 | php_flag magic_quotes_gpc off |
---|
99 | php_flag register_globals off |
---|
100 | php_flag magic_quotes_runtime off |
---|
101 | php_flag short_open_tag on |
---|
102 | |
---|
103 | You can set this in the httpd.conf, in php.ini or in an .htaccess file in |
---|
104 | the root of z-push. |
---|
105 | |
---|
106 | If you have several php applications on the same system, you could specify the |
---|
107 | z-push directory so these settings are considered only there. |
---|
108 | <Directory /usr/share/z-push> |
---|
109 | php_flag magic_quotes_gpc off |
---|
110 | php_flag register_globals off |
---|
111 | php_flag magic_quotes_runtime off |
---|
112 | php_flag short_open_tag on |
---|
113 | </Directory> |
---|
114 | |
---|
115 | If you don't set this up correctly, you will not be |
---|
116 | able to login correctly via z-push. |
---|
117 | |
---|
118 | Please also set a memory_limit for php to 128M in php.ini. |
---|
119 | |
---|
120 | Z-Push writes files to your file system like logs or data from the |
---|
121 | FileStateMachine (which is default). In order to make this possible, |
---|
122 | you either need to disable the php-safe-mode in php.ini or .htaccess with |
---|
123 | php_admin_flag safe_mode off |
---|
124 | or configure it accordingly, so Z-Push is allowed to write to the |
---|
125 | log and state directories. |
---|
126 | |
---|
127 | After doing this, you should be able to synchronize with your mobile device. |
---|
128 | |
---|
129 | To use the command line tools, access the installation directory |
---|
130 | (usually /usr/share/z-push) and execute: |
---|
131 | ./z-push-top.php and/or |
---|
132 | ./z-push-admin.php |
---|
133 | |
---|
134 | To facilitate the access symbolic links can be created, by executing: |
---|
135 | ln -s /usr/share/z-push/z-push-admin.php /usr/sbin/z-push-admin |
---|
136 | ln -s /usr/share/z-push/z-push-top.php /usr/sbin/z-push-top |
---|
137 | |
---|
138 | With these symlinks in place the cli tools can be accessed from any |
---|
139 | directory and without the php file extension. |
---|
140 | |
---|
141 | |
---|
142 | Upgrading from Z-Push 1.X versions |
---|
143 | ------------------------------------ |
---|
144 | |
---|
145 | The easiest way to upgrade is to follow the steps for a new installation. The states |
---|
146 | of Z-Push 1.X are not compatible and there is no upgrade path, but as this version |
---|
147 | implements a fully automatic resynchronisation of devices it should not affect the |
---|
148 | users and work without the user interaction. |
---|
149 | |
---|
150 | |
---|
151 | Update to newer Z-Push versions |
---|
152 | ------------------------------- |
---|
153 | |
---|
154 | Upgrading to a newer Z-Push version follows the same path as the initial |
---|
155 | installation. |
---|
156 | |
---|
157 | Please observe the published release notes of the new Z-Push version. |
---|
158 | For some releases it is necessary to e.g. resynchronize the mobile. |
---|
159 | |
---|
160 | |
---|
161 | Setting up your mobile device |
---|
162 | ----------------------------- |
---|
163 | |
---|
164 | This is simply a case of adding an 'exchange server' to your activesync |
---|
165 | server list, specifying the IP address of the Z-Push's apache server, |
---|
166 | disabling SSL, unless you have already setup SSL on your Apache server, |
---|
167 | setting the correct username and password (the domain is ignored, you can |
---|
168 | simply specify 'domain' or some other random string), and then going through |
---|
169 | the standard activesync settings. |
---|
170 | |
---|
171 | Once you have done this, you should be able to synchronise your mobile |
---|
172 | simply by clicking the 'Sync' button in ActiveSync on your mobile. |
---|
173 | |
---|
174 | *NOTE* using the synchronisation without SSL is not recommended because |
---|
175 | your private data is transmitted in clear text over the net. Configuring |
---|
176 | SSL on Apache is beyond of the scope of this document. Please refer to |
---|
177 | Apache documention available at http://httpd.apache.org/docs/ |
---|
178 | |
---|
179 | |
---|
180 | Troubleshooting |
---|
181 | --------------- |
---|
182 | |
---|
183 | Most problems will be caused by incorrect Apache settings. To test whether |
---|
184 | your Apache setup is working correctly, you can simply type the Z-Push URL |
---|
185 | in your browser, to see if apache is correctly redirecting your request to |
---|
186 | z-push. You can simply use: |
---|
187 | |
---|
188 | http://<serverip>/Microsoft-Server-ActiveSync |
---|
189 | |
---|
190 | If correctly configured, you should see a username/password request and |
---|
191 | when you specify a valid username and password, you should see a Z-Push |
---|
192 | information page, saying that this kind of requests is not supported. |
---|
193 | Without authentication credentials Z-Push displays general information. |
---|
194 | |
---|
195 | If not then check your PHP and Apache settings and Apache error logs. |
---|
196 | |
---|
197 | If you have other synchronisation problems, you can increase the LOGLEVEL |
---|
198 | parameter in the config e.g. to LOGLEVEL_DEBUG or LOGLEVEL_WBXML. |
---|
199 | |
---|
200 | The z-push.log file will then collect detailed debug information from your |
---|
201 | synchronisation. |
---|
202 | |
---|
203 | *NOTE* This setting will set Z-Push to log the detailed information for |
---|
204 | *every* user on the system. You can set a different log level for particular |
---|
205 | users by adding them comma separated to $specialLogUsers in the config.php |
---|
206 | e.g. $specialLogUsers = array("user1", "user2", "user3"); |
---|
207 | |
---|
208 | *NOTE* Be aware that if you are using LOGLEVEL_DEBUG and LOGLEVEL_WBXML |
---|
209 | Z-Push will be quite talkative, so it is advisable to use log-rotate |
---|
210 | on the log file. |
---|