WSO2 ESB - System Administration Guide [ Documentation Index ]

WSO2 Enterprise Service Bus (ESB) System Administration Guide

This is a manual on how to administrate and configure the WSO2 ESB through the management console. Descriptions on advanced configurations like Remote/Embedded Registry configuration, adding external libraries, Key store & User management. Briefly describes the performance tunning the ESB as well.

Contents

Introduction

WSO2 ESB is a production grade open source ESB solution based on the lightweight Apache Synapse ESB. WSO2 ESB supports service mediation, message mediation, load balancing, clustering and many more enterprise integration techniques out of the box. It also supports a range of application and transport level protocols such as HTTP, JMS, Mail, VFS, FIX and a variety of industrial messaging standards such as Hessian.

Starting from version 2.0, WSO2 ESB is based on the revolutionary WSO2 Carbon framework. WSO2 Carbon is an OSGi based middleware framework for SOA. Currently all WSO2 Java products are based on WSO2 Carbon including WSO2 Governance Registry and WSO2 WSAS. Since ESB is OSGi based some knowledge in OSGi would be helpful in administrating the WSO2 ESB.

This document explains how to get WSO2 ESB and install it on a server. The latter sections of the document illustrates how to setup and configure various features of the WSO2 ESB and how to performance tune various aspects of the product.

Document Conventions

Getting WSO2 ESB

Binary distributions and source distributions of WSO2 ESB can be downloaded free from the WSO2 ESB project home page in the WSO2 Oxygen Tank. Before proceeding to the downloads page you will be asked to register on the WSO2 Oxygen Tank. Registration is free and optional however it is recommended that you sign up for an account right away since registered Oxygen Tank users get exclusive access to our support forums and tons of valuable content related to SOA and Web Services.

Once you are on the downloads page click on the relevant links to download a binary distribution or a source distribution of the latest stable release of the WSO2 ESB. If you are interested in an older version of the ESB, scroll down in the downloads page to locate the links to previous releases. You will also find links to download developer releases and nightly builds of the WSO2 ESB on the same page. We recommend that you always download the latest stable release. If you want to try out a feature that was added very recently you can try out a nightly build.

If you downloaded a source distribution of the ESB you need to build the source to get the executable binary. WSO2 ESB uses an Apache Maven2 based build system and therefore you need to first download and install Apache Maven2. Please refer Maven2 documentation on installing and configuring Apache Maven2. Also note that Apache Maven2 requires Java to run. Once Maven2 is properly configured extract the downloaded source distribution and change your working directory to the directory that is created. Then execute the command mvn clean install to run the builder. Once the build process is complete you can find the binary distribution archive in ESB_SRC_HOME/modules/distribution/target directory.

Installing and Running WSO2 ESB

To install the WSO2 ESB simply extract the downloaded binary distribution archive. If you built WSO2 ESB from source extract the archive created by the builder. We recommend installing WSO2 ESB on a Unix/Linux system since that will enable you to get the maximum out of the ESB. In order to be able to start WSO2 ESB you first need Java 5 or higher. Having installed Java on your system please set the JAVA_HOME environment variable to point to the directory in which Java is installed.

Running WSO2 ESB in Standalone Mode

Now you are all set to start WSO2 ESB in the standalone mode. Go to ESB_HOME/bin directory and if you are on Unix/Linux execute the wso2server.sh shell script or if you are on Windows execute the wso2server.bat batch file. This will start the ESB and you can see the progress of the startup procedure on the console. Please note that server startup may take some time depending on the hardware configuration of your system. The first time startup can take up few additional seconds since some first time configuration logic is run by the ESB. If the server started up cleanly you should get an output similar to the following on the console.

  [2009-06-25 13:52:54,700] INFO - CarbonCoreActivator Starting WSO2 Carbon...
  [2009-06-25 13:52:54,714] INFO - CarbonCoreActivator Operating System : Linux 2.6.28-11-generic, i386
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Home : /opt/jdk1.5.0_19/jre
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Version : 1.5.0_19
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java VM : Java HotSpot(TM) Server VM 1.5.0_19-b02,Sun Microsystems Inc.
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Carbon Home : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.1.SNAPSHOT
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Temp Dir : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.1.SNAPSHOT/tmp
  [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator User : hiranya, en-US, Asia/Colombo
  [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Root : /
  [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Mode : READ-WRITE
  [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Type : embedded
  [2009-06-25 13:53:06,956] INFO - CarbonServerManager Starting Carbon initialization...
  [2009-06-25 13:53:07,300] INFO - ClusterBuilder Clustering has been disabled
  [2009-06-25 13:53:07,952] INFO - HttpCoreNIOSSLSender Loading Identity Keystore from : resources/security/wso2carbon.jks
  [2009-06-25 13:53:08,215] INFO - HttpCoreNIOSSLSender Loading Trust Keystore from : resources/security/client-truststore.jks
  [2009-06-25 13:53:08,451] INFO - HttpCoreNIOSender HTTPS Sender starting
  [2009-06-25 13:53:08,458] INFO - HttpCoreNIOSender HTTP Sender starting
  [2009-06-25 13:53:14,632] INFO - CarbonServerManager Initializing transport descriptions and their associated parameters
  [2009-06-25 13:53:14,653] INFO - CarbonServerManager Repository : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.1.SNAPSHOT/repository/
  [2009-06-25 13:53:14,684] INFO - ServiceBusInitializer Starting ESB...
  [2009-06-25 13:53:14,726] INFO - ServiceBusInitializer Initializing Apache Synapse...
  [2009-06-25 13:53:14,733] INFO - SynapseControllerFactory Using Synapse home : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.1.SNAPSHOT/
  [2009-06-25 13:53:14,734] INFO - SynapseControllerFactory Using synapse.xml location : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.1.SNAPSHOT/./conf/synapse.xml
  [2009-06-25 13:53:14,734] INFO - SynapseControllerFactory Using server name : WSO2 ESB Server
  [2009-06-25 13:53:14,767] INFO - SynapseControllerFactory The timeout handler will run every : 15s
  [2009-06-25 13:53:14,812] INFO - Axis2SynapseController Initializing Synapse at : Thu Jun 25 13:53:14 IST 2009
  [2009-06-25 13:53:14,814] INFO - Axis2SynapseController Loading mediator extensions...
  [2009-06-25 13:53:14,817] INFO - CarbonSynapseController Building the SynapseConfiguration
  [2009-06-25 13:53:14,985] INFO - Axis2SynapseController Deploying the Synapse service...
  [2009-06-25 13:53:15,055] INFO - Axis2SynapseController Deploying Proxy services...
  [2009-06-25 13:53:15,055] INFO - Axis2SynapseController Deploying EventSources...
  [2009-06-25 13:53:15,059] INFO - ServerManager Server ready for processing...
  [2009-06-25 13:53:15,627] INFO - HttpCoreNIOSSLListener Loading Identity Keystore from : resources/security/wso2carbon.jks
  [2009-06-25 13:53:15,631] INFO - HttpCoreNIOSSLListener Loading Trust Keystore from : resources/security/client-truststore.jks
  [2009-06-25 13:53:15,647] INFO - HttpCoreNIOListener HTTPS Listener started on port : 8243
  [2009-06-25 13:53:15,649] INFO - HttpCoreNIOListener HTTP Listener started on port : 8280
  [2009-06-25 13:53:16,498] INFO - EmbeddedRegistryBasedSubscriptionManager Connection established with the registry
  [2009-06-25 13:53:18,263] INFO - RegistryEventingServiceComponent Successfully Initialized Eventing on Registry
  [2009-06-25 13:53:18,263] INFO - StartupFinalizerServiceComponent Started Transport Listener Manager
  [2009-06-25 13:53:18,264] INFO - StartupFinalizerServiceComponent Server WSO2 ESB-2.0
  [2009-06-25 13:53:18,264] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 37 sec

To verify that the ESB is up and running fire off your Web browser and go to https://localhost:9443/carbon. This will take you to the WSO2 ESB on-line management console.

You can login to the console using the default user credentials given below.

If you can get that far then the ESB is properly installed and running.

WSO2 ESB startup scripts stated above accept a few useful arguments.

--cleanCache
This argument forces any cached jar files, configuration files, JSP pages to be cleaned before starting the ESB.

--cleanRegistry
This argument forces the embedded Registry instance to be cleaned before starting the ESB. Note that this will clean the internal database therefore any configurations you saved previously will be permanently lost.

--reset
This argument cleans the cache as well as the registry. The ESB will startup with factory settings.

-debug <port>
Enables remote debugging on the ESB through the specified port.

In addition to the above mentioned arguments the ESB startup scripts accept the following VM arguments.

-DosgiConsole
Starts the OSGi console from which you can directly interact with the underlying OSGi runtime.

-DuseSynapseXML
Generally ESB will load the configuration from the Registry. Using this argument we can force the ESB to load the configuration from ESB_HOME/conf/synapse.xml file.

Running ESB Samples

WSO2 ESB ships with a large number of sample configurations which enables you to get familiar with the product quickly and easily. Please refer the WSO2 ESB samples guide for sample configuration and details on how to run them. You may start WSO2 ESB using those sample configuration by executing the ESB_HOME/bin/wso2esb-sample.sh (for Unix/Linux) or ESB_HOME/bin/wso2esb-sample.bat (for Windows). These launcher scripts take a mandatory argument -sn. Use this argument to specify the sample number.

eg: ./wso2esb-sample.sh -sn 250 (This will launch the ESB using the Sample 250 configuration

The sample configuration files can be found in the ESB_HOME/repository/samples directory.

When launching the ESB using the wso2esb-sample.sh/wso2esb-sample.bat scripts a new registry context root will be created for storing data and configurations related to that sample. Also note that these launcher scripts accept the same set of arguments accepted by the wso2server.sh and wso2server.bat.

WSO2 ESB Directory Hierarchy

When you extract a WSO2 ESB binary distribution archive you will find the following directories in the top level that is created.

bin -
Contains all the necessary scripts to interact with the WSO2 ESB instance. There are shell scripts (with .sh extension) for Unix/Linux users and batch files (with .bat extension) for Windows users. In general you will find the following scripts in this directory.


In addition to the above mentioned scripts you will find a subdirectory named 'native' in the bin directory.

database -
This directory contains the embedded H2 database used by WSO2 ESB and all the associated log files. The database is setup during the first startup of the ESB. This is the database instance used by the embedded registry and the user manager. If you are running the ESB against the embedded registry you should be extra careful not to modify or remove any of the files stored in this directory.

repository -
This directory houses all the OSGi bundles, service artifacts, modules, sample configurations and related resources used by the WSO2 ESB instance. The repository/components directory will contain all the necessary OSGi bundles at server runtime. In the components subdirectory you can also find a set of child directories such as mediators and extensions which can be used to deploy custom mediators and third party dependencies into the ESB.

samples -
The samples directory contains the sample Axis2 server, sample Axis2 client, source code of the sample services and clients and the ANT scripts required to build and run them.

conf -
All the global configuration files (eg: axis2.xml, transports.xml, carbon.xml) used by the ESB are stored in this directory.

lib -
The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance. Starting from Carbon 2.0 the log4j.properties file used by the ESB is also stored here.

resources -
Contains additional resources required by WSO2 ESB. This includes security related resources such as keystores.

logs -
All the server logs created during server runtime will be stored here.

dbscripts -
Contains a collection of database scripts required to create the Carbon database on a variety of database management systems.

Using the WSO2 ESB Management Console

WSO2 ESB management console is a Web based constrol panel powered by JSP and AJAX which enables system administrators to interact with a running ESB instance, without having to touch any underlying configuration files. The management console allows the users to command and control proxy services, sequences, transports, local entries, registry, modules, endpoints and much more. ESB management console is a great way to try things out without having to edit the actual configuration files or without having to restart the ESB for changes to take effect.

We recommend using Mozilla Firefox 3 or Internet Explorer 7 to access the WSO2 ESB management console. Please note that your browser must be JavaScript enabled to take the full advantage of the management console. To access the ESB management console fire off you Web browser and navigate to https://<Server Host>:<Server Port>/<Context>. If you are running the Web browser on the same machine as the ESB you may use 'localhost' as the server host. The default port and the context for the ESB management console are '9443' and 'carbon' respectively. If you entered the URL correctly you will be taken to the management console's login page.

On the login page enter 'admin' as the username and the password to login to the system. You can change user credentials and even add new users once you login. Controls and wizards in the ESB management console are pretty much self explainatory. However if you are having trouble finsing your way in the management console, click on the 'Help' link at the top right corner of any page to access context sensitive help.

Please note that the ESB management console makes use of the default HTTPS servlet transport which is configured in the ESB_HOME/conf/transports.xml file. It is important that this transport is always properly configured in the mentioned file. Otherwise the management console might be inaccessible to the users.

User Management

To access the WSO2 ESB user management features, first sign in to the ESB management console and click on 'User Management' under the 'Configure' menu in the left navigation bar. This will take you to the User Management home page which contains the controls illustrated below.

From here you can manage users and roles. A user is associated with zero or more roles (generally specified at user creation time) and each role is associated with zero or more permissions (generally specified at role creation time). Therefore the set of permissions owned by a user is determined by the roles assigned to that user. A user owns the union of all the permissions associated with the roles assigned to that user. By default ESB comes with only one role, the 'admin' role. This role is associated with the following set of permissions. (In fact all the ESB related permissions are listed here, meaning that users with admin role gets all the permissions over the system)

By default the admin user is associated with the admin role and hence the admin user is entitiled to all the above permissions.

To add a new role to the system click on 'Roles' in the User Management home page and on the page that appears click the 'Add New Role' link. This will start the 'Add Role' wizard. The wizard will guide you though the process of creating a role by specifying a unique name for the role and adding the relevant permissions to the new role. Similarly to create a new user, click on 'Users' in the User Management home page. Then from the next page that appears select 'Create New User' link. This will launch the 'Add User' wizard which will enable you to create a new user account with login credentials and associate the account with one or more existing roles. The ESB management console also enables you to search for and modify existing users and roles.

WSO2 ESB can be easily configured to use an external user store in addition to the buiilt-in system user store. An external user store is an external database which stores user data. It could be as simple as a relational database or as sophiticated as an LDAP instance. Most organizations maintain such centralized databases and it would be productive from the organization's point of view to have the ESB pick up user data from the existing centralized user database. To connect the ESB to an external user store simply click on the 'Add External User Store' link on the User Management home page. Then on the page that appears select the type of user store that will be plugged into the ESB. Currently the following types of user stores are supported.

Having selected the type of the user store you need to provide additional information required by the ESB to connect to and retrieve user data from the external user store. If all the required parameters were specified accurately the ESB will pick up user data from the external user store and users registered on the external store will be able to access the ESB as if their accounts were created in the built-in system user store.

Setting Up Logging

Logging is one of the most important aspects of a production grade server. A properly configured logging system is vital in identifying errors, security threats and usage patterns. WSO2 ESB uses a log4j based logging mechanism through Apache Commons Logging facade library. The log4j.properties file which governs how logging is performed by the server can be found in ESB_HOME/lib directory. However it is recommended not to make any alterations to the default log4j.properties file. The recommended way of setting up logging is by using the ESB management console. Simply login to the management console and click on 'Logging' under the 'Configure' menu in the left navigation bar. From here you can setup various appenders and configure log levels for various loggers. Any changes to the logging configuration you make from the management console will get priority over what is defined in the actual log4j.properties file.

By default WSO2 ESB comes with the following log appenders configured.

Tracing can be enabled for individual mediation sequences and proxy services from the 'Mediation Sequences' home page and the 'Service Dashboard' page respectively. Click on the 'Sequences' link under 'Mediation' in the 'Manage' menu of the left navigation bar to access the 'Mediation Sequences' page. This oage lists all the deployed sequences. Each sequence gives you the options to enable/disable tracing. To access the service dashboard for a proxy service go to the Services List page and click on the proxy service that you are interested in. Once a sequence or a proxy service is tracing enabled you can view the generated log messages by visiting the 'Mediation Tracer' page under the 'Monitor' menu. The 'Monitor' menu also gives you access to the system logs and the SOAP tracer logs all through the Web interface itself.

Configuring the Underlying Axis2 Engine

WSO2 ESB is based on Apache Synapse lightweight ESB which in turns uses the Apache Axis2 SOAP engine. Every WSO2 ESB administrator is expected to have at least a basic understanding of Axis2 and Axis2 configuration model. The global configuration of the Axis2 engine is specified in a file named axis2.xml. This configuration file can be found in the ESB_HOME/conf directory. Any settings configured in the axis2.xml file are directly applied to the server at startup time. Generally, one can configure the following settings in the axis2.xml file.

The axis2.xml file which comes with WSO2 ESB contains examples and descriptions illustrating how the above can be configured and setup for common deployment scenarios.

Adding External Dependencies to the System

You would want to deploy external dependency jars into the WSO2 ESB server in many scenarios. Generally one would want to add external dependencies in following situations.

To add an external dependency to the WSO2 ESB you simply need to copy the necessary jar file(s) to ESB_HOME/repository/components/lib or ESB_HOME/repository/components/extensions. Jars copied to these directories will be automatically converted into OSGi bundles on ESB startup. Jars copied to ESB_HOME/repository/components/extensions will be converted into OSGi bundles which are fragments of the main system bundle. WSO2 ESB also provides the ESB_HOME/repository/components/mediators directory to deploy custom mediators into the ESB.

Currently WSO2 ESB does not support deploying external dependencies at runtime. Therefore after copying the external dependency jars to the relevant locations the server must be restarted for the server to be able to pick them up.

Registry Integration

WSO2 ESB makes use of a WSO2 Governance Registry instance to store various configurations and artifacts such as proxy services, sequences and endpoints. Simply put a registry is a content store and a metadata repository. Various SOA artifacts such as services, WSDLs and configuration files can be stored in a registry keyed by unique paths. A path is similar to a Unix file path. In WSO2 ESB all configurations pertaining to modules, logging, security, data sources and other service groups are stored in the registry by default. Starting from WSO2 Carbon 2.0 all the transport configurations are also stored in the registry. WSO2 ESB 2.1 introduced a feature to directly store endpoints and sequences to the registry with a user specified key value.

WSO2 ESB accesses the registry in two ways. In many cases it accesses the registry by directly calling the registry API from Carbon components. In some special situations it gains access to the registry through the underlying Apache Synapse configuration. It is important that Synapse configuration should always include a registry definition. That is the ESB configuration should include the following registry definition.

<syn:registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
	<syn:parameter name="cachableDuration">15000</syn:parameter>
</syn:registry>

One could browse the contents of the registry instance used by the ESB from the WSO2 ESB management console. To browse the registry, first login to the ESB management console and click on 'Registry Browser' link on the 'Registry' menu in the left navigation bar.

Using the Embedded Registry

WSO2 ESB comes with an embedded WSO2 Governance Registry (WSO2 G-Reg) which is used by the ESB to store configurations and other deployment artifacts. This is configured in the ESB_HOME/conf/carbon.xml as follows.

<Registry>
	<ReadOnly>false</ReadOnly>
	<Type>embedded</Type>
	<SystemUserName>carbon</SystemUserName>
</Registry>

When the registry ReadOnly mode is set to true the ESB will not be able to store resources or write values to the registry. It will be capable of reading the existing resources only. If you want to make sure that the ESB or any of the ESB administrators do not alter the resources already stored in the registry this value should be set to true.

The embedded registry instance makes use of the embedded ESB database. This is an H2 database and the data files are by default stored in the directory named ESB_HOME/database. If you are running the ESB in the embedded registry mode you should be careful not to manually alter any files stored in this directory as that might lead to database corruption or data loss. However in ceretain cases you would want to clean the embedded database and start fresh. In such situations you could pass the --cleanRegistry argument to ESB startup script.

The embedded registry instance is configured by the registry.xml file which can be found in the ESB_HOME/conf directory. In this configuration you could point the embedded registry to a database other than the default embedded H2 database. To change the database used by the registry or change the location of the database files edit the following section of the registry.xml.

<dbconfig name="wso2registry">
	<url>jdbc:h2:database/WSO2CARBON_DB</url>
	<userName>wso2carbon</userName>
	<password>wso2carbon</password>
	<driverName>org.h2.Driver</driverName>
	<maxActive>50</maxActive>
	<maxWait>60000</maxWait>
	<minIdle>5</minIdle>
</dbconfig>

In addition to configuring the database instance you can configure media type handlers for various media types and setup various registry related system parameters by modifying the registry.xml file. The default configuration defines the following parameters.

<staticConfiguration>
	<versioningProperties>true</versioningProperties>
	<versioningComments>true</versioningComments>
	<versioningTags>true</versioningTags>
	<versioningRatings>true</versioningRatings>
</staticConfiguration>

Please refer WSO2 G-Reg documentation for further information on setting up media type handlers and other global parameters.

Using the Remote Registry

You can get the WSO2 ESB to run against a remotely hosted WSO2 G-Reg instance easily. This is very important and useful in production deployment scenarios. Using this technique one can run several WSO2 ESB instances against the same registry thus effectively sharing the configurations and other resources across all the ESB instances. Also with a remote registry based deployment it is easy to change the environment and the configuration in which the WSO2 ESB runs. In remote registry mode, changing the configuration (say from test configuration to production configuration) is as simple as pointing the ESB to a different G-Reg instance.

To setup the ESB against a remote WSO2 G-Reg instance simply modify the 'Registry' section of the ESB_HOME/conf/carbon.xml file. You should specify the registry type as 'remote' and state the registry URL, chroot and login credentials.

<Registry>
	<ReadOnly>false</ReadOnly>
	<Type>remote</Type>
	<SystemUserName>carbon</SystemUserName>
	<Url>http://remote-ip:port/registry/</Url>
	<Chroot>/prefix</Chroot>
	<Username>username</Username>
	<Password>password</Password>
</Registry>

Setting Up Keystores

WSO2 ESB uses several keystores to power the HTTPS transport and encrypt other confidential information such as administrator passwords. The keystore of the HTTPS transport is configured in the ESB_HOME/conf/axis2.xml file under the HTTPS transport receiver and HTTPS transport sender configurations.

<parameter name="keystore" locked="false">
	<KeyStore>
		<Location>resources/security/wso2carbon.jks</Location>
		<Type>JKS</Type>
		<Password>wso2carbon</Password>
		<KeyPassword>wso2carbon</KeyPassword>
	</KeyStore>
</parameter>
<parameter name="truststore" locked="false">
	<TrustStore>
		<Location>resources/security/client-truststore.jks</Location>
		<Type>JKS</Type>
		<Password>wso2carbon</Password>
	</TrustStore>
</parameter>

The default keystores can be found in ESB_HOME/resources/security directory. To change the keystores used by the HTTPS transport update the HTTPS transport receiver and sender configurations by specifying the paths to keystore files and other attributes of the files such as the keystore passwords. Under the <KeyStore> element two password values must be specified. The <Password> element should indicate the password of the keystore file. The <KeyPassword> elemenet should point to the password required to access the private key.

The keystore used to encrypt administrator passwords and other confidential information in Carbon is configured in ESB_HOME/conf/carbon.xml file. This keystore configuration can be found under the <security> element of the carbon.xml file.

<KeyStore>
	<Location>${carbon.home}/resources/security/wso2carbon.jks</Location>
	<Type>JKS</Type>
	<Password>wso2carbon</Password>
	<KeyAlias>wso2carbon</KeyAlias>
	<KeyPassword>wso2carbon</KeyPassword>
</KeyStore>

Setting Up Host Names and Ports

The bind address values and HTTP/HTTPS ports used by the ESB server should be configured in the ESB_HOME/conf/axis2.xml file. To configure the bind address for the server, define the following parameter under the HTTP and HTTPS transport receiver configurations in the ESB_HOME/conf/axis2.xml file.

<parameter name="bind-address" locked="false">hostname or IP address</parameter>

Similarly the HTTP and HTTPS ports used by the ESB HTTP-NIO transport should be configured by specifying the following parameter in the HTTP/HTTPS transport receiver configurations in the axis2.xml file.

<parameter name="port" locked="false">8280</parameter>

The following sample HTTP configuration shows how to listen on HTTP port 8280 bound to the hostname my.test.server.com

<transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">
	<parameter name="port" locked="false">8280</parameter>
	<parameter name="non-blocking" locked="false">true</parameter>
	<parameter name="bind-address" locked="false">my.test.server.com</parameter>
</transportReceiver>

To change the ports used by the ESB management console you must modify the ESB_HOME/conf/transports.xml. By default the management console would accept HTTPS requests on port 9443. Change the following parameter to set the HTTPS port used by the console.

<parameter name="port">9443</parameter>

In situations where a bind address is specifically defined in the axis2.xml it is recommended to define a WSDL prefix for the HTTP and HTTPS transports. The WSDL prefix value will be added to all the HTTP/HTTPS endpoints defined in the auto generated and user published WSDLs. To setup a WSDL prefix define the following parameter under the HTTP and HTTPS receiver configurations in the axis2.xml file.

<parameter name="WSDLEPRPrefix" locked="false">https://apachehost:port/somepath</parameter>

WSO2 ESB also allows you to setup a HTTP proxy port to deploy the ESB behind a proxy server using Apache mod_proxy. In such deployments you need to specify the HTTP proxy port in the axis2.xml file's HTTP/HTTPS receiver configurations using the following parameter.

<parameter name="proxyPort">80</parameter>

Please refer the WSO2 Carbon Transports Catalog for more information on setting up HTTP and HTTPS NIO transports and the servlet HTTPS transport for various deployments.

Performance Tuning WSO2 ESB

We recommend that you install WSO2 ESB on Unix/Linux systems for production deployments. This section, for the most part, assumes that you have setup the ESB on a server running Unix/Linux. Also keep in mind that you should not take performance tuning steps described here lightly. Performance tuning requires you to modify some important system files which would effect all the programs running on the server. Hence care must be applied and please refer Unix/Linux documentation for more details on the configuration files described here.

To optimize the network performance and OS performance for the ESB you will have to modify the /etc/sysctl.conf file. We recommend specifying the following entries in this file.

net.ipv4.tcp_fin_timeout = 30
fs.file-max = 2097152
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1
net.core.rmem_default = 524288
net.core.wmem_default = 524288
net.core.rmem_max = 67108864
net.core.wmem_max = 67108864
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

These settings specify a larger port range, a more effective TCP connection timeout value and a number of other important parameters at the system level.

Also you may specify the following entries in the /etc/security/limits.conf file to alter the number of allowed open files for system users.

* soft nofile 4096
* hard nofile 65535

You can tune up the HTTP-NIO transport performance by creating a nhhtp.properties file for the ESB. This configuration file should be placed in the ESB_HOME/conf directory. You can change the socket timeout values, connection timeout values and HTTP receiver thread pool parameters by specifying them in the nhttp.properties file. A sample set of values that can be included in the nhttp.properties file is specified below.

http.socket.timeout=60000
http.socket.buffer-size=8192
http.tcp.nodelay=1
http.connection.stalecheck=0

# HTTP Sender thread pool parameters
snd_t_core=20
snd_t_max=100
snd_alive_sec=5
snd_qlen=-1
snd_io_threads=2

# HTTP Listener thread pool parameters
lst_t_core=20
lst_t_max=100
lst_alive_sec=5
lst_qlen=-1
lst_io_threads=2

When the nhttp.properties file is not providedd a set of default valules will be used to initialize the thread pool of the HTTP-NIO transports. However the default values (mentioned in the above example) are suitable for most deployments and it is recommended to leave them unchanged without overriding the values using a nhttp.properties configuration file.