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
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
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.
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.
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.
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
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.
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
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:[\pipe\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:[\pipe\lsass]' dcesrv_interface_register: interface 'exchange_emsmdb' registered on endpoint 'ncacn_np:[\pipe\protected_storage]' dcesrv_interface_register: interface 'exchange_emsmdb' registered on endpoint 'ncacn_ip_tcp:' dcesrv_interface_register: interface 'exchange_nsp' registered on endpoint 'ncacn_np:[\pipe\lsass]' dcesrv_interface_register: interface 'exchange_nsp' registered on endpoint 'ncacn_np:[\pipe\protected_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:[\pipe\lsass]' dcesrv_interface_register: interface 'exchange_ds_rfr' registered on endpoint 'ncacn_np:[\pipe\protected_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).
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.
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.
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
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.
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.
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!\n"));
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.
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.
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.
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
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
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:
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.
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 [email protected]:__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 [email protected]:__FILE__ __FILE__
In order to use the cache module, edit smb.conf and add cache to dcerpc_mapiproxy:modules.
dcerpc_mapiproxy:modules = downgrade,cache
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.
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
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
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.
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:\WINDOWS\system32\tc\drivers\hosts
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
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
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
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