
                         BRUTUS SERVER README

                  Installing or Building Brutus Server
 
          ======================= * ============================

Author:
	Jules Colding <colding@42tools.com>
	Copyright (C) 2004-2009 42tools ApS

License:
        Copying and distribution of this file, with or without modification,
        are permitted in any medium without royalty provided the copyright
        notice and this notice are preserved.


0. Contents
===========

   1. Overview

   2. Using the Easy Installer

   3. External Build Dependencies
      3.1 Microsoft Platform SDK
      3.2 Installing Perl
      3.3 Getting NASM
      3.4 Building OpenSSL
      3.5 Building ACE and TAO

   4. The Brutus Visual C++ Workspace
      4.1 Getting the files
      4.2 Creating the Visual C++ 2008 Solution file
      4.3 Visual C++ options settings
      4.4 Building Brutus
      4.5 Running Brutus

   5. Tips and troubleshooting


1. Overview
===========

   Brutus is a project whose aim it is to provide application developers
access to a Microsoft Exchange server on equal footing with Microsoft Outlook.

Brutus will enable any application to access any Exchange server, from version 
5.5 onwards, from any operating system platform, on an equal footing with MAPI 
based native Windows applications, such as Outlook. 

Brutus is based upon CORBA technology and is implemented as a set of wrapper 
interfaces that provides the application developer with access to the 
underlying MAPI subsystem.

Small variations of the settings below must be expected, depending on your 
exact environment and the actual installed versions of TAO and OpenSSL.

Please report all problems or errors to <bugs@42tools.com>. Thanks!


2. Using the Easy Installer
===========================

   By far the easiest way to get up and running with Brutus Server is to use
the binary installer which we provide as a convenient download here:

   http://www.42tools.com/sites/default/files/downloads/brutus-install-agplv3.exe

Just execute this installer on any Windows domain member machine and follow
the instructions. 

IMPORTANT: YOU MUST HAVE THE CORRECT VERSION OF MAPI INSTALLED ON YOUR BRUTUS
SERVER HOST. If Outlook is present on the host than you MUST:

  a) Remove Outlook (and MS Office if that is on the host machine too)
  b) Install the correct MAPI version 

Brutus Server is using another verison of MAPI than MS Outlook. You can get
the correct version of MAPI here:

  http://www.microsoft.com/downloads/details.aspx?familyid=94274318-27C4-4D8D-9BC5-3E6484286B1F&displaylang=en

The one thing you still need to do before starting Brutus Server, is to edit
the Lorica configuration file "lorica.conf", which you can find in the Brutus
Server installation directory.

You will find this line in the Lorica configuration file:

   External_Address <ADDRESS>:4082

You MUST replace "<ADDRESS>" with the actual IP address or DNS resolvable name
of your Brutus Server host. Follow the instructions in "lorica.conf" for more
advanced configurations.

Now you can start Brutus Server. Do that by starting the "Services" application 
in "Administrative Tools". Locate the Brutus Server service in the list of 
services. Right-click upon it and press "Start". You may also choose to restart
your Brutus Server host if you want.


3. External Build dependencies
==============================

   Brutus depends explicitly on TAO. TAO is build upon ACE, the "ADAPTIVE 
Communication Environment". TAO and ACE needs Perl in order of constructing the 
MSVC build files. TAO furthermore needs OpenSSL to build the SSL dependent 
sub-projects. 

Please follow the instructions in the following sections to get up and 
running with the remaining dependencies of the Brutus build environment.

You do not need to read further if you only intents to run Brutus Server. 
Running and using Brutus Server is described above.


3.1 Microsoft Platform SDK
--------------------------

   It was necessary, with older versions of Visual Studio, to install a recent 
version of the Microsoft Platform SDK before attempting to build Brutus. The 
PSDK contains header files and libraries which was needed for Brutus to build. 

Brutus has been build with Visual Studio 2008 without the platform SDK but you
may follow this link to get it if you need it for your platform:

   http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en

Just follow the instructions on that page to install the complete platform SDK.


3.2 Installing Perl
-------------------

   You must install ActivePerl from ActiveState to generate the ACE and TAO 
workspace files as opposed to any other win32 Perl variants such as Cygwin Perl. 

I am currently using version 5.10. ActivePerl is important as Cygwin Perl has been
seen to not work as well as ActivePerl. Remember to check that your Path 
environment variable is such that the ActivePerl binary is before the Cygwin Perl 
binary if you happen to have Cygwin installed. You can get ActivePerl from:

   http://activestate.com/Products/ActivePerl/


3.3 Getting NASM
----------------

   You should get NASM before building OpenSSL. Get the zip archive, extract 
nasm.exe and put it somewhere in your PATH. Download NASM from:

   http://nasm.sourceforge.net/


3.4 Building OpenSSL
--------------------

   OpenSSL is needed by the SSL dependent sub-project of ACE and TAO. You should 
always build from source. Please get the most recent OpenSSL source from:

    http://www.openssl.org/source/

This HOWTO assumes that you have unpacked the OpenSSL tar-ball to "C:\work\src\".
You will now have a "C:\work\src\openssl-VERSION" directory. The version used at 
the time of writing is 0.9.8k. Any recent version should work, but you must adjust 
the MSVS options accordingly. Please see section 3.5 below.

Detailed build instructions are in the "INSTALL-W32.TXT" file, but I'll give you 
the necessary essentials here:

    a) Open a Visual Studio 2008 command prompt:

	       Start->All Programs->Microsoft Visual Studio 2008->Visual Studio Tools->Visual Studio 2008 Command Prompt

    b) Go to the top-level OpenSSL directory, e.g. "C:\work\src\openssl-0.9.8k" and 
       execute:

	       perl Configure VC-WIN32

    b) From the same command prompt execute:

	       ms\do_nasm

    c) Still from the same command prompt just do:

          nmake -f ms\ntdll.mak

       to build the OpenSSL libraries and executables.


3.5 Building ACE and TAO
------------------------

   You must have ACE and TAO installed and compiled on your development 
workstation. All versions later than or equal to ACE 5.6 and TAO 1.6 should work 
with minor modifications to these instructions, but your millage may vary (a lot). 

This HOWTO assumes that you are using ACE-5.6.9/TAO-1.6.9 and Visual C++ 2008 on 
a Windows Server 2008 development box.

You can obtain ACE and TAO from <http://download.dre.vanderbilt.edu/> in a 
combined zip file. You *must* get the zip file, not the tar.gz-file. Winzip was, at 
the time of writting, unable to extract the tar-ball correctly but did work fine
with the zip file. The tar-ball can be untar'ed on *nix with no problems.

This should be a permanent link to the zip file:

    http://download.dre.vanderbilt.edu/previous_versions/ACE+TAO-5.6.9.zip

This HOWTO assumes that you have unpacked ACE and TAO to "C:\". You should end
up with the standard "C:\ACE_wrappers" directory containing all of the ACE and TAO 
files.

In this HOWTO we will use MPC to generate the Visual Studio solution files. It is 
easy to do this. Just do like me:

    a) First you must add "ssl=1" to:

            "C:\ACE_wrappers\bin\MakeProjectCreator\config\default.features". 

       Create the file if it does not exist. There might be other options pre-set 
       if the file exists. You should be able to deactivate these other options 
       without any ill effects, but please think and consider the eventuel bad 
       consequenses before disabling any pre-set options.

    b) Now create the SSL_ROOT, ACE_ROOT and TAO_ROOT environment variables. If you 
       have an identical setup to the one described in this document then valid 
       values would be:

       SSL_ROOT: C:\work\src\openssl-0.9.8k
       ACE_ROOT: C:\ACE_wrappers
       TAO_ROOT: C:\ACE_wrappers\TAO


    c) Next, open a command line (the "cmd" command), go to C:\ACE_wrappers\TAO and 
       invoke the mwc.pl Perl script:

            %ACE_ROOT%\bin\mwc.pl -type vc9 TAO_ACE.mwc

       to create the TAOACE workspace. 

    d) Create "C:\ACE_wrappers\ace\config.h" with the following content:

            #ifndef _WIN32_WINNT
            #define _WIN32_WINNT (0x0500) /* Windows 2000 or later */
            #endif

	    /* These seems to be needed for Visual Studio 2008 and later */
	    #ifndef NTDDI_VERSION
	    #define NTDDI_VERSION NTDDI_WIN2K
	    #endif

            #define ACE_HAS_STANDARD_CPP_LIBRARY (1)
            #define ACE_LACKS_DEPRECATED_MACROS (1)

            /* The following option is needed if you are using the OCI version */
            //#undef ACE_LACKS_DEPRECATED_MACROS

            /* This include statement must always be present */
            #include "ace/config-win32.h"

    e) Add the following paths to the beginning of the system PATH variable (you 
       will need this for later):

            1) C:\ACE_wrappers\lib
            2) C:\work\src\openssl-0.9.8k\out32dll
            3) C:\work\src\42tools\brutus-server\ServantLib

You are now ready to build ACE and TAO. Restart Visual C++ 2008 (if it was already 
up and running) and open the TAOACE Solution file:

   C:\ACE_wrappers\TAO\TAO_ACE.sln

Now open "Tools->Options...". Go to "Projects and Solutions->VC++ Directories" 
and add the following paths:

   Executable files:
      C:\ACE_wrappers\bin

   Include files:
      C:\ACE_wrappers
      C:\ACE_wrappers\TAO
      C:\work\src\openssl-0.9.8k\inc32

   Library files:
      C:\ACE_wrappers\lib
      C:\work\src\openssl-0.9.8k\out32dll

It is assumed that you have OpenSSL 0.9.8k installed. Any recent version should 
do.

Now open "Build->Configuration Manager..." and set the "Active solution configuration"
to "Release". Press "Close" to confirm your choice.

Go to "Build->Batch Build..." and select the sub-project that you want to build. 
You should at least build non-MFC debug *and* release versions of the following 
projects, unless otherwise noted:

    ACE
    AnyTypeCode
    BiDir_GIOP       (only if you want to build Lorica too)
    catior           (debug tool - you only need the release version if you need catior at all)
    CodecFactory
    Codeset
    Compression
    CosNaming
    CosNaming_IDL
    DynamicAny       (only if you want to build Lorica too)
    DynamicInterface (only if you want to build Lorica too)
    EndPointPolicy   (only if you want to build Lorica too)
    gperf            (build tool - just build the release version)
    IFR_Service      (only if you want to build Lorica too)
    IORTable
    Messaging
    PI
    PI_Server
    PortableServer
    RTCORBA          (only needed if you are building catior and then only the release version)
    Security
    SSL
    SSLIOP
    Strategies
    TAO
    TAO_IDL_BE       (only release version)
    TAO_IDL_EXE      (only release version)
    TAO_IDL_FE       (only release version)
    TAO_IFR_BE       (only if you want to build Lorica too)
    TAO_IFR_EXE      (only if you want to build Lorica too)
    TAO_Utils        (various tools - just build the release version)
    Valuetype


These projects are what I am building. A smaller number of projects might just 
work, but I have not experimented too much with minimal build configurations. 
Now press "Rebuild" to build all chosen projects and their dependencies. This 
will take some time...

After this you might need to re-link tao_idl.exe and gperf.exe. They tend to
link against the debug libraries for some unknown reason.


4. The Brutus Server Visual C++ Solution
========================================

I am using Visual C++ 2008 so this HOWTO will document how to get up and 
running using that particular version.


4.1 Getting the files
---------------------

   You can download Brutus from <http://www.42tools.com/node/8>. Get the
brutus-server tar-ball. Please read <brutus\brutus-server\edkinc\README> before
attempting to build Brutus. Another option is to use Subversion.

Using the Brutus Server Subversion repository in read-write mode requires you 
to install OpenSSH from the Cygwin project. Please go here to download Cygwin:

   http://www.cygwin.com/

Then you must add this line to your Subversion configuration file:

   ssh = "C:/(cygwin root path)/bin/ssh.exe" -i "C:/(path to your private key)"

Your Subversion configuration file is:

   C:\Documents and Settings\%USERNAME%\Application Data\Subversion\config

Or (at least for Windows 2008):

   C:\Users\%USERNAME%\AppData\Roaming\Subversion\config

Or here if you are using Cygwin Subversion:

   %HOME%\.subversion\config


"Application Data" and "AppData" are hidden directories so you must change your
folder options to be able to see them. Alternatively, just navigte to any of 
these directories with the power fo your command prompt.

You can now checkout the necessary repositories using this command:

   svn co svn+ssh://svn@42tools.com/home/svn/brutus-server/trunk brutus-server
   svn co svn+ssh://svn@42tools.com/home/svn/lorica/trunk lorica


If you are only accessing the subversion repository in read-only mode then you
can get the files by doing this:

   svn co http://svn.42tools.net/repos/brutus-server/trunk/ brutus-server
   svn co http://svn.42tools.net/repos/lorica/trunk/ lorica


4.2 Directory layout
----------------------

There are more content in the repository than shown below, but this is the
most important.

   %BRUTUS_ROOT%/
      README     - This file
      MPC/
         config/ - MPC base files
      brutus_loader/
         client/ - C++ client to run on Mac or Linux with a GNU Makefile
         idl/    - The interfaces
         proxy/  - The spawned Windows proxy process
         server/ - The Windows server that does the spawning
         utils/  - Utility library


4.2 Creating the Visual C++ 2008 Solution file
-----------------------------------------------

Create the BRUTUS_ROOT environment variable. If you have an identical setup to
the one described in this document then it sould be:

       BRUTUS_ROOT: C:\work\src\42tools\brutus-server

Now, one thing to remember, if you are building Brutus Server under a free license
you MUST out-comment these lines in %BRUTUS_ROOT%\brutus_loader\server\server.mpc:

   macros   += BRUTUS_HAS_ESELLERATE
   lit_libs += "validateLibrary"
   specific(vc9){
	ignore_default_library_names += LIBC.LIB
	ignore_default_library_names += LIBCMT.LIB
	ignore_default_library_names += LIBCD.LIB
	ignore_default_library_names += LIBCMTD.LIB
	ignore_default_library_names += MSVCRTD.LIB
   }

Nothing will work if you don't.

Next, please open a command line (the "cmd" command), go to %BRUTUS_ROOT%\brutus_loader
and invoke the mwc.pl Perl script:

       %ACE_ROOT%\bin\mwc.pl -type vc9 BrutusServer.mwc

to create the BrutusServer solution file.


Now please open "%BRUTUS_ROOT%\brutus_loader\BrutusServer.sln" in Visual C++. It
contains seven projects:

   a) Brutus_Loader      - All of *C.[cpp,h] generated files
   b) Brutus_Loader_IDL  - Brutus IDL files
   c) Brutus_Loader_Impl - Servant implementations
   d) Brutus_Loader_Skel - All of *S.[cpp,h] generated files
   e) Brutus_Utils       - Utility library
   f) Proxy              - A proxy program for an individual MAPI session
   g) Server             - The NT Service source


4.3 Visual C++ options settings
-------------------------------

   Now open "Tools->Options...". Go to "Projects and Solutions->VC++ Directories" 
   and add the following paths:

   Include files:
      C:\work\src\42tools
      C:\work\src\42tools\lorica

4.4 Building Brutus
-------------------

Just press F7 and Brutus should be build. Please report any errors to the brutus 
mailing list, bugzilla <http://bugzilla.42tools.com> or by email to <bugs@42tools.com>.


4.5 Running Brutus
------------------

   This section will only decribe how you could run Brutus in a test 
environment. Please read the source if you want to install Brutus as an NT
service. You should get the installation binary if you are not a developer 
and just want to use Brutus in your organization. Please contact 42tools at:

    <contact@42tools.com>

for futher information for using Brutus in a production environment.

You *must* run brutus.exe with the "-d" command line option during testing. 
To ensure that you are invoking the Brutus executable correctly, please
follow these instructions:

    a) Right-click on the NT_Service project in the Solution Explorer

    b) Left-click on "Properties".

    c) For "Configuration:" choose "All Configurations"

    d) Left-click on "Debugging" in the left side configuration tree view.

    e) Set "Command Arguments" to "-d".

    f) Set "Working Directory" to "$(SolutionDir)". This is the default. The 
       correct working directory is allways where your brutus.conf file is 
       stored.

    g) Press "OK" or "Apply".


Please edit the Brutus configuration file "brutus.conf" to suit your local 
setup. It has extensive inline documentation. Don't touch anything unless you
really know what you are doing. The default configuration should "just work".

You can now run Brutus in the Visual C++ environment or at a command line.

   Visual Studio: Just press F5.

   Command line: Open a command prompt (e.g. "cmd") and go to the directory
       where the Brutus configuration file is located. In that command prompt 
       execute:

	   "<PATH TO BRUTUS EXECUTABLE>\brutus.exe -d"

       Brutus Server will now be up and running. Remember to do all of this as
       a user with Administrator rights.

Log messages will be printed to the Brutus log file "brutus.log" or the system
application log. You can view the system log be opening the "Event Viewer" and 
look in the "Application" log. Brutus Server messages will have "Brutus Server" 
as their source. 

Please append brutus.log to all bug reports. Some critical errors will happend 
before the "brutus.log" file is created or appended to. Please find these early 
log messages in the system log and append them to your bug report. Please send 
all bug reports to <bugs@42tools.com> or the brutus mailing list.

Requirements: 

   Windows 2000 or later versions. Other Windows versions may or may not work.
   Remember to use the latest service packs for all of your Microsoft operating
   systems products.


5. Tips and troubleshooting
===========================

1) You *must* run brutus.exe with the "-d" command line option during debugging.
   This means, among other things, that you must right-click on the NT_Service 
   project in Visual C++ choose "Settings" and store the working directory and
   the debug argument in the "Debug" tab. The working directory must be where 
   your brutus.conf file is located. A precompiled Brutus Server binary is 
   available in a standard "setup.exe" style installation file from our web site..

2) It took me a while to figure out, but even though that all of the TAO and
   ACE DLLs are in your path, Visual C++ might not find them when running the
   debugger. Try moving the DLL directory to the beginning of your path. That 
   should "fix" it.

3) MAPIInitialize() fails with 0x80004005 (E_FAIL) and a popup dialog saying:

   "There is no default mail client or the current mail client cannot complete 
   the messaging request. Please run Outlook and set it as the default mail client."

   Additional information: 

       http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mapi/html/_mapistub__mapi32.dll_stub_registry_settings.asp

   Cause: The correct version of the MAPI32.dll is not available.

   Fix 1: (Preferred and strongly recommended) Install the stand-alone MAPI 
   installation as distributed by Microsoft. You can download it from:

       http://www.microsoft.com/downloads/details.aspx?familyid=94274318-27C4-4D8D-9BC5-3E6484286B1F&displaylang=en

   Fix 2: Install Microsoft Exchange 5.5, 2000, 2003 or 2007 and apply all service 
   packs.
   
   Fix 3: An equivalent fix is to install only Exchange System Management (or 
   Exchange Administrator in case of Exchange 5.5) on the Brutus server. That 
   will guarantee that the correct version of MAPI is installed. You must remember 
   to install all service packs for your version of Exchange as well.

4) Brutus Server and tao_idl.exe does not work when you build Brutus Server by 
   yourselves:

   Fix: It is important to take special care if you are trying to execute a 
   homebuilt Brutus Server on a server were you have previously installed 
   Brutus Server from the binary installation file as distributed by 42tools. 

   The binary install will add the Brutus Server install path at the beginning 
   of the PATH environment variable. This will make your homebuilt Brutus Server 
   executable, as well as tao_idl.exe, load the wrong DLLs. The DLLs that are 
   present in the Brutus Server installation directory will be preferred to the DLLs 
   in the build directories due to the PATH modification. Please take this into account 
   if building and executing Brutus Server. 

   You can use Dependency Walker (http://www.dependencywalker.com/) to check for errors
   of this kind.

5) Brutus Server might fail to start with the following error:

   "No MAPI installations found"

   Fix 3: Install the stand-alone MAPI installation as distributed by Microsoft. You 
   can download it from:

       http://www.microsoft.com/downloads/details.aspx?familyid=94274318-27C4-4D8D-9BC5-3E6484286B1F&displaylang=en


   Appendix: You must ensure that the MSEMS service is registered in the "mapisvc.inf" 
   file on your system. You can use the MAPIsvc.exe application to fix this if 
   required. MAPIsvc.exe is distributed with Brutus Server and is invoked by the 
   installer if the installation detects the need to do so.


--------------
Jules Colding <colding@42tools.com>
42tool ApS
April 17, 2009
