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.
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)
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.
Three WSO2 product instances running would require VM of 4 compute units, 8 GB RAM and 30 GB free space.
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|
For more information, see the Cassandra documentation on hardware recommendations for enterprise implementations.
- 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, .
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 *.
Oracle Java SE Development Kit (JDK)*
|Required by all WSO2 products to:|
1.6.27 or later / 1.7.*
|Apache ActiveMQ |
|5.5.0 or later|
If you use any other JMS provider (e.g. Apache Qpid), install any necessary libraries and/or components.
1.7.0 or later
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
Do the following to install the WSO2 product.
- If you have not done so already, download the latest version of the WSO2 product from the product section of wso2.com.
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.
- 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.
Add the following two lines at the bottom of the file, replacing
/usr/java/jdk1.6.0_25with the actual directory where the JDK is installed.
In Linux, the file should now look like this:
Save the file.
If you do not know how to work with text editors in a Linux SSH session, run the following command:
Paste the string from the clipboard and press "Ctrl+D".
To verify that the
JAVA_HOMEvariable is set correctly, execute the following command:
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
127.0.0.1 localhost in the
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:
config-validation.xmlfile in the
<PRODUCT_HOME>/repository/conf/etcdirectory 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.xmlfile in the
<PRODUCT_HOME>/repository/conf/tomcatdirectory. 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
wso2server.sh (on Linux) from the
To start and stop the server in the background mode of Linux, run
wso2server.sh start and
wso2server.sh stop commands.
- Open the command line on Linux and establish a SSH connection to the server or log into the text Linux console.
Execute the following command, where
<PRODUCT_HOME>is the directory where you installed the product distribution:
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/wso2server.sh -DworkerNode
If you want to check any additional options available to be used with the startup commands, type
-helpafter the command, such as:
sh <PRODUCT_HOME>/bin/wso2server.sh -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.
Note: Any configurations (including valves) defined in the
To control access only to the management console, add the IP addresses to the
<PRODUCT_HOME>/repository/conf/tomcat/carbon/META-INF/context.xmlfile as follows:
RemoteAddrValveTomcat 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.xmlfile as follows:
RemoteAddrValveTomcat 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.xmlfile (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:
<PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xmlfile 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/wso2server.sh [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.
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.
|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.
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
Tip: To run the JVM with 2 GB (-Xmx2048m), you should ideally have about 4GB of memory on the physical machine.
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
To configure host names for WSDLs and endpoints, users are recommended to add the following parameter in the <transportReceiver> section in the
It is recommended to configure logging using the management console.
|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.
WSO2 products offer three choices to store user details:
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.
|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
|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.
The following ports must be accessed when operating within a firewall.
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
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.
|Data backup and archiving||For data backup and for archiving of data, use the functionality provided by the RDBMS.|
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.
|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
To roll the wso2carbon.log based on size, the following configurations can be used.