SOAP and .net services for Apache HTTP Server

This is an open source contribution for gsoap, to enable Apache HTTP Server to run SOAP and .net services on Linux and other Unices.

Overview

To build and configure the mod_gsoap SOAP service you have to do three main parts:

1. Build mod_gsoap, which is a SOAP server independent generic module to allow gsoap shared libraries to be plugged into Apache HTTP Server. It contains the infrastructure to dynamically load the required gsoap servers at runtime, and the additional required shared libraries not statically linked into apache server. mod_gsoap passes the SOAP requests received from the clients, and calls into the SOAP server shared libraries and returns the response to the clients.

2. Build one or more gsoap shared libraries that implement the SOAP services. As a sample a simple calculator was used. Implementing other SOAP servers is straight forward. Please see gsoap for details of how to use soapcpp2 to generate the wsdl , the C++ and the other related code for your own SOAP services.

3. The configuration instructions for the apache http server in httpd.conf. This specifies which shared libraries are allowed to be loaded into the apache server process and where they reside.

The build process uses Automake . Inside that mod_gsoap.so is built in the standard Apache way using apxs. Please do not be shocked about the long description that follows. It is rather detailled, users acquainted with apache http server will skip most of it.

1. Building the Apache SOAP server

In order to reduce download times you must download and unpack the required standard packages like apache server separately from their original locations. For building I used libtool 1.4 downloaded from http://www.gnu.org/software/libtool, be sure to have it installed. Also be sure that you have apxs, which comes with the apache http server distribution, in your path.

Build instructions

• Make sure that apache http server is installed, otherwise download build and install apache_1.3.26.tar.gz or higher (not 2.0.* or higher) from http://www.apache.org/httpd
  This will also install apxs, the apache build tool that is required to compile mod_gsoap as a module. Also check the first line of apxs, so that it really points to your perl executable.

• download and install gsoap from http://www.cs.fsu.edu/~engelen/soap.html

• download the current gsoap_apache_0.0.5.tgz from http://www.webware.at/SOAP/apache_gsoap.0.0.5.tgz to /usr/local/src and unpack it with:
  tar -xzf apache_gsoap.0.0.5.tgz 

• change to the directory that has been created by the step above and run the following:
  ./configure 
  make
  
  This should build ./mod_gsoap/mod_gsoap.so and ./example/calculator/.libs/libCalculator.so (the .libs subdirectory is hidden). libCalculator.so is a shared library that contains the gsoap server generated with soapcpp2. You can use it as a template for your own servers. See later. This build step also copies mod_gsoap.so to the location of your other apache modules (e.g. /usr/local/apache/libexec).

Building a debugging version

The steps above are enough for running the release version. If you want to do debugging for mod_gsoap.c and/or your servers, you must enable debugging code. This is described in this paragraph. Skip it if you do not need debugging.

You can enable debugging for mod_gsoap.c by using --enable-debug
./configure --enable-debug

Debugging is easier when you link mod_gsoap.c statically into httpd, the Apache Server.

For that to the following:
Copy the whole mod_gsoap subdirectory to ~/apache_1.3.26/src/modules/
Next Edit the Configuration file (it is located in ~/apache/src).
Add the following lines:
# goap SOAP extension module.
AddModule modules/mod_gsoap/mod_gsoap.o

• in the same file locate in the section Makefile configuration the line containing EXTRA_LIBS and add change the lines to the following:
  EXTRA_CFLAGS=-g
  EXTRA_LDFLAGS=
  EXTRA_LIBS=-ldl -lpthread
  EXTRA_INCLUDES=-I~/apache_gsoap.0.0.5

  See the sample Configuration file that is in the downloaded sources for an example.

  There is also a config directory below mod_gsoap, which contains sample files edited in the way described here, where you can compare your changes.

• Run the src/Configure script:
  cd ~/apache-1.3.26/src
  ./Configure
  
  This will build the Makefile for the server itself.
  Note: do not run ~./apache-1.3.26/configure after it, this will overwrite the Makefiles generated above.

• Build the Apache Server, together with the mod_gsoap by running in the current ~/apache_1.3.26/src directory:
  make

• The previous step should have produced the file httpd
  Check that the mod_gsoap has really been linked correctly by running:
  ./httpd -l
  This should list as a module among others also mod_gsoap.c and mod_so.c

• In the next step we install apache to a directory of its own by running the standard apache install command from the ~/apache_1.3.26 directory. Before doing so, read the README.configure file in the apache distribution. After you know what you are doing, run the following command from ~/apache_1.3.26:
  make install
  This will generate the apache server in the directory you specified (or usually /usr/local/apache if you did not do so). This step will also generate the httpd.conf file that we need for debugging. You can of course omit this step, if was only done to easily get a working apache distribution on your machine, and a httpd.conf file that we must change in the next steps. If you already have a working installation, you can use that.

2. Implementing your own Servers

In my opinion it is not a good idea to start off with gsoap server programming by using this apache module. Before doing so (and especially before sending questions) please go to the gsoap home page and look at the very good and detailled examples and documentation there. Implement your server as a standalone server and test it. Once that works, you can easily convert it to run with mod_gsoap. How to convert your server to support mod_gsoap is described below in this chapter.

The only additional thing you must do to enable your own gsoap Server to be able to plug into Apache HTTP server is to add the lines below to your source code and build them as shared libraries. Then the required entry points will be exported.

Add the following 2 lines to your SOAP server source code:
#include "apache_gsoap.h"
IMPLEMENT_GSOAP_SERVER()

You also must change Makefile.am accordingly to add your source files and rename and run autoconf, automake, ./configure again of course. apache_gsoap.h came with the gsoap_apache_*.tgz that you downloaded above and will be in the include path of the compiler.

There is also a ConsoleServer subproject, that allows you to build and test your own gsoap server shared libraries indepent of Apache server. It is recommended to test your servers with this soaptest program before you try to use it in Apache Server. Change the search path for the library and the name of the library near the top of the file ConsoleServer.cpp for testing. Another subdirectory foo is there for testing, if you still get file not found errors in the attempt to load a shared library. foo does not depend on other libraries and will load also if your path is not correct. Of course it will not work as a soap server, it is only there to get your directory settings correct.

If you want to have a graphical development environment you can use kdevelop. See below how to use that. But also working with emacs and kdbg is fine. For implementing your own SOAP servers please download the standard gsoap package and follow the instructions there. The servers we use are separated into a shared library of its own, to allow the apache server to load them on demand.

3. Configuration of httpd.conf

Now after the binaries are built, it is necessary to tell Apache server where to find the libraries to answer the soap requests coming in. Locate the httpd.conf file that is in use on your installation (e.g. ~/apache-1.3.26/conf/httpd.conf or /usr/local/apache/conf/httpd.conf) and make your changes.

• httpd.conf file must be edited.
  This file will also be used to explicitly start debugging of the apache server process httpd and step into mod_gsoap with e.g. kdbg debugger. The same file is used when you run apache as a daemon. This procedure is identical to what is described in the example module README in the standard Apache distribution, only with different names. As a first step you must tell apache to load mod_gsoap. Add the line:
  LoadModule gsoap_module libexec/mod_gsoap.so
  below the place where the comment:
  # Dynamic Shared Object (DSO) Support
  is located (libexec/mod_gsoap.so is the place where shared modules are installed as a default, see other existing commented LoadModule instructions in your httpd.conf file as examples). gsoap_module is the module name hardcoded in mod_gsoap.c
  Next add the following lines to httpd.conf, near the other <Location> sections:
  # SOAP handler (see http://www.aberger.at/SOAP)
  <IfModule mod_gsoap.c>
  <Location /soap>
  SetHandler gsoap-handler
  SOAPLibrary /home/myusername/gsoap.0.0.5/apache/example/calculator/.libs/libCalculator.so
  </Location>
  </IfModule>
  You can paste the lines above from the sample file in config subdirectory. Of course you must change myusername to your login name, as above, so that the string /home/myusername above corresponds to your home directory. Do not use ~ for your home directory here. This will not be resolved by dlopen()!
  The isoap-handler knows 2 configuration directives:
  SOAPLibrary is the full path to the library that contains your SOAP server shared library, with the mandatory exported function as defined in the include file apache_gsoap.h. It tells the extension what shared object library to load to serve the SOAP requests for this location at runtime. You must change the path of course to the full path of your server. It is better to specifiy the full path, and not to use the LD_LIBRARY_PATH due to security reasons.
  SupportLibrary are all the libraries needed additionally by your Soap server shared library. They are dynamically loaded into the apache server process httpd when this instruction is encountered. Otherwise it would be necessary to statically link these libraries and rebuild httpd and mod_gsoap every time you change something. This was not the desired goal.

• Now test if the Apache Server itself is correctly configured, run the following from your ~/apache-1.3.26/src directory:
  ./httpd -X -f /usr/local/apache/conf/httpd.conf

• This will launch the server in console mode (does not return until you cancel it). Then open your favourite Web Browser and browse to:
  http://127.0.0.1:8080
  This should give astandard apache response, has nothing to do with your mod_gsoap yet. The port 8080 was also set in httpd.conf, if you don't get a response, check the port and see the error_log file. For the production server it maybe will be port 80, which you do not need to specify explicitly in the browser then. But for debugging I recommend to stay with port 8080, because for port 80 you would need root priviledges for debugging.
  This request should give a response from apache.

• As a next step let us test if your mod_gsoap responds. The request must contain the location you gave in the <Location> directive. Enter as address in your browser:
  http://127.0.0.1:8080/soap
  This should give a response from mod_gsoap, an error message, because your browser will propably not send the required SOAPAction header. Something is wrong if you get an url not found or a directory listing as a response. In that case check if you really added the LoadModule instruction described above properly.
  Note: the soap virtual directory was defined by yourself in the <Location> instruction above. Do not create a physical soap directory in your document root !

• Well, now it is time to check if Apache Server can answer your SOAP requests. Run the calculator client demo program. It has been built by the makefile already. Enter the following:
  cd ~/apache-gsoap/example/calculator
  ./client 1 + 2
  This should answer the SOAP requests like the gsoap web service does, but of course with all the quality, speed, scalability, stability etc. of the world's most popular http server.

Programming and Debugging Tips

Lookup the error log file of Apache Server

mod_gsoap logs apache errors in the standard way. So see the apache log file, typically it is located at /usr/local/apache/logs/apache_log.

Be sure you Debug the correct process

Sometimes when you exit the debugger it can happen that the httpd process is still alive. So before you continue, it might be a good idea to run
ps -ef | grep httpd
to see if there is still a server alive, which should be killed before the next debugging session. For killing all active httpd processes I use:
kill `ps -ef | grep httpd | sed -e"s/\ * /:/g" | cut -f2 -d:`

You do not debug the process /usr/local/apache/bin/httpd, but the httpd program that you build in your source code directory ~/apache/src. The key to successful debugging is the -X flag. So in your debugger run httpd from ~/apache/src, but use the same configuration file as your production server will use. Use the following commandline to start debugging:
./httpd -X -f /usr/local/apache/conf/httpd.conf

When the process is started in the debugger, set your breakpoints and use your favourite browser and refresh the page http://127.0.0.1:8080/soap.

See also the Frequently asked Questions at the end of  the IIS description.

How to use kdevelop for Programming and Debugging of Apache modules

If you want to use kdevelop to debug Apache then you can change to the directory ~/apache/src and run:
kimport > apache.kdevprj

After that you can open apache.kdevprj as a kdevelop project. Use the appropriate dialogs in your debugging environment to set the commandline arguments for debugging.

I hope you will have fun with this.

Enjoy,

Christian Aberger.