ZP-250 #comment autodiscover installation file

git-svn-id: https://z-push.org/svn/z-push/trunk@1915 b7dd7b3b-3a3c-0410-9da9-bee62a6cc5b5

src/autodiscover/INSTALL

+Z-Push AutoDiscover manual
+--------------------------
+This manual gives an introduction to the Z-Push AutoDiscover service, discusses 
+technical details and explains the installation.
+
+Introduction
+------------
+AutoDiscover is the service used to simplify the configuration of collaboration 
+accounts for clients, especially for mobile phones.
+While in the past the user was required to enter the server name, user name and 
+password manually into his mobile phone in order to connect, with AutoDiscover 
+the user is only required to fill in his email address and the password. 
+AutoDiscover will try several methods to reach the correct server automatically.
+
+
+How does it work?
+-----------------
+When speaking about AutoDiscover, this includes two distinct realms:
+- AutoDiscover is a specification which defines the steps a client should take 
+  in order to contact a service to request additional data.
+- The AutoDiscover service is piece of software which accepts requests from the 
+  clients, authenticates them, requests some additional data from the 
+  collaboration server and sends this data back to the client.
+The specification suggests several ways for client to contact the responsible 
+server to receive additional information. Tests have shown, that basically all 
+mobile phones tested support only the most basic ways. These are sufficient for 
+almost all types of scenarios and are the ones implemented by Z-Push AutoDiscover. 
+Please refer to the Mobile Compatibility List (http://z-push.sf.net/compatibility) 
+for an overview of supported and tested devices.
+The used email address is the key for the process. The client splits it up into 
+the local and domain part (before and after the @-sign). The client then tries 
+to connect to this domain in order to get in contact with the AutoDiscover 
+service. The local part of the email address is used as "login" to the 
+AutoDiscover service. There is also an option, to use the full email address as 
+login name (see "Configuration" section below for details).
+
+
+                     ---------------
+                     |    Client   |
+                     | e.g. mobile |
+                     ---------------
+                    /               \
+   1. Searches for /                 \ 2. Data access
+     information  /                   \
+                 /                     \
+                V                       V
+ ----------------                       --------------
+ | AutoDiscover |      redirects to     |   Z-Push   |
+ |              | --------------------> | ActiveSync |
+ ----------------                       --------------
+                \                       /
+       Authen-   \                     /  Synchronizes
+       ticates    \                   /
+       via Z-Push  \                 /
+       Backend      V               V
+                    -----------------
+                    | Collaboration |
+                    |    Platform   |
+                    -----------------
+
+Requirements
+------------
+As described in the previous chapter, the local part of the email address or 
+the email address is used in order to log in. 
+Your configuration requires that this type of login is possible:
+- either the user name is used to login and must be used in the email address 
+  entered on the mobile, or
+- the entire email address is used to login.
+ 
+Which option is used has to be configured in the AutoDiscover configuration and
+in the underlying platform (e.g. ZCP (hosting mode)).
+Most companies use the user name as local part of the email by default. From the
+AutoDiscover point of view, it is not required that user is able to receive 
+emails at the used email address. It is recommended allowing that in order not 
+to confuse end users.
+
+AutoDiscover also requires a valid SSL certificate to work as expected. A very 
+little percentage of mobiles support self-signed certificates (showing a 
+pop-up alerting the user). Most mobiles silently ignore self-signed certificates 
+and just declare the AutoDiscover process as failed in such cases. 
+If AutoDiscover fails, the user is generally redirected to the 
+"manual configuration" of the client.
+
+If you do not plan to acquire an official certificate, you will probably not be 
+able to use the AutoDiscover service.
+Depending on your setup, it could be necessary to add new DNS entries for your 
+mail domain.
+
+
+Domain setup
+------------
+There are two general ways the AutoDiscover process can be configured:
+1. Directly with "yourdomain.com" website ("www.yourdomain.com" will most 
+   probably not work)
+2. With the sub-domain "autodiscover.yourdomain.com"
+In both cases, an official SSL certificate is required. If you already have a 
+certificate for your domain, the webserver answering for that domain could be 
+reconfigured to allow AutoDiscover requests as well. In the case that you do 
+not have direct access to this type of configuration (e.g. hosting provider), 
+it's recommended to acquire a dedicated certificate for 
+"autodiscover.yourdomain.com". Please note, that this sub-domain can NOT be 
+renamed. In general, "wildcard" certificates can be used, as long they are 
+valid for the required domain.
+
+
+Software requirements
+---------------------
+Like Z-Push, AutoDiscover is written in PHP, where PHP 5.1 or newer is required. 
+Please consult the Z-Push INSTALL file for further information about PHP versions.
+If only AutoDiscover is to be executed on a host, the Z-Push PHP dependencies do 
+NOT need to be installed.
+AutoDiscover has one direct dependency, the php-xml parser library.
+
+These packages vary in names between the distributions.
+- Generally install the packages:                   php-xml
+- On Suse (SLES & OpenSuse) install the packages:   php53-xml
+- On RHEL based systems install the package:        php-xml
+
+
+Installation
+------------
+AutoDiscover is part of the Z-Push package and uses some of the functionality 
+available in Z-Push. 
+It is possible to install AutoDiscover on the same host as Z-Push, or to 
+install them on different hosts.
+
+Currently, independently from the setup, it's recommended to extract the entire 
+z-push tarball and configure the services as required.
+Please follow the install instructions from the Z-Push INSTALL file (section 
+"How to install") to copy the files to your server.
+If you do not want to setup Z-Push on the host, do not add the "Alias" for 
+ActiveSync.
+
+To setup the SSL certificate, please refer to one of the many setup guides 
+available on the internet, like that one:
+http://www.apache.com/resources/how-to-setup-an-ssl-certificate-on-apache/
+
+The mobiles requests these URLs (where "yourdomain.com" corresponds to the 
+domain part of the email used in the client):
+    https://yourdomain.com/Autodiscover/Autodiscover.xml                and/or
+    https://autodiscover.yourdomain.com/Autodiscover/Autodiscover.xml
+
+Add the following line to the apache site configuration file.
+    AliasMatch (?i)/Autodiscover/Autodiscover.xml "/usr/share/z-push/autodiscover/autodiscover.php"
+
+This line assumes that Z-Push is installed in /usr/share/z-push. If the path 
+is different, please adjust it accordingly.
+    
+Note: some mobiles use different casings, like "AutoDiscover" in the URL. The 
+above statement is valid for these as well.
+
+Please restart Apache afterwards.
+
+
+Configuration
+-------------
+There are several parameters in the configuration file, which allow to customize 
+the behaviour of the AutoDiscover Service.
+The configuration, generally is located in the z-push/autodiscover directory and 
+is called "config.php".
+
+The parameters:
+BASE_PATH               This property specifies where the AutoDiscover files are 
+                        located. Normally there is no need to adjust this parameter.
+SERVERURL               This is the full URL where the Z-Push server is available. 
+                        You should adjust it to the domain/server where Z-Push is 
+                        installed.
+                        
+USE_FULLEMAIL_FOR_LOGIN If this is set to "true", AutoDiscover will attempt to 
+                        login on the collaboration server with the full email 
+                        address sent by the client. If disabled (default), the 
+                        local part of the email address is used.
+                        
+LOGFILEDIR              The directory where logfiles are created.
+
+LOGFILE                 The default AutoDiscover log file.
+
+LOGERRORFILE            The default AutoDiscover error log file.
+
+LOGLEVEL                The loglevel, set it to WBXML to see the data received 
+                        and sent from/to clients.
+                        
+LOGAUTHFAIL             Set to true, to explicitly log failed login attempts.
+
+BACKEND_PROVIDER        The backend to be used. If empty (default) the code 
+                        will auto detect which backend to use.
+
+Please note: the desired backend also needs to be configured, in the 
+"backends/<backend>/config.php" file.
+
+
+Test installation
+-----------------
+If everything is correct, accessing with a browser the URL for your setup, you 
+should see:
+    1. a pop-up asking for your username + password. Always use the email 
+       address which you would also enter on the mobile (independently from 
+       the configuration).
+    2. if the authentication was successful, you will see a Z-Push informational 
+       page (like when accessing the Z-Push location).
+    
+Note: The same test can also be performed in the mobiles web browser to check 
+if the access works correctly from the mobile network.
+
+If the authentication fails, please check the configuration options of AutoDiscover.
+Also check the logfiles for possible failures.
+
+If the manual method works, try setting up your mobile phone! :)