Author: hiranya Date: Sat Jul 4 23:51:53 2009 New Revision: 40827 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=40827
Log: Adding the ESB server admin guide Added: branches/esb/java/2.1/product/docs/xdoc/admin_guide.xml Added: branches/esb/java/2.1/product/docs/xdoc/admin_guide.xml URL: http://wso2.org/svn/browse/wso2/branches/esb/java/2.1/product/docs/xdoc/admin_guide.xml?pathrev=40827 ============================================================================== --- (empty file) +++ branches/esb/java/2.1/product/docs/xdoc/admin_guide.xml Sat Jul 4 23:51:53 2009 @@ -0,0 +1,847 @@ +<?xml version="1.0" encoding="UTF-8"?> +<html> +<head> + <title>WSO2 ESB - System Administration Guide</title> +</head> + +<body> + +<h2> + WSO2 ESB - System Administration Guide +</h2> +<h4> + Contents +</h4> +<p> +1.0 Introduction<br/> +2.0 Document Conventions<br/> +3.0 Getting WSO2 ESB<br/> +4.0 Installing and Running WSO2 ESB<br/> +4.1 Running the ESB in Standalone Mode<br/> +4.2 Running ESB Samples<br/> +5.0 WSO2 ESB Directory Hierarchy<br/> +6.0 Using the WSO2 ESB Management Console<br/> +7.0 User Management<br/> +8.0 Setting Up Logging<br/> +9.0 Configuring the Underlying Axis2 Engine<br/> +10.0 Adding External Dependencies to the System<br/> +11.0 Registry Integration<br/> +11.1 Using the Embedded Registry<br/> +11.2 Using a Remote Registry<br/> +12.0 Setting Up Key Stores<br/> +13.0 Setting Up Host Names and Ports<br/> +14.0 Performance Tuning WSO2 ESB<br/> +</p> + +<h4> + 1.0 Introduction +</h4> +<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 WSAS. 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> + +<h4> + 2.0 Document Conventions +</h4> +<ul> + <li>The phrase 'ESB_HOME' refers to the directory in the file system where WSO2 ESB is installed</li> + <li>The phrase '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> + +<h4> + 3.0 Getting WSO2 ESB +</h4> +<p> +Binary distributions and source distributions of WSO2 ESB can be downloaded free from the <a href="http://wso2.org/projects/esb";> +WSO2 ESB project</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> + +<h4> + 4.0 Installing and Running WSO2 ESB +</h4> +<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> + +<h5> + 4.1 Running WSO2 ESB in Standalone Mode +</h5> +<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 first time startup can take up few additional seconds since some first time configuration logic is +run by the ESB. If the server started up cleanly you should get an output similar to the following on the console. +</p> +<pre> + [2009-06-25 13:52:54,700] INFO - CarbonCoreActivator Starting WSO2 Carbon... + [2009-06-25 13:52:54,714] INFO - CarbonCoreActivator Operating System : Linux 2.6.28-11-generic, i386 + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Home : /opt/jdk1.5.0_19/jre + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Version : 1.5.0_19 + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java VM : Java HotSpot(TM) Server VM 1.5.0_19-b02,Sun Microsystems Inc. + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Carbon Home : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.0.SNAPSHOT + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator Java Temp Dir : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.0.SNAPSHOT/tmp + [2009-06-25 13:52:54,715] INFO - CarbonCoreActivator User : hiranya, en-US, Asia/Colombo + [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Root : / + [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Mode : READ-WRITE + [2009-06-25 13:52:58,557] INFO - RegistryCoreServiceComponent Registry Type : embedded + [2009-06-25 13:53:06,956] INFO - CarbonServerManager Starting Carbon initialization... + [2009-06-25 13:53:07,300] INFO - ClusterBuilder Clustering has been disabled + [2009-06-25 13:53:07,952] INFO - HttpCoreNIOSSLSender Loading Identity Keystore from : resources/security/wso2carbon.jks + [2009-06-25 13:53:08,215] INFO - HttpCoreNIOSSLSender Loading Trust Keystore from : resources/security/client-truststore.jks + [2009-06-25 13:53:08,451] INFO - HttpCoreNIOSender HTTPS Sender starting + [2009-06-25 13:53:08,458] INFO - HttpCoreNIOSender HTTP Sender starting + [2009-06-25 13:53:14,632] INFO - CarbonServerManager Initializing transport descriptions and their associated parameters + [2009-06-25 13:53:14,653] INFO - CarbonServerManager Repository : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.0.SNAPSHOT/repository/ + [2009-06-25 13:53:14,684] INFO - ServiceBusInitializer Starting ESB... + [2009-06-25 13:53:14,726] INFO - ServiceBusInitializer Initializing Apache Synapse... + [2009-06-25 13:53:14,733] INFO - SynapseControllerFactory Using Synapse home : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.0.SNAPSHOT/ + [2009-06-25 13:53:14,734] INFO - SynapseControllerFactory Using synapse.xml location : /home/hiranya/Projects/Java/wso2-products/esb/modules/distribution/target/wso2esb-2.1.0.SNAPSHOT/./conf/synapse.xml + [2009-06-25 13:53:14,734] INFO - SynapseControllerFactory Using server name : WSO2 ESB Server + [2009-06-25 13:53:14,767] INFO - SynapseControllerFactory The timeout handler will run every : 15s + [2009-06-25 13:53:14,812] INFO - Axis2SynapseController Initializing Synapse at : Thu Jun 25 13:53:14 IST 2009 + [2009-06-25 13:53:14,814] INFO - Axis2SynapseController Loading mediator extensions... + [2009-06-25 13:53:14,817] INFO - CarbonSynapseController Building the SynapseConfiguration + [2009-06-25 13:53:14,985] INFO - Axis2SynapseController Deploying the Synapse service... + [2009-06-25 13:53:15,055] INFO - Axis2SynapseController Deploying Proxy services... + [2009-06-25 13:53:15,055] INFO - Axis2SynapseController Deploying EventSources... + [2009-06-25 13:53:15,059] INFO - ServerManager Server ready for processing... + [2009-06-25 13:53:15,627] INFO - HttpCoreNIOSSLListener Loading Identity Keystore from : resources/security/wso2carbon.jks + [2009-06-25 13:53:15,631] INFO - HttpCoreNIOSSLListener Loading Trust Keystore from : resources/security/client-truststore.jks + [2009-06-25 13:53:15,647] INFO - HttpCoreNIOListener HTTPS Listener started on port : 8243 + [2009-06-25 13:53:15,649] INFO - HttpCoreNIOListener HTTP Listener started on port : 8280 + [2009-06-25 13:53:16,498] INFO - EmbeddedRegistryBasedSubscriptionManager Connection established with the registry + [2009-06-25 13:53:18,263] INFO - RegistryEventingServiceComponent Successfully Initialized Eventing on Registry + [2009-06-25 13:53:18,263] INFO - StartupFinalizerServiceComponent Started Transport Listener Manager + [2009-06-25 13:53:18,264] INFO - StartupFinalizerServiceComponent Server WSO2 ESB-2.0 + [2009-06-25 13:53:18,264] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 37 sec +</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> +--cleanCache<br/> + This argument forces any cached jar files, configuration files, JSP pages to be cleaned before starting the ESB. +</p> +<p> + --cleanRegistry<br/> + This argument forces the embedded Registry instance to be cleaned before starting the ESB. Note that this will clean the internal database therefore any configurations you saved previously will be permanently lost. +</p> +<p> + --reset<br/> + This argument cleans the cache as well as the registry. The ESB will startup with factory settings. +</p> +<p> +-debug <port><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 runtime. +</p> +<p> + -DuseSynapseXML<br/> + Generally ESB will load the configuration from the Registry. Using this argument we can force the ESB to load the configuration from ESB_HOME/conf/synapse.xml file. +</p> + +<h4> + 4.2 Running ESB Samples +</h4> +<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> + +<h4> + 5.0 WSO2 ESB Directory Hierarchy +</h4> +<p> +When you extract a WSO2 ESB binary distribution archive you will find the following directories in the top level 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 -<TODO: Indika><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> + </ul> + <br/> + In addition to the above mentioned scripts you will find a subdirectory named 'native' in the bin directory.<br/> +</p> +<p> +database -<br/> +This directory contains the embedded H2 database used by WSO2 ESB and all the associated log files. The database is setup +during the first startup of the ESB. This is the database instance used by the embedded registry and the user manager. If you +are running the ESB against the embedded registry you should be extra careful not to modify or remove any of the files stored +in this directory. +</p> +<p> +repository -<br/> +This directory houses all the OSGi bundles, service artifacts, modules, sample configurations and related resources used by +the WSO2 ESB instance. The repository/components directory will contain all the necessary OSGi bundles at server runtime. In +the components subdirectory you can also find a set of child directories such as mediators and extensions which can be used to +deploy custom mediators and third party dependencies into the ESB. +</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> +conf -<br/> + All the global configuration files (eg: axis2.xml, transports.xml, carbon.xml) used by the ESB are stored in this directory. +</p> +<p> +lib -<br/> +The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance. Starting from Carbon 2.0 +the log4j.properties file used by the ESB is also stored here. +</p> +<p> +resources -<br/> +Contains additional resources required by WSO2 ESB. This includes security related resources such as keystores. +</p> +<p> +logs -<br/> +All the server logs created during server runtime will be stored here. +</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> + +<h4> + 6.0 Using the WSO2 ESB Management Console +</h4> +<p> +WSO2 ESB management console is a Web based constrol panel powered by JSP and AJAX which enables system administrators to interact +with a running ESB instance, without having to touch any underlying configuration files. The management console allows the users +to command and control proxy services, sequences, transports, local entries, registry, modules, endpoints and much more. ESB management +console is a great way to try things out without having to edit the actual configuration files or without having to restart the ESB for +changes to take effect. +</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://<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. +</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 explainatory. However if you are having +trouble finsing your way in the management console, click on the 'Help' link at the top right corner of any page to access context +sensitive help. +</p> +<p> +Please note that the ESB management console makes use of the default HTTPS servlet transport which is configured in the ESB_HOME/conf/transports.xml +file. It is important that this transport is always properly configured in the mentioned file. Otherwise the management console +might be inaccessible to the users. +</p> + +<h4> + 7.0 User Management +</h4> +<p> +To access the WSO2 ESB user management features, first sign in to the ESB management console and click on 'User Management' under the +'Configure' menu in the left navigation bar. This will take you to the User Management home page which contains the controls illustrated +below. +</p> +<img src="images/user-mgt.png"/> +<p> +From here you can manage users and roles. A user is associated with zero or more roles (generally specified at user creation time) and +each role is associated with zero or more permissions (generally specified at role creation time). Therefore the set of permissions +owned by a user is determined by the roles assigned to that user. A user owns the union of all the permissions associated with the roles +assigned to that user. By default ESB comes with only one role, the 'admin' role. This role is associated with the following set of +permissions. (In fact all the ESB related permissions are listed here, meaning that users with admin role gets all the permissions over +the system) +</p> +<ul> + <li> + login + </li> + <li> + manage-configuration + </li> + <li> + manage-security + </li> + <li> + upload-services + </li> + <li> + manage-services + </li> + <li> + manage-mediation + </li> + <li> + monitor-system + </li> + <li> + delegate-identity + </li> +</ul> +<p> +By default the admin user is associated with the admin role and hence the admin user is entitiled to all the above permissions. +</p> +<p> +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> +<p> +WSO2 ESB can be easily configured to use an external user store in addition to the buiilt-in system user store. An external user store +is an external database which stores user data. It could be as simple as a relational database or as sophiticated as an LDAP instance. +Most organizations maintain such centralized databases and it would be productive from the organization's point of view to have the +ESB pick up user data from the existing centralized user database. To connect the ESB to an external user store simply click on the +'Add External User Store' link on the User Management home page. Then on the page that appears select the type of user store that will +be plugged into the ESB. Currently the following types of user stores are supported. +</p> +<ul> + <li> + JDBC + </li> + <li> + LDAP + </li> + <li> + Active Directory + </li> +</ul> +<p> +Having selected the type of the user store you need to provide additional information required by the ESB to connect to and retrieve +user data from the external user store. If all the required parameters were specified accurately the ESB will pick up user data from +the external user store and users registered on the external store will be able to access the ESB as if their accounts were created +in the built-in system user store. +</p> + +<h4> + 8.0 Setting Up Logging +</h4> +<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/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/logs/wso2-esb-service.log) + </li> + <li> + TRACE_APPENDER (Writes mediation time tracing/debug messages to the ESB_HOME/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 oage lists all the deployed sequences. Each sequence gives you the options to enable/disable +tracing. To access the service dashboard for a proxy service go to the Services List page and click on the proxy service that you are +interested in. Once a sequence or a proxy service is tracing enabled you can view the generated log messages by visiting the 'Mediation +Tracer' page under the 'Monitor' menu. The 'Monitor' menu also gives you access to the system logs and the SOAP tracer logs all through +the Web interface itself. +</p> +<img src="images/logs.png"/> + +<h4> + 9.0 Configuring the Underlying Axis2 Engine +</h4> +<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/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> + +<h4> + 10.0 Adding External Dependencies to the System +</h4> +<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> + +<h4> + 11.0 Registry Integration +</h4> +<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> +<syn:registry provider="org.wso2.carbon.mediation.registry.WSO2Registry"> + <syn:parameter name="cachableDuration">15000</syn:parameter> +</syn:registry> +</pre> + +<p> +One could browse the contents of the registry instance used by the ESB from the WSO2 ESB management console. To browse the registry, +first login to the ESB management console and click on 'Registry Browser' link on the 'Registry' menu in the left navigation bar. +</p> + +<h5> + 11. 1 Using the Embedded Registry +</h5> +<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. This is configured in the ESB_HOME/conf/carbon.xml as follows. +</p> + +<pre> +<Registry> + <ReadOnly>false</ReadOnly> + <Type>embedded</Type> + <SystemUserName>carbon</SystemUserName> +</Registry> +</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. +</p> +<p> +The embedded registry instance makes use of the embedded ESB database. This is an H2 database and the data files are by default stored +in the directory named ESB_HOME/database. If you are running the ESB in the embedded registry mode you should be careful not to manually +alter any files stored in this directory as that might lead to database corruption or data loss. However in ceretain cases you would +want to clean the embedded database and start fresh. In such situations you could pass the --cleanRegistry argument to ESB startup script. +</p> +<p> +The embedded registry instance is configured by the registry.xml file which can be found in the ESB_HOME/conf directory. In this +configuration you could point the embedded registry to a database other than the default embedded H2 database. To change the database +used by the registry or change the location of the database files edit the following section of the registry.xml. +</p> + +<pre> +<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> +</pre> + +<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> +<staticConfiguration> + <versioningProperties>true</versioningProperties> + <versioningComments>true</versioningComments> + <versioningTags>true</versioningTags> + <versioningRatings>true</versioningRatings> +</staticConfiguration> +</pre> + +<p> +Please refer WSO2 G-Reg documentation for further information on setting up media type handlers and other global parameters. +</p> + +<h5> + 11.2 Using the Remote Registry +</h5> +<p> +You can get the WSO2 ESB to run against a remotely hosted WSO2 G-Reg instance easily. This is very important and useful in production +deployment scenarios. Using this technique one can run several WSO2 ESB instances against the same registry thus effectively sharing +the configurations and other resources across all the ESB instances. Also with a remote registry based deployment it is easy to change +the environment and the configuration in which the WSO2 ESB runs. In remote registry mode, changing the configuration (say from test +configuration to production configuration) is as simple as pointing the ESB to a different G-Reg instance. +</p> +<p> +To setup the ESB against a remote WSO2 G-Reg instance simply modify the 'Registry' section of the ESB_HOME/conf/carbon.xml file. You +should specify the registry type as 'remote' and state the registry URL, chroot and login credentials. +</p> + +<pre> +<Registry> + <ReadOnly>false</ReadOnly> + <Type>remote</Type> + <SystemUserName>carbon</SystemUserName> + <Url>http://remote-ip:port/registry/</Url> + <Chroot>/prefix</Chroot> + <Username>username</Username> + <Password>password</Password> +</Registry> +</pre> + +<h4> + 12.0 Setting Up Keystores +</h4> +<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 ESB_HOME/conf/axis2.xml file under the HTTPS transport receiver +and HTTPS transport sender configurations. +</p> + +<pre> +<parameter name="keystore" locked="false"> + <KeyStore> + <Location>resources/security/wso2carbon.jks</Location> + <Type>JKS</Type> + <Password>wso2carbon</Password> + <KeyPassword>wso2carbon</KeyPassword> + </KeyStore> +</parameter> +<parameter name="truststore" locked="false"> + <TrustStore> + <Location>resources/security/client-truststore.jks</Location> + <Type>JKS</Type> + <Password>wso2carbon</Password> + </TrustStore> +</parameter> +</pre> + +<p> +The default keystores can be found in ESB_HOME/resources/security directory. To change the keystores used by the HTTPS transport +update the HTTPS transport receiver and sender configurations by specifying the paths to keystore files and other attributes of the +files such as the keystore passwords. Under the <KeyStore> element two password values must be specified. The <Password> +element should indicate the password of the keystore file. The <KeyPassword> elemenet should point to the password required to +access the private key. +</p> +<p> +The keystore used to encrypt administrator passwords and other confidential information in Carbon is configured in +ESB_HOME/conf/carbon.xml file. This keystore configuration can be found under the <security> element of the carbon.xml file. +</p> + +<pre> +<KeyStore> + <Location>${carbon.home}/resources/security/wso2carbon.jks</Location> + <Type>JKS</Type> + <Password>wso2carbon</Password> + <KeyAlias>wso2carbon</KeyAlias> + <KeyPassword>wso2carbon</KeyPassword> +</KeyStore> +</pre> + +<h4> + 13.0 Setting Up Host Names and Ports +</h4> +<p> +The bind address values and HTTP/HTTPS ports used by the ESB server should be configured in the ESB_HOME/conf/axis2.xml file. To +configure the bind address for the server, define the following parameter under the HTTP and HTTPS transport receiver configurations +in the ESB_HOME/conf/axis2.xml file. +</p> + +<pre> +<parameter name="bind-address" locked="false">hostname or IP address</parameter> +</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> +<parameter name="port" locked="false">8280</parameter> +</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> +<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> +</pre> + +<p> +To change the ports used by the ESB management console you must modify the ESB_HOME/conf/transports.xml. By default the management +console would accept HTTPS requests on port 9443. Change the following parameter to set the HTTPS port used by the console. +</p> + +<pre> +<parameter name="port">9443</parameter> +</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> +<parameter name="WSDLEPRPrefix" locked="false">https://apachehost:port/somepath</parameter> +</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> +<parameter name="proxyPort">80</parameter> +</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> + +<h4> + 14.0 Performance Tuning WSO2 ESB +</h4> +<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/conf directory. You can change the socket timeout values, connection timeout values and HTTP receiver thread pool +parameters by specifying them in the nhttp.properties file. A sample set of values that can be included in the nhttp.properties file is +specified below. +</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 providedd a set of default valules will be used to initialize the thread pool of the HTTP-NIO +transports. However the default values (mentioned in the above example) are suitable for most deployments and it is recommended to +leave them unchanged without overriding the values using a nhttp.properties configuration file. +</p> +</body> +</html> \ No newline at end of file _______________________________________________ Esb-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/esb-java-dev
