Page Comparison

WSO2 API Manager is a complete API management solution, used for creating and publishing APIs, creating and managing a developer community, and scalably routing API traffic. The API Manager solution includes a Publisher, Store, Gateway, and Key Manager component.

...

Download and install MySQL Server.
Download the MySQL JDBC driver.
Unzip the downloaded MySQL driver zipped archive, and copy the MySQL JDBC driver JAR (mysql-connector-java-x.x.xx-bin.jar) into the <PRODUCT_HOME>/repository/components/lib directory of all the nodes in the cluster.
Define the host name for configuring permissions for the new database by opening the /etc/hosts file and adding the following line:
```
<MYSQL-DB-SERVER-IP> carbondb.mysql-wso2.com
```
Info
You would do this step only if your database is not on your local machine and on a separate server.
Enter the following command in a terminal/command window, where username is the username you want to use to access the databases:
mysql -u username -p
When prompted, specify the password that will be used to access the databases with the username you specified.

Create the three databases using the following commands, where <APIM_HOME> is the path to any of the API Manager instances you installed, and username and password are the same as those you specified in the previous steps.

Info

title	About using MySQL in different operating systems

For users of Microsoft Windows, when creating the database in MySQL, it is important to specify the character set as latin1. Failure to do this may result in an error (error code: 1709) when starting your cluster. This error occurs in certain versions of MySQL (5.6.x) and is related to the UTF-8 encoding. MySQL originally used the latin1 character set by default, which stored characters in a 2-byte sequence. However, in recent versions, MySQL defaults to UTF-8 to be friendlier to international users. Hence, you must use latin1 as the character set as indicated below in the database creation commands to avoid this problem. Note that this may result in issues with non-latin characters (like Hebrew, Japanese, etc.). The following is how your database creation command should look.

mysql> create database <DATABASE_NAME> character set latin1;

For users of other operating systems, the standard database creation commands will suffice. For these operating systems, the following is how your database creation command should look.

mysql> create database <DATABASE_NAME>;

Code Block

language	none

mysql> create database apimgtdb;
mysql> use apimgtdb;
mysql> source <APIM_HOME>/dbscripts/apimgt/mysql.sql;
mysql> grant all on apimgtdb.* TO username@localhost identified by "password";


mysql> create database userdb;
mysql> use userdb;
mysql> source <APIM_HOME>/dbscripts/mysql.sql;
mysql> grant all on userdb.* TO username@localhost identified by "password";


mysql> create database regdb;
mysql> use regdb;
mysql> source <APIM_HOME>/dbscripts/mysql.sql;
mysql> grant all on regdb.* TO username@localhost identified by "password";

Note
Ensure that MySQL is configured so that all nodes can connect to it.

Configure the data sources for the three database as follows:

Open the <APIM_HOME>/repository/conf/datasources/master-datasources.xml file in all four API Manager components.

Enable the components to access the API Manager database by modifying the WSO2AM_DB data source in the master-datasources.xml files in the Publisher, Store and Key Manager nodes as indicated below.

Code Block

language	none

<datasource>
 <name>WSO2AM_DB</name>
 <description>The datasource used for the API Manager database</description>
 <jndiConfig>
   <name>jdbc/WSO2AM_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://apimgtdb.mysql-wso2.com:3306/apimgtdb?autoReconnect=true</url>
     <username>user</username>
     <password>password</password>
     <defaultAutoCommit>false</defaultAutoCommit>
     <driverClassName>com.mysql.jdbc.Driver</driverClassName>
     <maxActive>50</maxActive>
     <maxWait>60000</maxWait>
     <testOnBorrow>true</testOnBorrow>
     <validationQuery>SELECT 1</validationQuery>
     <validationInterval>30000</validationInterval>
   </configuration>
 </definition>
</datasource>

Enable the Key Manager, Publisher, and Store components to access the users database by configuring the WSO2UM_DB data source in their master-datasources.xml files as follows:

Code Block

language	none

<datasource>
 <name>WSO2UM_DB</name>
 <description>The datasource used by user manager</description>
 <jndiConfig>
   <name>jdbc/WSO2UM_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://userdb.mysql-wso2.com:3306/userdb?autoReconnect=true</url>
     <username>user</username>
     <password>password</password>
     <driverClassName>com.mysql.jdbc.Driver</driverClassName>
     <maxActive>50</maxActive>
     <maxWait>60000</maxWait>
     <testOnBorrow>true</testOnBorrow>
     <validationQuery>SELECT 1</validationQuery>
     <validationInterval>30000</validationInterval>
   </configuration>
 </definition>
</datasource>

Enable the Publisher and Store components to access the registry database by configuring the WSO2REG_DB data source in their master-datasources.xml files as follows:

Code Block

language	none

<datasource>
 <name>WSO2REG_DB</name>
 <description>The datasource used by the registry</description>
 <jndiConfig>
   <name>jdbc/WSO2REG_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://regdb.mysql-wso2.com:3306/regdb?autoReconnect=true</url>
     <username>user</username>
     <password>password</password>
     <driverClassName>com.mysql.jdbc.Driver</driverClassName>
     <maxActive>50</maxActive>
     <maxWait>60000</maxWait>
     <testOnBorrow>true</testOnBorrow>
     <validationQuery>SELECT 1</validationQuery>
     <validationInterval>30000</validationInterval>
   </configuration>
 </definition>
</datasource>

Modify the /etc/hosts entries to map the IP addresses to the data source URLs:

- 127.0.0.1 apimgtdb.mysql-wso2.com
- 127.0.0.1 userdb.mysql-wso2.com
- 127.0.0.1 regdb.mysql-wso2.com

To give each of the components access to the API Manager database, open the <APIM_HOME>/repository/conf/api-manager.xml file in each of the components and add the following line as the first child node of the root element (if it is not already there):
<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

To give the Key Manager, Publisher, and Store components access to the users database with shared permissions, open the <APIM _HOME>/repository/conf/user-mgt.xml file in each of these three components and add or modify the dataSource property of the <configuration> element as follows:

Code Block

language	none

<configuration> 
...
	<Property name="dataSource">jdbc/WSO2UM_DB</Property>
</configuration>
 
<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
	<Property name="TenantManager">org.wso2.carbon.user.core.tenant.JDBCTenantManager</Property>
    <Property name="ReadOnly">false</Property>
    <Property name="MaxUserNameListLength">100</Property>
    <Property name="IsEmailUserName">false</Property>
    <Property name="DomainCalculation">default</Property>
    <Property name="PasswordDigest">SHA-256</Property>
    <Property name="StoreSaltedPassword">true</Property>
    <Property name="ReadGroups">true</Property>
    <Property name="WriteGroups">true</Property>
    <Property name="UserNameUniqueAcrossTenants">false</Property>
    <Property name="PasswordJavaRegEx">^[\S]{5,30}$</Property>
    <Property name="PasswordJavaScriptRegEx">^[\S]{5,30}$</Property>
    <Property name="UsernameJavaRegEx">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
    <Property name="UsernameJavaScriptRegEx">^[\S]{3,30}$</Property>
    <Property name="RolenameJavaRegEx">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
    <Property name="RolenameJavaScriptRegEx">^[\S]{3,30}$</Property>
    <Property name="UserRolesCacheEnabled">true</Property>
    <Property name="MaxRoleNameListLength">100</Property>
    <Property name="MaxUserNameListLength">100</Property>
    <Property name="SharedGroupEnabled">false</Property>
    <Property name="SCIMEnabled">false</Property>
</UserStoreManager>

To give the Publisher and Store components access to the registry database, open the <APIM_HOME>/repository/conf/registry.xml file in each of these two components and configure them as follows:

Info
Although it is mentioned that you need to do this on the Publisher and Store components only, if you are planning to create this setup for a multi-tenanted environment (create and work with tenants), it is required to perform the steps below on the Gateway and Key-Manager components as well.

Note

Note: Do not replace the following configuration when adding in the mounting configurations. The registry mounting configurations mentioned in the below steps must be added in addition to the following.

Code Block
<dbConfig name="wso2registry"> <dataSource>jdbc/WSO2CarbonDB</dataSource> </dbConfig>

In the Publisher component's registry.xml file, add or modify the dataSource attribute of the <dbConfig name="govregistry"> element as follows:

Code Block

language	none

<dbConfig name="govregistry">
  <dataSource>jdbc/WSO2REG_DB</dataSource>
</dbConfig>
<remoteInstance url="https://publisher.apim-wso2.com"> 
   <id>gov</id>
   <cacheId>user@jdbc:mysql://regdb.mysql-wso2.com:3306/regdb</cacheId>
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/config</targetPath>
</mount>

In the Store component's registry.xml file, add or modify the dataSource attribute of the <dbConfig name="govregistry"> element as follows (note that this configuration is nearly identical to the previous step with the exception of the remoteInstance URL):

Code Block

language	none

<dbConfig name="govregistry">
  <dataSource>jdbc/WSO2REG_DB</dataSource>
</dbConfig>
<remoteInstance url="https://store.apim-wso2.com"> 
   <id>gov</id>
   <cacheId>user@jdbc:mysql://regdb.mysql-wso2.com:3306/regdb</cacheId> 
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/config</targetPath>
</mount>

Modify the /etc/hosts entries to map the relevant IP addresses to the remoteInstance URLs.

- 127.0.0.1 publisher.apim-wso2.com
- 127.0.0.1 store.apim-wso2.com

Once registry caching is enabled, sync the published APIs between the Publisher and Store nodes by enabling clustering in both Store and Publisher nodes. To do this, open the <APIM_HOME>/repository/conf/axis2/axis2.xml file in each of these two components and configure them as follows:
<clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="true">

...

You will now configure the inter-component relationships illustrated in the following diagram by modifying their <APIM_HOME>/repository/conf/api-manager.xml files.

Note

In a clustered environment, you use Session Affinity to ensure that requests from the same client always get routed to the same server.
It is mandatory to set up Session Affinity in the Load Balancers when it is fronting the Publisher and Store clusters and it is not mandatory when configuring a Key Manager cluster with a Load Balancer. However, authentication via session ID fails when Session Affinity is disabled in the Load Balancer.
The Key Manager first tries to authenticate the request via the session ID. If it fails, the Key Manager tries to authenticate via basic authentication.

Open the <APIM_HOME>/repository/conf/api-manager.xml files in the Gateway, Publisher, Key Manager and Store components.

Modify each of the files as follows:

Key Manager:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>http://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0 and 1.7.0

Configure the <RevokeAPIURL> element in the api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node.

Code Block

<RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}/revoke</RevokeAPIURL>
...
<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>http://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.6.0 and 1.5.0

No changes required in the Key Manager node.

Gateway: configure the connection to the Key Manager component as follows:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<APIKeyValidator> 
  <ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
  <Username>admin</Username>
  <Password>admin</Password>
  ...
</APIKeyValidator>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Code Block

language	none

<APIKeyManager> 
  <ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
  <Username>admin</Username>
  <Password>admin</Password>
  ...
</APIKeyManager>

Publisher: configure connections to the Key Manager and Gateway as follows:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<APIKeyValidator>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyValidator>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Configure the <RevokeAPIURL> element in the api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node.

Code Block

language	none

<APIKeyManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyManager>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Info
Creating a connection to the Key Manager from the Publisher is required in API Manager 1.3.0 but is no longer required from API Manager 1.4.0 onwards.

Store

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<RevokeAPIURL>https://<IP of the Gateway>:8243/revoke</RevokeAPIURL>
 
 
<APIKeyValidator>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyValidator>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Code Block

language	none

<APIKeyManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyManager>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Tip
Tip: For more information on how different environment types, see Maintaining Separate Production and Sandbox Gateways. This is useful when configuring environments in different geographical locations.

...

Versions Compared

Old Version 125

New Version Current

Key