diff --git a/Documentation/SOGo Mobile Devices Configuration Guide.asciidoc b/Documentation/SOGo Mobile Devices Configuration Guide.asciidoc new file mode 100644 index 000000000..d1871b44a --- /dev/null +++ b/Documentation/SOGo Mobile Devices Configuration Guide.asciidoc @@ -0,0 +1,330 @@ +Mobile Devices Configuration Guide +================================== + +//// + + This file is part of the SOGo project. + + See SOGo Mobile Devices Configuration-docinfo.xml for authors, + copyright and license information. + +//// + +include::includes/global-attributes.asciidoc[] + +About this Guide +---------------- + +This guide will walk you through the installation and configuration of +popular SyncML clients to be used with the SOGo solution. + +This guide also include instructions for configuring Apple iPhone OS +devices (iPhone, iPod touch, and iPad). + +The instructions are based on version {release_version} of SOGo. + +The latest version of this guide is available at +http://www.sogo.nu/downloads/documentation.html. + +Introduction +------------ + +SOGo is a free and modern scalable groupware server. It offers shared +calendars, address books, and emails through your favourite Web browser +and by using a native client such as Mozilla Thunderbird and Lightning. + +SOGo is standard-compliant. It supports CalDAV, CardDAV, GroupDAV, iMIP +and iTIP and reuses existing IMAP, SMTP and database servers - making +the solution easy to deploy and interoperable with many applications. + +SOGo features: + +* Scalable architecture suitable for deployments from dozen to many +thousand users +* Rich Web-based interface that shares the look and feel, the features +and the data of Mozilla Thunderbird and Lightning +* Improved integration with Mozilla Thunderbird and Lighthing by using +the SOGo Connector and the SOGo Integrator +* Two-way synchronization support with any Microsoft ActiveSync-capable +device, or Outlook 2013 + +SOGo is developed by a community of developers located mainly in North +America and Europe. More information can be found on +http://www.sogo.nu/. + +Installation +------------ + +This section will guide you through the installation of popular SyncML +clients on various devices. + +Funambol SyncML Client +~~~~~~~~~~~~~~~~~~~~~~ + +The recommended SyncML client for BlackBerry, Apple iPhone (for +contacts), mobile devices based on Microsoft Windows Mobile Smartphone +or Windows Mobile PocketPC, is the one provided directly by Funambol, +which is free and open source. + +For Microsoft Window Mobile, you must identify which kind of device you +have ("Smartphone" vs. "PocketPC"). + +Once you've identified what kind of device you have, download the +appropriate client from: + +http://www.funambol.com/opensource/downloads.php + +The version 8.5 GA or later is required.  + +NextHaus SyncJe +~~~~~~~~~~~~~~~ + +For BlackBerry and Apple iPhone devices, you can also use the +SyncJe SyncML client from NextHaus (http://www.nexthaus.com/). This +client allows one to synchronize contacts, event and tasks with SOGo. + +The version 2.43 or later is required. For BlackBerry 7XXX devices, the +required version is 2.25 but isn't officially supported. You can install +SyncJe on your BlackBerry device, over the air, by opening the following +link from your BlackBerry device: + +http://www.nexthaus.com/bb/syncjebb.jad + +This will download and install the application on your mobile device. +It's important to use the Web browser application and not the WAP +browser to perform this operation. Once installed, restart the device. +This procedure can also be used to update the SyncJe application. Note +that an update of SyncJe will not affect the state of previous +synchronizations. It's not necessary to perform a "slow sync" after an +update of SyncJe.  + +Synthesis SyncML Client +~~~~~~~~~~~~~~~~~~~~~~~ + +The Synthesis (http://www.synthesis.ch/) company provides a SyncML +client for Palm OS-based devices. + +"Over The Air" synchronization is possible, as well as synchronization +through a cradle. For the latter, you must install Softick PPP using the +Palm Desktop software. The version 3.01 or later is required and you can +download it from http://www.softick.com/ppp/. Once installed, the +desktop computer must be restarted. + +Once completed, you must download the Synthesis client for Palm OS. The +version 3.0.2.9 or later is required. Either the standard or the +professional version can be used. + +Once downloaded, uncompress the archive and install the `.prc` file on +your Palm OS-based device. After, you should see a "SyncML" icon on your +device. + +Configuration +------------- + +In this section, you'll learn how to configure the popular SyncML +clients in order to fully synchronize your mobile device with SOGo. + +Instructions for Apple iPhone OS based devices are also included. Note +that those devices do not require a SyncML client for synchronizing +calendars. + +Funambol SyncML Client +~~~~~~~~~~~~~~~~~~~~~~ + +Once the Funambol SyncML client is installed, start the application from +your mobile device to configure it using the following steps: + +From the _Tools_ menu, choose _Options..._: + +* Specify the _Location_. If your SOGo server is `sogo.domain.com`, the +location should be `http://sogo.domain.com/funambol/ds`. +* Specify your username and password +* Check the _Contacts_ check box and click on the _Details_ button. + The synchronization type is _two-way_ and the _Remote name_ is + `sogo-card`. The data format is vCard. +* Check the _Calendar_ check box and click on the _Details_ button. The + synchronization type is _two-way_ and the _Remote name_ is `sogo-cal`. + The data format is vCalendar. +* Check the _Tasks_ check box and click on the _Details_ button. The + synchronization type is _two-way_ and the _Remote name_ is + `sogo-todo`. The data format is SIF. +* Save the preferences. + +To prevent the BlackBerry to automatically add a new event in the +calendar when an invitation is received by email (IMIP message) on the +BlackBerry device, you should delete the CICAL service from the Service +Book. To do so, proceed with the following steps: + +From the _Options_ menu: + +* Choose _Advanced Options_ +* Choose _Service Book_ +* Identify the line that mentions the email address of the BlackBerry + user followed by the `[CICAL]` string. For example, `user@domain.com +[CICAL]`. +* Delete this entry. + +Once completed, you must restart the device by removing its battery for +a couple of seconds. If you ever want to reactivate the CICAL service, +follow those instructions: + +http://support.appriver.com/KB/a205/how-to-resend-service-books-on-blackberry.aspx + +Once complete, the client is ready for an initial synchronization. + +Ideally, you should *delete* all data from the mobile device before the +initial synchronization. To do so: + +* From the _Tools_ menu, choose _Recover..._ +* Choose _Replace with data from server_ +* Check the _Contacts_, _Calendar_ and _Tasks_ check boxes + +Finally, click on the _Sync All_ button to proceed with the +synchronization. + +NextHaus SyncJe +~~~~~~~~~~~~~~~ + +Once NextHaus SyncJe is installed, proceed with the following steps, +from your BlackBerry device, to configure it: + +* Open the _SyncJe Client_ + +From the _Settings_ menu: + +* Specify the _Server URL_. If your SOGo server is `sogo.domain.com`, +the URL should be `http://sogo.domain.com/funambol/ds`. +* Specify your user name and password +* Check the _Contacts_ check box and specify `sogo-card` as the + _Foldername_ +* Check the _Calendar_ check box and specify `sogo-cal` as the + _Foldername_ +* Check the _ToDo_ check box and specify `sogo-todo` as the _Foldername_ +* Check the _Auto Sync_ check box if you wish to automatically + synchronize contacts, events and tasks at a predefined time interval +* Do *not* check the _Sync events between_ check box +* Check the _Skip saving attendees_ - this will prevent the BlackBerry + device from sending emails to meeting participants for events + downloaded from the SOGo server +* Check the _BIS_ check box (for _BlackBerry Internet Services_) +* Leave the other fields to the their default value +* Then choose _Save_ from the menu to save the preferences  + +To prevent the BlackBerry to automatically add a new event in the +calendar when an invitation is received by email (IMIP message) on the +BlackBerry device, you should delete the CICAL service from the Service +Book. To do so, proceed with the following steps: + +From the _Options_ menu: + +* Choose _Advanced Options_ +* Choose _Service Book_ +* Identify the line that mentions the email address of the BlackBerry +user followed by the `[CICAL]` string. For example, `user@domain.com +[CICAL]`. +* Delete this entry + +Once completed, you must restart the device by removing its battery for +a couple of seconds. If you ever want to reactivate the CICAL service, +follow those instructions: + +http://support.appriver.com/KB/a205/how-to-resend-service-books-on-blackberry.aspx + +Once done, you're now ready for your first synchronization. + +Ideally, you must delete all data on the BlackBerry before proceeding +with the initial synchronization. To do so, proceed with the following +steps: + +* Open the _SyncJe Client_ + +From the _Settings_ menu: + +* Choose the _Clear databases_ option +* Respond _Yes_ to all questions. This will delete all contacts, events + and tasks from your BlackBerry device.  +* Go back in the previous menu +* Choose the _Force Slow Sync_ option +* Choose the _Start Sync_ option to start the synchronization. This + could take a few minutes if you have many contacts, events or tasks. + Subsequent synchronizations should be much faster.  + +After the initial _Slow Sync_, you can simply chose the _Start Sync_ +option if you do a manual synchronization to synchronize all changes.  + +Synthesis SyncML Client +~~~~~~~~~~~~~~~~~~~~~~~ + +Once the Synthesis SyncML client is installed, proceed with the +following steps to configure it: + +* Open the _Synthesis SyncML Standard Edition_ application + +From the _Settings..._ menu: + +* Specify the _Server URL_. If your SOGo server is `sogo.domain.com`, + the URL should be `http://sogo.domain.com/funambol/ds`. +* Specify your user name and password +* Check the _Contacts_, _Events_ and _Task_ check boxes +* Click on the _more..._ button +* For the _Contacts_, choose _reload device_ and specify `sogo-card` as + the _Server Path_. +* For the _Events_, choose _reload device_ and specify `sogo-cal` as + the _Server Path_. Do *not* check the _Only from..._ check box. +* For the _Tasks_, choose _reload device_ and specify `sogo-todo` as + the _Server Path_. +* Once completed, click on the _Done_ button + +The _reload device_ value will *delete* all entries on the device during +the initial synchronization and obtain contacts, events and tasks from +the server. If you do not want to delete everything from the device, +please choose _normal_ instead of _reload device_. + +Once ready, click on the _Start_ button to proceed with the initial +synchronization. + +During the initial synchronization, the Palm device will ask you how to +connect to the desktop system. From the Palm device, choose _Windows +RAS_ without specifying an user name or a password. This will allow the +Palm device to establish a PPP connection between itself and Softick PPP +and then communicate using its TCP/IP stack to the Funambol server. + +Apple iOS — Calendars +~~~~~~~~~~~~~~~~~~~~~ + +Starting from iOS 3, Apple has added CalDAV support to the calendar +application included in the iPhone/iPod/iPad. + +To add a CalDAV account, follow those instructions: + +* From the _Settings_ menu, choose _Mail, Contacts, Calendars_ +* Choose _Add Account..._ +* Choose _Other_ +* Choose _Add CalDAV Account_ +* Specify the _Server_, the URL should be + `http://sogo.domain.com/SOGo/dav/` + +On iOS 3.1.2 and later, you must also specify the range of events you +want to have.  + +* From the _Settings_ menu, choose _Mail, Contacts, Calendars_ +* From the _Sync_ menu, choose _All Events_ + +Note that other options (_Events 2 Weeks Back_, etc.) do not work right +now. + +Apple iOS — Contacts +~~~~~~~~~~~~~~~~~~~~ + +If you want to synchronize contacts with your Apple mobile device, use +the native address book application with SOGo using the CardDAV +protocol. To configure the address book application so it works with +SOGo, create a new CardDAV account and specify your server name. In +the _Advanced Settings_, set the port to `8800`. + +On iOS prior to version 4, you must install the Funambol client and +configure the `sogo-card` source. + +include::includes/additional-info.asciidoc[] + +include::includes/commercial-support.asciidoc[] diff --git a/Documentation/SOGo Mozilla Thunderbird Configuration.asciidoc b/Documentation/SOGo Mozilla Thunderbird Configuration.asciidoc new file mode 100644 index 000000000..9457e37f0 --- /dev/null +++ b/Documentation/SOGo Mozilla Thunderbird Configuration.asciidoc @@ -0,0 +1,358 @@ +Mozilla Thunderbird Configuration Guide +======================================= + +//// + + This file is part of the SOGo project. + + See SOGo Mozilla Thunderbird Configuration Guide-docinfo.xml for + authors, copyright and license information. + +//// + +include::includes/global-attributes.asciidoc[] + +About this Guide +---------------- + +This guide will walk you through the installation and configuration of +Mozilla Thunderbird and its associated extensions so it can be used with +the SOGo solution. + +The instructions are based on version {release_version} of SOGo. + +The latest version of this guide is available +at http://www.sogo.nu/downloads/documentation.html. + +Introduction +------------ + +SOGo is a free and modern scalable groupware server. It offers shared +calendars, address books, and emails through your favourite Web browser +and by using a native client such as Mozilla Thunderbird and Lightning. + +SOGo is standard-compliant. It supports CalDAV, CardDAV, GroupDAV, iMIP +and iTIP and reuses existing IMAP, SMTP and database servers - making +the solution easy to deploy and interoperable with many applications. + +SOGo features: + +* Scalable architecture suitable for deployments from dozen to many +thousand users +* Rich Web-based interface that shares the look and feel, the features +and the data of Mozilla Thunderbird and Lightning +* Improved integration with Mozilla Thunderbird and Lightning by using +the SOGo Connector and the SOGo Integrator extensions +* Two-way synchronization support with any Microsoft ActiveSync-capable +device, or Outlook 2013 + +SOGo is developed by a community of developers located mainly in North +America and Europe. More information can be found on +http://www.sogo.nu/. + +Installation +------------ + +This section will guide you through the installation of Thunderbird and +its associated extensions. + +Mozilla Thunderbird +~~~~~~~~~~~~~~~~~~~ + +Mozilla Thunderbird is the official front end client of SOGo. + +Mozilla Thunderbird version 2, 3.1, 10 ESR (Extended Support Release), +17 ESR, and 24 are supported and it is recommended to use version 24 of +Thunderbird. + +In order to download and install Mozilla Thunderbird, please visit: + +https://www.mozilla.org/en-US/thunderbird/organizations/all-esr.html + +Mozilla Lightning +~~~~~~~~~~~~~~~~~ + +When using version 24 of Thunderbird, you can use the latest version of +Mozilla Lightning. Use the Add-ons manager of Thunderbird or visit: + +https://addons.mozilla.org/en-US/thunderbird/addon/lightning/ + +When using version 17 ESR of Thunderbird, you can use Mozilla Lightning +version 1.9.1. In order to download the extension, please visit: + +https://addons.mozilla.org/en-US/thunderbird/addon/lightning/versions/?page=1#version-1.9.1 + +For Thunderbird 2 and 3.1, you need the _Inverse Edition_of Mozilla +Lightning. It provides back ported features, bug fixes and security +fixes from the current development version of Mozilla Lightning. For +Thunderbird 2, it is based on release version 0.9 of Lightning. For +Thunderbird 3.1, it is based on 1.0b2. + +In order to download and install Mozilla Lightning – Inverse Edition for +Thunderbird 2 or 3.1, please visit: + +http://www.sogo.nu/downloads/frontends.html + +SOGo Connector and SOGo Integrator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SOGo Connector and Integrator extensions are provided to perfect the +integration of Mozilla Thunderbird 2, 3.1, 10 ESR, 17 ESR and 24 with +the SOGo groupware solution. + +First of all, the SOGo Connector extension transforms Thunderbird into a +full DAV client for groupware servers such as SOGo, eGroupware or +Citadel. It does this by adding support for remote DAV address books and +by adding features to be used along with the Lightning calendar +extension. + +Among supported features of the SOGo Connector extension, we have: + +* Free / Busy URL field in the address book +* Free / Busy functionality through HTTP +* Event organizers +* Synchronization of the address book using GroupDAV +* CardDAV implementation for the address book +* Support for WebDAV ACL + +On the other hand, the SOGo Integrator extension transforms Thunderbird +into a pure "heavy" client for SOGo. Whereas the SOGo Connector is meant +for portability (horizontal integration), the SOGo Integrator makes use +of the features and layout only available from SOGo (vertical +integration). + +Among the supported features of the SOGo Integrator extension, we have : + +* Remote administration of folder subscriptions +* Remote administration of folder access control lists (ACL) +* Automatic replication of your local and subscribed folders +* When correctly configured, it handles the propagation of updates to +chosen extensions from a local update server +* Automatic propagation of default settings + +In order to download and install the SOGo Connector and Integrator +extensions, please visit: + +http://www.sogo.nu/downloads/frontends.html + +Prior to installing the SOGo Integrator extension, you should read the +following chapter – _SOGo Integrator Customization_. + +SOGo Integrator Customization +----------------------------- + +In this section, you'll learn how to customize the SOGo Integrator +extension so it can be used alongside your SOGo server. + +Customization +~~~~~~~~~~~~~ + +The customization steps described here involves understanding of XML and +of text file edition. If you do not have those skills, it is recommended +that you don't try to use this extension. + +There are actually two steps in the configuration of a working +environment for SOGo Integrator. First of all, the Integrator will use +the same user name used to connect to the first email server configured +in Thunderbird. It is a current limitation but it will fit nearly all +configurations out there. + +For testing purpose, you are strongly recommended to create and +configure an additional user profile for Thunderbird. This is for two +reasons. The first is because of the limitation mentioned above. The +second is because the Integrator will synchronize your personal address +book onto the SOGo server and then remove it so that only your personal +address book on SOGo will be available. If you are not able to do that, +you may want to make a copy of that address book beforehand. + +The second part requires editing one file in the extension file sub tree +to specify where the SOGo server is located. This is done by hand. In an +enterprise environment, this step is only required once per release +since the updates are expected to propagate automatically.  + +Uncompress (using a ZIP or jar tool) the SOGo Integrator XPI and locate +the following file: + + extensions.rdf + +This file is used for locating the extension update server and the SOGo +server, which we consider to be the same for the moment. There is a line +starting with a "Seq" tag and with an attribute named "isi:updateURL". +Replace the host part of that url with the SOGo server you want to +connect to. + +For example, one would replace: + + + +by: + + + +if the SOGo server is accessible from the following URL: + + https://sogo.acme.com/SOGo + +Note that if you changed the `x-webobjects-server-url` configuration +setting from your HTTP server configuration file for SOGo, the +value *must* match the one you specify in `isi:updateURL` – even the +port number. + +Moreover, you *must* change the value of the +`sogo-integrator.autocomplete.server.urlid` preference from +`defaults/preferences/site.js` to match the identifier of your +_SOGoUserSources_. This source will be used by Thunderbird for +autocompletion. + +Once you're done modifying the configuration file, save your changes and +reconstruct the XPI file.  + +Now start Thunderbird and install your newly modified extension. + +SOGo Update Server +------------------ + +In this section, you will learn how to install and configure the SOGo +Update Server. + +The SOGo Update Server can be used to automatically install or uninstall +Mozilla Thunderbird extensions, push user settings and more – all from a +central place managed by system administrators. + +Installation +~~~~~~~~~~~~ + +Installation is relatively straightforward. You need to make +the `updates.php` script available through your HTTP server at the URL +you've specified from the `extensions.rdf` file. The `updates.php` +script can be found in the SOGo sources, under the `Scripts` directory. + +The `updateLink` section of the XML payload returned to sogo-integrator +is built dynamically using the `SCRIPT_URI` variable, which is only +available when running with mod_rewrite. It should work out of the box +as long as the script is placed in the same directory as the xpi files. + +If it is not the case, then the link should be adjusted to fit the +actual file layout: + + + +An http request similar to the following can be used to make sure that +the generated link is correct: + + http://sogo.host/path/to/updates.php?plugin=sogo-integrator@inverse.ca&version=0.00 + +Please refer to your HTTP server documentation for the installation and +configuration of PHP. + +Configuration +~~~~~~~~~~~~~ + +To configure the SOGo update server, you need to modify the +`updates.php` script directly. + +Adding an extension to be pushed automatically by the update server +require you to modify the `$plugins` array from updates.php and also +adjust accordingly SOGo Integrator's `extensions.rdf` file. + +For example, to automatically install SOGo Connector, SOGo Integrator +and Lightning, you would have: + +---- +$plugins += array( "sogo-connector@inverse.ca" + => array( "application" => "thunderbird", + "version" => "24.0.5", + "filename" => "sogo-connector-24.0.5.xpi" ), + "sogo-integrator@inverse.ca" + => array( "application" => "thunderbird", + "version" => "24.0.5", + "filename" => "sogo-integrator-24.0.5-sogo-demo.xpi" ), + "{e2fda1a4-762b-4020-b5ad-a41df1933103}" + => array( "application" => "thunderbird", + "version" => "2.6.5", + "filename" => "lightning.xpi" )); +---- + +The syntax is: + +---- + "" + => array( "application" => "thunderbird", + "version" => "", + "filename" => "" ) +---- + +The path of the filename, specified in the `filename` parameter, is +relative to the location of the `updates.php` script. For extensions +that are dependant on the architecture and operating system (Microsoft +Windows, Apple Mac OS X, etc.), they can be placed in subdirectories +relative again to the `updates.php` script (but the filename must be +identical in all subdirectories). For exemple, for Mozilla Lightning, we +could have: + +---- +Darwin_x86-gcc3/lightning.xpi +Linux_x86-gcc3/lightning.xpi +Linux_x86_64-gcc3/lightning.xpi +WINNT_x86-msvc/lightning.xpi +---- + +If you eventually want to disable an extension, that is, without +removing it from your users' computers, you can specify `disabled` as +the version number. + +Next is to modify the `extensions.rdf` file. Again, to automatically +install SOGo Connector, SOGo Integrator and Lightning, you would have: + +---- +
  • + +
    • +
  • + +
    • +
  • + +
    • +---- + +Using SOGo Integrator, you can also push user-settings for any part of +Thunderbird or its extensions. There are two kind of user-settings +push: + +* Settings that are pushed during the initial configuration of +Thunderbird +* Settings that are pushed upon every restart (ie., forced) of +Thunderbird + +Settings that pushed are pushed during initial configuration are +controlled by the `./defaults/preferences/site.js` file from SOGo +Integrator. Here is an example: + +---- +pref("calendar.alarms.showmissed", false); +pref("calendar.caldav.sched.enabled", true); +---- + +Preferences that are forced upon every restart of Thunderbird are +controlled from the `./chrome/content/general/custom-preferences.js` +configuration file. + +Here is an example: + +---- +force_int_pref("changequote.replyformat.format", 0); +force_bool_pref("changequote.headers.withcc", true); +force_char_pref(“foo.bar”, “zot”); +---- + +include::includes/additional-info.asciidoc[] + +include::includes/commercial-support.asciidoc[] diff --git a/Documentation/SOGo Native Outlook Configuration.asciidoc b/Documentation/SOGo Native Outlook Configuration.asciidoc new file mode 100644 index 000000000..75eb4eb86 --- /dev/null +++ b/Documentation/SOGo Native Outlook Configuration.asciidoc @@ -0,0 +1,691 @@ +Native Microsoft Outlook Configuration Guide +============================================ + +//// + + This file is part of the SOGo project. + + See SOGo Native Microsoft Outlook Configuration-docinfo.xml for + authors, copyright and license information. + +//// + +include::includes/global-attributes.asciidoc[] + +About this Guide +---------------- + +This guide will walk you through the installation and configuration of +the native Microsoft Outlook compatibility layer SOGo offers. + +Prior going over this guide, you should have a working SOGo +installation. Please refer to the _SOGo Installation and Configuration +Guide_ for more information on installing and configuring SOGo. + +This guide also includes instructions for configuring Microsoft Outlook +with SOGo. + +The instructions are based on version {release_version} of SOGo. + +The latest version of this guide is available +at http://www.sogo.nu/downloads/documentation.html. + +Introduction +------------ + +SOGo is a free and modern scalable groupware server. It offers shared +calendars, address books, and emails through your favourite Web browser +and by using a native client such as Mozilla Thunderbird and Lightning. + +SOGo is standard-compliant. It supports CalDAV, CardDAV, GroupDAV, iMIP +and iTIP and reuses existing IMAP, SMTP and database servers — making +the solution easy to deploy and interoperable with many applications. + +SOGo features: + +* Scalable architecture suitable for deployments from dozen to many +thousand users +* Rich Web-based interface that shares the look and feel, the features +and the data of Mozilla Thunderbird and Lightning +* Improved integration with Mozilla Thunderbird and Lightning by using +the SOGo Connector and the SOGo Integrator +* Native compatibility for Microsoft Outlook 2003, 2007, 2010, and 2013 +* Two-way synchronization support with any Microsoft ActiveSync-capable +device, and Outlook 2013 + +SOGo is developed by a community of developers located mainly in North +America and Europe. More information can be found +on http://www.sogo.nu/. + +Architecture +------------ + +The following diagram demonstrates the architecture of the native +Outlook compatibility layer of SOGo. + +image::images/openchange.png[] + +With Samba 4 and OpenChange, Microsoft Outlook clients can communicate +natively with SOGo using the Microsoft Exchange protocol, without +requiring costly and hard-to-maintain third-party MAPI connectors for +Microsoft Outlook. + +Requirements +------------ + +Organizations generally have solutions to authenticate users such as +LDAP servers or Microsoft Active Directory servers. + +The solution being used will influence how users are provisioned in +Samba 4, a key component for native Outlook compatibility in SOGo. + +LDAP Server +~~~~~~~~~~~ + +If your organization uses a LDAP server such OpenLDAP, Novell +eDirectory, Apache Directory or any other solution, you must use +Samba 4's internal directory server and synchronize the data between +both. + +Synchronization scripts are not provided and unless you have clear-text +passwords of your existing users, they will have to be changed during +your initial synchronization so that your LDAP's server passwords are +identical to the ones from Samba 4. + +Any modifications to your existing LDAP server (password change, user +addition or deletion, etc.) will have to be replicated to Samba 4's +internal directory server. + +Note that if you install Samba 4 on a server that is already running a +LDAP service, you will have to change to TCP port on which your LDAP +server listens to. Samba 4 will use the TCP port 389 and it can't be +changed. + +For example, with OpenLDAP, you can use the `-h` parameter for `slapd` +to make it listen on an other TCP port. + +Microsoft Active Directory +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your organization uses Microsoft Active Directory, Samba 4 will need +to be joined to your Active Directory domain, as a DC. + +Samba 4 will be able to reuse all the information contained in Microsoft +Active Directory and no synchronization process needs to be put in place +as information will get replicated to Samba 4 automatically. + +For more information on joining Samba 4 to an existing Microsoft Active +Directory domain, please refer to the Samba 4 documentation available at +the following URL: + +http://wiki.samba.org/index.php/Samba4 + +More specifically, have a look at the `samba-tool domain join` command. +Note that joining Samba 4 to your Active Directory domain as a member +will currently not work. An authentication bug is present in Samba 4 +which then prevents all Outlook users to successfully authenticate +through Samba 4. This issue has been reported to the Samba team and is +being worked on. + +Other or No Solution +~~~~~~~~~~~~~~~~~~~~ + +If your organization neither uses a LDAP server or Microsoft Active +Directory, you can start using Samba 4 as your directory server. + +Samba 4's directory can be queried over LDAP just like Microsoft Active +Directory and can also serve as a domain controller for Windows-based +environments. + +For example, SOGo can very well use Samba 4's built-in directory server +to authenticate users. A SOGoUserSources entry to achieve this wold look +like this: + +---- +su – sogo +defaults write sogod SOGoUserSources '( + { + CNFieldName = displayName; + IDFieldName = cn; + UIDFieldName = sAMAccountName; + baseDN = "cn=Users,dc=example,dc=com"; + bindDN = "cn=Administrator,cn=Users,dc=example,dc=com"; + bindFields = ( + sAMAccountName + ); + bindPassword = "%1OpenChange"; + canAuthenticate = YES; + displayName = "Shared Addresses"; + hostname = "127.0.0.1"; + id = samba; + isAddressBook = YES; + port = 389; + } +)' +---- + +Please refer to the _SOGo Installation and Configuration Guide_ for more +information regarding `SOGoUserSources`. + +IMAP Server and Trust +~~~~~~~~~~~~~~~~~~~~~ + +An IMAP server supporting the ACL, UIDPLUS and QRESYNC IMAP extensions +is required, such as Cyrus IMAP version 2.4 or later, or Dovecot version +2.1 or later. If your current IMAP server does not support these +extensions, you can use Dovecot's proxying capabilities. The follow +configuration example makes Dovecot proxy all IMAP request to an +existing server: + +---- +auth_mechanisms = plain login +imapc_host = inverse.ca +imapc_port = 993 +imapc_ssl = imaps +imapc_ssl_verify = no +mail_gid = imapproxy +mail_home = /home/imapproxy/%u +mail_location = imapc:~/imapc +mail_uid = imapproxy +passdb { + args = host=inverse.ca ssl=imaps port=993 ssl_ca_dir=/etc/pki/tls/certs + default_fields = userdb_imapc_user=%u userdb_imapc_password=%w + driver = imap +} +protocols = imap +ssl = no +userdb { + driver = prefetch +} +---- + +SOGo would then be configured to use Dovecot's proxy as the IMAP server. + +Moreover, the authentication mode in use by Windows with Samba and +Exchange servers prevent the backend from knowing the real password +being used by the user. This implies that the IMAP server must accept +any passwords from the host on which Samba is running. + +To accomplish this with Cyrus IMAP Server, set `sasl_pwcheck_method` +to `alwaystrue` in `/etc/imapd.conf`. You should restrain this to +an `imapd` instance dedicated to SOGo. + +For Dovecot, use an authentication source similar to: + +---- +passdb { + driver = static + args = nopassword=y allow_nets=127.0.0.1/32 +} +---- + +You should also make sure that you restrain this only to the SOGo +processes. + +For any other IMAP server, refer to the product's documentation. If such +capability is not offered, you can alternatively define the cleartext +password for each user. Please refer to the _Adding Users_ section from +this document. + +Installation +------------ + +This section will guide you through the installation of the native +Microsoft Outlook compatibility layer SOGo offers. + +Red Hat Enterprise Linux v5 and v6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using Red Hat Enterprise Linux (or CentOS) version 5 or +version 6, packages for Samba 4, OpenChange and SOGo and the SOGo +OpenChange backend are available from SOGo's web site. Please follow the +instructions from +http://www.sogo.nu/english/downloads/backend_nightly.html. + +In order to satisfy certain dependencies, you should also add the EPEL +source corresponding to your distribution and architecture. More +information on this is available here: +http://fedoraproject.org/wiki/EPEL – or more specifically, +http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F. + +Once ready, install the OpenChange packages on top of an existing SOGo +installation: + +---- +yum clean all && yum makecache +yum install samba4 \ + openchange \ + sogo-openchange-backend \ + openchange-ocsmanager \ + openchange-rpcproxy +---- + +Once the packages are installed, refer to the _Configuration_ chapter +from this guide. + +Debian 6.0 (Squeeze) and Ubuntu 12.04 (Precise Pangolin) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Samba 4, OpenChange, SOGo and the SOGo OpenChange backend are now +available from SOGo's web site. Please follow the instructions from +http://www.sogo.nu/english/downloads/backend_nightly.html to setup your +apt sources. + +Debian Squeeze ships an older version of some libraries required by +Samba 4. In order to workaround this, users of this distribution will +have to use the _squeeze-backports_ repository. To do so, create +`/etc/apt/sources.list.d/backports.list`: + + deb http://backports.debian.org/debian-backports squeeze-backports main + +Then install the dependencies on Debian Squeeze, do: + +---- +apt-get update +apt-get install -t squeeze-backports libwbclient-dev samba-common smbclient libsmbclient libsmbclient-dev +---- + +Once ready, install the `samba4` package on top of an existing SOGo +installation: + +---- +apt-get update +apt-get install samba4 +---- + +The current post installation script shipped with the Samba 4 package is +far from perfect and might fail even on a fresh install. The following +command is needed to let dpkg know that everything is fine about Samba 4 +if the post install script fails. + + sed --in-place 'N; s/Package: samba4\nStatus: install ok half-configured/Package: samba4\nStatus: install ok installed/;' /var/lib/dpkg/status + +Once completed, install the packages related to OpenChange and the SOGo +provider: + +---- +apt-get install openchangeserver \ + sogo-openchange \ + openchangeproxy \ + openchange-ocsmanager \ + openchange-rpcproxy +---- + +Once the packages are installed, refer to the _Configuration_ chapter +from this guide. + +Configuration +------------- + +In this section, you'll learn how to configure the native Microsoft +Outlook compatibility layer that SOGo offers. + +SOGo Configuration +~~~~~~~~~~~~~~~~~~ + +First thing to do is to configure SOGo to use your current services, +which are your IMAP, SMTP and SQL database servers. The configuration +instructions for this are available in the SOGo Installation and +Configuration Guide available from http://www.sogo.nu/. + +Please refer to that documentation before continuing with the +instructions included in this guide. + +Samba 4 Configuration +~~~~~~~~~~~~~~~~~~~~~ + +Run the following commands as root:  + +---- +samba-tool domain provision --realm=example.com \ + --domain=OPENCHANGE \ + --adminpass='%1OpenChange' \ + --server-role='domain controller' + +samba-tool user setexpiry administrator --noexpiry +---- + +You might consider changing the realm and domain used, to suit your +enviroment. + +You might also have to +remove `/etc/samba4/smb.conf` (or `/etc/samba/smb.conf` on Debian-based +distributions) prior running this command. + +Add the following parameters to the `[global]` section of the +`/etc/samba4/smb.conf` (`/samba/smb.conf` if you use a Debian-based +distribution) configuration file: + +---- +### Configuration required by OpenChange server ### +dcerpc endpoint servers = +epmapper, +mapiproxy +dcerpc_mapiproxy:server = true +dcerpc_mapiproxy:interfaces = exchange_emsmdb, exchange_nsp, exchange_ds_rfr +### Configuration required by OpenChange server ### +---- + +Your Samba 4 configuration file should look like this: + +---- +# Global parameters +[global] + server role = active directory domain controller + workgroup = EXAMPLE + realm = example.com + netbios name = sogo + passdb backend = samba4 + ### Configuration required by OpenChange server ### + dcerpc endpoint servers = +epmapper, +mapiproxy + dcerpc_mapiproxy:server = true + dcerpc_mapiproxy:interfaces = exchange_emsmdb, exchange_nsp, exchange_ds_rfr + ### Configuration required by OpenChange server ### + +[netlogon] + path = /var/lib/samba/sysvol/example.com/scripts + read only = No + +[sysvol] + path = /var/lib/samba/sysvol + read only = No +---- + +OpenChange Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +The Samba AD schema needs to be filled with additional object +definitions by running the following commands:  + +---- +openchange_provision + +NOTE: This operation can take several minutes +[+] Step 1: Register Exchange OIDs +[+] Step 2: Add Exchange attributes to Samba schema +[+] Step 3: Add Exchange auxiliary classes to Samba schema +[+] Step 4: Add Exchange objectCategory to Samba schema +[+] Step 5: Add Exchange containers to Samba schema +[+] Step 6: Add Exchange *sub* containers to Samba schema +[+] Step 7: Add Exchange CfgProtocol subcontainers to Samba schema +[+] Step 8: Add Exchange mailGateway subcontainers to Samba schema +[+] Step 9: Add Exchange classes to Samba schema +[+] Step 10: Add possSuperior attributes to Exchange classes +[+] Step 11: Extend existing Samba classes and attributes +[+] Step 12: Exchange Samba with Exchange configuration objects +[SUCCESS] Done! +---- + +You can safely ignore the "`ERROR: no subClassOf 'serviceAdministrationPoint' for 'rRASAdministrationConnectionPoint'`" message when running the `openchange_provision` command. + +Provision the OpenChange database:  + +---- +openchange_provision --openchangedb + +Setting up openchange db +[+] Public Folders +=================== + * Public Folder Root 0x0100000000000001 + * IPM_SUBTREE 0x0200000000000001 + * NON_IPM_SUBTREE 0x0300000000000001 + * EFORMS REGISTRY 0x0400000000000001 + * OFFLINE ADDRESS BOOK 0x0500000000000001 + * /o=First Organization/cn=addrlists/cn=oabs/cn=Default Offline Address Book 0x0600000000000001 + * SCHEDULE+ FREE BUSY 0x0700000000000001 + * EX:/o=First Organization/ou=Exchange Administrative Group (UBUNTU-OC) 0x0800000000000001 + * Events Root 0x0900000000000001 +---- + +On RHEL, make sure SELinux is disabled: + + setenforce 0 + +Next, you can start Samba using the usual command : + + /etc/init.d/samba4 start + +You can also launch the OpenChange web services: + + /etc/init.d/openchange-ocsmanager start + +Apache Configuration for Web Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The OpenChange web services consist of two components: + +1. *OCS Manager* which is used for autodiscovery and freebusy lookups on +Outlook 2007 and 2010. This service runs in its own application server +which listens on `127.0.0.1:5000` by default. Apache needs to be +configured to forward certain requests to it to make it accessible from +the outside. +Note that this service *MUST* be accessible over*HTTPS*, otherwise Outlook +won't use it. +2. *RPC Proxy* which is used for RPC over HTTP ("Outlook Anywhere"). +This service runs as a WSGI application under apache (mod_wsgi). +While HTTPS is not required to access this service, it is strongly +recommended. + +On RHEL-based distributions, the apache configuration required by these +services can be found in `/etc/httpd/conf.d/ocsmanager.conf` and +`/etc/httpd/conf.d/rpcproxy.conf`. + +For Debian-based distributions, these files can be found +in `/etc/apache2/conf.d/`. + +The configuration requires three Apache modules:  _mod_proxy_, +_mod_proxy_http_ and _mod_wsgi_. These are usually already installed but +might need to be activated on Debian-based installations: + + a2enmod proxy proxy_http wsgi + +On RHEL-based distributions, make sure the `LoadModule` directive is +uncommented in `/etc/httpd/conf.d/wsgi.conf` (or +`python26-mod_wsgi.conf` on RHELv5). + +The _reqtimeout_ apache module is known to cause problems when using the +default configuration shipped with Debian-based systems. On such +distributions, apache will close (HTTP/1.1 500) any HTTP request for +which the HTTP body hasn't arrived in 10 seconds. + +While this is arguably good practice with regular HTTP, it will disrupt +the RPC over HTTP protocol implemented by RPC Proxy: Outlook will +continuously disconnect and reconnect leading to suboptimal performance. + +To avoid this problem, use a much higher timeout or disable the module: + + a2dismod reqtimeout + +You should now restart the Apache service and make sure it will start on +boot. On RHEL-based distributions, do: + + chkconfig httpd on && /etc/init.d/httpd restart + +On Debian-based distributions, do: + + update-rc.d apache2 defaults && /etc/init.d/apache2 restart + +Name Service Configuration for Web Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The autodiscovery service must be made accessible in order to advertise +the web services provided by OpenChange. This can be done in two ways. + +1. The first is to associate the FQDN `autodiscover.example.com.` with +the machine that hosts Samba 4 / OpenChange, by adding a `CNAME` entry +in your DNS configuration. Note that, instead or changing your DNS +server configuration, you can simply add a similar entry to the _hosts_ +file of the Windows machine from where you'll run Outlook, which is +handy for testing purposes. +2. The second option is to add a `SRV` entry to your DNS configuration +where the `_service` value would be `Autodiscover` and the `_protocol` +would be `_tcp`. + +For example: + + _autodiscover._tcp.example.com. IN SRV 0 0 443 sogo.example.com. + +Again, the autodiscovery service must be accessible over HTTPS. + +Adding Users +------------ + +Users that wish to connect natively to SOGo must be provisioned in +Samba 4 and in OpenChange – even if they already exist in your current +LDAP or Microsoft Active Directory server. + +To add a user, execute the following commands:  + +---- +# add user to samba +samba-tool domain passwordsettings set --complexity=off +samba-tool domain passwordsettings set --min-pwd-length=1 +samba-tool user add +samba-tool user setexpiry --noexpiry +# create user in openchange+ +openchange_newuser --create +---- + +If you don't have a trust between your IMAP server and SOGo, you must at +this point set the cleartext password of the newly created user in +`/var/lib/samba4/private/mapistore/ Mail => Email Accounts. +* Select _Add a new e-mail account_ +* Choose _Microsoft Exchange Server_ +* Fill the required information. Enter the DNS name or the IP address of +your SOGo server in the _Microsoft Exchange Server_ field +* Leave the _Use Cached Exchange Mode_ checkbox enabled +* Enter your username in the _User Name_ field +* Click on _More Settings_ and ignore the warning, if any, about +Exchange being offline by clicking on Cancel +* From the Security tab, enable Always prompt for user name and password +* From the _Connection_ tab, enable _"Outlook Anywhere"_ if you plan to +use Outlook outside of your LAN. Moreover, click on the _Exchange Proxy +Settings..._ button to enable it for slow and fast networks. Specify +also the host, which should be the same value you specified in the +Microsoft Exchange Server field. +* Finally, click on Check Name and confirm your username and password + +Start Microsoft Outlook and enter your username and password. It will +start to synchronize your mailbox. This could take a long time if you +have many emails, events, tasks and contacts. Once this step is +completed, check the autodiscovery service with Outlook 2007 or 2010 by +simultaneously holding the CTRL key on your keyboard and right-clicking +on the Outlook icon in the notification toolbar. A special entry named +"Test E-mail AutoConfiguration..." will appear and will enable you to +check the service. + +Known Issues or Limitations +--------------------------- + +* Make sure you periodically backup all your data regarding SOGo. +* Make sure you have no firewalls activated between your Microsoft +Outlook clients and the SOGo server with Native Outlook Compatibility +module. If you do, use "Outlook Anywhere" to connect Outlook to +SOGo/OpenChange. + +Current Limitations +~~~~~~~~~~~~~~~~~~~ + +The current version of the Native Microsoft Outlook compatibility layer +has some limitations. + +Those limitations will be overcome in the upcoming releases. If you are +interested in having those limitations fixed more rapidly, please +contact Inverse by sending an email to support@inverse.ca. + +General +^^^^^^^ + +* If you can't see any email's content with Microsoft Outlook 2007, +install the latest Service Pack available from Microsoft's website for +this specific version. Microsoft Outlook 2007 (12.0.6423.100) SP2 MSO +(12.0.6425.1000) is known to work. +* When you create a new Microsoft Outlook profile, not all folders might +be synchronized during the first start. Simply select the appropriate +folder and click "Send and Receive". Synchronizing a folder may take +some time. For example, a folder with 1000 email messages might take +around 5 minutes based on the underlying hardware. +* Errors when synchronizing the "Offline Address Book" are normal and +can be ignored for now. This feature is currently not supported. +* If you face strange issues from Microsoft Outlook, you might want to +remove any data associated with the user from the SOGo server and +recreate a Microsoft Outlook profile. +To remove any data associated to a user, use +the `openchange_user_cleanup` script distributed with SOGo. The script +can be found in `/usr/share/doc/sogo/` (`/usr/share/sogo-VERSION/` on +RHEL). +To reset a user, run the script as root: +`python openchange_user_cleanup username`. See the usage output for additional options. +* The "Out of Office Assistant" will not currently work. This feature +has not been implemented. +* Creating folders below INBOX (when not normally permitted by the IMAP +server), below the Personal Calendar or Personal Address Book will work +in Outlook cached mode but the server-side operation will fail and these +folders will never be created. Potentially data loss can occur if the +Outlook profile is destroyed. If you wan to create additional top-level +mail folders, calendars or address books, open Outlook's folder list, +select the top level node (usually, "email@example.com") and choose "New +Folder..." from the contextual menu. Choose the relevant item types. + +Mail +^^^^ + +* Sharing mail folders is not supported. +* To avoid possibly lossy conversion from RTF to HTML, Outlook should be +configured to send all mails as HTML (or plaintext) instead of _Outlook +Rich Text Format_. + +Calendar +^^^^^^^^ + +* Labels will not work. +* It might be impossible to view event details from a shared calendar. +This issue is being worked on. + +Tasks +^^^^^ + +* Tasks with start/due dates created from Outlook might not appear +correctly in SOGo due to a timezone issue. +* Reminders are not yet supported. +* Assigning tasks will not work. + +Contacts +^^^^^^^^ + +* Categories will not work. +* Distribution lists will not work. +* Under Microsoft Outlook 2010, the special folder "Suggested Contacts" +will not work. +* The "Offline Address Book" will not work. This feature is not yet +supported. + +Notes +^^^^^ + +* Notes are not synchronized in any ways with SOGo. The current version +of SOGo lacks support for notes. + +If you notice anything else, please send contact Inverse by sending an +email to support@inverse.ca. + +include::includes/additional-info.asciidoc[] + +include::includes/commercial-support.asciidoc[] diff --git a/Documentation/images/openchange.png b/Documentation/images/openchange.png new file mode 100644 index 000000000..75c8f3036 Binary files /dev/null and b/Documentation/images/openchange.png differ