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.
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 AS. 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.
Binary distributions and source distributions of WSO2 ESB can be downloaded free from the WSO2 ESB 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.
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.
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.
[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
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.
--cleanRegistry
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.
--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 framework.
-DloadFromRegistry
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.
-DwriteToFile
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.
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.
When you extract a WSO2 ESB binary distribution archive you will find the following directories in the top level directory 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.
dbscripts -
Contains a collection of database scripts required to create the Carbon database on a variety of database
management systems.
lib -
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.
repository -
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.
resources -
Contains additional resources required by WSO2 ESB. This includes security related resources such as
keystores.
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.
tmp -
The temporary files directory used by the ESB
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.
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 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.
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.
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.
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.
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.
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.
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.
<UserStoreManager class="org.wso2.carbon.user.core.ldap.ApacheDSUserStoreManager">
<Property name="ReadOnly">false</Property>
<Property name="ConnectionURL">ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}</Property>
<Property name="ConnectionName">uid=admin,ou=system</Property>
<Property name="ConnectionPassword">admin</Property>
<Property name="passwordHashMethod">SHA</Property>
<Property name="UserNameListFilter">(objectClass=person)</Property>
<Property name="UserEntryObjectClass">wso2Person</Property>
<Property name="UserSearchBase">ou=Users,dc=wso2,dc=org</Property>
<Property name="UserNameSearchFilter">(&(objectClass=person)(uid=?))</Property>
<Property name="UserNameAttribute">uid</Property>
<Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property name="UsernameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>]{3,30}$</Property>
<Property name="ReadLDAPGroups">true</Property>
<Property name="WriteLDAPGroups">true</Property>
<Property name="EmptyRolesAllowed">true</Property>
<Property name="GroupSearchBase">ou=Groups,dc=wso2,dc=org</Property>
<Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupEntryObjectClass">groupOfNames</Property>
<Property name="GroupNameSearchFilter">(&(objectClass=groupOfNames)(cn=?))</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>
</UserStoreManager>
For more information on using external user stores please refer User Core Admin Guide.
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 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.
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.
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.
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.
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.
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.
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.
<MediationConfig>
<LoadFromRegistry>false</LoadFromRegistry>
<SaveToFile>false</SaveToFile>
<Persistence>enabled</Persistence>
<RegistryPersistence>enabled</RegistryPersistence>
</MediationConfig>
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.
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.
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:
synapse.observers=org.wso2.carbon.mediation.dependency.mgt.DependencyTracker
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.
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.
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')
<parameter name="hotdeployment" locked="false">false</parameter>
<parameter name="hotupdate" locked="false">false</parameter>
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.
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.
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.
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.
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.
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.
<registry provider="org.wso2.carbon.mediation.registry.WSO2Registry"> <parameter name="cachableDuration">15000</parameter> </registry>
Starting from ESB 3.0 the registry that comes with WSO2 ESB is actually a combination of 3 registries.
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.
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.
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.
<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>
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.
<readOnly>false</readOnly>
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.
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.
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.
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.
<parameter name="keystore" locked="false"> <KeyStore> <Location>repository/resources/security/wso2carbon.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> <KeyPassword>wso2carbon</KeyPassword> </KeyStore> </parameter> <parameter name="truststore" locked="false"> <TrustStore> <Location>repository/resources/security/client-truststore.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> </TrustStore> </parameter>
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 <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/repository/conf/carbon.xml file. This keystore configuration can be found under the <security> 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.
<KeyStore>
<Location>${carbon.home}/resources/security/wso2carbon.jks</Location>
<Type>JKS</Type>
<Password>wso2carbon</Password>
<KeyAlias>wso2carbon</KeyAlias>
<KeyPassword>wso2carbon</KeyPassword>
</KeyStore>
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.
<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/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.
<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.
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/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.
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 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.