[7589] | 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. |
---|