Wednesday, December 5, 2012

How to create a Governance Registry cluster with WSO2 ELB.

G-Reg clustering is different from the usual clustering from other WSO2 products like ESB, AS,..etc. Therefore, this blog post is to provide the basic guide for this. Following details are based on WSO2 Governance Registry 4.5.3 and WSO2 ELB 2.0.3.

wso2 Governance Registry Clustering.

1.We are going to use MySQL as the registry database, but MySQL cluster is  most suitable for the production deployment.

Open a terminal and log-in to the MySQL server.

create database governancedb;

mysql -u root -p governancedb   < wso2greg-4.5.3/dbscripts/mysql.sql

2. Create JDBC mounts(Config and Governance registry spaces) from all the "Read Write" G-Reg nodes to registry database("governancedb") of the cluster.

i) Open the master-datasources.xml file under wso2greg-4.5.3/repository/conf/datasources. Add the following <datasource> config under <datasources> configs.

            <description>The datasource used for registry and user manager</description>
            <definition type="RDBMS">
                    <validationQuery>SELECT 1</validationQuery>

ii) Add following configs to registry.xml file under wso2greg-4.5.3/repository/conf.

<dbConfig name="wso2registry_mount">

<remoteInstance url="https://localhost:9443/registry">

<mount path="/_system/config" overwrite="true">

<mount path="/_system/governance" overwrite="true">

iii) Open the axis2.xml file under wso2greg-4.5.3/repository/conf/axis2 and enable clustering.

 (G-Reg use local instance cache and cache invalidation messages to update the cache across the cluster nodes. Axis2 cluster messages are used to send those invalidation messages)

<clustering class="org.apache.axis2.clustering.tribes.TribesClusteringAgent" enable="true">

iv) If you are going to run the multiple G-Reg servers in same machine, you should change the port <Offset> value in carbon.xml file to avoid the port conflicts.

3. All the G-reg nodes in cluster  are used embedded H2 as the local registry.
(No need additional configurations, because default database settings are configured to embedded H2 database.)

4. Copy the mysql jdbc driver to wso2greg-4.5.3/repository/components/lib.

5. Configure the WSO2 Load balance server in front of the G-Reg nodes.

i) Download the WSO2 Elastic Load Balancer(WSO2 ELB).

ii) Open the loadbalancer.conf file under wso2elb-2.0.3/repository/conf.

iii) Add the governance service under <services> config.

governance {
                domains {

                        wso2.governance.domain {
                                hosts ;
                                tenant_range    *;

iv) Open the axis2.xml file and add configure the  localMemberHost.(This is to be exposed to members of the cluster.)
<parameter name="localMemberHost"></parameter>
v) Update the host file.
vi) Start the WSO2 ELB instance.
 Go to the wso2elb-2.0.3/bin and execute the or wso2server.bat.

6. Configure Governance Registry nodes.

i) Open axis2.xml of G-Reg node1 and configure the "membershipScheme" as "wka".
<parameter name="membershipScheme">wka</parameter>
ii) Configure the "domain" ,"localMemberHost", and "localMemberPort" as follow in the axis2.xml.
<parameter name="domain">wso2.governance.domain</parameter>
<parameter name="localMemberHost"></parameter>
<parameter name="localMemberPort">4250</parameter>
iii) Open the axis2.xml file of node1 and add the following details of LB.
      <hostName></hostName> <!-- LB host name-->
      <port>4000</port> <!--LB  local member port -->
iv) Open the catalina-server.xml file of node1 and add the proxyPort attribute in
HTTP and HTTPS connectors as shown below.

  In HTTP Connector : proxyPort="8280"
  In HTTPS Connector : proxyPort="8243"

 v) Update the  "HostName" and  "MgtHostName" element in carbon.xml as shown below.
vi)Open the user-mgt.xml file of node1 and update the "datasource" property as follow. Now user manager tables also will create in "governancedb".
<Property name="dataSource">jdbc/WSO2CarbonDB_mount</Property>

vi) Repeat the same steps for node2 and node3 (You only need to change the value of the "localMemberPort" to 4251 and 4252 in axis2.xml).

vii) Start  the G-Reg node1 ,node2 & node3.

viii) After started the node1 and node2, you should see the following type of logs in LB console.
2013-02-19 01:06:55,647]  INFO - RpcMembershipRequestHandler Received JOIN message from
[2013-02-19 01:06:55,648]  INFO - MembershipManager Application member joined group wso2.governance.domain
[2013-02-19 01:07:06,652]  INFO - DefaultGroupManagementAgent Application member Host:, Port: 4250, HTTP:9764, HTTPS:9444, Domain: wso2.governance.domain, Sub-domain:null, Active:true joined application cluster

[2013-02-19 01:11:07,423]  INFO - RpcMembershipRequestHandler Received JOIN message from
[2013-02-19 01:11:07,423]  INFO - MembershipManager Application member joined group wso2.governance.domain
[2013-02-19 01:11:18,425]  INFO - DefaultGroupManagementAgent Application member Host:, Port: 4251, HTTP:9765, HTTPS:9445, Domain: wso2.governance.domain, Sub-domain:null, Active:true joined application cluster

ix) Point your browser to .

Note: You can set up  WSO2 ELB cluster to achieve the high availability of the LB layer.

If you are going to use any other load balancer , then you only need the above (1),(2),(3) & (4) steps.  after that you can set up your own load balancer in front of the G-Reg nodes to make the accessibility through the single URL to handle the high load. 

If you need to achieve the high availability, then you can create the virtual IP and server pool to include the G-Reg servers.

Download the sample configs :

Monday, December 3, 2012

How to add new keystore to Carbon 4 based wso2 products.

All the wso2 carbon based products are shipping with default keystore called wso2carbon.jks.
You can be found it under PRODUCT_HOME/repository/resources/security. 
This keystore is used to communicate over SSL , encrypting security related information.

1. Create new keystore.

The Keystore is using to store the private key and certificates with their public keys.
Here, I'm going to use keytool functions, which is default shipped with your JDK installation.
Open a command window and execute the following command.

keytool -genkey -alias companycert -keyalg RSA -keysize 1024 -keypass companypkpassword -keystore companykeystore.jks -storepass companypkpassword

New keystore name = companykeystore.jks

Alias of the public certificate = companycert

Keystore password = companypkpassword (same password used as private key password)

You have to provide required info to generate the key store.
What is your first and last name?

[Unknown]: Ajith Vitharana

What is the name of your organizational unit?

[Unknown]: Engineering

What is the name of your organization?

[Unknown]: ABC

What is the name of your City or Locality?

[Unknown]: Colombo

What is the name of your State or Province?

[Unknown]: Western

What is the two-letter country code for this unit?

[Unknown]: LK

Is CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK correct?

[no]: yes

Now you can find the companykeystore.jks in the same location that you execute the command.  If you want to view the content of the new key store ,execute the following command.

keytool -list -v -keystore companykeystore.jks -storepass companypkpassword

Sample output :
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: companycert
Creation date: Dec 4, 2012
Entry type: PrivateKeyEntry
Certificate chain length: 1
Owner: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Issuer: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Serial number: 50bd3295
Valid from: Tue Dec 04 04:45:33 IST 2012 until: Mon Mar 04 04:45:33 IST 2013
Certificate fingerprints:
     MD5:  75:AE:2B:41:DF:C5:2A:D8:A2:D6:89:66:F0:1B:E4:EC
     SHA1: 52:35:50:EA:5D:6C:5A:27:AB:01:56:48:9F:97:48:CA:FB:5F:48:BC
     Signature algorithm name: SHA1withRSA
     Version: 3


2. Public certificate signed by CA.

We are recommend to get your public certificate signed by a CA. However for the testing purpose we are going to use the self signed certificate.

Note : Please find more details on this blog post on “get public certificate signed by CA” 

3. Export public key certificate.
keytool -export -alias companycert -keystore companykeystore.jks -storepass companypkpassword -file ABCcompanycert.pem

Now you can find the public certificate(ABCcompanycert.pem) in same directory that you execute the command. 

4. Import public key to client trust store. 
The trust store is using to store the certificates of other parties that are suppose to communicate, or of  CAs(Certificate Authorities) that we trust to identify other parties.

Now, we should import this public key in to the client trust store.
i) Copy companykeystore.jks and ABCcompanycert.pem file to PRODUCT_HOME/repository/resources/security

ii) Locate your command line window to PRODUCT_HOME/repository/resources/security.

iii) Execute the following command to import the public certificate to client truststore(client-truststore.jks).
keytool -import -alias compantcert -file ABCcompanycert.pem -keystore client-truststore.jks -storepass wso2carbon
(wso2carbon = client truststore password)

Sample results:

Owner: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Issuer: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Serial number: 50bd0961
Valid from: Tue Dec 04 01:49:45 IST 2012 until: Mon Mar 04 01:49:45 IST 2013
Certificate fingerprints:
     MD5:  B8:6B:79:CA:6F:1D:4A:D3:04:64:8E:D7:C4:96:6A:BC
     SHA1: A1:48:1B:FC:8F:D8:69:B0:F3:3E:4B:EC:83:62:11:D6:63:71:1D:D8
     Signature algorithm name: SHA1withRSA
     Version: 3
Trust this certificate? [no]:  yes
Certificate was added to keystore
5) Change the key store configuration in carbon.xml

Open the carbon.xml file and change the default key store configuration as follow.







6) Open the PRODUCT_HOME/repository/conf/tomcat/catalina-server.xml and change keystoreFile and keystorePass  



7) Find inside the conf directory ( PRODUCT_HOME/repository/conf) for "wso2carbon.jks" to locate the all the other places having default key store configurations (axis2.xml, identity.xml ..etc), then configure that locations as well.

8) Start the Wso2 Carbon based product. 

9) Locate your browser to https://localhost:9443/carbon.

10) Now you should see the "Security Certificate Not Trusted" warning, because this is self signed certificate.

11) View the certificate details.
 12) Login to the admin console and navigate to Configure--> Keystore.
        Now you can view the details of companykeystore.jks .



Sunday, December 2, 2012

How to use Governance Registry with Non-English characters.

If you want to use Governance Registry with Non-English(Chinese , Russian , Spanish, ..etc ) characters, you can follow the one of the following method as a solution.

1) Firs
t approach :

Add -Dfile.encoding="UTF8" property as a command line argument in the startup scrip.

Eg:  In Windows.

Eg : In Linux

2) Second approach :

Start the Governance Registry with the proper encoding type of the characters

-Dcarbon.registry.character.encoding={Encoding type of the characters}
Eg: If you want to use Cyrillic characters,  start the Governance Registry with following system property.

Linux :
sh -Dcarbon.registry.character.encoding=Windows-1251

wso2server.bat  -Dcarbon.registry.character.encoding=Windows-1251

(Windows-1251 is the encoding type of the Cyrillic characters)

*Please see the more details on documentation [1]


Wednesday, November 21, 2012

How to install "Webseal based authenticator feature" to WSO2 Governance Registry.

The Equinox P2 has integrated with WSO2 Carbon. Therefore it provides the  provisioning capabilities by allowing users to install new features(or remove existing feature) to any Carbon based product. This is the recommended way to customize the default product.

1) Add p2-repo

Go to the Configure --> Features and add the p2-repository.

2) Add the remote repository name and the URL.

     Name : any value
     Location :

3) Select the newly added repository and find the features.

4) Expand the Identity server feature and select the "Webseal based authenticator feature". Now you can install that feature.

5) Accept the license agreement and install.

6) After complete the installation restart the server.

Note: If you want to verify the installation you can start the Governance Registry server with OSGI console (sh -DosgiConsole). After successfully started press enter. Now you will be able to see the OSGI console.

i) Execute the "ss" command to list jars. (type ss and press enter).

ii) Now you can see the jars which are related to "Webseal authenticator feature" are in "activate" state.

** You can follow the above steps to install any feature to any Carbon based product. 

How to configure WSO2 Governance Registry with Webseal

The main objective of this blog post is to provide the necessary steps to configure WSO2 Governance Registry with the IBM Webseal.

1) Configure the Governance Registry.

i) Download the WSO2 Governance Registry (4.5.0) from here.

ii) Copy the Webseal authentication jars to the GREG_HOME/repository/components/dropins.

Jars location :

(Or you can install "Webseal based authenticator  feature" from the p2-repo, because it is not  shipped with Governance Registry.)

iii) Open the authenticators.xml which is reside the GREG_HOME/repository/conf/security and add the following entry.
<Authenticator disabled="false" name="WebSealUIAuthenticator">
iv) Start the Governance Registry server.

v) Login to the management console using default user name and password (admin and admin).

vi) Go to the Configure → users and roles , and create a new user called “webSealUser”.

vii) Go to the Configure → users and roles and create a new role called “delegated-admin” and assign the “webSealUser” to this role.

Note: This user name and it's password will be used by Webseal to authenticate to Governance Registry server.

vii) Grant “login” permission to the “everyone” role.

2) Configure the IBM WebSeal.

i) Add the above user name and password to the iv.conf file in Webseal.


Note : Those values will be set as the headers in the request that is going from the Webseal to Governance Registry server.

ii) You should add the login redirect page to

Note: This is the URL which is going to be redirected after login to the Webseal.

3) Test without Webseal setup

Here, we are going to create the request manually that is going from Webseal to Governance Registry.
I'm going to use “Modify Header” plugin [1] in  Firefox browser.


We can inject the required headers(iv-user and Authorization) to the request using this plugin.

i) Install that plugin to your browser and open the plugin.

ii) Add the following two headers.

Name : iv-user
Value : name of the user who is going to login to Governance Registry.

Name: Authorization
Value: Basic <Base 64 encoded value of the webSealUser:password>

Eg :

If the user name of the delegated-admin is “webSealUser” and password is “123456” then you should generate the value of the Authorization header using webSealUser:123456 .

You can use some online services[2] to easily generate the value of the Authorization header.

Note: You should click on the “Start” button of the plugin window.

Iii) Restart the browser.

iii) Point your browser to the

iv) Now you should be able to login to the Governance Registry server without see the login page :) .


Tcpmon view.