Copyright 2005-2010 OpenChange Project
under the terms at http://creativecommons.org/licenses/by-sa/3.0/


OpenChange developer howto
--------------------------

== Updated in May 2010 ==


###############
[0x0] CONTENTS
###############

+------------------------------------+
[0x1] INTRODUCTION
     [0x1a] What is OpenChange?
     [0x1b] What is libmapi?
[0x2] INSTALLATION
     [0x2a] Samba4 installation
     [0x2b] Requirements
     [0x2c] OpenChange installation
[0x3] POST INSTALLATION
     [0x3a] Create a profile store
     [0x3b] Create a profile
     [0x3c] Test the profile
[0x4] USING LIBMAPI
     [0x4a] Doxygen
     [0x4b] Sample applications
     [0x4c] External resources
[0x5] OPENCHANGE SERVER
     [0x5a] Provision
     [0x5b] Extending users Samba AD schema
     [0x5c] Setting smb.conf
     [0x5d] Running the Server (EMSABP / EMSMDB / RFR)
     [0x5e] Solving problems     
+------------------------------------+


####################
[0x1] INTRODUCTION
####################


[0x1a] What is OpenChange?
==========================

OpenChange both provides an Open Source implementation of Microsoft
Exchange protocols under unix/linux platforms and a server able to
replace transparently Exchange in a company environment.


[0x1b] What is libmapi?
=======================

libmapi is the OpenChange MAPI implementation. It is a programming
interface designed to offer Exchange support to third party
applications.


[0x1c] Why do I have to do all this compilation?
================================================

Several distributions (Debian, Ubuntu, SuSE and Fedora) contain
packages for OpenChange. These packages are not maintained by the
OpenChange team but by the distributions, and may be out of date.

Furthermore the OpenChange project is moving along quickly and you may
want to evaluate or benefit from latest features, changes and bug
fixes we may supply in the future.


####################
[0x2] INSTALLATION 
####################


[0x2a] Samba4 Installation
==========================

[*] First of all, you need to install a Samba 4 version and pidl
    version compliant with OpenChange. Furthermore talloc became an
    external dependency and needs to be installed apart from
    Samba4. This task can automatically be done using the
    installsamba4.sh script located in the script directory.

    Note that the script relies on sudo for "make install" operations
    and requires your account to be in the sudoers file.

    Run the following command:


$ make samba


This should give you the libraries, headers and tools you need to
compile OpenChange. It is rare that you will need to update Samba,
when you have successfully done this once you should not need to do it
again.  As a hint, as well as your base compiler (apt-get install
build-essential on Debian and Ubuntu) you will need pkg-config.

If you want to control every detail of the Samba build, follow the
instructions for checking out the git tree. You will require
tools such as autoconf (apt-get install automake on Debian and
Ubuntu), it will take more time and disk space, and there is more to
go wrong.

Since the libraries will be installed in /usr/local/samba/lib,
ldconfig needs to know about it. On Linux, make sure this directory is
listed in /etc/ld.so.conf and run 'ldconfig -v'. On FreeBSD, add this
directory to the line 'ldconfig_paths' in /etc/rc.conf and then run
'ldconfig -rv'.

Similarly, you need to have /usr/local/samba/bin in your PATH for the
pidl binary. This is also where OpenChange installs its binaries. Eg,
if your shell is bash:

$ export PATH=$PATH:/usr/local/samba/bin

If you did a standard Samba install to the normal Samba4 location you
should not need to change PKG_CONFIG_PATH, however it does need to be
set. Use 

$ echo $PKG_CONFIG_PATH

to see if it has a current value. So if PKG_CONFIG_PATH points to a valid place
and OpenChange configure still complains, you may have a problem with the Samba 
installation.)

If you have installed Samba4 somewhere else, you need to change Samba references
in ld.so.conf, and in the PATH and PKG_CONFIG_PATH environment variables. 
For example, if you installed to /opt/otherplace/samba
run:

$ export PATH=$PATH:/opt/otherplace/samba
$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/otherplace/samba/lib/pkgconfig

pkg-config >= 0.20 is required.


[0x2b] Requirements
===================

OpenChange has only these dependencies in addition to Samba4's
requirements:

* automake (autogen will fail with 'autogen.sh: aclocal not found')
* flex
* libpopt

Samba4 can *use* some of the above, and will tell you in the
'configure' summary that some of them have not been found, however it
does not *require* them.

OpenChange also includes a new build system which will gathers
dependencies on your system and only build what can be compiled with
your current system. If your system doesn't meet the requirements for
a particular tool or library, you will need to install missing
dependencies check below for the list of dependencies you need to
install:

	* libmagic (with development headers): exchange2mbox. For
          example:
		# apt-get install libmagic-dev   (Debian, Ubuntu)
		# pkg_add libmagic               (BSD)

	* bison: libocpf, openchangeclient

	* dcerpc_samr (samba4 installation): libmapiadmin and
          openchangepfadmin

	* doxygen: build the documentation

	* boost-thread: thread support for libmapi++

Similarly for the others:

# apt-get install automake flex bison libpopt    or
# pkg_add automake flex bison libpopt

If you have boost development libraries installed, but they aren't being
found by the configure script (see below), you may need to set the
BOOST_LIB_SUFFIX environmental variable:
$ export BOOST_LIB_SUFFIX=-mt


[0x2c] OpenChange libmapi installation
======================================

If you retrieved the soure code from Subversion, run autogen.sh now:

$ ./autogen.sh

Now, run configure:

$ ./configure --prefix=path_where_samba_is_installed

The default is not /usr/local/samba as you might expect, but /usr/local . So you normally
do need to specify --prefix.

You should already have made sure that the output of 'ldconfig -v' mentions
the samba library directory in the Samba installation step. If you didn't, OpenChange
will not find the libraries it needs.

You should now be able to build and install openchange MAPI library:

$ make && make install

You can test like this:

$ openchangeclient --help



#########################
[0x3] POST-INSTALLATION
#########################

The MAPI library requires a profile database and a profile in that database
before it can be used.


[0x3a] Create a profile store
=============================

$ mapiprofile --database=/tmp/profiles.ldb	\
	      --ldif=/usr/local/samba/share/setup -n


[0x3b] Create a profile
=======================

$ mapiprofile --database=/tmp/profiles.ldb	\
	      --profile=testuser-2000		\
	      --username=testuser		\
	      --password=openchange		\
	      --domain=OPENCHANGE		\
	      -I 192.168.194.22			\
	      --create
Profile testuser-2000 completed and added to database /tmp/profiles.ldb

You need to specify:
    - the full path to the profile store database
    - the profile name you want to create
    - the username/password couple mapiprofile will use to connect to
      the Exchange server (you might want to use Administrator, on a test server)
    - the Windows domain your Exchange server belongs to
    - the IP address of the Exchange server (this must be real. Change the example!)
    - the create operation


[0x3c] Test the profile
=======================

You can next ensure your profile was correctly created by running the
commands below:

$ mapiprofile --database=/tmp/profiles.ldb --list
We have 1 profiles in the database:
        Profile = testuser-2000

$ mapiprofile --database=/tmp/profiles.ldb --profile=testuser-2000 --dump
Profile: testuser-2000
        username       == testuser
        password       == openchange
        mailbox        == /o=First Organization/ou=First Administrative Group/cn=Recipients/cn=testuser
        workstation    == LOCALHOST
	domain	       == OPENCHANGE
        server         == 192.168.194.22


####################
[0x4] USING LIBMAPI
####################

[0x4a] Doxygen
==============

HTML documentation and Man pages are supplied with the MAPI library so
developers can have an overview on how to use each function properly.

Run the following commands to generate and install man pages:
$ make doxygen
# make installman

If you have troubles accessing man pages, be sure your MANPATH
environment variable is set properly and point on openchange prefix
installation path.

$ export MANPATH=$MANPATH:/usr/local/samba/share/man

The HTML documentation is available in the apidocs/html/ directory or
can directly be browsed online at http://www.openchange.org/apidocs/.

[0x4b] Sample applications
==========================

A sample openchangeclient application is supplied so you can test the
library and have an overview on how to use it into your
applications. Please refer to the openchangeclient man page for
further information on its command line option.

$ openchangeclient --database=/tmp/profiles.ldb --profile=testuser-2000 --fetchmail



For further examples see:

$ man openchangeclient

openchangeclient is also useful in its own right as a scriptable client.

[0x4c] Web resources
====================

For up to date material on how to use libmapi + discussions, you
are strongly encouraged to visit the OpenChange wiki:
    * http://apidocs.openchange.org
    * http://wiki.openchange.org
    * http://wiki.openchange.org/index.php/ClientSideProgramming



########################
[0x5] OPENCHANGE SERVER
########################

If you download one of the libmapi releases, please note that the
server code is not supplied. Consider using subversion to retrieve the
latest openchange revision:

svn co https://svn.openchange.org/openchange/trunk


[0x5a] Provision
================

In order to run the openchange server, you need to setup Samba4
correctly. If you have not already installed Samba4, please refer to
section 2 for further information.

Under your root account, provision the server. Starting from the openchange source
directory, do the following steps (replacing the domain, realm and adminpass
arguments with appropriate entries):

# samba4/source4/setup/provision --domain=OPENCHANGE --realm=OPENCHANGE.LOCAL \
		    --adminpass=0Chas7secret --server-role='domain controller'

If you need to add a user, run the following command (replacing <username> and
<password> with appropriate entries):

# samba4/bin/samba-tool user add <username> <password>

[0x5b] Extending Samba AD schema
================================

In the OpenChange source directory, run the following command to extend
Samba4 AD. This script will add necessary schema and attributes to run
OpenChange Server

# ./setup/openchange_provision

[0x5c] Extending Samba AD users
===============================

Finally running OpenChange server for a given user implies it belongs
to the "Exchange Organization". The openchange_newuser script will
extend existing user records and add attributes needed by OpenChange

# ./setup/openchange_newuser --create <username>

Users created with this script are enabled by default. You can
enable/disable these users at any time by running:

# ./setup/openchange_newuser --enable <username>
# ./setup/openchange_newuser --disable <username>


You now need to add the dispatcher database for user mailboxes.

# ./setup/openchange_provision --openchangedb

Mailbox will automatically be provisioned by backends when user first logs in.

[0x5c] Setting smb.conf
=======================

In order to run OpenChange server, you need to set up additional
parameters in the [global] section of smb.conf. OpenChange server
being part of mapiproxy, detailed and up to date information can be
found at the following address:

http://mapiproxy.openchange.org

Roughly, you need to add the following entries to the [globals] section:

### 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 ###


[0x5d] Running the Server (EMSABP / EMSMDB / RFR)
=================================================

The simplest is to just run "samba", but as a developer you may find
the following more useful:

   # samba -d3 -i -M single

that means "start samba server without messages in stdout, and running a
single process". That mode of operation makes debugging samba with gdb
particularly easy.


[0x5e] Solving problems
=================================================

The most common problem is not having sufficient rights - make sure
you are doing the configuration and process startup as root.

Also, make sure that you don't have any older versions (e.g. partial or
full provisioning). As a last resort, considering deleting the whole
samba installation directory and reinstalling both samba4 and 
OpenChange.

If you still have problems, please post a detailed message to the
development mailing list (devel@lists.openchange.org) showing what
commands you followed and what the results of each command were.

