Merge pull request #251 in ZP/z-push from...

Merge pull request #251 in ZP/z-push from bugfix/ZP-942-update-install-to-reflect-changes to develop

* commit '78251c22':
  ZP-942 More typos.
  ZP-942 Fixed typos.
  ZP-942 PLEASE!.
  ZP-942 Changed wording.
  ZP-942 Document shared memory as default IPC provider.
  ZP-942 Removed buildnr as this is not available in GIT anymore.
  ZP-942 Updated INSTALL. Released under the Affero GNU General Public License (AGPL) version 3.

src/INSTALL

 Installing Z-Push
 ======================
 
+The information contained in this file is also available at: 
+https://wiki.z-hub.io/display/ZP/Installation+from+source
+
 Requirements
 ------------
 
-Z-Push 2 runs only on PHP 5.1 or later
+Z-Push 2.3 runs only on PHP 5.4 or later
 A PEAR dependency as in previous versions does not exist in Z-Push 2.
 
 The PHP version requirement is met in these distributions and versions (or later).
 
-Debian      4.0 (etch)
-Ubuntu      8.04 (hardy heron)
-RHEL/CentOS 5.5
-Fedora      5 (bordeaux)
-OpenSuse    10.1
-Slackware   12.0
-Gentoo      2006.1
-FreeBSD     6.1
-OpenBSD     4.0
-Mandriva    2007
+Debian      7.0
+Ubuntu      14.04
+RHEL/CentOS 6
+Fedora      23
+OpenSuse    13.2
+SLES        12
 
 If your distribution is not listed here, you can check which PHP version
 is default for it at http://distrowatch.com/.
 
-Additional informations can be found in the Kopano Core Administrator Manual:
-https://documentation.kopano.io/kopanocore_administrator_manual/
+For other relevant information related to distributions supported by Kopano/Zarafa please check the according admin manual.
 
 Additional php packages
 ----------------------
-To use the full featureset of Z-Push 2 and the z-push-top command line utility,
+To use the full featureset of Z-Push 2.3 and the z-push-top command line utility,
 additional php packages are required. These provide SOAP support, access to
 process control and shared memory.
 
+Depending on the features you want to use, different packages are required.
 These packages vary in names between the distributions.
+
+Dependencies for Z-Push are:
 - Generally install the packages:                   php-cli php-soap 
-- On Suse (SLES & OpenSuse) install the packages:   php53 php53-soap php53-pcntl php53-sysvshm php53-sysvsem php53-posix
-- On RHEL based systems install the package:        php-cli php-soap php-process
+- On Suse (SLES & OpenSuse) install the packages:   php php-soap php-pcntl php-posix php-mbstring
+- On RHEL based systems install the package:        php-cli php-soap php-process php-mbstring
   In order to install these packages you need to add an extra channel subscription
   from the RHEL Server Optional channel.
 
+To use the shared memory IPC Provider, install:
+- Debian and Ubuntu:                                no additional packages required
+- On Suse (SLES & OpenSuse):                        php-sysvshm php-sysvsem
+
+To use the memcached IPC Provider, install:
+- Debian, Ubuntu and Suse:                          php-memcached
+- On RHEL based systems:                            php-pecl-memcached
+
+The memcache deamon is also required, normally it's available in the "memcached" package.
+
+Most backends have own requirements, like Kopano/Zarafa depends on php-mapi while the 
+IMAP backend depends on php-imap. See dependencies for each backend you plan to use individually.
 
 How to install
 --------------
 
+1. Extraction / getting sources
 To install Z-Push, simply untar the z-push archive, e.g. with:
-   tar -xzvf z-push-[version]-{buildnr}.tar.gz
+   tar -xzvf z-push-[version].tar.gz
 
 The tar contains a folder which has the following structure:
-    z-push-[version]-{buildnr}
+    z-push-[version]
+
+The contents of the archive are similar to the content of a GIT checkout. 
+The only difference is that in GIT you will find three directories "src", "tools" and "config". 
+Contents of the "src" directory are located directly in the z-push-[version] folder, 
+"tools" is a subdirectory of it.
+The "config" directory of GIT is not being distributed in the tarball. 
  
+2. Directories
 The contents of this folder should be copied to /usr/share/z-push.
 In a case that /usr/share/z-push does not exist yet, create it with:
     mkdir -p /usr/share/z-push
 
-    cp -R z-push-[version]-{buildnr}/* /usr/share/z-push/
+The directory should be owned by the webuser, e.g. apache or www-data depending on your distribution.
+    chown -R apache: /usr/share/z-push
+
+    cp -R z-push-[version]/* /usr/share/z-push/
+
+By default the state directory is /var/lib/z-push, the log directory /var/log/z-push.
+The locations can be changed in the configuration file. See next section on other options.
+
+Make sure that these directories exist and are writable for your webserver process.
+If you don't want to use the file statemachine (default) you don't need to create the state
+directory. More information on the different state machines is available here:
+https://wiki.z-hub.io/display/ZP/State+Machines
+
+Either change the owner of these directories to the UID of your apache process or 
+make the directories world writable:
+
+    chmod 755 /var/lib/z-push /var/log/z-push
+    chown apache:apache /var/lib/z-push /var/log/z-push
+    
+For the default webserver user please refer to your distribution's manual.
 
+3. Z-Push configuration
 Edit the config.php file in the Z-Push directory to fit your needs.
+Here you can define the location of the states (if using the file statemachine) or 
+alternatively configure the sql statemachine (file states are not required in this case).
+ 
 If you intend to use Z-Push with Kopano backend and Kopano is installed
 on the same server, it should work out of the box without changing anything.
 Please also set your timezone in the config.php file.
 
 The parameters and their roles are also explained in the config.php file.
 
-By default the state directory is /var/lib/z-push, the log directory /var/log/z-push.
-Make sure that these directories exist and are writeable for your webserver
-process, so either change the owner of these directories to the UID of
-your apache process or make the directories world writeable:
+By default the parameter IPC_PROVIDER (InterProcessCommunication) is empty
+in the configuration. This will lead to Z-Push using the first available provider.
+Two providers are currently available:
+- Shared memory provider (might require additional shared memory packages - same used in Z-Push 2.2.x)
+- Memcache provider (requires php-memcached and a memcache server installed and configured) 
 
-    chmod 755 /var/lib/z-push /var/log/z-push
-    chown apache:apache /var/lib/z-push /var/log/z-push
+The shared memory provider is the preferred IPC provider. If the IPC_Provider is not configured,
+the code will try to use shared memory (if available), the same as in Z-Push 2.2.x. 
 
-For the default webserver user please refer to your distribution's manual.
+To force the usage of the memcached provider, set the IPC_PROVIDER parameter in the config to:
+    define('IPC_PROVIDER', 'IpcMemcachedProvider'); 
 
-Now, you must configure Apache to redirect the URL
+4. Webserver configuration
+You must configure Apache to redirect the URL
 'Microsoft-Server-ActiveSync' to the index.php file in the Z-Push
 directory. This can be done by adding the line:
 
@@ -88,6 +135,9 @@ distribution).
 
 You have to reload your webserver after making these configurations.
 
+It's known that other webservers like nginx also work with Z-Push. Please
+feel free to contribute configuration steps and file in our wiki.
+
 *WARNING* You CANNOT simply rename the z-push directory to
 Microsoft-Server-ActiveSync. This will cause Apache to send redirects to the
 mobile device, which will definitely break your mobile device synchronisation.
@@ -114,7 +164,7 @@ z-push directory so these settings are considered only there.
 If you don't set this up correctly, you will not be
 able to login correctly via z-push.
 
-Please also set a memory_limit for php to 128M in php.ini.
+Please also set a memory_limit for php to 128M or higher in your php.ini.
 
 Z-Push writes files to your file system like logs or data from the
 FileStateMachine (which is default). In order to make this possible,
@@ -125,6 +175,8 @@ log and state directories.
 
 After doing this, you should be able to synchronize with your mobile device.
 
+Tools
+-----
 To use the command line tools, access the installation directory
 (usually /usr/share/z-push) and execute:
     ./z-push-top.php        and/or
@@ -137,6 +189,9 @@ To facilitate the access symbolic links can be created, by executing:
 With these symlinks in place the cli tools can be accessed from any
 directory and without the php file extension.
 
+The usage of the tools is explained here:
+https://wiki.z-hub.io/display/ZP/Tools:+z-push-top
+https://wiki.z-hub.io/display/ZP/Tools:+z-push-admin
 
 Upgrade
 -------
@@ -159,7 +214,7 @@ will break completely.
 *Important*
 Upgrading to Z-Push 2.X from 1.X it is not necessary to copy the state
 directory because states are not compatible. However Z-Push 2 implements
-a fully automatic resynchronizing of devices in the case states are
+a fully automatic re-synchronizing of devices in the case states are
 missing or faulty.
 
 *Important*
@@ -172,13 +227,19 @@ States of Z-Push 2.0 and Z-Push 2.1 are not compatible. A state migration
 script called migrate-2.0.x-2.1.0.php is available in the tools folder.
 
 *Important*
-When running Z-Push seperately from your Kopano installation you had in
+When upgrading your states from Z-Push 2.2.x to 2.3 it's required to run 
+"z-push-admin -a fixstates" once to ensure state compatibility.
+More recommendations on upgrading here:
+https://wiki.z-hub.io/display/ZP/Upgrade+to+Z-Push+2.3
+
+*Important*
+When running Z-Push separately from your Kopano installation you had in
 the past to configure MAPI_SERVER directly in the config.php of Z-Push.
 This setting has now moved to the config.php file of the Kopano backend
 (backend/kopano/config.php).
 
 Please also observe the published release notes of the new Z-Push version.
-For some releases it is necessary to e.g. resynchronize the mobile.
+For some releases it is necessary to e.g. re-synchronize the mobile.
 
 
 S/MIME
@@ -203,13 +264,13 @@ Symantec or Comodo or community-driven e.g. CAcert.org.
 
 Both most popular directory services Microsoft Active Directory (MS AD)
 and free open source solution OpenLDAP allow to save certificates. Private
-keys/certificates reside in user’s directory or on a smartcard. Public
+keys/certificates reside in user's directory or on a smartcard. Public
 certificates are saved in directory. MS AD and OpenLDAP both use
-serCertificate attribute to save it.
+userCertificate attribute to save it.
 
 In Active Directory the public key for contacts from GAB is saved in
 PR_EMS_AB_TAGGED_X509_CERT (0x8C6A1102) property and if you save a key
-in a contact it’s PR_USER_X509_CERTIFICATE (0x3A701102).
+in a contact it's PR_USER_X509_CERTIFICATE (0x3A701102).
 
 In LDAP public key for contacts from GAB is saved in userCertificate
 property. It should be mapped to 0x3A220102 in ldap.propmap.cfg
@@ -229,7 +290,7 @@ http://www.zarafa.com/blog/post/2013/05/smime-z-push-signing-and-en-decrypting-e
 Setting up your mobile device
 -----------------------------
 
-This is simply a case of adding an 'exchange server' to your activesync
+This is simply a case of adding an 'exchange server' to your ActiveSync
 server list, specifying the IP address of the Z-Push's apache server,
 disabling SSL, unless you have already setup SSL on your Apache server,
 setting the correct username and password (the domain is ignored, you can
@@ -242,7 +303,7 @@ simply by clicking the 'Sync' button in ActiveSync on your mobile.
 *NOTE* using the synchronisation without SSL is not recommended because
 your private data is transmitted in clear text over the net. Configuring
 SSL on Apache is beyond of the scope of this document. Please refer to
-Apache documention available at http://httpd.apache.org/docs/
+Apache documentation available at http://httpd.apache.org/docs/
 
 
 Troubleshooting
@@ -251,7 +312,7 @@ Troubleshooting
 Most problems will be caused by incorrect Apache settings. To test whether
 your Apache setup is working correctly, you can simply type the Z-Push URL
 in your browser, to see if apache is correctly redirecting your request to
-z-push. You can simply use:
+Z-Push. You can simply use:
 
     http://<serverip>/Microsoft-Server-ActiveSync