ModCBroker: Administration Guide
DocumentId:GradSoft-CBroker-e-AG503-79-10.05.2000-3.3.0

Ruslan Shevchenko, Alexandr Yanovec, Julia Prokopenko

October 15, 2008

Contents

1 Introduction
2 Installation and Compilation
 2.1 For UNIX
  2.1.1 Installation of ModCbroker as DSO module
  2.1.2 configure options
 2.2 For Windows NT/XP
  2.2.1 Installation process:
 2.3 Compiling of client library clcbroker
  2.3.1 For Unix
  2.3.2 For NT/XP
3 Testing
4 Using
5 Tuning
 5.1 httpd.conf directives:
 5.2 Typical examples
  5.2.1 Call of servlet for content output
  5.2.2 Note about ORB threading model
  5.2.3 Servlet usage for authorization
  5.2.4 Using of filters
6 Integration with tcl [2] [1]
7 Integration with mod_ssl
8 Platforms matrix
9 Changes

1 Introduction

ModCBroker – Apache module, for translation of HTTP requests to CORBA requests Cbroker is developed and supported by GradSoft company, source distribution ModCBroker is available on the web site http://www.gradsoft.kiev.ua. This manual is written for version 3.1.1 of software.

2 Installation and Compilation

2.1 For UNIX

Necessary software packages:

  1. Operation System: Sun Solaris 2.8 or higher, Linux with kernel 2.4.0 or higher, FreeBSD 4.7 or higher. Porting to any posix-compatible platform is possible.
  2. installed ORB - whether ORBacus 3.x/4.x or TAO or omniORB or Visibroker-4.5 or Orbix/E 2.0 or MICO
  3. C++ compiler, compatible with ORB
  4. installed Apache distribution with headers, version 2.0.44 or higher.
  5. Gnu make 3.76 or higher

2.1.1 Installation of ModCbroker as DSO module

Preconditions:

From now cbroker module is loaded at the web server startup, so you can begin testing procedures.

2.1.2 configure options

You can view the list of all options of configure by typing

./configure --help

For details of ORB configuration procedure, please, read corbaconf [3]. Write us, is you’ve encountered any problems.

2.2 For Windows NT/XP

Necessary software packages:

  1. ORB - ORBacus-4.0.x or 4.1.0
  2. Installed Apache, ver. 2.0.44 or higher.
  3. C++ compiler Microsoft Visual C++, ver. 6.0 or higher.

2.2.1 Installation process:

  1. unzip archive ModCBroker.zip.
  2. cd to the inside directory ModCBroker/msvc.gen
  3. In env_inc.mak set values for the following variables:
  4. cd to the ModCBroker/msvc.gen
  5. Start compilation, by running make.bat or typing make
  6. Start installation, by typing make install
  7. (Install library) by typing make install-dll
  8. Add to the Apache configuration file (httpd.conf) string
    LoadModule cbroker_module modules/mod_cbroker.so

    This directive must be declared after all other LoadModule directives.

2.3 Compiling of client library clcbroker

Client library is just a set of generated CORBA stub files, so you can create it on any computer and for any language by translating idl/HTTP.idl using your idl compiler. Then you can add generated files to you project, or assemble ones into library.

Client library for C++ is automatically generated during ModCBroker build process, so if client and server are situated on the same machine, you already have clcbroker.a (or .sp) .

Also, you can automatically create client library for C++, using source distribution of ModCBroker via next procedures.

2.3.1 For Unix

  1. Unzip and untar source distribution of ModCBroker
  2. Configure, by typing ./configure --without-apache
  3. Compile, by typing make client
  4. Install, by typing make install-client

2.3.2 For NT/XP

  1. Unzip distribution of ModCBroker
  2. Compile, by typing nmake -f Makefile.nt client
  3. Install, by typing nmake -f Makefile.nt install-client

3 Testing

  1. After ModCBroker installation, assure: that Apache is working, and add to httpd.conf the next block:
    CbrokerLocation /cbroker  
    CbrokerORBArgs -ORBInitRef NameService=corbaloc::your-host-name:10000/NameService

  2. Restart httpd
  3. Start CORBA NameService on port 10000. (for ORBACUS command is: nameserv -OAport 10000)
  4. Cd to directory mod-cbroker-dir/demo/HelloWorld
  5. Start HelloWorldServlet with set NameService by command:
    ./HelloWorldServlet -ORBInitRef \  
              NameService=corbaloc::your-host-name:10000/NameService  
    For TAO 1.1  
    ./HelloWorldServlet -ORBInitRef \  
              NameService=iioploc://your-host-name:10000/NameService

  6. Type in Web browser the next URL: http://your.host.name/cbroker/Hello/Hello

4 Using

  1. Set in httpd cbroker config arguments of ORB, which correspond with location of your NameService.
  2. Users programs, which work with ModCBroker must be linked with libclcbroker.so

5 Tuning

Tuning of ModCBroker consist in setting handler (by directory, host or file extension) and adjust of authorization, in addition you can set filters and scripting interfaces.

5.1 httpd.conf directives:

  1. CbrokerORBArgs <arguments for ORB>
  2. CbrokerLocation
  3. CbrokerDefaultServlet
  4. CbrokerDefaultHandler
  5. CbrokerAddAuthByLocation location servletName handlerName
  6. CbrokerPrefix
  7. CbrokerSuffix
  8. CbrokerPrefix0
  9. CbrokerSuffix0
  10. CbrokerFormAuth on—off
  11. CbrokerFormAuthCookieName
  12. CbrokerFormAuthKey
  13. CbrokerFormAuthLoginUrl
  14. CbrokerFormAuthLogoutUrl
  15. CbrokerFormAuthAfterLogoutUrl
  16. CbrokerFormAuthLoginFormTemplate

5.2 Typical examples

5.2.1 Call of servlet for content output
CbrokerORBArgs -ORBInitRef NameService=corbaloc::www.name.com:10000/NameService  
CbrokerLocation /cbroker  
<Location /cbroker>  
AuthType Basic  
AuthName authorization  
require  valid-user  
</Location>

This example shows that:

  1. apache call ModCBroker, in virtual directory cbroker (i. e. when request URL starts with /cbroker )
  2. ORB is initialized by initialization string:
       -ORBInitRef NameService=corbaloc::www.name.com:10000/NameService

  3. Servlets must be authorized. Note, that actually authorization is processed by users-s selvlet. Though it isn’t mentioned in the configuration.

5.2.2 Note about ORB threading model

Before running mod_cbroker you must set threading model for ORB, which support callbacks. In some ORB (such as ORBacus) the default threading model does not support callbacks and your client will be hanged up at the first call of HTTPStream method.

So, for ORBacus, CbrokerORBArgs directive in our example of httpd.conf config must look as follows:

CbrokerORBArgs -ORBInitRef NameService=corbaloc::www.name.com:10000/NameService \  
         -ORBreactive -OAreactive

For other ORB-s, where default threading model is not blocked:

CbrokerORBArgs -ORBInitRef NameService=corbaloc::www.name.com:10000/NameService \

5.2.3 Servlet usage for authorization

Let’s suppose you need to define access to some resource (web application or just set of html pages) with help of ModCbroker. In this case you can use directive CbrokerAddAuthByLocation. Don’t forget to make Apache calling authorization routines.

CbrokerAuthLocation  MyProtectedArea AuthServlet AuthHandler  
<Location MyProtectedArea>  
AuthType Basic  
AuthName MyResources  
require  valid-user  
</Location>

Without AuthType setting Apache will generate internal error while access of MyProtectedArea.

5.2.4 Using of filters

ModCbroker also defines two filters: CBROKER and CBROKER0. You can set this filters to process content of some type with the command AddOutputFilterByType. For example:

AddOutputFilterByType  CBROKER  cbhtml

6 Integration with tcl [2] [1]

Also you can use cbroker with script language. In subdirectory add_on/tcl of distributive you can find tcl extension, which can be loaded from websh.

It must be compiled as Tcl extension in TEA standard and result library (libwebshcbroker.so for UNIX, libwebshcbroker.dll for Windows) should be loaded in section of interpreter initialization. After this it will be possible to call cbroker from websh.

7 Integration with mod_ssl

Since in Apache2 mod-ssl is already integrated as usual module, then you don’t need any special settings.

8 Platforms matrix

                   |                |       |        |
-OS----------------|ORB-------------|P-orted-|Checked-|F-ormalSupport--
-FreeBSD----4.x-----|TAO---1.3-------|Y-es---|Y-es-----|Y-es-----------
-FreeBSD----4.x-----|OmniORB---- 3.0.4|Y-es---|Y-es-----|Y-es-----------
-FreeBSD----4.x-----|OmniORB---- 4.0.0|Y-es---|Y-es-----|Y-es-----------
-FreeBSD----4.x-----|ORBacus---4.1.0--|Y-es---|Y-es-----|Y-es-----------
-Linux-------------|OmniORB---- 3.0.4|Y-es---|Y-es-----|Y-es-----------
-Linux-------------|M-ICO---2.3.9----|Y-es---|Y-es-----|Y-es-----------
-Linux-------------|TAO---1.2-------|Y-es---|N-o-----|Y-es-----------
-Linux-------------|Orbix-∕E --2.0---|Y-es---|Y-es-----|N-o------------
-Linux-------------|Orbacus--4.1.0---|Y-es---|Y-es-----|N-o------------
-Linux--------------Visibroker--4.5---Y-es----N-o------N-o------------
 Solaris- 2.8∕Sparc |OmniORB   - 3.0.4|Y es   |N o     |Y es
---------------------------------------------------------------------

Meaning of columns:

9 Changes

References

[1]   Apache Software Foundation NetCetera AG. websh home page, 2000-2002. http://tcl.apache.org/websh.

[2]   J. K. Osterhout. Tcl: An embeddable command language. pages 133–146, 1990.

[3]   Ruslan Shevchenko. corbaconf: autoconf-based package for CORBA based applications, 2000. http://corbaconf.kiev.ua.