[Download]
| [Documentation Home] | [Release Note]
WSO2 Web Services Application Server, v2.1-RC4 - Installation
Guide
This installation guide provides information on,
- the prerequisites for WSO2 WSAS
- installation instructions
- starting up WSO2 WSAS, and
- accessing the management console
Of the two main sections of this document, one explains the installation
of the
WSO2 WSAS in Standalone Mode, while the other
explains the installation of the
WSO2 WSAS into a J2EE compliant
servlet container.
For the more adventurous user, WSO2 WSAS can also be built using the
source distribution available with this release. The third
section of this installation guide explains how to build WSO2 WSAS using the
source distribution.
Your feedback on WSO2 WSAS is most appreciated. Please send them to our
mailing lists.
Content
Introduction
WSO2 WSAS is a lightweight application server for Web services. It is
built on the Apache Axis2 framework and incorporates leading open source
components into a simple, easy-to-use, and highly performant package. Web
services specifications support include WS-Addressing, WS-Policy,
WS-ReliableMessaging, WS-Security and more, giving a fully secure,
transactional and reliable infrastructure.
WSO2 WSAS is distributed in several convenient distribution packages, and
can be installed either as a standalone server or as part of a J2EE compliant
servlet container. WSO2 WSAS is distributed under the
Apache License,
version 2.0.
[Download
WSO2 WSAS ]
System Requirements
Java Runtime Environment |
1.4 or 1.5 (For instructions on setting up the JRE in different
operating systems, visit http://java.sun.com) |
Memory |
No minimum requirement |
Disk |
No minimum requirement.
Approximately 40 MB will be used for the .zip distribution
|
Operating System |
Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu,
Gentoo |
Installing WSO2 Web Services Application Server v2.1-RC4 in
the Standalone Mode
Installing on Microsoft Windows
Note: The WSO2 WSAS, v2.1-RC4 release has been
successfully tested only on Windows XP.
There are two methods of installation on the MS Windows operating
system.
- Using the Installation Wizard (WSO2 WSAS for
Java, v2.1-RC4 Setup wizard)
- Using the Binary Distribution
Running the Installation Wizard
Download
the wso2wsas-2.1-RC4.msi
Execute the .msi and follow the instructions on the WSO2 WSAS ,
v2.1-RC4 Setup wizard
The first page of the installation wizard is as follows.

Click Next. It will lead you to the End-User License Agreement.

Select the check box to accept the terms in the license agreement; this
will enable the Next button. Click Next to move to the Custom Setup page
shown below. Custom Setup will allow you to select the features you want to
install.
On the next screen you'll be shown the custom installation features select section.

Click Next on the Custom Setup Page to move to
the Ready to Install page displayed below. Click Install. WSO2 WSAS ,
v2.1-RC4 will be installed in your computer.

Once the installation is complete and the setup exits, click Finish on the
WSAS setup wizard. You willl be able to view WSO2 WSAS on the programs list of
the Start menu of Windows. A shortcut to WSO2 WSAS , v2.1-RC4 will
also appear on the Desktop.
On the programs list of the Start menu, WSO2 WSAS will have the following
options :
- Start the server
- Add server as a Network (NT) Service to Windows Services
- Remove WSO2 WSAS service from Windows Services

Once you add WSO2 WSAS as an NT service to Windows services, you can start
this service from Services in Administrative tools of the Control Panel.
Installing using Binary Distribution
The following steps will take you through the installation for the MS
Windows operating system.
- Download
the WSO2 WSAS binary distribution.
- Extract the zip archive.
- Set the JAVA_HOME environment
variable to your Java installation.
- Execute the WSO2 WSAS starting script. e.g.,
C:\wso2wsas-2.1-RC4\bin\wso2wsas.bat
- Check your WSO2 WSAS instance using the URL https://localhost:9443
Installing on Linux
Again, there are two methods of installing on Linux:
- Using Binary Distribution
- Using Binary Installers
(deb/rpm)
Installing using Binary Distribution
- Download
the WSO2 WSAS binary distribution.
- Extract the zip archive. e.g., unzip wso2wsas-2.1-RC4.zip -d
/opt
- Set the JAVA_HOME environment variable to your Java installation using
the export command or by editing /etc/profile. e.g., export
JAVA_HOME="/opt/j2sdk"
- Execute the WSO2 WSAS starting script. e.g., cd
/opt/wso2wsas-2.1-RC4/bin; sh wso2wsas.sh
- Check your WSO2 WSAS instance using the URL https://localhost:9443
Installing using Binary Installers (deb/rpm)
The following steps will take you through the binary distribution
installation.
- Download WSO2 WSAS deb or
RPM
binary.
- Install Debian binary ( deb ) e.g., dpkg -i
wso2wsas-java-2.1-RC4.deb (To install deb, log on to the
system as root user.)
- Install RPM binary ( rpm ) e.g., rpm -Uvh
wso2wsas-java-2.1-RC4.i386.rpm (To install rpm, log on to the
system as root user.)
- Execute/start the WSO2 WSAS from the shell. e.g., /etc/init.d/wso2wsas
start
(You can also stop the server from the shell. e.g., /etc/init.d/wso2wsas
stop)
Troubleshooting Installation
When trying to execute the WSO2 WSAS binary from a shell, e.g.,
/usr/bin/wso2wsas (after WSO2 WSAS , v2.1-RC4 has been installed),
if the error message 'Permission denied' pops up, then check the file
permission of the run.sh script and set the execution permission.
Modify/ Repair/ Remove Installation
On
MS Windows systems,
- Use the "Add or Remove programs" utility on the Control Panel to change
or remove the WSO2 WSAS installation
or
- Return to wso2wsas-2.1-RC4.msi, execute, and follow the
instructions given below.

In
Debian Linux systems, use the dpkg utility to remove
the WSO2 WSAS installation. e.g., dpkg -r wso2wsas-java-2.1-RC4
In
Redhat Linux systems, use the rpm utility to remove
the WSO2 WSAS installation. e.g.,: rpm -e wso2wsas-java-2.1-RC4
Accessing the Management Console
Once WSO2 WSAS , v2.1-RC4 has been successfully installed, in
order to access the Management Console, first start the server, launch a web
browser instance, and then point it to the URL
https://localhost:9443/ (if you are using
the default settings). This will take you to the "Sign In" page of the
Management Console as displayed below.
Note: By default, WSO2 WSAS has two listeners, HTTP and
HTTPS. The HTTP listener opens on port 9762, while the HTTPS listener opens
on port 9443. The administrator functions are exposed only via the HTTPS
port.

For details on WSO2 WSAS Management Console see the
Administrator's Guide
Installing WSO2 Web Services Application Server, v2.1-RC4 in a
Servlet Container
This section provides instructions on how to install the WSO2 WSAS in a
Servlet container. This also includes information on how to configure WSO2
WSAS on JBoss, Geronimo and Tomcat servers. Some guidelines on installing
WSO2 WSAS on other application servers have also been included.
Your feedback on WSO2 WSAS is most appreciated. Please send them to our
mailing lists.
Introduction
The WSO2 WSAS Servlet should be installed on a J2EE compliant servlet
container.
WSO2 WSAS has been fully tested on the following J2EE Application Servers,
and specific installation instructions for each server are listed under the
Application Server Specific Installation section.
J2EE Application Servers
Apache Tomcat Server:
JBoss AS:
Apache Geronimo AS:
BEA WebLogic AS
General:
Web application servers that do not fall under the above list will have to
follow the
Generic Application Server Installation Steps
described below.
Application Server Specific Information
Installation Instructions
Follow the simple installation steps to successfully install WSO2 WSAS
into a JBoss AS, Apache Geronimo AS or Apache Tomcat server.
1. Download the WSO2 WSAS binary distribution if you haven't done so.
Download
Unzip wso2wsas-2.1-RC4.zip to a desired location. (eg:
c:\wso2-wsas on windows or /home/wso2wsas on linux). This folder will be
referred to as WSO2WSAS_HOME.
2. Run install.sh for Linux or install.bat for MS Windows from
WSO2WSAS_HOME/bin
3. Select the WSO2WSAS_HOME.
4. Select the application server and its version.
5. After this point, there are a few application server specific steps to
be followed:
Apache Tomcat Server:
- Enter Tomcat HOME directory
- Prompts whether to replace the existing server.xml
- If the answer is No, then, follow the advanced
configuration steps
- If the answer is Yes, the existing server.xml is backed up, and
then replaced with the default server.xml shipped with the WSO2 WSAS
Servlet Edition
JBoss AS:
- Enter JBoss HOME directory
- Select the set of configuration files into which WSO2 WSAS
will be installed from the given options.
- Prompts whether to replace the existing server.xml
- If the answer is No, then, follow the advanced
configuration steps
- If the answer is Yes, the existing Tomcat server.xml is backed up,
and then replaced with the default JBoss-Tomcat server.xml shipped
with WSO2 WSAS
Some specific libraries and application server
specific files will be copied to the relevant directories.
7. Restart the application server.
Now the Management Console should be available
on https://localhost:9443/wso2wsas if you used the default settings.
Advanced Configuration Instructions
We support the following Application Servers out of the box with our
installer. However, if you wish to manually carry out the configuration, the
following tips will be helpful:
Apache Tomcat Server:
a) Version 5.5.x
1. Enabling SSL on Tomcat
To enable SSL on Tomcat 5.5.x the server XML should contain the following
segment:
<Connector port="9443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25"
maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="wso2wsas/conf/wso2wsas.jks"
keystorePass="wso2wsas" />
NOTE: You can use any keystoreFile of your preference instead of the
wso2wsas.jks which is shipped with WSO2 WSAS.
2. Registering the WSO2 WSAS Data Store
To register the data source, include the following segment in the
server.xml within the 'host' element
<Context path="/wso2wsas" >
<Resource name="jdbc/wso2wsas_db"
auth="Container"
type="javax.sql.DataSource"
maxActive="100"
maxIdle="30"
maxWait="10000"
username="wso2wsas"
password="wso2wsas"
driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
url="jdbc:derby:../database/WSO2WSAS_DB"/>
</Context>
b) Version 5.0.x
1. Enabling SSL on Tomcat
To enable SSL on Tomcat 5.0.x the server XML should contain the following
segment
<Connector port="9443"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="wso2wsas/conf/wso2wsas.jks"
keystorePass="wso2wsas />
NOTE: You can use any keystoreFile of your preference instead of the
wso2wsas.jks which is shipped with WSO2 WSAS.
2. Registering the WSO2 WSAS Data Store
To register the data store, include the following segment in the
server.xml within the 'host' element
<Context path="/wso2wsas" docBase="wso2wsas"
reloadable="true" crossContext="true">
<Resource name="jdbc/wso2wsas_db" auth="Container"
type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/wso2wsas_db">
<parameter><name>username</name><value>wso2wsas</value></parameter>
<parameter><name>password</name><value>wso2wsas</value></parameter>
<parameter><name>driverClassName</name>
<value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
<parameter><name>url</name>
<value>jdbc:derby:../database/WSO2WSAS_DB</value>
</parameter>
</ResourceParams>
</Context>
c) Version 4.1.x
1. Enabling SSL on Tomcat
To enable SSL on Tomcat 4.1.x the server.xml should contain the following
segment
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="9443" minProcessors="5" maxProcessors="75"
enableLookups="true"
acceptCount="100" debug="0"
scheme="https"
secure="true"
useURIValidationHack="false"
disableUploadTimeout="true">
<Factory
className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
keystoreFile="wso2wsas/conf/wso2wsas.jks"
keystorePass="wso2wsas"
clientAuth="false" protocol="TLS" />
</Connector>
NOTE: You can use any keystoreFile of your preference instead of the
wso2wsas.jks which is shipped with WSO2 WSAS .
2. Registering the WSO2 WSAS Data Store
To register the wso2 wsas data store, include the following segment in the
server.xml within the 'host' element
<Context path="/wso2wsas" docBase="wso2wsas"
reloadable="true" crossContext="true">
<Resource name="jdbc/wso2wsas_db" auth="Container"
type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/wso2wsas_db">
<parameter><name>username</name><value>wso2wsas</value></parameter>
<parameter><name>password</name><value>wso2wsas</value></parameter>
<parameter><name>driverClassName</name>
<value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
<parameter><name>url</name>
<value>jdbc:derby:../database/WSO2WSAS_DB</value>
</parameter>
</ResourceParams>
</Context>
2. JBoss AS
Version 3.2.x and 4.0.x
1. Enabling SSL on JBoss
To enable SSL on JBoss, add the following segment to
JBOSS_HOME/server/default/deploy/jbossweb-tomcatxx.sar/server.xml as a child
of the jboss.web Service element.
<Connector port="9443" address="${jboss.bind.address}"
maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
emptySessionPath="true"
scheme="https" secure="true" clientAuth="false"
keystoreFile="${jboss.server.home.dir}/tmp/wso2wsas/conf/wso2wsas.jks"
keystorePass="wso2wsas" sslProtocol = "TLS" />
NOTE: You can use any keystoreFile of your preference instead of the
wso2wsas.jks which is shipped with WSO2 WSAS.
2. Registering the WSO2 WSAS Data Source
To register the data source, create the wso2wsas-derby-ds.xml file in
JBOSS_HOME/server/default/deploy with the following text:
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>jdbc/wso2wsas_db</jndi-name>
<connection-url>jdbc:derby:../database/WSO2WSAS_DB/connection-url>
<driver-class>org.apache.derby.jdbc.EmbeddedDriver</driver-class>
<user-name>wso2wsas</user-name>
<password>wso2wsas</password>
</local-tx-datasource>
</datasources>
3. Apache Geronimo AS
Version 1.1.1
1. Creating connectors with Geronimo
The easiest way to manage the Geronimo server is by using the management
console. The management console can be accessed from the URL
http://localhost:8080/console. The default user name is system, and
the password is manager. Web server connectors can be managed by
using the "Web Server" link found under the "Console Navigation".
2. Deploying data sources
Data sources can also be easily created with the management console, using
the "Data pools" link found under the "Console Navigation". The Deployer tool
can also be used to deploy a data source if a deploy plan is present. In this
case, use the following command.
java -jar bin/deployer.jar --user system --password manager deploy <path to deploy plan>
repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar
3. Deploying Web applications
The Deployer tool can be used to deploy web applications. Use the
following command.
java -jar bin/deployer.jar --user system --password manager deploy <pathto Web application>
Issues to Note
- On JBoss version 4.0.0 and possibly some other versions, the
hibernate2.jar and cglib-full-2.0.1.jar should be removed from the lib
directories since wso2wsas uses the latest hibernate version, which
conflicts with the older version used by JBoss.
- On JBoss version 4.0.0 and possibly some other versions, if the
jboss-ws4ee.sar is present inside the deploy directory, the admin service
will not start due to a conflict in the WSDL API. In this case, the
jboss-ws4ee.sar needs to be completely removed from the deploy
directory
- On JBoss version 4.0.0 and possibly other versions, the ant.jar file
included inside the jbossweb-tomcat50.sar may cause problems with the
code generation. In order to ensure a smooth operation, replace the
ant.jar with the ant-1.6.x.jar found in the wso2wsas lib folder. Also the
ant-nodeps-x.x.x.jar needs to be copied into the
jbossweb-tomcat50.sar.
- On JBoss version 4.0.0 and possibly other versions, the Windows
installation may cause problems if the wso2wsas home resides in a
directory path which has spaces.
- On JBoss version 4.0.1
JBOSS_HOME/server/default/deploy/jboss-hibernate.deployer should be
removed since some of its hibernate related libraries conflict with the
latest hibernate libraries used by WSO2 WSAS.
- On JBoss version 3.2.7
JBOSS_HOME/server/default/deploy/jboss-hibernate.sar should be removed
since some of its hibernate related libraries conflict with the latest
hibernate libraries used by WSO2 WSAS.
- The output from Hibernate is extremely verbose. Add the following
segment to your log4j.xml to avoid this output:
<category name="org.hibernate">
<priority value="ERROR"/>
</category>
- In MacOSX the classes.jar needs to be copied into the commons/lib dir
of the Tomcat installation in order to run the generate client and 'Try
it!' features.
Generic Web Application Server
Installation Instructions
For Web application servers other than JBoss, Apache Tomcat and Geronimo,
follow the installation steps as given below.
- Unzip wso2wsas-servlet-edition-java-1.1.zip
- Run install.sh for Linux or install.bat for MS Windows from
wso2wsas-servlet-edition-java-1.1/bin
- Select the WSO2WSAS_HOME.
- Select the Application Server's WAR file deployment directory.
- Configure HTTP, HTTPS and configure the WSO2 WSAS JNDI datasource. See
advanced configurations for more details
- Restart the application server.
- Now the Management Console should be available on
https://localhost:9443/wso2wsas if you used the default settings.
Advanced Configuration
1. Register a JNDI datasource with the JNDI name jdbc/wso2wsas_db Use the
following details to configure this datasource;
a. Database Driver : org.apache.derby.jdbc.EmbeddedDriver
b. Database URL : e.g. jdbc:derby:/wso2wsas/WSO2WSAS_DB
c. Database Username : wso2wsas
d. Database Password : wso2wsas
NOTE: You should provide the correct path to the WSO2 WSAS database in the
database URL
2. Copy the wso2wsas-servlet-edition-java-1.1/lib/derby-10.1.1.0.jar and
the wso2wsas-servlet-edition-java-1.1/lib/log4j-1.2.13.jar to your
application server's classpath.
3. Copy the JDK tools.jar (in the case of Windows and Linux JDKs) or
classes.jar (in the case of Mac OS X) to your application server's classpath,
if they have not been added to the application server's classpath already.
4. Enable SSL on your application layer. If you intend to use the key
store file shipped with wso2wsas, you should point your application server to
it. The wso2wsas key store file is
wso2wsas-servlet-edition-java-1.1/conf/wso2wsas.jks
If you intend to use your own key store file, you need to configure the
server.xml HTTPS KeyStore Location element.
Post Installation Modifications
This section contains information on modifications that can be carried out
after WSO2 WSAS has been successfully installed on your application
server.
1. The wso2wsas.properties file
This file is created during installation and may be located at
wso2wsas.war/WEB-INF/classes/wso2wsas.properties, in your application
server's webapp deployment directory.
The wso2wsas.home and other application server specific properties can be
changed by modifying this file. You may have to re-archive the wso2wsas.war
after modifying this file.
2. Changing the WSO2 WSAS database configurations
- In your application server's configuration file, locate the section
where the wso2wsas JDBC datasource is registered, and modify the relevant
parameters.
- Locate wso2wsas.hibernate.cfg.xml in ../WEB-INF/classes and change the
"dialect" property, if necessary, to match your RDBMS. e.g. for MySQL,
the dialect is org.hibernate.dialect.MySQLDialect
3. Changing HTTP/HTTPS ports
In your application server's configuration file, locate the section where
the ports have been registered, and changed it to the appropriate values.
If you carried out a Generic installation, in addition to modifying your
application server's configuration file, you also have to modify the
server.xml file, which can be found at WSO2WSAS_HOME/conf.
Accessing the Management Console
Once WSO2 WSAS 2.1-RC4 is successfully installed, in order to
access the Management Console, first start the server, then launch a web
browser instance and point it to the URL
https://localhost:9443/wso2wsas
(if you are using the default settings). This will take you to the "Sign In"
page of the Management Console seen as below.
Note: By default, WSO2 WSAS has two listeners; HTTP and
HTTPS. The HTTP listener opens on port 9762, while the HTTPS listener opens
on port 9443. The admin functionality is exposed only via HTTPS.
For details on the Management Console see
Administrator's Guide