

Production Deployment Guidelines

The requirements for deploying WSO2 products can change based on the deployment scenario and pattern. 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 if there are large deployments, these guidelines may not be sufficient.

See Troubleshooting in Production Environments for information on how to analyse production issues.

Common Product Guidelines

Listed below are the common guidelines for making a WSO2 product ready for production.

Guideline	Details
Security hardening	Guidelines for hardening the security of a WSO2 deployment in a production environment can be discussed under three high-level categories: Product-level security OS-level security Network-level security Related links See Security Guidelines for the detailed list of security-related recommendations.
Hostname	By default, WSO2 products identify the hostname 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 hostname by setting the HostName parameter in the deployment.toml file. [server] hostname="localhost" To configure hostnames for WSDLs and endpoints, users are recommended to add the following parameter for the transport listener in the deployment.toml file. [transport.http] listener.wsdl_epr_prefix="$ref{server.hostname}"
Registry and governance	The H2 database-based registry is not available in the Micro Integrator. Instead, it has a file system based registry, which provides the same functionality.
Tuning WSO2 products	Most of the performance tuning recommendations are common to all WSO2 products. However, each WSO2 product may have additional guidelines for optimizing the performance of product-specific features. Related links Read about tuning the JVM and tuning the network and OS.
Firewalls	The following ports must be accessed when operating within a firewall. 8290 - Default HTTP port used by the Micro Integrator for proxy services and APIs. 8253 - Default HTTPS port used by the Micro Integrator for proxy services and APIs. 9164 - Default HTTPS port used by the Micro Integrator Management APIs.
Proxy servers	If the product is hosted behind a proxy such as ApacheHTTPD, users can configure products to use the proxy server by providing the following system properties at the start-up. -Dhttp.proxyHost=xxxx -Dhttp.proxyPort=xxxx Alternatively, this can be done by adding the following configurations in the deployment.toml file. [transport.http] sender.proxy_host = "$ref{server.hostname}" sender.proxy_port = 3128
High availability	In the cloud native deployment, high availability should be achieved via the container orchestration system ( Ex: Kubernetes ). There are builtin readiness and liveness probes available in Micro Integrator. We can invoke the readiness probe as follows curl -X GET http://localhost:9201/healthz In a VM deployment, we can use a load balancer with multiple nodes as described here to achieve high availability.
Data backup and archiving	For data backup and for archiving of data, use the functionality provided by the RDBMS.

Security Guidelines

Given below are the common security guidelines for deploying a WSO2 product in a production environment.

WSO2 product-level security

Guideline	Details
Apply security updates	Micro Integrator security fixes can be taken from one of the following methods. Using WUM ( WSO2 Update Manager ) to get the latest fixes. Users with a subscription can take the latest security fixes via the WUM security channel. The WSO2 Security Advisories page and the U2 Portal has all the security patches for the latest product versions. WSO2 does not issue patches publicly for older product versions. Community users are encouraged to use the latest product version to receive all the security fixes. WSO2 Docker repository releases docker images with security fixes. Users with a subscription can fetch these docker images.
Change default keystores	Change the default key stores and create new keys for all the cryptographic operations. 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. Consider the following guidelines when creating the keystores: Select a key size of at least 2048 bits. Use an SHA256 certificate. Make sure that WSO2 default certificates do not exist in any of the keystores in your production environment. For example, be sure to delete the default public certificate in the default trust store that is shipped with the product. See Creating New Keystores for information on how to create and configure your own keys.
Encrypt passwords in configuration files	WSO2 products use a tool called Secure Vault to encrypt the plain-text passwords in configuration files. See Securing Passwords in Configuration Files for instructions.
Change default ports	All the default ports used by WSO2 products are listed in here. For example, proxy services are exposed over the following ports: 8253 and 8290. To change a default port, update the offset element in the deployment.toml file as explained in Changing the Default Ports .
Always communicate (with external user stores) over TLS	All connections from your WSO2 product to external databases, userstores (LDAP), or other services, should be over TLS, to ensure adequate network-level protection. Therefore, be sure to use external systems (user stores, databases) that are TLS-enabled.
Connect to data stores using a less privileged user	When connecting the WSO2 product to external databases or user stores (LDAP), be sure to go through a user who does not have permission to change the data store's schema. Be sure not to use the root user of the data store because all permissions are generally granted to the root user.
Configure strong HTTP(S) security	To have strong transport-level security, use TLS 1.2 and disable SSL, TLS 1.0 and 1.1. The TLS protocol and strong ciphers are configured for the passthrough transport in the deployment.toml file. See the following links for instructions: Configuring Transport-Level Security Note the following: When deciding on the TLS protocol and the ciphers, consider the compatibility with existing client applications. Imposing maximum security might cause functional problems with client applications. Apply ciphers with 256 bits key length if you have applied the Unlimited strength policy. Note that Unlimited strength policy is recommended. Also, consider the following factors when deciding on the ciphers: DES/3DES are deprecated and should not be used. MD5 should not be used, due to known collision attacks. RC4 should not be used, due to crypto-analytical attacks. DSS is limited to a small 1024 bit key size. Cipher-suites that do not provide Perfect Forward Secrecy/ Forward Secrecy (PFS/FS). GCM based ciphers are recommended over CBC ciphers.
Remove weak ciphers for PassThrough transport	Remove any weak ciphers from the PassThrough transport and ensure that the server does not accept connections using those weak ciphers. The PassThrough transport is configured using the deployement.toml file. See Disabling weak ciphers for instructions.
Increase Ephemeral Diffie-Hellman Key size	Before starting the server, open the product startup script ( micro-integrator.sh in Linux and micro-integrator.bat in Windows) and enter the following with the other Java properties: -Djdk.tls.ephemeralDHKeySize=2048 \
Disable client-initiated renegotiation	Before starting the server, open the product startup script ( micro-integrator.sh in Linux and micro-integrator.bat in Windows) and enter the following with the other Java properties: -Djdk.tls.rejectClientInitiatedRenegotiation=true \
Enable HostName Verification	Make sure that hostname verification is enabled in the product startup script ( micro-integrator.sh in Linux and micro-integrator.bat in Windows) with the Strict mode. That is, you need to enable the following parameter: -Dhttpclient.hostnameVerifier=Strict \
Change default admin credentials	Change the deployment.toml with following configuration to change the admin password [super_admin] username = "admin" password = "admin" admin_role = "admin" create_admin_account = true
Enable log rotation and monitoring	Ensure that you have a relevant log rotation scheme to manage logs. Log4J properties for Micro Integrator can be configured in the <MI_HOME>/conf/log4j2.properties file. To roll the wso2carbon.log based on size, this guide can be used. See Monitoring Logs for details on how to configure logging details in WSO2 products.
Prevent Log Forging	Log forging can be prevented by appending a UUID to the log message. Read about configuring the log4j.properties file.
Set appropriate JVM parameters	The recommended JDK version is JDK 1.8 or 1.11. See the installation pre-requisites for more information. Tip: To run the JVM with 2 GB (-Xmx2048m), you should ideally have about 4GB of memory on the physical machine.

OS-level security

This section provides the list of OS-level security guidelines for your production environment.

Guideline	Details
Run WSO2 processes with a specific OS-level user	Use a separate OS-level user to run WSO2 products. Make sure that the user is only granted the permissions required for running the product for that particular user. Do not use the root/administrator user of your OS because the root/administrator is granted all privileges by default.
Minimize software to avoid vulnerability	Make sure that you only install the software/packages that are relevant to your WSO2 product's deployment. Also, continuously monitor the software that you install. See the Installation Prerequisites to identify the minimum software your WSO2 product will need.
Enable the Firewall	Enable a firewall at the OS level (for example, iptables). This will provide protection for inbound and outbound connections of your WSO2 product. Make sure that you only open the required outbound and inbound ports from the OS-level firewall.
Use Secure Shell(SSH)	Use Secure Shell (SSH) when interacting with servers and executing commands. Adhere to the following best practices when you configure SSH: Change the default ssh port to a higher value. Disable the root or administrator. Enable login with user keys. Display a legal banner or a security banner with security warnings before SSH authentication.
Keep the system up-to-date	If there are security updates available for the packages installed in your OS (including the Java runtime), be sure to perform the necessary testing in a staging environment, and then proceed to install them for your OS.
Monitor user activities	Monitor the activities of your OS users. You can do this by enabling OS-level logs and by reviewing them regularly. You can also set up a centralized log monitoring system for this purpose.
Make regular backups	Make sure to backup important files and archive them continuously. See Backup and Recovery Recommendations for more information.

Network-level security

This section provides the list of security guidelines for configuring the network.

Guideline	Details
Create a failover setup	In the cloud native deployment, high availability should be achieved via the container orchestration system ( Ex: Kubernetes ) In a VM deployment, there should be atleast two nodes with the failover configuration.
Maintain network level logging	Be sure to maintain and monitor logs for your proxy servers, load balancers, and other network devices.
Check open ports and services	Periodically check for open ports using port scanning tools and make sure that only the necessary ports are open to both internal and external networks. Be sure that only the ports relevant to your WSO2 products are open for communication. If there are other ports started, be sure to monitor them. See the default ports for more information.
Configure device-level security	All your network devices should be periodically checked for anomalies. For example, you need to verify routing tables and firewall rules. Also, make sure that the default credentials are changed before the first use of those devices.
Apply firmware updates	Firmware updates for your network devices should be applied regularly.

Monitoring Transaction Counts

A Transaction in WSO2 Micro Integrator is typically defined as an inbound request (a request coming to the server). That is, any inbound request to a REST API, Proxy service, or Inbound Endpoint is considered as one transaction.

However, when the Micro Integrator is configured as both the message producer and consumer to handle asynchronous messaging scenarios, the two requests (listening request and sending request) are considered as a single transaction.

If you need to track the number of transactions in your Micro Integrator deployment, you can enable the transaction counter component in each Micro Integrator instance of your deployment. Currently, the transaction counter is responsible for counting all requests received via the HTTP Passthru and JMS transports and for persisting the summary of the transaction count in a database for future use.

Follow the instructions given below.

Enabling the Transaction Counter

Configure a relational database to persist transaction count information and then enable the Transaction Counter component from the deployment.toml file (stored in the <MI_HOME>/conf folder).

1. Select the preferred database type from the list given below and follow the relevant link to set up a database.

   • Setting up a MySQL database
   • Setting up an MSSQL database
   • Setting up an Oracle database
   • Setting up a Postgre database
   • Setting up an IBM database

2. Once you have set up the database, verify that the deployment.toml file of your Micro Integrator contains the relevant datasource configurations:

   MySQL

   [[datasource]]
   id = "WSO2_TRANSACTION_DB"
   url= "jdbc:mysql://localhost:3306/transactiondb"
   username="root"
   password="root"
   driver="com.mysql.jdbc.Driver"
   pool_options.maxActive=50
   pool_options.maxWait = 60000
   pool_options.testOnBorrow = true

   MSSQL

   [[datasource]]
   id = "WSO2_TRANSACTION_DB"
   url= "jdbc:sqlserver://<IP>:1433;databaseName=transactiondb;SendStringParametersAsUnicode=false"
   username="root"
   password="root"
   driver="com.microsoft.sqlserver.jdbc.SQLServerDriver"
   pool_options.maxActive=50
   pool_options.maxWait = 60000
   pool_options.testOnBorrow = true

   Oracle

   [[datasource]]
   id = "WSO2_TRANSACTION_DB"
   url= "jdbc:oracle:thin:@SERVER_NAME:PORT/SID"
   username="root"
   password="root"
   driver="oracle.jdbc.OracleDriver"
   pool_options.maxActive=50
   pool_options.maxWait = 60000
   pool_options.testOnBorrow = true

   PostgreSQL

   [[datasource]]
   id = "WSO2_TRANSACTION_DB"
   url= "jdbc:postgresql://localhost:5432/transactiondb"
   username="root"
   password="root"
   driver="org.postgresql.Driver"
   pool_options.maxActive=50
   pool_options.maxWait = 60000
   pool_options.testOnBorrow = true

   IBM DB

   [[datasource]]
   id = "WSO2_TRANSACTION_DB"
   url="jdbc:db2://SERVER_NAME:PORT/transactiondb"
   username="root"
   password="root"
   driver="com.ibm.db2.jcc.DB2Driver"
   pool_options.maxActive=50
   pool_options.maxWait = 60000
   pool_options.testOnBorrow = true

3. Add the parameters given below to the deployment.toml file and update the values.

   [transaction_counter]
   enable = true
   data_source = "WSO2_TRANSACTION_DB"
   update_interval = 2

   Parameters used above are explained below.

   Parameter	Description
   enable	This paramter is used for enabling the Transaction Counter. Default value if 'false'.
   data_source	The ID of the datasource. This refers the datasource ID configured under the datasource configuration.
   update_interval	The transaction count is stored in the database with an interval (specified by this parameter, which will be taken as the number of minutes) between the insert queries. The default update interval is one minute.

Getting the Transaction Count

You can get the transaction count for a particular month or period. This data can be viewed or saved to a report. There are two ways to get transaction count data:

• Start the Micro Integrator CLI and use the mi transaction option.

• Directly access the Management API resources and invoke the /transaction/count and /transaction/report resources.

Top