This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, go to

Product Administration

WSO2 API Manager is shipped with default configurations that allow you to download, install and get started with your product instantly. However, when you go into production, it is recommended to change some of the default settings to ensure that you have a robust system that is suitable for your operational needs. Also, you may have specific use cases that require specific configurations to the server. If you are a product administrator, the follow content will provide an overview of the administration tasks that you need to perform when working with WSO2 API Manager (WSO2 API-M).

What is the WSO2 Administration Guide?

The WSO2 Administration Guide is a WSO2 guide that is common to all WSO2 products, and it explains all you need to know about how to set up and configure a WSO2 product to meet your enterprise requirements. In the subsequent sections we point you to the WSO2 Administration Guide where necessary.


Upgrading from a previous release

If you are upgrading from WSO2 API Manager 2.5.0 to WSO2 API Manager 2.6.0, see the /wiki/spaces/AM260/pages/30902279.

Changing the default database

By default, WSO2 products are shipped with an embedded H2 database, which is used for storing user management and registry data. We recommend that you use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, MS SQL, etc. when you set up your production environment. You can change the default database configuration by simply setting up a new physical database and updating the configurations in the product server to connect to that database. 

For instructions on setting up and configuring databases, see the following sections in the WSO2 Administration Guide.

Setting up the Physical Database

You can use the scripts provided with WSO2 API-M to install and configure several other types of relational databases. For more information, see the following sections.

Changing the Carbon Database

WSO2 API-M is shipped with an H2 database, which serves as the default Carbon database. You can change this default database to one of the standard databases listed below.

When changing the default database, which is H2, to any other RDBMS, be sure to change all the other required datasources (WSO2AM_DB, WSO2AM_STATS_DB, WSO2_MB_STORE_DB, WSO2_METRICS_DB, etc.) to the same RDBMS. For more information, see Changing the Default API-M Databases.

Configuring users, roles, and permissions

The user management feature in your product allows you to create new users and define the permissions granted to each user. You can also configure the user stores that are used for storing data related to user management. 

Configuring security

After you install WSO2 API Manager, it is recommended to change the default security settings according to the requirements of your production environment. As API Manager is built on top of the WSO2 Carbon Kernel (version 4.4.11), the main security configurations applicable to API Manager are inherited from the Carbon kernel.

For instructions on configuring security in your server, see the following topics in the WSO2 Administration Guide.


If you are configuring your production environment, be sure to check the Security Guidelines for Production Deployment before applying any security configurations.

Securing Passwords in Configuration Files

All WSO2 Carbon products contain some configuration files with sensitive information such as passwords. Let's take a look at how such plain text passwords in configuration files can be secured using the Secure Vault implementation that is built into Carbon products.

The following topics will be covered under this section:

Configuring Transport-Level Security

The transport level security protocol of the Tomcat server is configured in the <PRODUCT_HOME>/core/conf/tomcat/catalina-server.xml file. Note that the ssLprotocol attribute is set to "TLS" by default. 

The following topics will guide you through the configuration options:

Enabling Java Security Manager

The Java Security Manager is used to define various security policies that prevent untrusted code from manipulating your system.  Enabling the Java Security Manager for WSO2 products activates the Java permissions that are in the <PRODUCT_HOME>/core/repository/conf/sec.policy file. You modify this file to change the Java security permissions as required.

Using Asymmetric Encryption

WSO2 products use asymmetric encryption by default for the purposes of authentication and data encryption. In asymmetric encryption, keystores (with key pairs and certificates) are created and stored for the product. It is possible to have multiple keystores so that the keys used for different use cases are kept unique. The following topics explain more details on keystores. 

Using Symmetric Encryption

WSO2 Carbon-based products use asymmetric encryption by default as explained in the previous section. From Carbon 4.4.3 onwards, you have the option of switching to symmetric encryption in your WSO2 product. Using symmetric encryption means that a single key will be shared for encryption and decryption of information. 
Mitigating Cross Site Request Forgery AttacksCross Site Request Forgery (CSRF) attacks trick you to send a malicious request, by forcing you to execute unwanted actions on an already authenticated web browser. For more information, see the following sections that describe the impact of the Cross Site Request Forgery (CSRF) attack and how to mitigate it.
Mitigating Cross Site Scripting Attacks

Cross Site Scripting (XSS) attacks use web applications to inject malicious scripts or a malicious payload, generally in the form of a client side script, into trusted legitimate web applications. For more information, see the following sections that describe the impact of XSS attack and the approaches you can use to mitigate it.

Enabling HostName Verification

Hostname verification is enabled in WSO2 products by default, which means that when a hostname is being accessed by a particular client, it will be verified against the hostname specified in the product's SSL certificate.  
Configuring TLS TerminationWhen you have Carbon servers fronted by a load balancer, you have the option of terminating SSL for HTTPS requests. This means that the load balancer will be decrypting incoming HTTPS messages and forwarding them to the Carbon servers as HTTP. This is useful when you want to reduce the load on your Carbon servers due to encryption. To achieve this, the load balancer should be configured with TLS termination and the Tomcat RemoteIpValve should be enabled for Carbon servers.

Configuring multitenancy

You can create multiple tenants in your product server, which will allow you to maintain tenant isolation in a single server/cluster. For instructions on configuring multiple tenants for your server, see Working with Multiple Tenants in the WSO2 Administration Guide and to understand how multitenancy works with the API Store, see Managing Tenants.

Configuring the registry

registry is a content store and a metadata repository for various artifacts such as services, WSDLs and configuration files. In WSO2 products, all configurations pertaining to modules, logging, security, data sources and other service groups are stored in the registry by default. 

For instructions on setting up and configuring the registry for your server, see Working with the Registry in the WSO2 Administration Guide.

Performance tuning

You can optimize the performance of your WSO2 server by using configurations and settings that are suitable to your production environment. At a basic level, you need to have the appropriate OS settings, JVM settings etc. Since WSO2 products are all based on a common platform called Carbon, most of the OS, JVM settings recommended for production are common to all WSO2 products. Additionally, there will be other performance enhancing configuration recommendations that will depend on very specific features used by your product. 

For instructions on the Carbon platform-level performance tuning recommendations, see Performance Tuning in the WSO2 Administration Guide.

For instructions on performance tuning recommendations that are specific to WSO2 API Manager, see tuning performance in the WSO2 API-M Guide.

Changing the default ports

When you run multiple WSO2 products, multiple instances of the same product, or multiple WSO2 product clusters on the same server or virtual machines (VMs), you must change their default ports with an offset value to avoid port conflicts.

What is port offset?

The port offset feature allows you to run multiple WSO2 products, multiple instances of a WSO2 product, or multiple WSO2 product clusters on the same server or virtual machine (VM). The port offset defines the number by which all ports defined in the runtime such as the HTTP/S ports will be offset. For example, if the HTTP port is defined as 9763 and the portOffset is 1, the effective HTTP port will be 9764. Therefore, for each additional WSO2 product, instance, or cluster you add to a server, set the port offset to a unique value (the default is 0).

For the list of ports in all WSO2 products, see Default Ports of WSO2 Products in the WSO2 Administration Guide.

For instructions on configuring ports, see Changing the Default Ports in the WSO2 Administration Guide.

Configuring custom proxy paths

This feature is particularly useful when multiple WSO2 products (fronted by a proxy server) are hosted under the same domain name. By adding a custom proxy path you can host all products under a single domain and assign proxy paths for each product separately . 

 Click here to see how to add custom proxy paths...

Before you begin...

Follow steps 1 to 8 in the Administration guide, to install Nginx if you haven't done so already.

The sample usecase to route requests is shown below.

Some of the Nginx configuration syntaxes may slightly vary based on the Nginx version you use. The configurations below are tested with version 1.15.0.

  1. Open the /etc/nginx/sites-enabled/wso2 file and enter the following configurations.

    server {
                 listen 443 ssl;
                 ssl_certificate     nginx.crt;
                 ssl_certificate_key nginx.key;
            location ~ ^/apimanager/publisher/(.*)registry/(.*)$ {
                index index.html;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           location /apimanager/publisher {
              index index.html;
              proxy_set_header X-Forwarded-Host $host;
              proxy_set_header X-Forwarded-Server $host;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_pass https://localhost:9443/publisher;
              proxy_redirect  https://localhost:9443/publisher  https://localhost/apimanager/publisher;
              proxy_cookie_path /publisher /apimanager/publisher;
          location ~ ^/apimanager/store/(.*)registry/(.*)$ {
               index index.html;
               proxy_set_header X-Forwarded-Host $host;
               proxy_set_header X-Forwarded-Server $host;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           location /apimanager/store {
               index index.html;
               proxy_set_header X-Forwarded-Host $host;
               proxy_set_header X-Forwarded-Server $host;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_pass https://localhost:9443/store;
               proxy_redirect https://localhost:9443/store https://localhost/apimanager/store;
               proxy_cookie_path /store /apimanager/store;
           location /apimanager/admin {
               index index.html;
               proxy_set_header X-Forwarded-Host $host;
               proxy_set_header X-Forwarded-Server $host;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_pass https://localhost:9443/admin;
               proxy_redirect https://localhost:9443/admin https://localhost/apimanager/admin;
               proxy_cookie_path /admin /apimanager/admin;
  2. Configure the reverseProxy for the following. 

  3. Open the <API-M_HOME>/repository/conf/api-manager.xml file. Set the URL as shown below, to get the View in Store link on API overview tab in the API Publisher.

You have now added custom proxy paths for the API Publisher, API Store, and Admin Portal.

For instructions on configuring custom proxy paths, see Adding a Custom Proxy Path in the WSO2 Administration Guide.

Customizing error pages

You can make sure that sensitive information about the server is not revealed in error messages, by customizing the error pages in your product. 

For instructions, see Customizing Error Pages in the WSO2 Administration Guide.

Customizing the management console

Some of the WSO2 products, such as WSO2 API Manager consist of a web user interface named the management console. This allows administrators to configure, monitor, tune, and maintain the product using a simple interface. You can customize the look and feel of the management console for your product.

For instructions, see Customizing the Management Console in the WSO2 Update Manager Guide. 

Applying patches 

For information on updating WSO2 API-M with the latest available patches (issued by WSO2) using the WSO2 Update Manager (WUM) tool, see Getting Started with WUM in the WSO2 Administration Guide.

Monitoring the server

Monitoring is an important part of maintaining a product server. Listed below are the monitoring capabilities that are available for WSO2 API Manager.

  • Monitoring server logs: A properly configured logging system is vital for identifying errors, security threats and usage patterns in your product server. For instructions on monitoring the server logs, see Monitoring Logs in the WSO2 Administration Guide.
  • Monitoring using WSO2 metrics: WSO2 API Manager is shipped with JVM Metrics, which allows you to monitor statistics of your server using Java Metrics. For instructions on setting up and using Carbon metrics for monitoring, see Using WSO2 Metrics in the WSO2 Administration Guide.

  • JMX-based monitoring: For information on monitoring your server using JMX, see JMX Monitoring in the WSO2 Administration Guide.