mapiproxy-documentation(3) MAPIProxy mapiproxy-documentation(3)
NAME
mapiproxy-documentation - .PP
Contents
o Revision History
o 1. Introduction
o 1.1. Purpose and Scope
o 1.2. General Overview
o 1.3. Bugs and Limitations
o 2. Installation
o 2.1. Download MAPIProxy
o 2.2. Samba4 installation
o 2.3. MAPIProxy installation
o 3. Configuration
o 3.1. 5-Minute Configuration
o 4. Technical Concepts
o 4.1. NSPI Bindings Replacement
o 4.2. NSPI Referral FQDN Replacement
o 4.3. Force EMSMDB Protocol Version
o 4.4. OpenChange IDL file
o 5. Stackable Modules
o 5.1. General Overview
o 5.2. Module entry point
o 5.3. Module Hooks
o 5.4. mapiproxy structure
o 6. Available Modules
o 6.1. Downgrade Module
o 6.2. Pack Module
o 6.3. Cache Module
o 7. Server Mode
o 7.1. 5-Minute Configuration
o 7.2. General Overview
o 8. Frequently Asked Questions
o 8.1. The action could not be completed
o 8.2. Profile creation goes fine, but Outlook can't open your default e-mail folders
o 8.3. Does MAPIProxy need to be domain controller?
o 8.4. Generating Samba's private keys takes infinite time
o 8.5. On Ubuntu make samba-git exits with gmake: not found
Revision History
Date Revision Number Author Revision Content 27/11/2010 0.6.3 Brad Hards Fix tracker link and a couple of typos. 03/03/09 0.6.2 Julien
Kerihuel Add configuration info for server mode. 01/02/09 0.6.1 Julien Kerihuel Add configuration info for server mode. 04/01/09 0.6
Julien Kerihuel server mode documented, update mapiproxy naming to MAPIProxy. 29/12/08 0.5.5 Julien Kerihuel Add 3 new questions to FAQ
section 09/12/08 0.5.4 Julien Kerihuel Add dcesrv:assoc group checking to smb.conf configuration requirements 10/07/08 0.5.3 Julien
Kerihuel Rename smbd process to samba session API and update documentation 08/26/08 0.5.2 Julien Kerihuel documentation update on NSPI
replacement and new FAQ question added 08/26/08 0.5.1 Julien Kerihuel documentation on NSPI referral added 08/11/08 0.5 Julien Kerihuel
unbind hook added, cache module documentation and scenario added 07/23/08 0.4 Julien Kerihuel MAPIProxy API hooks, IDL update, mapiproxy
structure description and documentation added for the cache module 06/25/08 0.3.2 Julien Kerihuel Minor installation update 06/04/08
0.3.1 Brad Hards Minor edits 05/27/08 0.3 Julien Kerihuel Available modules section added 05/24/08 0.2 Julien Kerihuel EMSMDB protocol
version subsection updated, modules system section added, 5-minute configuration updated 05/15/08 0.1 Julien Kerihuel Initial Revision
1. Introduction
1.1. Purpose and Scope
MAPIProxy is an endpoint server for Samba4 which proxies ExchangeRPC traffic from MAPI clients (Outlook, openchangeclient, etc.) to
Microsoft Exchange Server (and back). It can either act as a transparent proxy, for hacking, monitoring or debugging purposes or modify
traffic on the fly and so provide new features. It is primarily developed for - but not limited to - third-party implementors looking for a
development framework they can use for MAPI acceleration purposes.
This project is originally based on dcerpc_remote.c code from Stefan Metzemacher (Samba4 trunk) and is released under GPLv3 or later. It
creates a dynamic shared object file which is loaded into samba and uses the Samba configuration file (smb.conf) to set common options.
1.2. General overview
Figure 1. General MAPIProxy network overview
The MAPIProxy traffic can be divided into 3 different parts as described in the figure above:
o [1] clients to MAPIProxy:
The origin of a client connect does not have much importance: it can either be an incoming connection from a real MAPI client, a
connection relayed from another third-party proxy or another MAPIProxy instance. MAPIProxy runs as an endpoint server registered when
samba starts. When the Samba4 endpoint mapper receives an incoming connection asking for one of the ExchangeRPC endpoints: NSPI (Name
Service Provider Interface - Address Book) or EMSMDB (Exchange Message Store), the endpoint mapper redirects ExchangeRPC traffic to
MAPIProxy which will pull, push and dispatch MAPI operations.
o [2] MAPIProxy to MAPIProxy:
The main objective of MAPIProxy is not to directly connect to the remote message server, but rather to relay some kind of modified MAPI
traffic to the next MAPIProxy hop. This configuration can be used to add a compression layer between MAPIProxy instances, or to send
specific third-party vendor information. However, a proxied connection directly from a MAPI client to an Exchange server (i.e. client-
MAPIProxy-server is possible and such a configuration could be used for many other purposes.
o [3] MAPIProxy to server:
This last node is responsible for restoring MAPI contents and pushing it to the real Exchange server.
1.3. Bugs and Limitations
If you find bugs, limitations or have features you would like to see included in MAPIProxy, please register on the OpenChange Tracker
System and create new tickets.
2. Installation
2.1. Download MAPIProxy
MAPIProxy is only available through SVN at the moment. A tarball release will only be made when we have a stabilized API with a preliminary
set of useful features. You will need a SVN client to download openchange (including MAPIProxy).
$ svn co https://svn.openchange.org/openchange/trunk openchange
2.2. Samba4 installation
The MAPIProxy implementation requires a very recent Samba4 version in order to run properly. If Samba4 is planned to be installed from
scratch for MAPIProxy only, please use the make samba-git compilation rule provided in the build system. This command will automate most
part of the samba4 installation process. The only requirement for this step is to have an up to date GIT version installed on the system.
# make samba-git
When the installation process is finished, a running samba4 installation will be located in /usr/local/samba/. You will possibly be
required to run ldconfig before you move to next steps. Please refer to doc/howto.txt for further information on openchange compilation.
2.3. MAPIProxy installation
If you have existing OpenChange DSO in the /usr/local/samba/modules/dcerpc_server/ folder, such as dcesrv_exchange.so, please remove them
prior loading samba with MAPIProxy.
$ ./autogen.sh
$ ./configure --prefix=/usr/local/samba
$ make
# make install
# rm -rf /usr/local/samba/modules/dcerpc_server/dcesrv_exchange.so
3. Configuration
3.1. 5-Minute Configuration
This 5-Minute configuration will help you set up a minimal MAPIProxy using specified credentials and relaying traffic from Outlook clients
to a remote Exchange server. This configuration will be performed in three steps:
o [1] Provision Samba:
From samba4/source4 directory, run under the root account:
# ./setup/provision --realm=OPENCHANGE.LOCAL --domain=OPENCHANGE --adminpass=openchange --server-role='domain controller'
If you don't have DNS resolution and your realm can't be resolved, samba will be unable to authenticate the user in its user database. You
must specify a realm which MAPI clients and MAPIProxy can resolve.
If everything works fine, the provisioning script will have created all the databases, populated the AD (Active Directory) and generated a
valid smb.conf file.
o [2] Add a user account:
In this configuration, we'll set the same credentials both for the user in the windows domain and on the Samba4 server. Let say there is
already a user named testuser with its password set to openchange on the Exchange server:
# ./setup/newuser testuser
New Password: openchange
o [3] Configure MAPIProxy options:
In this final step, we only need to customize a small set of parameters:
o dcerpc endpoint servers:
MUST include epmapper and mapiproxy separated with comma.
o dcerpc_mapiproxy:binding:
This is the binding string used to connect to the remote Exchange server. The format of this string is: transport:address[flags]. In
the example below, we'll be using the TCP over IP transport, connect on 192.168.1.1 and add the print flag so MAPI packets get
dissected on samba stdout (or logfile).
o dcerpc_mapiproxy:username and dcerpc_mapiproxy:password:
The specified credentials we will be using to connect to the remote Exchange server.
o dcerpc_mapiproxy:domain:
The Windows domain the remote Exchange server belongs to.
o dcerpc_mapiproxy:interfaces:
In our case, we want to relay the whole ExchangeRPC traffic, so we need to load both the EMSMDB and NSP interface. In the meantime,
people interested in NSPI proxy only would only have to load the exchange_nsp interface.
o dcerpc_mapiproxy:modules:
MAPIProxy provides a stackable modular system which primary objective is to provide developers an API for modules development. In our
case we want to activate the downgrade module responsible for the EcDoConnect/EcDoRpc EMSMDB RPC functions negotiation.
[globals]
netbios name = MAPIPROXY
workgroup = OPENCHANGE
realm = OPENCHANGE.LOCAL
server role = domain controller
### Configuration required by mapiproxy ###
dcesrv:assoc group checking = false
dcerpc endpoint servers = epmapper, mapiproxy
dcerpc_mapiproxy:binding = ncacn_ip_tcp:192.168.1.1[print]
dcerpc_mapiproxy:username = testuser
dcerpc_mapiproxy:password = openchange
dcerpc_mapiproxy:domain = EXCHANGE
dcerpc_mapiproxy:interfaces = exchange_emsmdb, exchange_nsp, exchange_ds_rfr
dcerpc_mapiproxy:modules = downgrade
### Configuration required by mapiproxy ###
[netlogon]
path = /usr/local/samba/var/locks/sysvol/openchange.local/scripts
read only = no
[sysvol]
path = /usr/local/samba/var/locks/sysvol
read only = no
We are now ready to run samba:
# samba -d5 -i -M single
If everything works properly, the following lines should be displayed in samba output:
DCERPC endpoint server 'exchange_emsmdb' registered
DCERPC endpoint server 'exchange_nsp' registered
DCERPC endpoint server 'exchange_ds_rfr' registered
DCERPC endpoint server 'mapiproxy' registered
dcesrv_interface_register: interface 'epmapper' registered on endpoint 'ncacn_np:[ipepmapper]'
dcesrv_interface_register: interface 'epmapper' registered on endpoint 'ncacn_ip_tcp:[135]'
dcesrv_interface_register: interface 'epmapper' registered on endpoint 'ncalrpc:[EPMAPPER]'
MAPIPROXY module 'downgrade' registered
MAPIPROXY module 'downgrade' loaded
mapiproxy_module_load 'downgrade' (Downgrade EMSMDB protocol version EcDoConnect/EcDoRpc)
dcesrv_interface_register: interface 'exchange_emsmdb' registered on endpoint 'ncacn_np:[ipess]'
dcesrv_interface_register: interface 'exchange_emsmdb' registered on endpoint 'ncacn_np:[iperotected_storage]'
dcesrv_interface_register: interface 'exchange_emsmdb' registered on endpoint 'ncacn_ip_tcp:'
dcesrv_interface_register: interface 'exchange_nsp' registered on endpoint 'ncacn_np:[ipess]'
dcesrv_interface_register: interface 'exchange_nsp' registered on endpoint 'ncacn_np:[iperotected_storage]'
dcesrv_interface_register: interface 'exchange_nsp' registered on endpoint 'ncacn_ip_tcp:[]'
dcesrv_interface_register: interface 'exchange_ds_rfr' registered on endpoint 'ncacn_np:[ipess]'
dcesrv_interface_register: interface 'exchange_ds_rfr' registered on endpoint 'ncacn_np:[iperotected_storage]'
dcesrv_interface_register: interface 'exchange_ds_rfr' registered on endpoint 'ncacn_ip_tcp:[]'
You should now be able to configure Outlook to use an Exchange account with the proxy IP address and run Outlook seamlessly (both online or
cached exchange mode).
4. Technical Concepts
4.1. NSPI Bindings Replacement
When Outlook sets up an Exchange account using either the mail applet from the configuration panel or the account editor within Outlook, it
uses the NSPI protocol (Name Service Provider Interface, effectively the address book provider). In this case, NSPI is used to resolve the
Exchange username and fetch from Exchange server all information needed by Outlook to initiate direct connection to the EMSMDB pipe
(effectively the message store) the next time it connects to the server.
At some point of the profile's creation process, Outlook queries Exchange for some specific connection information using the NspiGetProps
(0x9) RPC operation . More specifically, when Outlook requests for the PR_EMS_AB_NETWORK_ADDRESS MAPI property, Exchange returns a list
binding strings. Outlook next stores these binding strings at some location - associated to the Outlook profile - in the windows registry
and uses them for future connections.
Outlook can also rely on other information returned by NSPI functions and connect to the real Exchange server rather than MAPIProxy. Such
case occurs when Outlook is able to resolve the exchange server using its hostname. This reference to the original Exchange server can be
found when Outlook requests for the PR_EMS_AB_HOME_MDB MAPI property during the NspiQueryRows (0x3) RPC operation. MAPIProxy replaces the
Exchange server name with its own netbios name and forward the reply to the client.
In the meantime, this information is next used by Outlook to query a minimal entry ID for a distinguished name using this server name.
MAPIProxy needs to substitute the server name in the inbound request string with the original exchange one.
MAPIProxy needs to avoid Outlook clients being aware of this remote server address and trying to communicate directly with the remote
server instead of using the proxy. In order to do this, MAPIProxy alters the Outlook-Exchange MAPI traffic and replaces these binding
strings with the MAPIProxy FQDN and netbios name.
4.2. NSPI Referral Replacement
The Address Book Name Service Provider Interface (NSPI) Referral Service is a service used by Outlook to retrieve the name of an NSPI
server. No NSPI connection should be initiated without first querying for the correct NSPI server. In this case, RFR returns the fully
qualified domain name of the real Exchange server and starts using it if available.
MAPIProxy needs to avoid Outlook clients being aware of this server address and trying to communicate directly with the remote server
instead of using the proxy. In order to do this, MAPIProxy alters the Outlook-Exchange MAPI traffic and replaces the server DN returned by
RfrGetNewDSA (0x0) RPC operation with the MAPIProxy realm as specified in smb.conf.
4.3. Force EMSMDB Protocol Version
When Outlook starts and presumably calls MapiLogonEx, it first opens a connection to the Exchange server on the NSPI pipe, then on the
EMSMDB pipe. Under Outlook 2003, the very first EMSMDB RPC call Outlook makes can be considered as a kind of protocol version negotiation.
Depending on which version of Outlook is used, and how the Exchange server replies to the EMSMDB connect request, Outlook will either keep
using the same pool of RPC calls or downgrade.
For example Outlook 2003 (default behavior) tests if the remote server supports the 2 new EMSMDB calls (EcDoConnectEx/EcDoRpcExt2)
introduced in Exchange 2003. If Exchange replies to the EcDoConnectEx request with a dcerpc_fault, it means the server does not support the
RPC operation, presumably has a version before 2003, and Outlook needs to downgrade its version in order to communicate with the server:
o EcDoConnectEx (0xa) call
o On success, Outlook will use EcDoRpcExt2 (0xb) to handle MAPI traffic
o On failure (dcerpc_fault: nca_op_rng_error), Outlook calls EcDoConnect (0x0) and use EcDoRpc (0x2) to handle MAPI traffic
If MAPIProxy runs in an environment with Outlook clients and Exchange servers using a version above 2003, a last step is required to
successfully use Outlook. The EcDoConnect RPC reply returns the Exchange server version (as an array of 3 short integers). When Outlook
detects this particular server version, it automatically closes the connection and keep requesting indefinitely for EcDoConnectEx. To deal
with this, MAPIProxy modifies the EcDoConnect reply sent by Exchange and replaces the server version with a one equal to that sent by
Exchange 2000.
In the meantime, if we reproduce this test with Outlook 2000 which doesn't support these 2 new RPC calls, Outlook will directly call
EcDoConnect.
The main difference between the EcDoConnectEx/EcDoRpcExt2 operations and the EcDoConnect/EcDoRpc operations is that the former use both XOR
0xA5 obfuscation and LZ77 compression/Direct2 encoding; while the latter only use the XOR obfuscation to handle MAPI content. If MAPIProxy
wants to act as an intelligent proxy (for example, to be able to analyze MAPI content on the fly, compress MAPI data etc), receiving non
compressed MAPI traffic would probably improve the overall process.
Below is a list of Exchange/Outlook pairs and the EMSMDB connect function they will use by default: Exchange version Outlook version EMSMDB
connect function 5.5/2000 any EcDoConnect (0x0) 2003 2000 EcDoConnect (0x0) 2007 2000 EcDoConnect (0x0)
Microsoft officially says it is unsupported 2003 2003-2007 EcDoConnectEx (0xa) 2007 2003 EcDoConnectEx (0xa) 2007 2007 EcDoConnectEx
(0xa)
MAPIProxy reproduces the Exchange 2000 behavior and prevents Outlook from communicating with the Exchange server using the
EcDoConnectEx/EcDoRpcExt2 as described in Figure 2 below. When Outlook sends an EcDoConnectEx request, MAPIProxy does not relay the request
to the remote Exchange server and immediately returns a dcerpc_fault to Outlook. Outlook, assuming the server doesn't support this call
uses EcDoConnect instead. From this call, MAPIProxy relay the information to Exchange.
Figure 2. MAPIProxy behavior on Outlook EMSMDB connection
From the Exchange side, the server will analyze this EcDoConnect request as a call sent by Outlook 2000 or below version. Exchange works
fine using this protocol version unless Exchange 2007 SP1 which appears to introduce client version restrictions by default. In the
meantime, existing tests demonstrate similar restrictions would apply to Outlook 2003 connection (without MAPIProxy) and prevent Outlook
version before 2007 connecting to Exchange 2007. Further information and solution is available at the following addresses:
o Earlier Outlook clients cant connect to Exchange 2007 Server
o Exchange 12 and Public Folders
4.4. OpenChange IDL File
IDL stands for Interface Definition Language and OpenChange uses this format to describe ExchangeRPC communications. This file is processed
by pidl (Perl IDL compiler provided by Samba4) which turns this protocol description into C-code dealing with the push, pull and print
operations.
OpenChange development policy in trunk used to push a new MAPI call in the IDL only when the associated libmapi implementation and mapitest
unit is developed, but this was preventing from distributing MAPIProxy with further openchange releases. Furthermore, the OpenChange IDL is
now almost complete and merging back to the trunk helps improving libmapi reliability.
5. Stackable Modules
5.1. General Overview
The MAPIProxy stackable modules system provides implementers a development framework to add new features. This stackable mechanism allows
developers to write modules with a very specific scope of which modifications will transparently be relayed to the next module until it is
finally pushed by MAPIProxy to the next hop (Figure 3.).
Figure 3. MAPIProxy module stack and EcDoRpc interaction
With this system, developers can focus their effort on ExchangeRPC traffic - or any other protocol samba supports - interception,
modification, analysis and avoid spending time on implementing a new endpoint server. Furthermore it provides an easier way for
implementers to divide the work in smaller units and develop each of them in a separated module.
MAPIProxy modules are dynamic shared objects with an entry point and a limited set of hooks. These modules have to be installed in the
dcerpc_mapiproxy folder within the samba4 modules directory (e.g. /usr/local/samba/modules). MAPIProxy modules specified in the Samba
configuration file (smb.conf) will be loaded into MAPIProxy at runtime and interact with each other in the same order they were defined:
dcerpc_mapiproxy:modules = downgrade,dummy
All MAPIProxy modules will be registered but only those specified on the dcerpc_mapiproxy:modules parametric option line will be added to
the chained list of effective modules.
5.2. Module entry point
MAPIProxy modules must have an entry point function named samba_init_module. This function needs to set general information about the
module, specify the module's hooks and finally call the mapiproxy_module_register function to register itself in the MAPIProxy module
subsystem.
NTSTATUS samba_init_module(void)
{
struct mapiproxy_module module;
NTSTATUS ret;
/* Fill in our name */
module.name = 'sample';
module.description = 'A sample module';
module.endpoint = 'any';
/* Fill in all the operations */
module.init = sample_init;
module.push = sample_push;
module.ndr_pull = sample_ndr_pull;
module.pull = sample_pull;
module.dispatch = NULL;
module.unbind = NULL;
/* Register ourselves with the MAPIPROXY subsytem */
ret = mapiproxy_module_register(&module);
if (!NT_STATUS_IS_OK(ret)) {
DEBUG(0, ('Failed to register 'sample' mapiproxy module!0));
return ret;
}
return ret;
}
o module.name:
This is the module name. This name will be used by dcerpc_mapiproxy:modules in smb.conf to load the module
o module.description:
This field lets developers specify a brief module description for information purpose only.
o module.endpoint:
This field defines the interface which this module is designed to work with. The primary objective is to avoid calling the module hooks
if the module doesn't have any impact on the requests or replies. For example, a module only interacting with the EcDoRpc function should
define exchange_emsmdb.
In the meantime, it can happen that a module requires to interact with more than a single interface. In such case, use the 'any' keyword
which will call the modules functions with any endpoints proxied by MAPIProxy.
5.3. Module Hooks
MAPIProxy offers a set of hooks which modules can implement to modify/change/alter client to server MAPI traffic. The figure below shows
how and when hooks are called during a request/response lifetime.
Figure 4. Usage of MAPIProxy Hooks during a request/response life time
o init: This is the initialization function for the module which is only called once - when the module is loaded. It is generally used to
retrieve smb.conf parametric options for the module and initialize some global structures
o pull: This is the function called when MAPIProxy receives a MAPI request. The request has already been extracted and its information
filled into MAPI structures
o push: This is the function called when MAPIProxy receive a MAPI response. The response has already been extracted and its information
filled into MAPI structures
o dispatch: Similarly to the MAPIProxy top-level dispatch function, it is used to dispatch the information. This function is called after
the pull but before the push. Moreover it is called before the request is forward to the remote endpoint.
o ndr_pull: This is the function called before data from a request is extracted from the NDR blob.
o ndr_push: This is the function called before data from a response is extracted from the NDR blob.
o unbind: This is the function called when the connection closes. It can be used to free data associated to a given session and stored
within a module global list.
Please note that the module API is still under development and is likely to change in further revisions.
5.4. mapiproxy structure
MAPIProxy uses a structure modules can modify in their dispatch routine and which impact on the general MAPIProxy behavior.
Figure 5. overview of mapiproxy structure variables scope
o norelay: This boolean variable can be used by modules to tell MAPIProxy not to relay the incoming request to the remote server through
dcerpc_ndr_request() but directly jump to the push (response) MAPIProxy code. This variable is for example in use within the cache module
when we read stream from the local filesystem and play it back to MAPI clients.
o ahead: This boolean variable can be used by modules to tell MAPIProxy not to relay the incoming response to the client through the push
and dcerpc_ndr_request routine but loop over the dispatch routine. This variable is for example in use within the cache module when we
want to read a stream ahead from Exchange server to the remote MAPIProxy instance.
6. Available Modules
6.1. Downgrade Module
The downgrade module implements the EcDoConnect/EcDoRpc negotiation as described in section 4.2. It ensures Outlook will not send
compressed information or use functions other than EcDoRpc for EMSMDB transport. In order to use the downgrade module, edit smb.conf and
add downgrade to dcerpc_mapiproxy:modules.
dcerpc_mapiproxy:modules = downgrade
6.2. Pack Module
Note that this module only works with an infrastructure using two or more instances of MAPIProxy as described in Figure 1
The pack module implements routines designed to manipulate and factorize MAPI content between different MAPIProxy instances. It also offers
a developer overview on how to manipulate mapi requests. Last but not least, it provides data which can next be used by subsequent
MAPIProxy modules for example to compress or encrypt this proxypack blob.
o First, MAPIProxy extracts and removes specific MAPI calls from the request, pack them within the proxypack MAPI call data blob, prefix
them with their real offset in the array of mapi requests and finally append this custom call at the end of the mapi requests array
(Figure 4).
Figure 6. Pack process
o Final MAPIProxy hop will seek the mapi requests array looking for the proxypack call. If found, it unpacks MAPI data and restore these
calls at their initial location within the mapi requests array (Figure 6).
Figure 7. Unpack process
This module has two configuration options:
o mpm_pack:opnums
This option takes a list of MAPI calls to pack into the proxypack data blob. It can take one or more MAPI opnums, each of them separated
with a comma.
o mpm_pack:lasthop
This options takes either true or false.the lasthop option defines whether this is a MAPIProxy directly connected to Outlook/Exchange or
yet another proxy inserted within the MAPIProxy chain of hops. If this MAPIProxy instance is not a last hop, then it will skip the
pack/unpack operations and forward the request to the next one.
mpm_pack:opnums = 0x70,0x75,0x76,0x77,0xa
mpm_pack:lasthop = true
In order to use the pack module, edit smb.conf and add pack to dcerpc_mapiproxy:modules.
dcerpc_mapiproxy:modules = downgrade,pack
6.3. Cache Module
The cache module implements a cache mechanism for streams related to messages or attachments. This module reduces communication latency
between MAPI clients (using online mode) and Exchange. When configured with online mode, MAPI clients retrieve data from Exchange each time
they access a message and don't have any offline storage mechanisms enabled - data are downloaded and stored within a temporary files
folder. This module also offers a preliminary synchronization mechanism which can be used to transfer files between different MAPIProxy
instances and use different protocols than MAPI for data transfer (such as rsync or wget).
The cache module is designed to cover different cases:
Scenario 1: Replay attachments
This scenario only requires a single MAPIProxy instance and requires a single configuration option:
mpm_cache:path = /tmp/cache
Figure 8. Replay stream scenario
o 1. Outlook reads a stream for the first time:
MAPIProxy monitors the Outlook-Exchange traffic and store the attachment on the local filesystem.
o 2. Outlook requests this stream again:
MAPIProxy looks over its cache, find the requested stream and directly communicate with Outlook without forwarding requests to the
remote server.
Scenario 2: Read stream ahead
This scenario requires two MAPIProxy instances and requires different configuration options for local and remote MAPIProxy:
o local MAPIProxy smb.conf sample:
mpm_cache:path = /tmp/cache
mpm_cache:ahead = false
mpm_cache:sync = true
mpm_cache:sync_cmd = /usr/bin/rsync -z mapiproxy@192.168.102.2:__FILE__ __FILE__
o remote MAPIProxy smb.conf sample:
mpm_cache:path = /tmp/cache
mpm_cache:ahead = true
mpm_cache:sync = false
Figure 9. Read ahead scenario with synchronization mechanism
o This scenario uses 2 MAPIProxy instances. We call remote MAPIProxy, the MAPIProxy instance connected to the Exchange server network and
local MAPIProxy the instance connected to the MAPI clients network.
o 1. Outlook wants to read an attachment for the first time:
The remote MAPIProxy monitors the first ReadStream request and read the full stream ahead on its own and stores it on its local
filesystem.
o 2. remote MAPIProxy replies to local MAPIProxy and local MAPIProxy runs the synchronization mechanism. The current implementation
provides a fork/execve/waitpid process which allows to run any command with parameters. When local MAPIProxy finishes to store the file
locally through the synchronization mechanism, it marks the stream as being cached.
o 3. local MAPIProxy plays the attachment back to the client from cache.
The module monitors OpenMessage, OpenAttach, OpenStream, ReadStream and Release MAPI calls and stores streams on the local filesystem with
indexation in a TDB database. Note that the module doesn't yet provide semantics needed to remove entries from the TDB database.
This module has different configuration options and modes:
o mpm_cache:path
This option takes the full path to an existing folder on the filesystem. This folder will be the storage root path for the cache module
and will hold the TDB store, a folder hierarchy and stream files.
mpm_cache:path = /tmp/cache
o mpm_cache:ahead
This option takes a boolean value (true or false) and defines whether the ahead mechanism should be enabled or not. This mode should
only be enabled on the remote MAPIProxy instance. It can be enabled on local MAPIProxy instance, however there won't be any benefit but
Outlook unexpectedly falling in some time out mode and close the connection.
mpm_cache:ahead = true
o mpm_cache:sync
This option takes a boolean value (true or false) and defines whether the synchronization mechanism should be enabled or not. This mode
only makes sense on the local MAPIProxy instance and mpm_cache:sync_cmd must also be configured.
mpm_cache:sync = true
o mpm_cache:sync_cmd
This option takes the command line to execute for the synchronization process. A preliminary substitution variable mechanism is
available but should be improved over time. For the moment, the cache module only provides __FILE__ which will be substituted by the full
path to the cached file. The synchronization process currently assumes local and remote MAPIProxy instances have the same storage path
(mpm_cache:path).
mpm_cache:sync_cmd = /usr/bin/rsync -z mapiproxy@192.168.102.2:__FILE__ __FILE__
In order to use the cache module, edit smb.conf and add cache to dcerpc_mapiproxy:modules.
dcerpc_mapiproxy:modules = downgrade,cache
Notes
o While the cache module implements a preliminary session mechanism (multiple clients support), this mode is currently only implemented up
to 50%. Multiple clients will work for files already cached, but will cause unexpected behaviors while synchronizing a remote file at the
same moment from different session. This bug should be fixed when the streaming and lock mechanism will be implemented.
o The synchronization mechanism is yet experimental and we have deliberately changed the storage path permissions from 0700 to 0777 for
trivial setup. File permissions will become parametric smb.conf options in the future.
7. Server Mode
7.1. 5-Minute Configuration
This 5-Minute configuration will help you set up a preliminary OpenChange server. This configuration will be performed in three steps.
Before running these commands, make sure you have followed step 1 (Provision Samba) and step 2 (Add a user account) in MAPIProxy 5-Minute
configuration section.
o [1] Provision OpenChange:
From openchange root directory, run under the root account:
# ./setup/openchange_provision
This script will extends Samba4 Active Directory with Exchange classes and attributes needed to run OpenChange server. Note that this
operation may require several minutes to complete.
o [2] Create the Exchange user account:
OpenChange does not create the user account the way Samba does. It only extends existing users from the SAM database and add attributes
required to access OpenChange server. The underlying concept is that system administrators may want to give access to Samba shares to a
specific user but do not want him to access OpenChange server.The user must have been created using the Samba4 samba-tool newuser script
before you run this command. Run under the root account:
# ./setup/openchange_newuser --create <username>
where username is the user account you want to give access to OpenChange server
o [3] Create the OpenChange Dispatcher database:
OpenChange uses a dispatcher database designed to store generic and top-level information about user mailbox. The following command will
create a blank openchangedb ldb database:
# ./setup/openchange_provision --openchangedb
o [4] Create a mailbox for the user in the OpenChange Dispatcher database:
Run under the root account:
# ./setup/openchange_newuser --mailbox <username>
o [5] Configure OpenChange server options:
OpenChange server only requires a very limited set of options to be added to smb.conf in order to run. Note that the following
configuration also works with existing MAPIProxy configuration. This configuration will turn MAPIProxy into OpenChange server only and no
remote connection to Exchange server will be made:
[globals]
netbios name = MAPIPROXY
workgroup = OPENCHANGE
realm = OPENCHANGE.LOCAL
server role = domain controller
### 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 = /usr/local/samba/var/locks/sysvol/openchange.local/scripts
read only = no
[sysvol]
path = /usr/local/samba/var/locks/sysvol
read only = no
7.2. General Overview
Although section 1.1 only describes MAPIProxy as a proxy, recent work makes it possible to turn MAPIProxy either into a complete and real
stand-alone server or server/proxy hybrid.
MAPIProxy behaviour is controlled through the dcerpc_mapiproxy:server parametric option. To use MAPIProxy as an independent server, set
dcerpc_mapiproxy:server = true
o dcerpc_mapiproxy:server = true
When this parametric option is set to true, MAPIProxy will not initiate connections to a remote server, but instead will direct client
connections to its own default NSPI, RFR and EMSMDB servers and work as a stand-alone server.
o dcerpc_mapiproxy:server = false
If this option is unset or set to false (default behavior), MAPIProxy will work in proxy mode only and initiates a connection to a
remote server using the binding/credentials configuration as specified in section 3.1 (5-Minute Configuration).
In addition to the server mode described above, MAPIProxy provides an additional set of configuration options which makes possible to
override and customize MAPIProxy behavior. The server mode has been designed to supply a modular mechanism somewhat similar to the modules
one described in section 5. While MAPIProxy modules are stackable and can be chained, server modules only support a single module for a
given endpoint:
o When dcerpc_mapiproxy:server is set to true, MAPIProxy registers dynamic shared object stored at a specific location
(modules/dcerpc_mapiproxy_servers) and load server modules tagged with the MAPIPROXY_DEFAULT status. For each of the endpoints MAPIProxy
can handle (exchange_nsp, exchange_emsmdb, exchange_ds_rfr), the associated default server will be loaded. These default servers are
located within mapiproxy/servers/modules. (Figure 10.)
Figure 10. Server mode enabled
o When dcerpc_mapiproxy:server is set to false, MAPIProxy still registers server dynamic shared objects but does not load any of them,
which means that ExchangeRPC traffic will be relayed to remote server.
However there may be some cases where developers would like to run a custom server they have developed, or handle a limited set of
ExchangeRPC traffic on their own for a given endpoint. This configuration is made possible through 3 parametric options:
dcerpc_mapiproxy:nspi_server = nspi_server
dcerpc_mapiproxy:emsmdb_server = emsmdb_server
dcerpc_mapiproxy:rfr_server = exchange_ds_rfr
Each of these options specifies the server module name to be loaded for a given endpoint. Note that these options override the
dcerpc_mapiproxy:server state:
o If dcerpc_mapiproxy:server is set to true, specifying one or all of these options will override default servers with your own custom
servers. For example Figure 11 shows a mapiproxy configuration where server mode is enabled but where the NSPI server has been replaced
with a custom one.
Figure 11. Server mode enabled but custom NSPI server loaded
o If dcerpc_mapiproxy:server is set to false, specifying one or all of these options will force MAPIProxy to relay the associated traffic
to default or custom server. For example, Figure 12 shows a mapiproxy configuration where NSPI traffic is handled by OpenChange NSPI
server while EMSMDB and RFR traffic is relayed to the remote server.
Figure 12. Server mode disabled but NSPI server loaded
8. Frequently Asked Questions
8.1. The action could not be completed
Figure 13. Outlook error: The action could not be completed
If you have followed the 5-Minute Configuration instructions and the above error message box (Figure 13) is displayed each time you click
the Check Name button, then you need to:
o Click on More Settings
o Open the security Tab
o Tick the Always prompt for username and password checkbox in the User Configuration section (Figure 14)
Figure 14. Resolution: Always prompt for username and password
Next time you click on Check Name, Outlook will prompt for username and password. A similar credentials dialog will be displayed each time
Outlook is launched.
8.2. Profile creation goes fine, but Outlook can't open your default e-mail folders
The profile was properly created using the mail applet from the configuration panel (or using Outlook wizard). However when I launch
Outlook, I keep having the following error message:
Figure 15. Outlook error: Unable to Open your default e-mail folders
This probably means Outlook is unable to lookup the resolved name of your MAPIProxy/samba4 server. You can either:
o 1. Make your Windows workstation points to a domain name server able to resolve MAPIProxy fully qualified name.
o 2. Open
C:WINDOWStem32 criversts
file and add an entry for mapiproxy. For example if I have mapiproxy.openchange.local pointing at 192.168.102.2, then hosts file should
hold the following line:
192.168.102.2 mapiproxy.openchange.local mapiproxy
8.3. Does MAPIProxy need to be domain controller?
No it doesn't. MAPIProxy works fine as a member server of a Windows domain. However, since delegated credentials and forwarded kerberos
credentials don't yet work, you'll need to force samba to rely on the local SAM database. To force this behavior, add to smb.conf within
the global section:
server role = member server
aux_methods:member server = sam
8.4. Generating Samba's private keys takes infinite time
For some configuration, the private keys generation process at Samba startup can be very long. In case private keys are not generated
within a couple of minutes, it is suggested to recompile Samba with gnutls disabled as in the example below:
$ ./configure.developer --enable-debug --disable-gnutls
$ gmake idl_full
$ gmake
$ sudo gmake install
8.5. On Ubuntu make samba-git exits with gmake: not found
On Ubuntu, I have the following output while trying to install samba4 from OpenChange sources:
To build Samba, run /usr/bin/make
Step2: Compile Samba4 (IDL)
./script/installsamba4.sh: 332: gmake: not found
Step3: Compile Samba4 (Source)
./script/installsamba4.sh: 332: gmake: not found
Error in Step3 (error code 127)
gmake is make on Ubuntu. Creating the following symbolic link will fix the issue:
$ sudo ln -s /usr/bin/make /usr/bin/gmake
Version 1.0 Sat Jun 14 2014 mapiproxy-documentation(3)