Skip to end of metadata
Go to start of metadata
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. The default HTTP and HTTPS ports (without offset) of a WSO2 product are 9763 and 9443 respectively. Port offset defines the number by which all ports defined in the runtime such as the HTTP/S ports will be changed. For example, if the default HTTP port is 9763 and the port offset is 1, the effective HTTP port will change to 9764. For each additional WSO2 product instance, you set the port offset to a unique value. The default port offset is 0.

There are two ways to set an offset to a port as follows.

  • Pass the port offset to the server during startup. The following command starts the server with the default port incremented by 3:./wso2server.sh -DportOffset=3
  • Set the Ports section of <PRODUCT_HOME>/repository/conf/carbon.xml as follows: <Offset>3</Offset>

Usually, when you offset the port of the server, all ports it uses are changed automatically. However, there are few exceptions as follows in which you have to change the ports manually according to the offset as follows.

Changing endpoints of default APIs

After offsetting a port, be sure to edit any hard-coded endpoints used in a product, if there are any, according to the offset. There are few default APIs deployed in the App Manager with hard-coded endpoints. For example, the Login API's Token endpoint URL is hardcoded as follows: <address uri="https://localhost:9443/oauth2endpoints/token">. If you offset the Key Manger node's port by 2, change the token endpoint URL to <address uri=" https://localhost:9445/oauth2endpoints/token"/>.

Find all default APIs of the App Manager in the <AppM_HOME>/repository/deployment/server/synapse-configs/default/api/ directory. Few examples are Authorize API, Login API, Token API and Revoke API.

Changing the App Manager configurations

After offsetting a port, you need to replace the default value of the following configurations with the new port in the <AppM_HOME>/repository/conf/app-manager.xml file.

Changing the Thrift client and server ports

The port offset specified earlier in the <AppM_HOME>/repository/conf/carbon.xml file does not affect the ports of the Thrift client and server because Thrift is run as a separate server within WSO2 servers. Therefore, you must change the Thrift ports separately using <ThriftClientPort> and <ThriftServerPort> elements in the <AppM_HOME>/repository/conf/app-manager.xml file. For example, the following configuration sets an offset of 2 to the default Thrift port, which is 10397:

        Configurations related to enable thrift support for key-management related communication.
        If you want to switch back to Web Service Client, change the value of "KeyValidatorClientType" to "WSClient".
        In a distributed environment;
        -If you are at the Gateway node, you need to point "ThriftClientPort" value to the "ThriftServerPort" value given at KeyManager node.
        -If you need to start two App Manager instances in the same machine, you need to give different ports to "ThriftServerPort" value in two nodes.
        -ThriftServerHost - Allows to configure a hostname for the thrift server. It uses the carbon hostname by default.


When you run multiple instances of the App Manager in distributed mode, the Gateway and Key Manager (used for validation and authentication) can run on two different JVMs. When the API Gateway receives API invocation calls, it contacts the API Key Manager service for verification (given that caching is not enabled at the Gateway level). Communication between API Gateway and Key Manager happens in either of the following ways:  

  • Through a Web service call
  • Through a Thrift call

The default communication mode is using Thrift. Assume that the Gateway port is offset by 2, Key Manager port by 5 and the default Thrift port is 10397. If the Thrift ports are changed by the offsets of Gateway and Key Manager, the Thrift client port (Gateway) will now be 10399 while the Thrift server port (Key Manager) will change to 10402. This causes communication between the Gateway and Key Manager to fail because the Thrift client and server ports are different.

To fix this, you must change the Thrift client and server ports of Gateway and Key Manager to the same value. In this case, the difference between the two offsets is 3, so you can either increase the default Thrift client port by 3 or else reduce the Thrift server port by 3.

Changing the entitlement service configuration

In the <AppM_HOME>/repository/conf/app-manager.xml file, change the default port value (i.e. 9443) of the <ServerUrl> parameter under the <EntitlementServiceConfiguration> property. For example, if you set a port offset of 2, change the configurations as follows.


Changing the SSO configuration

In the <AppM_HOME>/repository/conf/app-manager.xml file, change the default port value (i.e. 9443) of the <providerURL> parameter under the <SSOConfiguration> property. For example, if you set a port offset of 2, change the configurations as follows.

        <!-- URL of the IDP use for SSO -->

Changing the offset of the Workflow Callback Service

The App Manager has a service which listens for workflow callbacks. Find this service configuration at <AppM_HOME>/repository/deployment/server/synapse-configs/default/proxy-services/WorkflowCallbackService.xml. Open this file and change the port value of the <address uri> accordingly. 

For example,

<address uri="https://localhost:9445/store/site/blocks/workflow/workflow-listener/ajax/workflow-listener.jag" format="rest"/>

Changing the SSO IDP configurations

In the <AppM_HOME>/repository/conf/identity/sso-idp-config.xml file, change the default port value (i.e. 9443) in the URL, which is defined as the value of the <AssertionConsumerService> property in each of the <Issuer> types. For example, if you set a port offset of 2, change the values of the <AssertionConsumerService> properties of the store, social, and publisher service provider issuers as follows.

  • https://<AppM_HOST>:9445/store/acs
  • https://<AppM_HOST>:9445/social/acs
  • https://<AppM_HOST>:9445/publisher/acs
  • No labels