This documentation is for older WSO2 products. View documentation for the latest release.
Production Deployment Guidelines - Clustering Guide 4.2.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

The requirements for deploying WSO2 products can change based on the deployment scenario and pattern used. The recommendations in this topic are for general production use, assuming moderate load conditions. For situations where a high volume of traffic is expected and larger deployments, these guidelines may not be sufficient. See Troubleshooting in Production Environments for information on how to obtain and analyze information to solve production issues. The following are the topics addressed in this section.

Installation prerequisites

Prior to installing any WSO2 Carbon-based product, it is necessary to have the appropriate hardware and software necessary for running the product.

Note: The specifications listed in this section are general requirements for setting up a WSO2 product in a production environment. These specifications may vary for some WSO2 products, so check the installation prerequisites for the specific product when setting up your WSO2 product instance.

Hardware requirements (per WSO2 product instance)

  • 3 GHz Dual-core Xeon/Opteron (or latest)
  • 4 GB RAM (2 GB for JVM and 2 GB for the operating system)
  • 10 GB free disk space

Disk space is based on the expected storage requirements that are calculated by considering the file uploads and the backup policies. For example, if three WSO2 product instances are running in a single machine, it requires a 4 GHz CPU, 8 GB RAM (2 GB for the operating system and 6 GB (2 GB for each WSO2 product instance)) and 30 GB of free space.

Virtual Machine
  • 2 compute units minimum (each unit having 1.0-1.2 GHz Opteron/Xeon processor)
  • 4 GB RAM
  • 10 GB free disk space
  • One CPU unit for the operating system and one for JVM.

Three WSO2 product instances running would require VM of 4 compute units, 8 GB RAM and 30 GB free space.

  • 1 c3.large instance to run one WSO2 product instance.

Three WSO2 product instances can be run in 1 EC2 Extra-Large instance. Based on the I/O performance of the c3.large instance, it is recommended to run multiple instances in a larger instance (c3.xlarge or c3.2xlarge).

Cassandra data nodes
  • 4 core processors
  • 8 GB RAM

For more information, see the Cassandra documentation on hardware recommendations for enterprise implementations.

Environment compatibility

  • All WSO2 Carbon-based products are Java applications that can be run on any platform that is Oracle JDK 1.6.*/1.7.* compliant. JDK 1.8 is not supported yet. Also OpenJDK is not recommended or supported. 
  • All WSO2 Carbon-based products are generally compatible with most common DBMSs. For more information, see Working with Databases.
  • It is not recommended to use Apache DS in a production environment due to issues with scalability. Instead, it is recommended to use an LDAP like OpenLDAP for user management.
  • On a production deployment, it is recommended that WSO2 products are installed on latest releases of RedHat Enterprise Linux or Ubuntu Server LTS.

  • For environments that WSO2 products are tested with, see Environments Tested with WSO2 Products. 
  • If you have difficulty in setting up any WSO2 product in a specific platform or database, please contact us.

Required applications

The following applications are required for running the WSO2 product and its samples or for building from the source code. Mandatory installs are marked with *.




Download Links

Oracle Java SE Development Kit (JDK)*

Required by all WSO2 products to:
  • To launch the product as each product is a Java application.
  • To build the product from the source distribution (both JDK and Apache Maven are required).
  • To run Apache Ant.

1.6.27 or later / 1.7.*

  • If you are using JDK 1.6, you might need to replace the Java Cryptography Extension (JCE) policy files in your JDK with the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy files. This will avoid "illegal key size" errors when you try to invoke a secured Web service.
  • To build the product from the source distribution, you must use JDK 1.6 instead of JDK 1.7.
  • Oracle and IBM JRE 1.7 are also supported when running (not building) WSO2 products.
  • If you are using JDK 1.7 on Mac OS or Solaris, install the snappy-java library using the following steps:

    1. Download the snappy-java JAR and extract it to a preferred location. This folder will be referred to as <SNAPPY_HOME>.

    2. Copy the appropriate snappy-java library file i386.jnilib (32bit) or x86_64.jnilib (64bit), which is in the <SNAPPY_HOME>/org/xerial/snappy/native/Mac/directory, to the <PRODUCT_HOME> directory.
    For more information on installing snappy-java library, see Snappy-java fails on Mac OS JDK 1.7.
Apache ActiveMQ 
JMS Provider*
  • To enable the product's JMS transport and try out JMS samples. The ActiveMQ client libraries must be installed in the product's classpath before you can enable the JMS transport.
5.5.0 or later

If you use any other JMS provider (e.g. Apache Qpid), install any necessary libraries and/or components.

Apache Ant

  • Required by all WSO2 products to compile and run the product samples.

1.7.0 or later
SVN Client
  • To check out the code to build the product from the source distribution. If you are installing by downloading and extracting the binary distribution instead of building from the source code, you do not need to install SVN.


Apache Maven

  • To build the product from the source distribution (both JDK and Apache Maven are required). If you are installing by downloading and extracting the binary distribution instead of building from the source code, you do not need to install Maven.

Web Browser

  • Required by all WSO2 products to access each product's Management Console. The Web Browser must be JavaScript enabled to take full advantage of the Management console.

NOTE: On Windows Server 2003, you must not go below the medium security level in Internet Explorer 6.x.



You are now ready to install the WSO2 product.

Installing the WSO2 product

Before you beginplease see our compatibility matrix to find out if this version of the product is fully tested on your operating system. 

Do the following to install the WSO2 product.

  1. If you have not done so already, download the latest version of the WSO2 product from the product section of

  2. Extract the archive file to a dedicated directory for the WSO2 product. This will hereafter be referred to as <PRODUCT_HOME> in this guide.


You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK) is installed on the computer.

Environment variables are global system variables accessible by all the processes running under the operating system.

  1. In your home directory, open the BASHRC file (.bash_profile file
 on OS X) in a Linux text editor, such as vi, emacs, pico, or mcedit.
  2. Add the following two lines at the bottom of the file, replacing /usr/java/jdk1.6.0_25 with the actual directory where the JDK is installed.

    On Linux:
    export JAVA_HOME=/usr/java/jdk1.6.0_25
    export PATH=${JAVA_HOME}/bin:${PATH}
    On OS X:
    export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

    In Linux, the file should now look like this:

  3. Save the file.

    If you do not know how to work with text editors in a Linux SSH session, run the following command:

    cat >> .bashrc

    Paste the string from the clipboard and press "Ctrl+D".

  4. To verify that the JAVA_HOME variable is set correctly, execute the following command:

    On Linux:
    echo $JAVA_HOME
    On OS X:
    which java
    If the above command gives you a path like /usr/bin/java, then it is a symbolic link to the real location. To get the real location, run the following:
    ls -l `which java`

    The system returns the JDK installation path.

Setting system properties

If you need to set additional system properties when the server starts, you can take the following approaches:

  • Set the properties from a script. Setting your system properties in the startup script is ideal, because it ensures that you set the properties every time you start the server. To avoid having to modify the script each time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script and adds the properties you want to set, rather than editing the WSO2 startup script directly.
    Set the properties from an external registry. If you want to access properties from an external registry, you could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data such as username and password to connect to the registry in a properties file instead of in the Java code and secure the properties file with the secure vault.

Note: When using SUSE Linux, it ignores /etc/resolv.conf and only looks at the /etc/hosts file. This means that the server will throw an exception on startup if you have not specified anything besides localhost. To avoid this error, add the following line above localhost in the /etc/hosts file: <ip_address>  <machine_name> localhost

You are now ready to run the product.

Running the product

To run WSO2 products, you start the product server at the command line. You can then run the Management Console application to configure and manage the product. Before you start the server, note the following:

  • The config-validation.xml file in the <PRODUCT_HOME>/repository/conf/etc directory contains a list of recommended system parameters, which are validated against your system when the server starts. See Configuring config-validation.xml for details on modifying these parameters before starting the server.
  • The Management Console uses the default HTTP-NIO transport, which is configured in the catalina-server.xml file in the <PRODUCT_HOME>/repository/conf/tomcat directory. This transport must be properly configured in this file for the Management Console to be accessible.

Starting the server

To start the server, you run the script (on Linux) from the bin folder.

To start and stop the server in the background mode of Linux, run start and stop commands.

  1. Open the command line on Linux and establish a SSH connection to the server or log into the text Linux console.
  2. Execute the following command, where <PRODUCT_HOME> is the directory where you installed the product distribution:

    sh <PRODUCT_HOME>/bin/

    If you want to provide access to the production environment without allowing any user group (including admin) to log into the management console, execute the following command.
    sh <PRODUCT_HOME>/bin/ -DworkerNode

    If you want to check any additional options available to be used with the startup commands, type -help after the command, such as: sh <PRODUCT_HOME>/bin/ -help.

    Alternatively, you can restrict access to the management console of your product by binding the management console with selected IP addresses. Note that you can either restrict access to the management console only, or you can restrict access to all web applications in your server as explained below.

    • To control access only to the management console, add the IP addresses to the <PRODUCT_HOME>/repository/conf/tomcat/carbon/META-INF/context.xml file as follows:

      <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="<IP-address-01>|<IP-address-02>|<IP-address-03>"/>

      The RemoteAddrValve Tomcat valve defined in this file will only apply to the Carbon management console, and thereby all outside requests to the management console will be blocked. 

    • To control access to all web applications deployed in your server, add the IP addresses to the <PRODUCT_HOME>/repository/conf/context.xml file as follows:

      <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="<IP-address-01>|<IP-address-02>|<IP-address-03>"/>

      The RemoteAddrValve Tomcat valve defined in this file will apply to each web application hosted on the Carbon server. Therefore, all outside requests to any web application will be blocked.

    • You can also restrict access to particular servlets in a web application by adding a Remote Address Filter to the web.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory), and by mapping that filter to the servlet url. In the Remote Address Filter that you add, you can specify the IP addresses that should be allowed to access the servlet.

      The following example from a web.xml file illustrates how access to the management page (/carbon/admin/login.jsp) is granted only to one IP address:
          <filter-name>Remote Address Filter</filter-name>
          <filter-name>Remote Address Filter</filter-name>
    Note: Any configurations (including valves) defined in the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file applies to all web applications and is globally available across server, regardless of host or cluster. See the official Tomcat documentation for more information about using remote host filters.

    The operation log appears. When the product server is running, the log displays the message "WSO2 Carbon started in 'n' seconds."

Stopping the server

To stop the server, press Ctrl+C in the command window, or click the Shutdown/Restart link in the navigation pane in the Management Console.

Running recommendations for security

The following are security related recommendations to be followed when running the product.

  • Running as a different user: For security reasons, it's recommended to run the product as an unprivileged user. After adding a user to the system, apply your organizational security policies to that user.
  • Running on a different port: If you want to run on a different port, like port 80, the recommended way is to add a port forwarding rule from your firewall.
  • Running as a Unix daemon: You have the option of running each product as a standard Unix service. You can start, stop and restart the WSO2 product instances as follows.
    # sh bin/ [start | stop | restart]

Host machine security hardening

Integrate the newly added server to your organizational backup policy of critical services. This will help you to recover a critical system in case of a compromise. We recommend you apply all the critical security patches from the respective OS vendor. If you have RedHat Enterprise Linux installed you must have a RHN subscription to receive updates. Turning off all services that you're not using is also critical. You can further add a firewall rule to close all ports other than the ports the WSO2 product is running on.

The following links give some sample guidelines on server hardening:

Common guidelines and checklist

The following table lists out the common guidelines and details pertaining to them. These are common to all products and are followed for making an installed WSO2 product ready for production.

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.

Related 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.

Related 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.

Recommended 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.


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.

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

It is recommended to configure logging using the management console.

Related 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.

H2 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.

Related 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, 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.

Related 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.

Related 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.

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.

Related 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.
Related 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.


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

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

Related 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.

Related 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.

  • No labels