amorfo77/sogo
1
0
Fork 0
mirror of https://github.com/inverse-inc/sogo.git synced 2026-05-19 18:35:25 +00:00
Code Issues Projects Releases Wiki Activity

Added other documentation files as asciidoc

Browse Source
This commit is contained in:
Jens Erat
2014-07-20 00:22:38 +02:00
parent 8d4c0ff694
commit 95191cb29b
4 changed files with 1379 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/SOGo Mobile Devices Configuration Guide.asciidoc
+330
View File
@@ -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/<username>`
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[]
Documentation/SOGo Mozilla Thunderbird Configuration.asciidoc
+358
View File
@@ -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:
<Seq about="http://inverse.ca/sogo-integrator/extensions" isi:updateURL="http://sogo-demo.inverse.ca/plugins/updates.php?plugin=%ITEM_ID%&amp;version=%ITEM_VERSION%&amp;platform=%PLATFORM%">
by:
<Seq about="http://inverse.ca/sogo-integrator/extensions" isi:updateURL="https://sogo.acme.com/plugins/updates.php?plugin=%ITEM_ID%&amp;version=%ITEM_VERSION%&amp;platform=%PLATFORM%">
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:
<em:updateLink><?php echo dirname(getenv('SCRIPT_URI')) . '/relative/path/to/' . $plugin["filename"] ?></em:updateLink>
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:
----
"<extension ID>"
=> array( "application" => "thunderbird",
"version" => "<exact version found in the extension's install.rdf file>",
"filename" => "<exact filename on the filesystem>" )
----
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:
----
<li>
<Description
em:id="{e2fda1a4-762b-4020-b5ad-a41df1933103}"
em:name="Lightning"/>
</li>
<li>
<Description
em:id="sogo-integrator@inverse.ca"
em:name="SOGo Integrator"/>
</li>
<li>
<Description
em:id="sogo-connector@inverse.ca"
em:name="SOGo Connector"/>
</li>
----
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[]
Documentation/SOGo Native Outlook Configuration.asciidoc
+691
View File
@@ -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 <username>
samba-tool user setexpiry <username> --noexpiry
# create user in openchange+ +openchange_newuser --create <username>
----
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/<username/password` (or
`/var/lib/samba/private/mapistore/<username/password` on Debian-based
distributions).
This per-user file contains the cleartext password of the user as a
UTF-8 string, on a single line. This password will be used to
authenticate SOGo/OpenChange storage provider to your IMAP server.
Microsoft Outlook Configuration
-------------------------------
To connect Microsoft Outlook, you can either use the IP address of the
server or its DNS name. If you prefer using the DNS name, add an entry
like the following to the `c:\windows\system32\drivers\etc\hosts` file
in order to associate the IP address with the right DNS names:
192.168.1.1 sogo.example.com autodiscover.example.com
Next, you must configure Microsoft Outlook.
* Open the Control Panel => 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[]
Documentation/images/openchange.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 311 KiB