This documentation is for older WSO2 products. View documentation for the latest release.
Page Comparison - Production Deployment Guidelines (v.33 vs v.34) - Clustering Guide 4.2.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Default credentials

Once you have installed the product, it is a good practice to change the default passwords. All WSO2 products have an administrator account set to “admin” as username and password. You can change it in the user management section of the Management Console.

titleRelated links

See Changing a Password for more information on how to change the password of the administrator.

Secure Sockets Layer (SSL) keys

WSO2 products by default come with a self-signed SSL key. Since these keys are public, it is recommended to configure your own keys for security purposes.

titleRelated links
JVM version

The recommended version is JDK 1.6.24 or later/1.7.*.

Set the appropriate Heap and Permgen values for JVM based on your deployment scenario. These can be set in the <PRODUCT_HOME>/bin/ file.

Code Block
titleRecommended memory parameters for typical WSO2 deployments
-Xms512m -Xmx2048m -XX:MaxPermSize=1024m

Tip: To run the JVM with 2 GB (-Xmx2048m), you should ideally have about 4GB of memory on the physical machine.

 Host name

By default, WSO2 products identify the host name of the current machine through the Java API. However, this value sometimes yields erroneous results on some environments. Therefore, users are recommended to configure the host name by setting the HostName parameter in the <PRODUCT_HOME>/repository/conf/carbon.xml file.

Code Block

To configure host names for WSDLs and endpoints, users are recommended to add the following parameter in the <transportReceiver> section in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file as shown below.

Code Block
<parameter name="WSDLEPRPrefix" locked="false">[http]://[port]</parameter>
titleRelated links
Managing logs

It is recommended to configure logging using the management console.

titleRelated links

See Managing Logs for details on how to configure logging details in WSO2 products.

Registry and governance

All WSO2 products make use of an instance of a registry to store configurations. The registry uses a database as the persistent storage. By default, the registry uses an embedded H2 database.

titleH2 is not recommended in production

The embedded H2 database is NOT recommended in enterprise testing and production environments. It has lower performance, clustering limitations, and can cause file corruption failures. Please use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, or MS SQL instead.

You can use the embedded H2 database in development environments and as the local registry in a registry mount.

As the default setup does not include database backup procedures, the production setup should have regular database backup procedures configured.

When the registry database is pointed to a remote database, multiple running instance of the same product can boot up and run against the same configuration stored in the registry. This, in turn, helps with governance.

titleRelated links

See here for more information on sharing a registry space across multiple WSO2 product instances.

User stores

WSO2 products offer three choices to store user details:

  • Using a database
  • Using a LDAP server
  • Using an Active Directory service

The default is to use the embedded H2 database , with the user store schema. Like in the case of the registry database, you can H2 is not recommended in enterprise testing and production environments. We recommend that you switch to a database like Oracle, MySQL or MSSQL. You can point to an existing LDAP or an Active Directory to make use of existing user bases and grant access privileges for WSO2 products based on those user stores.

titleRelated links

See Working with User Stores for more information on user stores, how they work, and how to configure them.

Monitoring with JMX

WSO2 Products support JMX for monitoring. By default, JMX uses port 9999. You can configure this to a desired port by setting the JMX port parameter in the <PRODUCT_HOME>/repository/conf/carbon.xml file.

Code Block
titleRelated links

See JMX-based Monitoring for information on monitoring WSO2 products using JMX.

Tuning WSO2 products

There are performance tuning guidelines for all products. Check these in their respective product documentation.

titleRelated links
Securing plain-text passwords

WSO2 products use a tool called “Secure Vault” to secure the plain-text passwords in configuration files. With this tool, you can encrypt the passwords.

titleRelated links

See Carbon Secure Vault Implementation for more information on how to secure plain-text passwords in WSO2 product configuration files.


The following ports must be accessed when operating within a firewall.

  • 9443 - Used by the management console and services that use the servlet transport, and is defined in the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file.
  • 9763 - Used by the services that use servlet transport, and is defined in the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file.
  • 9999 - Used for JMX monitoring, defined in the <PRODUCT_HOME>/repository/conf/carbon.xml file.
  • 8280 - Default HTTP port used by ESB for proxy services, and is defined in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file.
  • 8243 - Default HTTPS port used by ESB for proxy services, and is defined in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file.
titleRelated links

See Default Ports of WSO2 Products for a list of common and product-specific ports used by WSO2 products.

Proxy servers

If the product is hosted behind a proxy such as Apache HTTPD, users can configure products to use the proxy server by providing the following system properties at the start-up.

Code Block

Alternatively, this can be done by adding the following configurations in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file.

Code Block
<parameter name="Proxy">
High availability

For high availability, WSO2 products must run on a cluster. This enables the WSO2 products to still work in the case of failover. Databases used for the repository, user management and business activity monitoring can also be configured in a cluster or can use replication management provided by the RDBMS.

titleRelated links
  • See Overview for more details on clustering, what it is, how it helps and other related information.
  • See Creating a Worker/Manager Separated Cluster for information on clustering WSO2 products by separating worker and manager concerns between the nodes.
  • See Configuring Clustering for Specific Products for more information on product-specific clustering configurations.
  • See Setting up a Cluster for more information on clustering WSO2 products when fronted by a third-party load balancer.
  • See Setting up a MySQL cluster for more information on configuring a cluster for a database. In this case, MySQL is used as an example.
Data backup and archivingFor data backup and for archiving of data, use the functionality provided by the RDBMS.
Feature management

Compatible features can be installed on any WSO2 product using the WSO2 Carbon Feature Manager that comes with the product. The feature manager is powered by Equinox P2 and allows you to connect to a remote or local P2 repository and get any compatible WSO2 feature installed into the product's runtime.

titleRelated links

Spooling and log rotation

Ensure that you have a relevant log rotation scheme to manage logs. Log4J properties for WSO2 products can be configured in the <PRODUCT_HOME>/repository/conf/ file.

To roll the wso2carbon.log based on size, the following configurations can be used.

Code Block