<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~  Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<html>
<head>
  <title>
      WSO2 ESB - System Administration Guide
  </title>
  <link href="css/esb-docs.css" rel="stylesheet" type="text/css" media="all"/>
  <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>
</head>

<body>
    [ <a href="docs_index.html"> Documentation Index </a> ]
<h1>
  WSO2 Enterprise Service Bus (ESB) System Administration Guide
</h1>
<p>
This is a manual on how to maintain and administrate a WSO2 ESB instance. It explains how various
features of the ESB can be configured using the ESB management console and by modifying the ESB
configuration files. Descriptions are provided on advanced features like Remote/Embedded
registry configuration, adding external libraries, managing key stores and user management. It
also explains how to performance tune the ESB runtime for extreme throughput.
</p>
<h2>Contents</h2>
<p>
  <ul>
    <li><a href="#Intro">Introduction</a></li>
    <li><a href="#DocConv">Document Conventions</a></li>
    <li><a href="#GettingESB">Getting WSO2 ESB</a></li>
    <li><a href="#InstallESB">Installing and Running WSO2 ESB</a>
        <ul>
            <li><a href="#Standalone">Running the ESB in Standalone Mode</a></li>
            <li><a href="#ESBSamples">Running ESB Samples</a></li>
        </ul>
    </li>
    <li><a href="#DirHierarchy">WSO2 ESB Directory Hierarchy</a></li>
    <li><a href="#ESBMan">Using the WSO2 ESB Management Console</a></li>
    <li><a href="#UserMan">User Management</a></li>
        <ul>
            <li><a href="ExStore">Using External User Stores (LDAP/AD)</a></li>
        </ul>
    <li><a href="#SettingLogging">Setting Up Logging</a></li>
    <li><a href="#ConfigureAxis2">Configuring the Underlying Axis2 Engine</a></li>
    <li><a href="#Mediation">Mediation Configuration</a></li>
        <ul>
            <li><a href="#Persistence">Persistence</a></li>
            <li><a href="#DepTracking">Dependency Tracking</a></li>
            <li><a href="#HotDeployment">Hot Deployment of Mediation Artifacts</a></li>
        </ul>
    <li><a href="#P2">Installing and Managing Features</a></li>
    <li><a href="#ExternalDeps">Adding External Dependencies to the System</a></li>
    <li><a href="#Registry">Registry Integration</a></li>
        <ul>
            <li><a href="EmbeddedReg">Using the Embedded Registry</a></li>
            <li><a href="RemoteReg">Using the Remote Registry</a></li>
        </ul>
    <li><a href="#KeyStore">Setting Up Key Stores</a></li>
    <li><a href="#HostPort">Setting Up Host Names and Ports</a></li>
    <li><a href="#PerfTune">Performance Tuning WSO2 ESB</a></li>
  </ul>
</p>

<h2 id="Intro">
  Introduction
</h2>
<p>
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.
</p>
<p>
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 AS. Since ESB is OSGi based some knowledge in
OSGi would be helpful in administrating the WSO2 ESB.
</p>
<p>
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.
</p>

<h2 id="DocConv">Document Conventions</h2>
<ul>
   <li>'ESB_HOME' refers to the directory in the file system where WSO2 ESB is installed</li>
   <li>'ESB_SRC_HOME' refers to the directory in the file system where WSO2 ESB source distribution is installed</li>
   <li>All file paths follow Unix/Linux conventions but they resemble Windows file paths as well</li>
</ul>

<h2 id="GettingESB">Getting WSO2 ESB</h2>
<p>
Binary distributions and source distributions of WSO2 ESB can be downloaded free from the <a href="http://wso2.org/projects/esb">
WSO2 ESB</a> home page in the <a href="http://wso2.org">WSO2 Oxygen Tank</a>. 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.
</p>
<p>
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.
</p>
<p>
If you downloaded a source distribution of the ESB you need to build the source to get the executable
binary. WSO2 ESB uses an <a href="http://maven.apache.org">Apache Maven2</a> 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.
</p>

<h2 id="InstallESB">Installing and Running WSO2 ESB</h2>
<p>
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.
</p>
<h3 id="Standalone">Running WSO2 ESB in Standalone Mode</h3>
<p>
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 very first startup of the ESB can take up a few additional seconds since some first time configuration
procedure is run by the ESB. If the server started up cleanly you should get an output similar to the following
on the console.
</p>
<pre>
  [2010-03-23 10:34:17,594]  INFO - Main Initializing system...
  [2010-03-23 10:34:25,176]  INFO - CarbonCoreActivator Starting WSO2 Carbon...
  [2010-03-23 10:34:25,178]  INFO - CarbonCoreActivator Operating System : Linux 2.6.28-16-generic, amd64
  [2010-03-23 10:34:25,178]  INFO - CarbonCoreActivator Java Home        : /opt/jdk1.6.0_16/jre
  [2010-03-23 10:34:25,178]  INFO - CarbonCoreActivator Java Version     : 1.6.0_16
  [2010-03-23 10:34:25,178]  INFO - CarbonCoreActivator Java VM          : Java HotSpot(TM) 64-Bit Server VM 14.2-b01,Sun Microsystems Inc.
  [2010-03-23 10:34:25,178]  INFO - CarbonCoreActivator Carbon Home      : /home/user/wso2esb-3.0.1
  [2010-03-23 10:34:25,179]  INFO - CarbonCoreActivator Java Temp Dir    : /home/user/wso2esb-3.0.1/tmp
  [2010-03-23 10:34:25,179]  INFO - CarbonCoreActivator User             : user, en-US, Asia/Colombo
  [2010-03-23 10:34:29,715]  INFO - RegistryCoreServiceComponent Registry Mode    : READ-WRITE
  [2010-03-23 10:34:32,349]  INFO - CarbonServerManager Starting Carbon initialization...
  [2010-03-23 10:34:32,561]  INFO - ClusterBuilder Clustering has been disabled
  [2010-03-23 10:34:32,742]  INFO - DeploymentInterceptor Deploying Axis2 module : relay-3.0
  [2010-03-23 10:34:32,799]  INFO - DeploymentInterceptor Deploying Axis2 module : wso2mex-3.0
  [2010-03-23 10:34:32,818]  INFO - DeploymentInterceptor Deploying Axis2 module : rampart-SNAPSHOT
  [2010-03-23 10:34:32,862]  INFO - DeploymentInterceptor Deploying Axis2 module : sandesha2-3.0
  [2010-03-23 10:34:32,916]  INFO - DeploymentInterceptor Deploying Axis2 module : wso2caching-3.0
  [2010-03-23 10:34:32,989]  INFO - DeploymentInterceptor Deploying Axis2 module : wso2xfer-3.0
  [2010-03-23 10:34:33,001]  INFO - DeploymentInterceptor Deploying Axis2 module : rahas-SNAPSHOT
  [2010-03-23 10:34:33,019]  INFO - DeploymentInterceptor Deploying Axis2 module : savan-SNAPSHOT
  [2010-03-23 10:34:33,034]  INFO - DeploymentInterceptor Deploying Axis2 module : wso2throttle-3.0
  [2010-03-23 10:34:33,125]  INFO - DeploymentInterceptor Deploying Axis2 module : addressing-1.6-wso2v1
  [2010-03-23 10:34:33,202]  INFO - HttpCoreNIOSSLSender Loading Identity Keystore from : resources/security/wso2carbon.jks
  [2010-03-23 10:34:33,228]  INFO - HttpCoreNIOSSLSender Loading Trust Keystore from : resources/security/client-truststore.jks
  [2010-03-23 10:34:33,256]  INFO - HttpCoreNIOSender HTTPS Sender starting
  [2010-03-23 10:34:33,269]  INFO - HttpCoreNIOSender HTTP Sender starting
  [2010-03-23 10:34:33,370]  INFO - DeploymentInterceptor Deploying Axis2 service : echo
  [2010-03-23 10:34:33,899]  INFO - DeploymentInterceptor Deploying Axis2 service : version
  [2010-03-23 10:34:37,698]  INFO - DeploymentInterceptor Deploying Axis2 service : wso2carbon-sts
  [2010-03-23 10:34:38,273]  INFO - DeploymentInterceptor Deploying Axis2 service : XKMS
  [2010-03-23 10:34:38,480]  INFO - CarbonServerManager Repository       : /home/user/wso2esb-3.0.1/repository/deployment/server/
  [2010-03-23 10:34:38,506]  INFO - EmbeddedRegistryBasedSubscriptionManager Connection established with the registry
  [2010-03-23 10:34:38,530]  INFO - ServiceBusInitializer Starting ESB...
  [2010-03-23 10:34:38,573]  INFO - ServiceBusInitializer Initializing Apache Synapse...
  [2010-03-23 10:34:38,580]  INFO - SynapseControllerFactory Using Synapse home : /home/user/wso2esb-3.0.1/.
  [2010-03-23 10:34:38,580]  INFO - SynapseControllerFactory Using synapse.xml location : /home/user/wso2esb-3.0.1/./repository/conf/synapse-config
  [2010-03-23 10:34:38,580]  INFO - SynapseControllerFactory Using server name : localhost
  [2010-03-23 10:34:38,584]  INFO - SynapseControllerFactory The timeout handler will run every : 15s
  [2010-03-23 10:34:38,634]  INFO - Axis2SynapseController Initializing Synapse at : Tue Mar 23 10:34:38 IST 2010
  [2010-03-23 10:34:38,636]  INFO - Axis2SynapseController Loading mediator extensions...
  [2010-03-23 10:34:38,642]  INFO - CarbonSynapseController Loading the mediation configuration from the file system
  [2010-03-23 10:34:38,645]  INFO - MultiXMLConfigurationBuilder Building synapse configuration from the synapse artifact repository at : ./repository/conf/synapse-config
  [2010-03-23 10:34:38,646]  INFO - XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration
  [2010-03-23 10:34:39,077]  INFO - SynapseConfigurationBuilder Loaded Synapse configuration from the artifact repository at : ./repository/conf/synapse-config
  [2010-03-23 10:34:39,208]  INFO - Axis2SynapseController Deploying the Synapse service...
  [2010-03-23 10:34:39,212]  INFO - Axis2SynapseController Deploying Proxy services...
  [2010-03-23 10:34:39,212]  INFO - Axis2SynapseController Deploying EventSources...
  [2010-03-23 10:34:39,217]  INFO - ServerManager Server ready for processing...
  [2010-03-23 10:34:40,219]  INFO - HttpCoreNIOSSLListener Loading Identity Keystore from : resources/security/wso2carbon.jks
  [2010-03-23 10:34:40,221]  INFO - HttpCoreNIOSSLListener Loading Trust Keystore from : resources/security/client-truststore.jks
  [2010-03-23 10:34:40,237]  INFO - HttpCoreNIOListener HTTPS Listener started on port : 8243
  [2010-03-23 10:34:40,239]  INFO - HttpCoreNIOListener HTTP Listener started on port : 8280
  [2010-03-23 10:34:40,798]  INFO - RegistryEventingServiceComponent Successfully Initialized Eventing on Registry
  [2010-03-23 10:34:43,926]  INFO - CarbonUIServiceComponent Mgt Console URL  : https://10.100.1.209:9443/carbon/
  [2010-03-23 10:34:43,940]  INFO - StartupFinalizerServiceComponent Started Transport Listener Manager
  [2010-03-23 10:34:43,940]  INFO - StartupFinalizerServiceComponent Server           :  WSO2 ESB-3.0.1
  [2010-03-23 10:34:43,940]  INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 25 sec
</pre>
<p>
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.
</p>
<img src="images/login.png"/>
<p>
You can login to the console using the default user credentials given below.
</p>
<ul>
  <li>Username: admin</li>
  <li>Password: admin</li>
</ul>
<p>
If you can get that far then the ESB is properly installed and running.
</p>
<p>
WSO2 ESB startup scripts stated above accept a few useful arguments.
</p>
<p>
--cleanRegistry<br/>
This argument will remove the settings stored in the registry and replace them with factory settings.
It removes the /_system/config/repository collection and the /_system/local/repository collection in the
registry which are used to store resources and configurations managed by the ESB and the underlying
Carbon framework. Therefore the ESB will be forced to start fresh with factory settings. Starting from
WSO2 ESB 3.0 the mediation configuration (sequences, proxies etc) is read from the file system by default.
In that case this argument does not have any effect on the mediation configuration used by the ESB.
</p>
<p>
--debug &lt;port&gt;<br/>
Enables remote debugging on the ESB through the specified port.
</p>
<p>
In addition to the above mentioned arguments the ESB startup scripts accept the following VM arguments.
</p>
<p>
-DosgiConsole<br/>
Starts the OSGi console from which you can directly interact with the underlying OSGi framework.
</p>
<p>
-DloadFromRegistry<br/>
This argument was first introduced in ESB 3.0. When set to 'true' it will force the ESB to load the mediation
configuration from the registry, instead of loading it from the file system. Please note that for this
argument to work the registry must contain a valid mediation configuration stored in it. Therefore one
cannot pass this argument to a fresh ESB instance which is starting from a clean registry. However after the
first startup the registry will contain a mediation configuration and hence subsequent startups can proceed
with this VM parameter.
</p>
<p>
-DwriteToFile<br/>
Newly added to WSO2 ESB 3.0, this argument takes effect only when the mediation configuration is loaded
from the registry. When set to 'true' this parameter will force the ESB to save the configuration loaded
from the registry to the local file system at startup.
</p>

<h3 id="ESBSamples">Running ESB Samples</h3>
<p>
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.
</p>
<p>
eg: ./wso2esb-sample.sh -sn 250 (This will launch the ESB using the Sample 250 configuration)
</p>
<p>
The sample configuration files can be found in the ESB_HOME/repository/samples directory.
</p>
<p>
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.
</p>

<h2 id="DirHierarchy">WSO2 ESB Directory Hierarchy</h2>
<p>
When you extract a WSO2 ESB binary distribution archive you will find the following directories in the
top level directory that is created.
</p>

<p>
bin -<br/>
  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.<br/>
  <br/>
  <ul>
    <li>
      wso2server.sh/wso2server.bat - Launches WSO2 ESB
    </li>
    <li>
      wso2esb-samples.sh/wso2esb-samples.bat - Launches WSO2 ESB using one of the sample configurations
    </li>
    <li>
      wsdl2java.sh/wsdl2java.bat - Launches the Java stub generation tool for Web Services
    </li>
    <li>
      java2wsdl.sh/java2wsdl.bat - Launches the WSDL generation tool for Java Web Services
    </li>
    <li>
      tcpmon.sh/tcpmon.bat - Launches TCPMon, the TCP connection monitor
    </li>
    <li>
      chpasswd.sh/chpasswd.bat -Use this script to change the administrator password without signing in to the server<br/>
    </li>
    <li>
      ciphertool.sh/ciphertool.bat -&lt;TODO: Indika&gt;<br/>
    </li>
    <li>
      daemon.sh -Start WSO2 ESB as a daemon on Unix/Linux systems<br/>
    </li>
    <li>
      install.bat - Install WSO2 ESB as a background service on Windows<br/>
    </li>
    <li>
      repowriter.sh/repowriter.bat
    </li>
    <li>
      carbondump.sh/carbondump.bat - Create a dump file containing runtime information related to the ESB (Dump file is useful in debugging issues)
    </li>
  </ul>
  <br/>
  In addition to the above mentioned scripts you will find a subdirectory named 'native' in the bin
  directory.<br/>
</p>
<p>
dbscripts -<br/>
Contains a collection of database scripts required to create the Carbon database on a variety of database
management systems.<br/>
</p>
<p>
lib -<br/>
The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance.
The log4j.properties file used by the ESB is also stored here. In addition to that, the Carbon webapp
can be found in the lib/core directory. The lib/core/WEB-INF/classes directory houses some of
important configuration files of the ESB such as nhttp.properties, synapse.properties and datasources.properties.
</p>
<p>
repository -<br/>
This directory houses all the OSGi bundles, service artifacts, modules, configurations and related resources
used by the WSO2 ESB instance. The repository/components/plugin 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 lib,
mediators and extensions which can be used to deploy custom mediators and third party dependencies into the ESB.
The repository/conf subdirectory contains all the crucial configuration files such as axis2.xml and carbon.xml. The
mediation configuration is loaded from the repository/deployment/server/synapse-config directory. Also starting from ESB 3.0
server logs are stored in the repository/logs directory.
</p>
<p>
resources -<br/>
Contains additional resources required by WSO2 ESB. This includes security related resources such as
keystores.
</p>
<p>
samples -<br/>
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.
</p>
<p>
tmp -<br/>
The temporary files directory used by the ESB
</p>

<h2 id="ESBMan">Using the WSO2 ESB Management Console</h2>
<p>
WSO2 ESB management console is a Web based control 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.
</p>
<p>
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://&lt;Server Host&gt;:&lt;Server Port&gt;/&lt;Context&gt;. 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.
</p>
<p>
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 explanatory. However if you are having trouble finding your way in the management
console, click on the 'Help' link at the top right corner of any page to access context sensitive help.
</p>
<p>
Please note that the ESB management console makes use of the default HTTPS servlet transport which is
configured in the ESB_HOME/repository/conf/mgt-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.
</p>

<h2 id="UserMan">User Management</h2>
<p>
To access the WSO2 ESB user management features, first sign in to the ESB management console and click on
'User and Roles' 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.
</p>
<img src="images/user-mgt.png"/>
<p>
From here you can manage users and roles. A user is associated with one 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 two roles, the 'admin' role and the 'everyone' role. There is also a third role
named 'system' which is not visible in the management console. Every user will be assigned the
'everyone' role. This role does not have any permissions by default. Users with the 'admin' role have full
access to all the features and controls in the ESB (all permissions). By default the user 'admin' is assigned the
'admin' role along with the 'everyone' role. Also note that the ESB UI does not allow configuing the permissions
assigned to the 'admin' role.
</p>
<p>
The permission model of WSO2 ESB is hierarchical. Therefore permissions
can be assigned in a fine grained manner or a coarse grained manner. For an example one could assign the 'Configure'
admin permission to a role. The role will be able to configure event sources, scheduled tasks and many other things.
This is a coarse grained permission allocation. On the other hand one may assign the specific
'Transport Management', 'Configure Tasks' or 'Configure Data Sources' permission to a role which is a fine grained
permission allocation. The full ESB permission tree looks as follows.
</p>
<img src="images/perm-tree.png"/>
<p>
Use the 'User Management' page in the UI to add new users, add new roles, assign and withdraw permissions from
roles and change login credentials of users. 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.
</p>
<h3 id="ExStore">Using External User Stores (LDAP/AD)</h3>
<p>
You can also connect an external user store (database) with WSO2 ESB. Such external stores are configured through
the user-mgt.xml file which can be found in the repository/conf directory. Settings required to connect an LDAP
based user store or an Active Directory based user store are provided in the default user-mgt.xml file. Simply
uncomment the relevant entries in the file and update the required parameters. Also note that the ESB can have
only one user store at any given moment. Hence when you want to connect to a different user store you also need
to comment out the default user store settings (LDAP user store manager) in the user-mgt.xml file. Configuration
settings for the LDAP based user store looks as follows.
</p>
<pre>
&lt;UserStoreManager class="org.wso2.carbon.user.core.ldap.ApacheDSUserStoreManager"&gt;
    &lt;Property name="ReadOnly"&gt;false&lt;/Property&gt;
    &lt;Property name="ConnectionURL"&gt;ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}&lt;/Property&gt;
    &lt;Property name="ConnectionName"&gt;uid=admin,ou=system&lt;/Property&gt;
    &lt;Property name="ConnectionPassword"&gt;admin&lt;/Property&gt;
    &lt;Property name="passwordHashMethod"&gt;SHA&lt;/Property&gt;
    &lt;Property name="UserNameListFilter"&gt;(objectClass=person)&lt;/Property&gt;
    &lt;Property name="UserEntryObjectClass"&gt;wso2Person&lt;/Property&gt;
    &lt;Property name="UserSearchBase"&gt;ou=Users,dc=wso2,dc=org&lt;/Property&gt;
    &lt;Property name="UserNameSearchFilter"&gt;(&amp;(objectClass=person)(uid=?))&lt;/Property&gt;
    &lt;Property name="UserNameAttribute"&gt;uid&lt;/Property&gt;
    &lt;Property name="PasswordJavaScriptRegEx"&gt;[\\S]{5,30}&lt;/Property&gt;
    &lt;Property name="UsernameJavaScriptRegEx"&gt;[\\S]{3,30}&lt;/Property&gt;
    &lt;Property name="UsernameJavaRegEx"&gt;^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;]{3,30}$&lt;/Property&gt;
    &lt;Property name="RolenameJavaScriptRegEx"&gt;[\\S]{3,30}&lt;/Property&gt;
    &lt;Property name="RolenameJavaRegEx"&gt;^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;]{3,30}$&lt;/Property&gt;
    &lt;Property name="ReadLDAPGroups"&gt;true&lt;/Property&gt;
    &lt;Property name="WriteLDAPGroups"&gt;true&lt;/Property&gt;
    &lt;Property name="EmptyRolesAllowed"&gt;true&lt;/Property&gt;
    &lt;Property name="GroupSearchBase"&gt;ou=Groups,dc=wso2,dc=org&lt;/Property&gt;
    &lt;Property name="GroupNameListFilter"&gt;(objectClass=groupOfNames)&lt;/Property&gt;
    &lt;Property name="GroupEntryObjectClass"&gt;groupOfNames&lt;/Property&gt;
    &lt;Property name="GroupNameSearchFilter"&gt;(&amp;(objectClass=groupOfNames)(cn=?))&lt;/Property&gt;
    &lt;Property name="GroupNameAttribute"&gt;cn&lt;/Property&gt;
    &lt;Property name="MembershipAttribute"&gt;member&lt;/Property&gt;
&lt;/UserStoreManager&gt;
</pre>
<p>
For more information on using external user stores please refer <a href="user-core/admin_guide.html">User Core Admin
Guide</a>.    
</p>

<h2 id="SettingLogging">Setting Up Logging</h2>
<p>
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.
</p>
<p>
By default WSO2 ESB comes with the following log appenders configured.
</p>
<ul>
  <li>
    CARBON_CONSOLE (Logs to the console when the server is running)
  </li>
  <li>
    CARBON_LOGFILE (Writes the logs to ESB_HOME/repository/logs/wso2-esb.log)
  </li>
  <li>
    CARBON_MEMORY
  </li>
  <li>
    CARBON_SYS_LOG
  </li>
  <li>
    SERVICE_APPENDER (Writes mediation time audit messages to ESB_HOME/repository/logs/wso2-esb-service.log)
  </li>
  <li>
    TRACE_APPENDER (Writes mediation time tracing/debug messages to the ESB_HOME/repository/logs/wso2-esb-trace.log for tracing enabled services)
  </li>
  <li>
    TRACE_MEMORYAPPENDER
  </li>
</ul>
<p>
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 page 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.
</p>
<img src="images/logs.png"/>

<h2 id="ConfigureAxis2">Configuring the Underlying Axis2 Engine</h2>
<p>
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/repository/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.
</p>
<ul>
  <li>
    Global system parameters (eg: hotdeployment, hotupdate, servicepath etc)
  </li>
  <li>
    Global Axis2 listeners (Axis2 observer implementations which are notified of Axis2 events)
  </li>
  <li>
    Deployers
  </li>
  <li>
    Message receivers, formatters and builders
  </li>
  <li>
    Transport receivers and senders
  </li>
  <li>
    Globally engaged modules (eg: addressing)
  </li>
  <li>
    Clustering
  </li>
  <li>
    Axis2 phases
  </li>
</ul>
<p>
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.
</p>

<h2 id="Mediation">Mediation Configuration</h2>
<p>
Mediation configuration is the most important part of the WSO2 ESB as far as the functionality of the service
bus is concerned. The mediation configuration consists of following items.
</p>
<ul>
    <li>Endpoints</li>
    <li>Sequences</li>
    <li>Proxy services</li>
    <li>Scheduled tasks</li>
    <li>Event sources</li>
    <li>Local entries</li>
    <li>Priority executors (new in ESB 3.0)</li>
</ul>
<p>
Each of the above items can be configured through the management console. New instances of above items
can be added to the ESB, existing items can be modified or removed. The 'Synapse' entry in the 'Configure'
menu provides a single unified view of the entire mediation configuration and allows the user to make
modifications to it using the Synapse configuration language.
</p>

<h3 id="Persistence">Persistence</h3>
<p>
By default the mediation configuration is stored in the file system as well as in the registry. In the file
system, configuration is saved under the ESB_HOME/repository/conf/synapse-config directory. There are separate
subdirectories to store different types of configuration items. When you add a new item using the management
console it will be saved to a new file under the synapse-config directory. For an example, if you add a new
endpoint named 'foo' from the UI, it will be saved to a file named foo.xml in ESB_HOME/repository/conf/synapse-config/endpoints
directory. Any further modifications to the endpoint foo will be saved back to the same file. However if you
add a new item from the Synapse configuration editor in the UI (in Configure menu) it will be saved to
ESB_HOME/repository/conf/synapse-config/synapse.xml file.     
</p>
<p>
You can customize the behavior of mediation configuration persistence by editing the carbon.xml file. You may
add the following entry to the carbon.xml and tune up the parameter values as appropriate.
</p>
<pre>
&lt;MediationConfig&gt;
    &lt;LoadFromRegistry&gt;false&lt;/LoadFromRegistry&gt;
    &lt;SaveToFile&gt;false&lt;/SaveToFile&gt;
    &lt;Persistence&gt;enabled&lt;/Persistence&gt;
    &lt;RegistryPersistence&gt;enabled&lt;/RegistryPersistence&gt;
&lt;/MediationConfig&gt;
</pre>
<p>
Set the LoadFromRegistry to 'true' if you want to load the mediation configuration from the registry instead of the file
system. SaveToFile option takes effect only when LoadFromRegistry is set to 'true'. If both values are set to 'true'
the mediation configuration will be loaded from the registry and will also be saved to the local file system at
startup. If you want to prevent the ESB from saving the mediation configuration to the registry set RegistryPersistence
to 'disabled'. By default this is enabled. You can turn off all persistence activies by setting Persistence to
'disabled'. In that case mediation configuration will not be saved to the file system nor the registry. The configuration
in the disk/registry is effectively frozen. But the changes made from the UI will still take effect in the runtime. But
such changes will not survive a restart since they are not saved to persistence store.
</p>

<h3 id="DepTracking">Dependency Tracking</h3>
<p>
WSO2 ESB keeps track of the dependencies among various mediation configuration elements. In a typical mediation
configuration there are often dependencies among sequences, endpoints, proxy services and local entires. A
sequence can make references to other sequences, local entries and endpoints. A proxy service may also make references to
sequences and endpoints. The ESB runtime by default keeps track of such dependencies and warns the user, if he
attempts to remove a particular item from the configuration which is a dependency for another item.
</p>
<img src="images/dep-tracking.png"/>
<p>
The dependency tacking process takes up a few CPU cycles and memory to compute and keep track of the
dependencies at runtime. Therefore it is recommended to turn this feature off in production environments.
To turn off dependency tracking open up the synapse.properties file which can be found in the
ESB_HOME/webapps/ROOT/WEB-INF/classes directory and comment out the following line:
</p>
<pre>synapse.observers=org.wso2.carbon.mediation.dependency.mgt.DependencyTracker</pre>
<p>
You also need to restart the ESB for the change to take effect. Commenting out the above entry will disengage
the dependency tracker and hence the ESB will stop computing and keeping track of dependencies among
different configuration items in the mediation configuration.    
</p>

<h3 id="HotDeployment">Hot Deployment of Mediation Artifacts</h3>
<p>
WSO2 ESB 3.0 introduces the hot deployment feature for mediation artifacts. With this feature you can hot
deploy artifacts like endpoints, sequences and proxy services into the ESB_HOME/repository/conf/synapse-config
directory. Simply save the artifact configuration to an XML file and drop it into the relevant subdirectory in
the synapse-config parent directory. ESB will pick up the newly added file and get it deployed in the server
runtime. Once deployed you will be able to view it through the management console and make further changes if
necessary. Similarly you can make changes to an existing file which contains a mediation configuration item
and the ESB will pick the changes up through the hot update feature.
</p>
<p>
In a production system it is recommended to turn off hot deployment and update for smooth operation of the ESB.
To turn off hot deployment and hot update open up the axis2.xml file in repository/conf directory and set the
following two parameter values to 'false'. (These are by default set to 'true')
</p>
<pre>
    &lt;parameter name="hotdeployment" locked="false"&gt;false&lt;/parameter&gt;

    &lt;parameter name="hotupdate" locked="false"&gt;false&lt;/parameter&gt;
</pre>

<h2 id="P2">Installing and Managing Features</h2>
<p>
New features can be easily installed into the ESB by using the 'WSO2 Carbon Component Manager' that comes
with the ESB. Component manager is powered by Equinox P2 and allows you to connect to a remote or local P2
repository and get any feature installed into the ESB runtime. You can also uninstall existing features of
the ESB and come up with a customized version of WSO2 ESB tailored to meet your requirements.
</p>
<p>
To use the component manager, login to the management console and click on 'Features' under the
'Configure' menu. Go to the 'Settings' tab and click on 'Manage Repositories'. Click 'Add New Repository'
and specify the P2 repository to which you wish to connect to. The official WSO2 P2 repository is available
over http://dist.wso2.org/p2.
</p>
<p>
Once the repository is configured go to the 'Available Features' tab to browse through the features and get them
installed to the ESB. The installation of a feature can take a while depending on the network bandwidth and
hardware configuration available. Once a feature has been successfully installed you will be prompted to logout
and restart the ESB.
</p>
<p>
If you wish to uninstall an existing feature go to the 'Installed Features' tab, select the features to be
uninstalled and click on 'Uninstall' at the bottom of the page.
</p>
<img src="images/installed-features.png"/>

<h2 id="ExternalDeps">Adding External Dependencies to the System</h2>
<p>
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.
</p>
<ul>
  <li>
    Enabling and configuring a new transport (Many transport implementations such as JMS and FIX require
    adding a set of external dependencies to the server)
  </li>
  <li>
    Adding a custom mediator
  </li>
  <li>
    Adding a custom handler or a module
  </li>
</ul>
<p>
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.
</p>
<p>
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.
</p>

<h2 id="Registry">Registry Integration</h2>
<p>
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.
</p>
<p>
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.
</p>

<pre>
&lt;registry provider="org.wso2.carbon.mediation.registry.WSO2Registry"&gt;
	&lt;parameter name="cachableDuration"&gt;15000&lt;/parameter&gt;
&lt;/registry&gt;
</pre>

<p>
Starting from ESB 3.0 the registry that comes with WSO2 ESB is actually a combination of 3 registries.
</p>
<ul>
    <li>Local repository (Used to store settings/metadata specific to the ESB node - This registry cannot be shared)</li>
    <li>Configuration registry (Used to store settings/metadata that is shared across a cluster of ESB instances)</li>
    <li>Governance registry (Used to store user specified metadata and resources and can be shared across an organization)</li>
</ul>
<p>
The above registry instances are mounted to a single top level registry to provide a single unified view. Mount points of
the three registries are /_system/local, /_system/config and /_system/governance respectively. One could browse
the contents of the registry 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 under the 'Registry' menu.
</p>
<img src="images/browse-registry.png"/>

<h3 id="EmbeddedReg">Using the Embedded Registry</h3>
<p>
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. 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/repository/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.
</p>
<p>
The embedded registry instance is configured by the registry.xml file which can be found in the ESB_HOME/repository/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.    
</p>
<pre>
&lt;dbconfig name="wso2registry"&gt;
	&lt;url&gt;jdbc:h2:database/WSO2CARBON_DB&lt;/url&gt;
	&lt;userName&gt;wso2carbon&lt;/userName&gt;
	&lt;password&gt;wso2carbon&lt;/password&gt;
	&lt;driverName&gt;org.h2.Driver&lt;/driverName&gt;
	&lt;maxActive&gt;50&lt;/maxActive&gt;
	&lt;maxWait&gt;60000&lt;/maxWait&gt;
	&lt;minIdle&gt;5&lt;/minIdle&gt;
&lt;/dbconfig&gt;
</pre>    
<p>
WSO2 Governance Registry can be run in two operational modes, namely the ReadWrite mode and the ReadOnly mode. By default
it operates in the ReadWrite mode. This mode is set by the following element in the registry.xml file.
</p>
<pre>
&lt;readOnly&gt;false&lt;/readOnly&gt;    
</pre>
<p>
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. Also in a clustered deployment it is recommended that only one ESB instance
accesses the registry in the ReadWrite mode. All other ESB nodes should be accessing the registry in the
ReadOnly mode to prevent different ESB servers from modifying the same resources at the same time. Any
configuration updates should be done via the ESB instancce in ReadWrite mode.    
</p>
<p>
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.
</p>
<pre>
&lt;staticConfiguration&gt;
	&lt;versioningProperties&gt;true&lt;/versioningProperties&gt;
	&lt;versioningComments&gt;true&lt;/versioningComments&gt;
	&lt;versioningTags&gt;true&lt;/versioningTags&gt;
	&lt;versioningRatings&gt;true&lt;/versioningRatings&gt;
&lt;/staticConfiguration&gt;    
</pre>
<p>
Please refer WSO2 G-Reg documentation for further information on setting up media type handlers and other
global parameters.    
</p>

<h3 id="RemoteReg">Using the Remote Registry</h3>
<p>
You can configure the ESB to use a remotely hosted WSO2 Governance Registry instance as the metadata and
configuration store, instead of using the embedded registry instance. For that you need to edit the
ESB_HOME/repository/conf/registry.xml file and modify the database configuration to point to the same
database as the remote registry instance. Edit the dbconfig element in the registry.xml and make sure that
the ESB is pointed to the same database as your WSO2 Governance Registry instance.
</p>

<h2 id="KeyStore">Setting Up Keystores</h2>
<p>
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 axis2.xml file
under the HTTPS transport receiver and HTTPS transport sender configurations.
</p>

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

<p>
The default keystores can be found in ESB_HOME/repository/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 &lt;KeyStore&gt;
element two password values must be specified. The &lt;Password&gt; element should indicate the password of
the keystore file. The &lt;KeyPassword&gt; elemenet should point to the password required to access the private key.
</p>
<p>
The keystore used to encrypt administrator passwords and other confidential information in Carbon is configured in
ESB_HOME/repository/conf/carbon.xml file. This keystore configuration can be found under the &lt;security&gt;
element of the carbon.xml file. By default this is also used by the security management component when it
comes to securing deployed Web Services with WS-Security.
</p>

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

<h2 id="HostPort">Setting Up Host Names and Ports</h2>
<p>
The bind address values and HTTP/HTTPS ports used by the ESB server should be configured in the
ESB_HOME/repository/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 axis2.xml file.
</p>

<pre>
&lt;parameter name="bind-address" locked="false"&gt;hostname or IP address&lt;/parameter&gt;
</pre>

<p>
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.
</p>

<pre>
&lt;parameter name="port" locked="false"&gt;8280&lt;/parameter&gt;
</pre>

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

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

<p>
To change the ports used by the ESB management console you must modify the ESB_HOME/repository/conf/mgt-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.
</p>

<pre>
&lt;parameter name="port"&gt;9443&lt;/parameter&gt;
</pre>

<p>
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.
</p>

<pre>
&lt;parameter name="WSDLEPRPrefix" locked="false"&gt;https://apachehost:port/somepath&lt;/parameter&gt;
</pre>

<p>
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.
</p>

<pre>
&lt;parameter name="proxyPort"&gt;80&lt;/parameter&gt;
</pre>

<p>
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.
</p>

<h2 id="PerfTune">Performance Tuning WSO2 ESB</h2>
<p>
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.
</p>
<p>
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.
</p>

<pre>
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
</pre>

<p>
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.
</p>
<p>
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.
</p>

<pre>
* soft nofile 4096
* hard nofile 65535
</pre>

<p>
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/lib/core/WEB-INF/classes 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.
</p>

<pre>
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
</pre>

<p>
When the nhttp.properties file is not provided a set of default values 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.
</p>
</body>
</html>