Improvement/Fix for Installation Guide docs on mod_axis2 --------------------------------------------------------
Key: AXIS2C-517 URL: https://issues.apache.org/jira/browse/AXIS2C-517 Project: Axis2-C Issue Type: Improvement Components: documentation Affects Versions: 0.96 Environment: n.a. Reporter: markus mayer Priority: Minor Attachments: Axis2-C - Axis2-C Installation Guide.htm Hi, I just stepped through the installation guide for installing the mod_axis2. the doc is very good but i tripped over a detail not mentioned (thanks to Nabeel for helping me out on the mailing-list). i created a slightly more explicit version of the installation guide. maybe you can include that for future release. changes made: - included an example of a httpd.conf (to make it clear that the repo path is the axis main dir and not a sub-dir) - which cost me a couple of hours to find out. - corrected APACHE_INSTALL_DIR to APACHE_BIN_DIR which is the property name in configure.in Bye, Markus new version of "Axis2-C - Axis2-C Installation Guide.htm": ====================================================================================== <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3c.org/TR/1999/REC-html401-19991224/loose.dtd"> <!-- saved from url=(0056)http://ws.apache.org/axis2/c/docs/installationguide.html --> <HTML><HEAD><TITLE>Axis2/C - Axis2-C Installation Guide</TITLE> <STYLE type=text/css media=all>@import url( ../style/maven-base.css ); @import url( ../style/maven-classic.css ); </STYLE> <LINK media=print href="Axis2-C - Axis2-C Installation Guide_files/print.css" type=text/css rel=stylesheet></LINK> <META http-equiv=Content-Type content="text/html; charset=ISO-8859-1"></META> <META content="MSHTML 6.00.2900.3020" name=GENERATOR></HEAD> <BODY class=composite> <DIV id=banner><A id=organizationLogo href="http://www.apache.org/"><IMG alt="Apache Software Foundation" src="Axis2-C - Axis2-C Installation Guide_files/asf-logo.gif"></IMG></A><A id=projectLogo href="http://ws.apache.org/axis2/c"><IMG alt="Apache Axis2 C" src="Axis2-C - Axis2-C Installation Guide_files/axis.jpg"></IMG></A> <DIV class=clear> <HR> </HR></DIV></DIV> <DIV id=breadcrumbs> <DIV class=xleft>Last published: 22 December 2006 | Doc for 0.96</DIV> <DIV class=xright></DIV> <DIV class=clear> <HR> </HR></DIV></DIV> <DIV id=leftColumn> <DIV id=navcolumn> <DIV id=menuAxis2_C> <H5>Axis2/C</H5> <UL> <LI class=none><A href="http://ws.apache.org/axis2/c/index.html">Home</A> <LI class=expanded><A href="http://ws.apache.org/axis2/c/download.cgi">Download Axis2/C</A> <UL> <LI class=none><A href="http://ws.apache.org/axis2/c/download.cgi">Releases</A> <LI class=none><A class=externalLink title="External Link" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/">View Source Code Online</A> <LI class=none><A href="http://ws.apache.org/axis2/c/svn.html">Checkout Source Code</A></LI></UL> <LI class=expanded><A href="http://ws.apache.org/axis2/c/docs/index.html">Documentation</A> <UL> <LI class=none><A href="http://ws.apache.org/axis2/c/docs/installationguide.html">Installation Guide</A> <LI class=none><A href="http://ws.apache.org/axis2/c/docs/developerguide.html">Developer Guide</A> <LI class=none><A href="http://ws.apache.org/axis2/c/docs/userguide.html">User Guide</A> <LI class=none><A href="http://ws.apache.org/axis2/c/docs/axis2c_manual.html">Axis2/C manual</A></LI></UL> <LI class=expanded><A href="http://ws.apache.org/axis2/c/mail-lists.html">Get Involved</A> <UL> <LI class=none><A href="http://ws.apache.org/axis2/c/mail-lists.html">Mailing Lists</A></LI></UL> <LI class=expanded><A href="http://ws.apache.org/axis2/c/team-list.html">Project Information</A> <UL> <LI class=none><A href="http://ws.apache.org/axis2/c/team-list.html">Project Team</A> <LI class=none><A href="http://ws.apache.org/axis2/c/issue-tracking.html">Issue Tracking</A></LI></UL></LI></UL></DIV><A id=poweredBy title="Built by Maven" href="http://maven.apache.org/"><IMG alt="Built by Maven" src="Axis2-C - Axis2-C Installation Guide_files/maven-button-1.png"></IMG></A></DIV></DIV> <DIV id=bodyColumn> <DIV class=contentBox> <DIV class=section><A name=Axis2_C_Installation_Guide></A> <H2>Axis2/C Installation Guide</H2> <P>This document will guide you on how to install Axis2/C and run the server and client samples on Linux and Microsoft Windows operating systems.</P> <P>This release comes in two forms, source and binary. Instructions are given below to install using any of those two forms.</P> <P>Please send your feedback to the developer mailing list: <A href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</A> (please remember to prefix the subject with [Axis2]). To subscribe to developer mailing list see <A href="http://ws.apache.org/axis2/c/mail-lists.html">here</A></P> <DIV class=subsection><A name=Contents></A> <H3>Contents</H3> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#linux">Installing and running on Linux</A> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#linux_binary">Using binary release</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#linux_source">Using source release</A> </LI></UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#win">Installing and running on Microsoft Windows (win32)</A> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#win_binary">Using the binary release</A> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#bin_req">Requirements</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#bin_binaries">Binaries in the release</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#bin_run">Running the binaries</A> </LI></UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#win_source">Using the source release</A> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#src_req">Requirements</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#edit">Editing Configure.in file</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#src_compile">Compiling the source</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#src_run">Running the binaries</A> </LI></UL></LI></UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#installing-apache2">Installing Apache2 Web Server integration module (mod_axis2)</A> <UL> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#building-apache2">Building mod_axis2 from source tree</A> <LI><A href="http://ws.apache.org/axis2/c/docs/installationguide.html#deploying-apache2">Deploying in Apache2 Web Server</A> </LI></UL></LI></UL> <P><A id=linux></A></P></DIV> <DIV class=subsection><A name=1__Installing_and_Running_on_Linux></A> <H3>1. Installing and Running on Linux</H3> <P>This can be done using binary or source distributions.</P> <P>To get both the binary and source distributions working, you need libxml2, which can be <A class=externalLink title="External Link" href="http://xmlsoft.org/downloads.html">downloaded</A>.</P> <P><B>Note :</B> Most Linux systems have libxml2 installed by default. On MS Windows you need to download and install libxml2.</P> <P><A id=linux_binary></A></P></DIV> <DIV class=subsection><A name=1_1__Using_Binary_Release></A> <H3>1.1. Using Binary Release</H3> <P>The following steps need to be taken to install and run Axis2/C using binary distribution on Linux : - </P> <OL> <LI>Extract the binary tar package to a folder. <LI>Set AXIS2C_HOME environment variable pointing to the location where you have extracted Axis2C <UL> <LI>AXIS2C_HOME='/your_path_to_axis2c' <LI>export AXIS2C_HOME <P><STRONG>Note :</STRONG> You will need to set AXIS2C_HOME only if you need to run Axis2C samples or tests. The reason is that the samples and test codes use AXIS2C_HOME to get the path to Axis2C. To write your own services or clients this is not a requirement.</P></LI></UL> <LI>Run the simple axis server: <UL> <LI>To start the simple axis server on default port 9090, run the following commands. <UL> <LI>cd /your_path_to_axis2c/bin <LI>./axis2_http_server </LI></UL> <LI>To see the possible command line options run ./axis2_http_server -h <P><STRONG>Note :</STRONG> If you run into shared lib problems, try setting the LD_LIBRARY_PATH</P> <UL> <LI>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib </LI></UL></LI></UL> <LI>Run the sample clients in a new shell <UL> <LI>cd /your_path_to_axis2c/bin/samples <LI>To run client for echo service <UL> <LI>./echo </LI></UL> <LI>To run client for math service <UL> <LI>./math </LI></UL> <LI>To see the possible command line options for sample clients run them with '-h' option <P><STRONG>Note :</STRONG> If you run into shared lib problems, try setting the LD_LIBRARY_PATH</P> <UL> <LI>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib </LI></UL></LI></UL></LI></OL><AI id=linux_source> <H3>1. 2. Using Source Release</H3> <P>The following steps need to be taken to install and run Axis2/C using source distribution on Linux : - </P> <OL> <LI>Extract the source tar package to a folder. <LI>Set AXIS2C_HOME environment variable pointing to the location where you want to install Axis2C. <UL> <LI>AXIS2C_HOME='/your_desired_path_to_axis2c_installation' <LI>export AXIS2C_HOME <UL> <LI><STRONG>Note :</STRONG> You will need to set AXIS2C_HOME only if you need to run Axis2C samples or tests. The reason is that the samples and test codes use AXIS2C_HOME to get the path to Axis2C. To write your own services or clients this is not a requirement. </LI></UL></LI></UL> <LI>Then go to the folder where you extracted the source <UL> <LI>cd /your_path_to_axis2c_source </LI></UL> <LI>Build the source <UL> <LI>This can be done using the following command sequence in the directory where you have extracted the source: <UL> <LI>./configure --prefix=${AXIS2C_HOME} <LI>make <LI>make install </LI></UL> <LI>Use './configure --help' for possible command line options. <LI><STRONG>Note :</STRONG>If you do not provide a --prefix configure option, it will by default be installed into /usr/local/axis2c directory. <LI>You may need to try Axis2/C with Guththila XML parser. You can do it by giving --enable-guththila=yes <UL> <LI>./configure --enable-guththila=yes [other configuration options] <LI>make <LI>make install </LI></UL> <LI>In order to build Rampart (Axis2/C security module) <UL> <LI>./configure --enable-rampart=yes [other configuration options] <LI>make <LI>make install </LI></UL> <LI>If you need to get the samples working, you also need to build the samples. <BR><BR>To build the samples: <UL> <LI>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/axis2c/lib/ <LI>cd samples <LI>./configure --prefix=${AXIS2C_HOME} --with-axis2_util=${AXIS2C_HOME}/include --with-axiom=${AXIS2C_HOME}/include <LI>make <LI>sudo make install </LI></UL> <LI>Please run "./configure --help" in samples folder for more information on configure options. <LI><STRONG>Note :</STRONG> If you do not provide a --prefix configure option, samples will by default be installed into "/usr/local/axis2c/samples" directory. </LI></UL> <LI>Go to where you installed Axis2/C. <LI>Start simple axis server <UL> <LI>To start the simple axis server on port 9090 run the following command lines <UL> <LI>cd ${AXIS2C_HOME}/bin <LI>./axis2_http_server </LI></UL> <LI>To see the possible command line options run ./axis2_http_server -h <LI><STRONG>Note :</STRONG> You may need to be logged in as a superuser to run the simple axis server. </LI></UL> <LI>Run the sample clients in a new shell using the following command lines <UL> <LI>cd ${AXIS2C_HOME}/bin/samples <LI>to run client for echo service <UL> <LI>./echo </LI></UL> <LI>to run client for math service <UL> <LI>./math </LI></UL> <LI>To see the possible command line options for sample clients run them with '-h' option </LI></UL></LI></OL><A id=win></A> <H2>2. Installing and Running on Microsoft Windows (win32)</H2> <P>This too can be done using either binary or source distributions.</P> <P>For both the binary and source distributions, you need to <A class=externalLink title="External Link" href="http://xmlsoft.org/downloads.html">download</A> libxml2.</P> <P>(NOTE: most Linux systems have libxml2 by default. On MS Windows you need to download and install libxml2)</P><A id=win_binary></A> <H3>2. 1. Using Binary Release</H3><A id=bin_req></A> <H4>2.1.1. Requirements</H4> <UL> <LI>The binaries shipped with this version are compiled with Microsoft Visual Studio Compiler (cl) <P>(Note: you can download Microsoft VSExpress2005 edition from the Microsoft Web site and install it to run these binaries)</P> <LI>You also need the following dlls: <UL> <LI>libxml2.dll [http://www.xmlsoft.org - download the version >= libxml2-2.6.20.win32] <LI>iconv.dll [http://www.xmlsoft.org - download the version >= iconv-1.9.1.win32] <LI>zlib1.dll [http://www.xmlsoft.org - download the version >= zlib-1.2.3.win32] </LI></UL></LI></UL><A id=bin_binaries></A> <H4>2.1.2. Binaries in The Release</H4> <UL> <LI>Extract the binary distribution to a folder of your choice. (example: C:\axis2c) <LI>The C:\axis2c folder structure is as follows: <P><IMG alt="Figure: c:\axis2c Folder Structure" src="Axis2-C - Axis2-C Installation Guide_files/binary_folder_structure.jpg"></IMG></P> <P><EM>The above folders contain the following files:</EM></P> <UL> <LI>bin - server and other executables <LI>bin\samples - client samples go here <LI>lib - library modules <LI>services - deployed services <LI>modules - deployed modules <LI>include - all include files of Axis2 C <LI>logs - system and client logs are written to this folder </LI></UL> <LI>Copy libxml2.dll, iconv.dll and zlib1.dll downloaded to C:\axis2c\lib </LI></UL><A id=bin_run></A> <H4>2.1.3. Running The Binaries</H4> <UL> <LI>First, you need to set a couple of environment variables before you can run the server and samples. <UL> <LI>Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c) <LI>Add the path to lib directory to the PATH variable (%AXIS2C_HOME%\lib) </LI></UL> <LI>Now everything is set to run the server (C:\axis2c\bin\> axis2_http_server.exe) <LI>If the server is running successfully you should see the message "Started Simple Axis2 HTTP Server..." <LI>The log is by default created in %AXIS2C_HOME%\logs folder with the name axis2.log. <LI>(Note: You may provide command line options to change the default behaviour. Use the command "axis2_http_server.exe -h" to learn about the usage) <LI>Now you can run any sample client located in %AXIS2C_HOME%\bin\samples\ <UL> <LI>Example: C:\axis2c\bin\samples\> echo.exe </LI></UL></LI></UL><A id=win_source></A> <H3>2. 2. Using The Source Release</H3><A id=src_req></A> <H4>2.2.1. Requirements</H4> <UL> <LI>The makefile shipped with this version needs Microsoft Visual Studio Compiler (cl) and nmake build tool. <P>(Note: You can download Microsoft VSExpress2005 edition and Platform SDK from Microsoft Web site. You will need to add the path to Platform SDK Include and Lib folders to makefile)</P> <LI>You also need <UL> <LI>libxml2 [http://www.xmlsoft.org - download the version >= libxml2-2.6.20.win32] <LI>iconv [http://www.xmlsoft.org - download the version >= iconv-1.9.1.win32] <LI>zlib [http://www.xmlsoft.org - download the version >= zlib-1.2.3.win32] </LI></UL></LI></UL><A id=edit></A> <H4>2.2.3. Editing configure.in File</H4> <UL> <LI>The default paths for libxml2 and iconv are specified in configure.in <UL> <LI>Example:Default location for libxml2 is C:\libxml2 </LI></UL> <LI>You can either extract libxml2 to this folder, in which case folder structure for C:\libxml2 should look like the following: <P><IMG alt="Figure: C:\libxml2 Folder Structure" src="Axis2-C - Axis2-C Installation Guide_files/folder_structure_libxml2.jpg"></IMG></P> <P>Or extract to a location of your choice and edit the configure.in accordingly.</P> <LI>You need to have zlib1.dll in a library path. You may copy this dll to libxml2/lib. </LI></UL><A id=src_compile></A> <H4>2.2.4. Compiling The Source</H4> <P>The following steps will take you through the source compilation</P> <UL> <LI>Extract the source distribution to a folder of your choice. (Example: C:\axis2c) <LI>Open a DOS shell <LI>cd C:\axis2c\build\win32 <LI>to access .Net tools, run <UL> <LI>C:\axis2c\build\win32> vcvars32.bat </LI></UL> <P>(Note: You may need to set the PATH environment variable to vcvars32.bat if Windows complaints that it cannot find this bat)</P> <LI>build the system and create a directory named deploy under build directory: <UL> <LI>C:\axis2c\build\win32>nmake install </LI></UL> <LI>The deploy folder structure is as follows: <P><IMG alt="Figure: deploy Folder Structure" src="Axis2-C - Axis2-C Installation Guide_files/folder_structure.jpg"></IMG></P> <P><EM>The above folders contain the following files:</EM></P> <UL> <LI>bin - server and other executables <LI>bin\samples - client samples <LI>lib - library modules <LI>services - deployed services <LI>modules - deployed modules <LI>include - all include files of Axis2 C <LI>logs - system and client logs are written to this folder </LI></UL></LI></UL><A id=src_run></A> <H4>2.2.5. Running The Binaries</H4> <UL> <LI>You need to set couple of environment variables before you can run the server and samples. <UL> <LI>Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c\build\deploy) <LI>Add the path to lib directory to PATH variable (%AXIS2C_HOME%\lib) <LI>Copy libxml2.dll, iconv.dll and zlib1.dll to axis2c lib folder (%AXIS2C_HOME%\lib) </LI></UL> <LI>Now run the server - C:\axis2c\build\deploy\bin> axis2_http_server.exe <LI>If server is running successfully you should see the message "Started Simple Axis2 HTTP Server..." <LI>The log is by default created under %AXIS2C_HOME%\logs folder with the name axis2.log. <LI>(Note: you may provide command line options to change the default behaviour. Use the command "axis2_http_server.exe -h" to learn about the usage) <LI>Now you can run any sample client deployed under %AXIS2C_HOME%\bin\samples\ <UL> <LI>Example: C:\axis2c\build\deploy\bin\samples> echo.exe </LI></UL></LI></UL><A id=installing-apache2></A> <H3>3. Installing Apache2 Web Server Integration Module (mod_axis2).</H3><A id=building-apache2></A> <H4>3.1. Building mod_axis2 From Source Tree</H4> <H4>3.1.1 On Linux Platform:</H4> <UL> <LI>Provide the apache2 include files location as configure option ./configure --with-apache2="<apache2 include files location>" [other configure options] - Some apache2 distributions install APR (Apache Portable Runtime) include files in a separate location which is required to build mod_axis2. In that case use <UL> <LI>./configure --with-apache2="<apache2 include files location>" --with-apr="<apr include files location>" [other configure options] </LI></UL> <LI>Then build the source tree <UL> <LI>make <LI>make install <P>This will install mod_axis2.so into your "<your_path_to_axis2c>/lib"</P></LI></UL></LI></UL> <H4>3.1.2 On Win32 Platform:</H4> <UL> <LI>Provide the apache2 location in configure.in file in APACHE_BIN_DIR<BR><BR>eg : APACHE_BIN_DIR = E:\Apache\bin <LI>After compiling the sources (As described in <A href="http://ws.apache.org/axis2/c/docs/installationguide.html#win">Section 2</A>) build the mod_axis2.dll by issuing the command "nmake axis2_apache_module". <LI>This will build the mod_axis2.dll and copy it to %AXIS2C_HOME%\lib directory.<BR><BR>eg: C:\axis2c\build\deploy\lib </LI></UL><A id=deploying-apache2></A> <H4>3.2. Deploying in Apache2 Web Server</H4> <P><B>Note:</B> To do the following tasks you might need super user privileges in your machine.</P> <UL> <LI>Copy the mod_axis2 (libmod_axis2.so.0.0.0 on Linux and mod_axis2.dll in Windows) to "<apache2 modules directory>" (eg: /usr/lib/apache2/modules in Linux or C:\Apache2\modules in Windows) as mod_axis2.so <P>eg: cp $AXIS2C_HOME/lib/libmod_axis2.so.0.0.0 /usr/lib/apache2/modules/mod_axis2.so<BR><BR>copy C:\axis2c\build\deploy\lib\mod_axis2.dll C:\Apache2\modules\mod_axis2.so</P> <LI>Edit Apache2's configuration file (generally httpd.conf) and add the following directive : - <PRE> LoadModule axis2_module <apache2 modules directory>/mod_axis2.so Axis2RepoPath <axis2 repository path> Axis2LogFile <axis2 log file path> Axis2LogLevel LOG_LEVEL <Location /axis2> SetHandler axis2_module </Location> </PRE> <P>LOG_LEVEL can be one of following</P> <P>AXIS2_LOG_LEVEL_CRITICAL - Log critical errors only <BR><BR>AXIS2_LOG_LEVEL_ERROR - Log errors critical errors <BR><BR>AXIS2_LOG_LEVEL_WARNING - Log warnings and above <BR><BR>AXIS2_LOG_LEVEL_INFO - Log info and above <BR><BR>AXIS2_LOG_LEVEL_DEBUG - Log debug and above (default) <BR><BR>AXIS2_LOG_LEVEL_TRACE - Log trace messages</P> <P>An example of a httpd.conf:<br> <PRE> LoadModule axis2_module modules/mod_axis2.dll Axis2RepoPath C:/axis2c/build/deploy Axis2LogFile C:/axis2c/build/deploy/logs Axis2LogLevel AXIS2_LOG_LEVEL_DEBUG <Location /axis2> SetHandler axis2_module </Location> </PRE></P> <LI>Use forward slashes "/" for path seperators in <apache2 modules directory>, <axis2 repository path> and <axis2 log file path> <LI>Make sure that the Apache2 user has correct permissions to above paths.<BR><BR> <UL> <LI>Read permission to the repository <LI>Write permission to the log file </LI></UL> <LI>Restart Apache2 and test whether mod_axis2 module is loaded by typing the URL http://localhost/axis2/services </LI></UL></AI></DIV></DIV></DIV></DIV> <DIV class=clear> <HR> </HR></DIV> <DIV id=footer> <DIV class=xright>© 2005-2006, Apache Software Foundation</DIV> <DIV class=clear> <HR> </HR></DIV></DIV></BODY></HTML> -- This message is automatically generated by JIRA. - You can reply to this email to add a comment to the issue online. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]