<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> | |
<HTML> | |
<HEAD> | |
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-15"> | |
<TITLE>mod_gsoap - Apache HTTP Server SOAP loadable module for .net Se</TITLE> | |
<META NAME="GENERATOR" CONTENT="Microsoft FrontPage 4.0"> | |
<META NAME="CREATED" CONTENT="20010518;23082600"> | |
<META NAME="CHANGEDBY" CONTENT=" "> | |
<META NAME="CHANGED" CONTENT="20020920;1270700"> | |
<META NAME="DESCRIPTION" CONTENT="SOAP module for Apache HTTP-Server to run SOAP and .NET(tm) Services under linux"> | |
<META NAME="KEYWORDS" CONTENT="mod_gsoap, gsoap, apache, HTTP, Server, Apache HTTP Server, .NET, .NET for linux, open source"> | |
</HEAD> | |
<BODY> | |
<H1 ALIGN=CENTER><FONT FACE="Veranda">SOAP and .net services for | |
Apache HTTP Server</FONT></H1> | |
<P ALIGN=CENTER>This is an open source contribution for <A HREF="http://www.cs.fsu.edu/~engelen/soap.html">gsoap</A>, | |
to enable <A HREF="http://www.apache.org/httpd">Apache HTTP Server</A> | |
to run <A HREF="http://www.w3.org/TR/SOAP/">SOAP</A> and .net | |
services on Linux and other Unices. | |
</P> | |
<H1>Overview</H1> | |
<P>To build and configure the mod_gsoap SOAP service you have to do | |
three main parts: | |
</P> | |
<OL> | |
<LI><P>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.</P> | |
<LI><P>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 | |
<A HREF="http://www.cs.fsu.edu/~engelen/soap.html">gsoap</A> for | |
details of how to use soapcpp2 to generate the wsdl , the C++ and | |
the other related code for your own SOAP services. | |
</P> | |
<LI><P>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.</P> | |
</OL> | |
<P>The build process uses <FONT FACE="Veranda"><A HREF="http://www.gnu.org/software/autmake">Automake</A> | |
</FONT>. Inside that mod_gsoap.so is built in the standard Apache way | |
using apxs. <FONT FACE="Veranda">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.</FONT></P> | |
<H1><FONT FACE="Veranda">1. Building the Apache SOAP server</FONT></H1> | |
<P><FONT FACE="Veranda">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 <A HREF="http://www.gnu.org/software/libtool">http://www.gnu.org/software/libtool</A>, | |
be sure to have it installed. Also be sure that you have apxs, which | |
comes with the apache http server distribution, in your path. </FONT> | |
</P> | |
<H2>Build instructions</H2> | |
<UL> | |
<LI><P>Make sure that apache http server is installed, otherwise <FONT FACE="Veranda">download | |
build and install apache_1.3.26.tar.gz or higher | |
(not 2.0.* or higher) from </FONT><A HREF="http://www.apache.org/httpd"><FONT FACE="Veranda">http://www.apache.org/httpd<br> | |
</FONT></A><font face="Veranda">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.</font> | |
</P> | |
<LI><P><FONT FACE="Veranda">download and install gsoap from <A HREF="http://www.cs.fsu.edu/~engelen/soap.html">http://www.cs.fsu.edu/~engelen/soap.html</A></FONT> | |
</P> | |
<LI><P><FONT FACE="Veranda">download the current gsoap_apache_0.0.5.tgz from | |
<A HREF="http://www.webware.at/SOAP/apache_gsoap.0.0.5.tgz">http://www.webware.at/SOAP/apache_gsoap.0.0.5.tgz</A> | |
</FONT>to <FONT FACE="Veranda">/usr/local/src and unpack it with:<br> | |
</FONT><font face="Courier New">tar -xzf apache_gsoap.0.0.5.tgz </font></P> | |
<LI><P>change to the directory that has been created by the step above and | |
run the following:<br> | |
<font face="Courier New">./configure <br> | |
make<BR></font><font face="Courier, monospace"><BR></font><FONT FACE="Veranda">This should build | |
./mod_gsoap/mod_gsoap.so and ./example/calculator/.libs/libCalculator.so (the | |
.libs subdirectory is hidden). lib</FONT>Calculator.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).</P> | |
</UL> | |
<H2>Building a debugging version</H2> | |
<P>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. | |
</P> | |
<P>You can enable debugging for mod_gsoap.c by using | |
--enable-debug<BR><FONT FACE="Courier, monospace">./configure | |
--enable-debug</FONT></P> | |
<P>Debugging is easier when you link mod_gsoap.c statically into | |
httpd, the Apache Server.</P> | |
<P>For that to the following: <BR>Copy the whole mod_gsoap | |
subdirectory to <FONT FACE="Veranda">~/apache_1.3.26</FONT>/src/modules/<BR>Next | |
Edit the Configuration file (it is located in ~/apache/src).<BR>Add | |
the following lines:<BR><SPAN STYLE="font-weight: medium"><FONT SIZE=3><FONT FACE="Courier, monospace"># | |
goap SOAP extension module. <BR>AddModule | |
modules/mod_gsoap/mod_gsoap.o </FONT></FONT></SPAN> | |
</P> | |
<UL> | |
<LI><P><FONT FACE="Times, serif">in the same file locate in the | |
section Makefile configuration the line containing EXTRA_LIBS and | |
add change the lines to the following: | |
<BR></FONT><FONT SIZE=3><FONT FACE="Courier, monospace">EXTRA_CFLAGS=-g<BR>EXTRA_LDFLAGS=<BR>EXTRA_LIBS=-ldl | |
-lpthread<BR>EXTRA_INCLUDES=-I~/apache_gsoap.0.0.5</FONT></FONT></P> | |
<P><font size="3">See the sample Configuration file that is in the | |
downloaded sources for an example.</font></P> | |
<P><FONT FACE="Times, serif">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.</FONT></P> | |
</UL> | |
<UL> | |
<LI><P><FONT FACE="Times, serif">Run the src/Configure script:</FONT><FONT FACE="Courier, monospace"><BR>cd | |
~/apache-1.3.26/src<BR>./Configure<BR><BR></FONT><FONT FACE="Times, serif">This | |
will build the Makefile for the server itself.<BR><FONT SIZE=2>Note: | |
do not run ~./apache-1.3.26/configure after it, this will overwrite | |
the Makefiles generated above. </FONT></FONT> | |
</P> | |
</UL> | |
<UL> | |
<LI><P><FONT FACE="Times, serif">Build the Apache Server, together | |
with the mod_gsoap by running in the current ~/apache_1.3.26/src | |
directory:<FONT FACE="Courier, monospace"><BR>make</FONT></FONT></P> | |
</UL> | |
<UL> | |
<LI><P><FONT FACE="Courier, monospace"><FONT FACE="Times, serif">The | |
previous step should have produced the file httpd<BR>Check that the | |
mod_gsoap has really been linked correctly by running:</FONT><BR>./httpd | |
-l<BR><FONT FACE="Times, serif">This should list as a module among | |
others also mod_gsoap.c and mod_so.c</FONT></FONT></P> | |
</UL> | |
<UL> | |
<LI><P><FONT FACE="Courier, monospace"><FONT FACE="Times, serif">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: </FONT><BR>make install<BR><FONT FACE="Times, serif">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. </FONT></FONT> | |
</P> | |
</UL> | |
<H2><BR><BR> | |
<FONT SIZE=6>2. Implementing your | |
own Servers</FONT> | |
</H2> | |
<P>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 <A HREF="http://www.cs.fsu.edu/~engelen/soap.html">gsoap | |
home page</A> 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.</P> | |
<P>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. | |
</P> | |
<P>Add the following 2 lines to your SOAP server source code: | |
<BR><FONT FACE="Courier, monospace">#include | |
"apache_gsoap.h"<BR>IMPLEMENT_GSOAP_SERVER()</FONT></P> | |
<P><FONT SIZE=3><FONT FACE="Times, serif">You also must change | |
Make</FONT></FONT>file.am accordingly to add your source files and | |
rename and run autoconf, automake, ./configure again of course. | |
apache_gsoap.h came with the <FONT FACE="Veranda">gsoap_apache_*.tgz | |
that you downloaded above and will be in the include path of the | |
compiler.</FONT></P> | |
<P>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.</P> | |
<P ALIGN=LEFT>If you want to have a graphical development environment | |
you can use <A HREF="http://www.kdevelop.org/">kdevelop</A>. 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 | |
<A HREF="http://www.cs.fsu.edu/~engelen/soap.html">gsoap</A> 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.</P> | |
<P><FONT FACE="Lucida, sans-serif"><FONT SIZE=6><B>3. Configuration | |
of httpd.conf</B></FONT></FONT></P> | |
<P><FONT FACE="Times, serif"><FONT SIZE=3>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.</FONT></FONT></P> | |
<UL> | |
<LI><P><FONT FACE="Times, serif">httpd.conf file must be edited. | |
<BR>This file will also be used to explicitly start debugging of the | |
apache server process httpd and step into mod_gsoap with e.g. <A HREF="http://members.nextra.at/johsixt/kdbg.html">kdbg</A> | |
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:<BR><FONT FACE="Courier, monospace">LoadModule | |
gsoap_module libexec/mod_gsoap.so</FONT><BR>below the place where | |
the comment: <BR><FONT FACE="Courier, monospace"># Dynamic Shared | |
Object (DSO) Support</FONT><BR>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 <BR>Next add the following lines to httpd.conf, near the | |
other <Location> sections:<BR><FONT FACE="Courier, monospace"># | |
SOAP handler (see </FONT><A HREF="http://www.aberger.at/SOAP"><FONT FACE="Courier, monospace">http://www.aberger.at/SOAP</FONT></A><FONT FACE="Courier, monospace">)<BR><IfModule | |
mod_gsoap.c><BR><Location /soap><BR>SetHandler | |
gsoap-handler<BR>SOAPLibrary /home/myusername/gsoap</FONT></FONT><font face="Courier, monospace">.0.0.5</font><FONT FACE="Times, serif"><FONT FACE="Courier, monospace">/apache/example/calculator/.libs/libCalculator.so<BR></Location><BR></IfModule></FONT><BR><FONT SIZE=3>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()! <BR>The | |
isoap-handler knows 2 configuration directives:<BR><B><U>SOAPLibrary</U></B> | |
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.<BR><B><U><SPAN STYLE="font-style: normal">SupportLibrary</SPAN></U></B> | |
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.</FONT></FONT></P> | |
<LI><P><FONT FACE="Times, serif">Now test if the Apache Server | |
itself is correctly configured, run the following from your | |
~/apache-1.3.26/src directory:<BR><FONT FACE="Courier, monospace">./httpd | |
-X -f /usr/local/apache/conf/httpd.conf</FONT></FONT></P> | |
<LI><P><FONT FACE="Times, serif">This will launch the server in | |
console mode (does not return until you cancel it). Then open your | |
favourite Web Browser and browse to:<BR><A HREF="http://127.0.0.1:8080/soap?structures"><FONT FACE="Courier, monospace">http://127.0.0.1:8080<BR></FONT></A>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.<BR>This request should give a | |
response from apache.</FONT></P> | |
<LI><P><FONT FACE="Times, serif">As a next step let us test if your | |
mod_gsoap responds. The request must contain the location you gave | |
in the <Location> directive. <FONT FACE="Times, serif">Enter | |
as address in your browser:</FONT><BR><A HREF="http://127.0.0.1:8080/soap">http://127.0.0.1:8080/soap<BR></A>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. <BR>Note: the soap | |
virtual directory was defined by yourself in the <Location> | |
instruction above. Do <B><U>not</U></B> create a physical soap | |
directory in your document root !</FONT></P> | |
<LI><P><FONT FACE="Times, serif">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:<BR></FONT><FONT FACE="Courier, monospace">cd | |
~/apache-gsoap/example/calculator<BR>./client 1 + 2</FONT><BR>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.</P> | |
</UL> | |
<H1>Programming and Debugging Tips</H1> | |
<H2>Lookup the error log file of Apache Server</H2> | |
<P>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.</P> | |
<H3>Be sure you Debug the correct process</H3> | |
<P>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<BR>ps -ef | grep httpd<BR>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:<BR><FONT FACE="Courier, monospace">kill | |
`ps -ef | grep httpd | sed -e"s/\ * /:/g" | cut -f2 -d:`</FONT> | |
</P> | |
<P>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:<BR><FONT FACE="Courier, monospace">./httpd | |
-X -f /usr/local/apache/conf/httpd.conf</FONT></P> | |
<P><FONT FACE="Times, serif">When the process is started in the | |
debugger, set your breakpoints and use your favourite browser and | |
refresh the page <A HREF="http://127.0.0.1:8080/soap">http://127.0.0.1:8080/soap</A>. | |
</FONT> | |
</P> | |
<P> | |
</P> | |
<P><FONT FACE="Times, serif">See also the Frequently asked Questions | |
at the end of the <A HREF="iis_index.html">IIS description</A>.</FONT> | |
</P> | |
<H2>How to use kdevelop for Programming and Debugging of Apache | |
modules | |
</H2> | |
<P>If you want to use <A HREF="http://www.kdevelop.org/"><FONT FACE="Times, serif">kdevelop</FONT></A><FONT FACE="Times, serif"> | |
to debug Apache then you can change to the directory ~/apache/src and | |
run:<BR></FONT><FONT FACE="Courier, monospace">kimport > | |
apache.kdevprj</FONT></P> | |
<P>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. <BR><BR><BR> | |
</P> | |
<P>I hope you will have fun with this. | |
</P> | |
<P>Enjoy, | |
</P> | |
<P><A HREF="http://www.webware.at/">Christian Aberger</A>.</P> | |
</BODY> | |
</HTML> |