trusty (3) mapiproxy-documentation.3.gz
NAME
mapiproxy-documentation - .PP
Contents
• Revision History
• 1. Introduction
• 1.1. Purpose and Scope
• 1.2. General Overview
• 1.3. Bugs and Limitations
• 2. Installation
• 2.1. Download MAPIProxy
• 2.2. Samba4 installation
• 2.3. MAPIProxy installation
• 3. Configuration
• 3.1. 5-Minute Configuration
• 4. Technical Concepts
• 4.1. NSPI Bindings Replacement
• 4.2. NSPI Referral FQDN Replacement
• 4.3. Force EMSMDB Protocol Version
• 4.4. OpenChange IDL file
• 5. Stackable Modules
• 5.1. General Overview
• 5.2. Module entry point
• 5.3. Module Hooks
• 5.4. mapiproxy structure
• 6. Available Modules
• 6.1. Downgrade Module
• 6.2. Pack Module
• 6.3. Cache Module
• 7. Server Mode
• 7.1. 5-Minute Configuration
• 7.2. General Overview
• 8. Frequently Asked Questions
• 8.1. The action could not be completed
• 8.2. Profile creation goes fine, but Outlook can't open your default e-mail folders
• 8.3. Does MAPIProxy need to be domain controller?
• 8.4. Generating Samba's private keys takes infinite time
• 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:
• [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.
• [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.
• [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:
• [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.
• [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
• [3] Configure MAPIProxy options:
In this final step, we only need to customize a small set of parameters:
• dcerpc endpoint servers:
MUST include epmapper and mapiproxy separated with comma.
• 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).
• dcerpc_mapiproxy:username and dcerpc_mapiproxy:password:
The specified credentials we will be using to connect to the remote Exchange server.
• dcerpc_mapiproxy:domain:
The Windows domain the remote Exchange server belongs to.
• 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.
• 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:[ipe\pmapper]'
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:
• EcDoConnectEx (0xa) call
• On success, Outlook will use EcDoRpcExt2 (0xb) to handle MAPI traffic
• 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:
• Earlier Outlook clients cant connect to Exchange 2007 Server
• 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;
}
• module.name:
This is the module name. This name will be used by dcerpc_mapiproxy:modules in smb.conf to load the
module
• module.description:
This field lets developers specify a brief module description for information purpose only.
• 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
• 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
• 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
• 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
• 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.
• ndr_pull: This is the function called before data from a request is extracted from the NDR blob.
• ndr_push: This is the function called before data from a response is extracted from the NDR blob.
• 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
• 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.
• 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.
• 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
• 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:
• 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.
• 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
• 1. Outlook reads a stream for the first time:
MAPIProxy monitors the Outlook-Exchange traffic and store the attachment on the local filesystem.
• 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:
• 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__
• 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
• 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.
• 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.
• 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.
• 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:
• 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
• 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
• 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
• 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
• 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.
• 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.
• [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.
• [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
• [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
• [4] Create a mailbox for the user in the OpenChange Dispatcher database:
Run under the root account:
# ./setup/openchange_newuser --mailbox <username>
• [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
• 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.
• 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:
• 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
• 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:
• 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
• 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:
• Click on More Settings
• Open the security Tab
• 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:
• 1. Make your Windows workstation points to a domain name server able to resolve MAPIProxy fully
qualified name.
• 2. Open
C:WINDOWStem32\tcriversts
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