next_inactive up previous


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

Ruslan Shevchenko, Alexandr Yanovec, Julia Prokopenko


Contents

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.

Installation and Compilation

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

Installation of ModCbroker as DSO module

Preconditions:

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


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.

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.

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.

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.

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

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

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

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

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.

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

Typical examples

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.

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 \

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.

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

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.

Integration with mod_ssl

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

Platforms matrix


\begin{displaymath}
\begin{array}{ l \vert l \vert l \vert l \vert l}
OS & ORB ...
...2.8/Sparc & OmniORB-3.0.4 &Yes & No & Yes \\ \hline
\end{array}\end{displaymath}

Meaning of columns:

Changes

06.02.2003
reviewed for 3.1.1 version. Deleted obsolete support information.
06.02.2003
reviewed for 3.1.0 version.
21.05.2002
reviewed for 3.0.0 version.
18.03.2002
added platform matrix and contribution of Richard Bouska
15.02.2002
added note about using TAO-1.1
16.08.2001
added note about installing Apache on FreeBSD from ports collection.
21.06.2001
Changed order of installation for Windows NT.
02.06.2001
some restructuring.
27.05.2001
DSO module installation instructions added.
09.04.2001
Added section about integration with mod_ssl.
17.03.2001
review.
04.02.2001
Added note about ORB threading models; added formal document attributes.
06.09.2000
created.

Bibliography

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, 1990.

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


next_inactive up previous
GradSoft