| <!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> |