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.

<datasource>
            <name>WSO2_CARBON_DB_mount</name>
            <description>The datasource used for registry and user manager</description>
            <jndiConfig>
                <name>jdbc/WSO2CarbonDB_mount</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:mysql://localhost:3306/governancedb</url>
                    <username>root</username>
                    <password>root123</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>

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

<dbConfig name="wso2registry_mount">
        <dataSource>jdbc/WSO2CarbonDB_mount</dataSource>
 </dbConfig>


<remoteInstance url="https://localhost:9443/registry">
        <id>instanceid</id>
        <dbConfig>wso2registry_mount</dbConfig>
        <readOnly>false</readOnly>
        <enableCache>true</enableCache>
        <registryRoot>/</registryRoot>
</remoteInstance>


<mount path="/_system/config" overwrite="true">
        <instanceId>instanceid</instanceId>
        <targetPath>/_system/config</targetPath>
    </mount>

<mount path="/_system/governance" overwrite="true">
        <instanceId>instanceid</instanceId>
        <targetPath>/_system/governance</targetPath>
</mount>

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           governance.cluster.wso2.com;
                                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">127.0.0.1</parameter>
v) Update the host file.
127.0.0.1   governance.cluster.wso2.com
vi) Start the WSO2 ELB instance.
 Go to the wso2elb-2.0.3/bin and execute the wso2server.sh 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">governance.cluster.wso2.com</parameter>
<parameter name="localMemberPort">4250</parameter>
iii) Open the axis2.xml file of node1 and add the following details of LB.
<members>
   <member>
      <hostName>127.0.0.1</hostName> <!-- LB host name-->
      <port>4000</port> <!--LB  local member port -->
   </member>
</members>
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.
<HostName>governance.cluster.wso2.com</HostName>
<MgtHostName>governance.cluster.wso2.com</MgtHostName>
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 127.0.0.1:4250(wso2.governance.domain)
[2013-02-19 01:06:55,648]  INFO - MembershipManager Application member 127.0.0.1:4250(wso2.governance.domain) joined group wso2.governance.domain
[2013-02-19 01:07:06,652]  INFO - DefaultGroupManagementAgent Application member Host:127.0.0.1, 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 127.0.0.1:4251(wso2.governance.domain)
[2013-02-19 01:11:07,423]  INFO - MembershipManager Application member 127.0.0.1:4251(wso2.governance.domain) joined group wso2.governance.domain
[2013-02-19 01:11:18,425]  INFO - DefaultGroupManagementAgent Application member Host:127.0.0.1, Port: 4251, HTTP:9765, HTTPS:9445, Domain: wso2.governance.domain, Sub-domain:null, Active:true joined application cluster

ix) Point your browser to https://governance.cluster.wso2.com:8243/carbon .

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 : http://sdrv.ms/VsgfVl

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.
Eg:
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
Certificate[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” http://blog.facilelogin.com/2008/03/keystore-management-part-i.html 

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.
<KeyStore>

<Location>${carbon.home}/repository/resources/security/companykeystore.jks</Location>

<Type>JKS</Type>

<Password>companypkpassword</Password>

<KeyAlias>ABCcompanycert</KeyAlias>

<KeyPassword>companypkpassword</KeyPassword>

</KeyStore>
  

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

keystoreFile="${carbon.home}/repository/resources/security/companykeystore.jks"

keystorePass="companypkpassword"


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 wso2server.sh -Dcarbon.registry.character.encoding=Windows-1251

Windows:
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]

[1]http://docs.wso2.org/wiki/display/Governance450/Supported+System+Properties