How to hide your application name using nginx proxy_pass directive

For the showcase purpose I will be using the store application which resides inside WSO2 API Manager 2.1.0

Following are API Manager specific configs which needs to be done.

1. Set proxyPort attribute for connector configs resides in <AM_HOME>/repository/conf/tomcat/catalina-server.xml file.

        <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
                   port="9763"
                   redirectPort="9443"
                   proxyPort="80"
                   bindOnInit="false"
                   maxHttpHeaderSize="8192"
         />

        <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
                   port="9443"
                   proxyPort="443"
                   bindOnInit="false"
                   sslProtocol="TLS"
                   maxHttpHeaderSize="8192"
          />

Note that I have removed some attributes for brevity.

2. Update reverseProxy configuration resides inside <AM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json

    "reverseProxy" : {
        "enabled" : true, 
        "host" : "localhost",
        "context":"",
    }

After above changes start/restart the AM node.


Now the Nginx configuration,

Make sure to generate and store SSL certificate and the key within /etc/nginx/ssl directory.

For the explanation purpose I will be having two server blocks, which can be consolidated to a one.

server{
    listen 80;
    server_name localhost;
    location / {
            proxy_pass http://localhost:9763/store/;
            proxy_redirect off;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP      $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            include /etc/nginx/proxy_params;
            proxy_cookie_path ~*^/.* /;
    }
}
server{
    listen 443 ssl;
    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;
    server_name localhost;
    location / {
            proxy_pass https://localhost:9443/store/;
            proxy_redirect off;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP      $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            include /etc/nginx/proxy_params;
            proxy_cookie_path ~*^/.* /;
    }
}

After reloading the newly added config browse https://localhost or https://localhost,

Firebird sample with WSO2 DSS

I'm going to provide instructions to showcase how we can use Firebird data-source with WSO2 DSS.

Note:
I will be using the employee database(/opt/firebird/examples/empbuild/employee.fdb) which is available by-default with the Firebird 2.5.7  in this post.

Following are the Firebird/JDBC driver and WSO2 DSS versions which I have tried.

• Firebird: 2.5.X
• JDBC Driver: jaybird-full-2.2.12
• WSO2 DSS: 3.5.1

Steps:

1. Download the JDBC driver for Firebird and copy into the <DSS_HOME>/repository/components/lib/ directory.
2. Start the DSS node.(or restart if it's already started)
3. Add a new Data Service with the following configuration.

Datasource type: RDBMS

Database Engine: Generic

Driver Class: org.firebirdsql.jdbc.FBDriver

URL: jdbc:firebirdsql://localhost:3050//opt/firebird/examples/empbuild/employee.fdb

* Provide Host, Port, Database Path, User Name, Password accordingly.

Create and test the Datasource connection.

Save and proceed next, to add the query

select EMP_NO,FIRST_NAME,
LAST_NAME,PHONE_EXT,HIRE_DATE,DEPT_NO,SALARY from employee where EMP_NO=:EMP_NO

Add Input/Output mappings accordingly.

Save and proceed next, to add the operation.

 

Save and finish.

Now if you go to the Home> Manage> Services> List> firebirdTest> Edit Data Source(XML Edit) you can see the following Data Service definition.

<data disableStreaming="true" name="firebirdTest" transports="http https local">
   <config enableOData="false" id="emp">
      <property name="driverClassName">org.firebirdsql.jdbc.FBDriver</property>
      <property name="url">jdbc:firebirdsql://localhost:3050//opt/firebird/examples/empbuild/employee.fdb</property>
      <property name="username">SYSDBA</property>
      <property name="password">admin</property>
   </config>
   <query id="select" useConfig="emp">
      <sql>select EMP_NO,FIRST_NAME,&#xd;LAST_NAME,PHONE_EXT,HIRE_DATE,DEPT_NO,SALARY from employee where EMP_NO=:EMP_NO</sql>
      <result element="Entries" rowName="Entry">
         <element column="EMP_NO" name="EMP_NO" xsdType="string"/>
         <element column="FIRST_NAME" name="FIRST_NAME" xsdType="string"/>
         <element column="LAST_NAME" name="LAST_NAME" xsdType="string"/>
         <element column="PHONE_EXT" name="PHONE_EXT" xsdType="string"/>
         <element column="HIRE_DATE" name="HIRE_DATE" xsdType="string"/>
         <element column="DEPT_NO" name="DEPT_NO" xsdType="string"/>
         <element column="SALARY" name="SALARY" xsdType="string"/>
      </result>
      <param name="EMP_NO" sqlType="STRING"/>
   </query>
   <operation disableStreaming="true" name="getEmp">
      <call-query href="select">
         <with-param name="EMP_NO" query-param="EMP_NO"/>
      </call-query>
   </operation>
</data>

How to test the data-service(Try-it tool)

Go to Home> Manage> Services> List> firebirdTest> Try this service.

Provide the EMP_NO and press send.

Further information on query/input and output mappings/operation can be found here.

WSO2 ESB Mutual SSL - Certificate exchange

We need to consider two scenarios here.

1. External system act as a client to ESB. 
     Eg:- SOAP UI invoking ESB proxy

2. External system is a server to ESB.
    EG:- ESB invoking external service

Following image depicts all certificate exchange steps to cater above scenarios.

Build Carbon Application(capp) for WSO2 DAS

You need to work with multiple artifact types while working with WSO2 DAS. Following is a list of artifacts supported in WSO2 DAS, (Tried both DAS 3.0.0 and 3.0.1)

• Event Streams
• Event Stores
• Even Receivers
• Analytic Scripts
• Execution Plans
• Gadgets
• Layouts
• Dashboards

Rather than deploying these artifacts one by one we can deploy a set of artifacts using a single deployable artifact, Carbon Application (capp)[1]. Here what we do is, create an archive with .car extension and deploy using management console.

But there can be usecases where we need to build above archive programmatically, using a build tool. Here I’m using Maven to fulfil above requirement.

Assume we have all artifacts within das-capp directory,

.

├── das-capp

│   ├── artifacts.xml

│   ├── Dashboard_1.0.0

│   ├── Eventreceiver_1.0.0

│   ├── Eventstore_1.0.0

│   ├── Eventstream_1.0.0

│   ├── GadgetTotalDailyViews_1.0.0

│   ├── GadgetViewsPreviousmonth_1.0.0

│   ├── GagdetPageFilter_1.0.0

│   ├── Layout_1.0.0

│   └── Sparkscripts_1.0.0

└── pom.xml

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

 <modelVersion>4.0.0</modelVersion>

 <groupId>org.wso2.das.example</groupId>

 <artifactId>das-capp</artifactId>

 <version>1.0.0-SNAPSHOT</version>

 <packaging>pom</packaging>

 <name>DAS CAR</name>

 <description>This project contains artifacts to process and display sample capp</description>

 <properties>

    <artifact.types>jaggery/app=zip,service/rule=aar,lib/library/bundle=jar,event/receiver=xml,synapse/message-processors=xml,synapse/endpointTemplate=xml,synapse/message-store=xml,synapse/proxy-service=xml,event/execution-plan=siddhiql,carbon/application=car,registry/resource=zip,lib/dataservice/validator=jar,synapse/endpoint=xml,web/application=war,synapse/inbound-endpoint=xml,synapse/sequence=xml,synapse/configuration=xml,lib/registry/handlers=jar,synapse/task=xml,service/meta=xml,webapp/jaxws=war,synapse/api=xml,synapse/lib=zip,bpel/workflow=zip,lib/registry/filter=jar,service/dataservice=dbs,event/publisher=xml,synapse/local-entry=xml,synapse/priority-executor=xml,synapse/event-source=xml,synapse/template=xml,event/stream=json,lib/carbon/ui=jar,service/axis2=aar,synapse/sequenceTemplate=xml,wso2/gadget=dar,lib/synapse/mediator=jar</artifact.types>

 </properties>

 <build>

    <pluginManagement>

     <plugins>

       <plugin>

         <artifactId>maven-antrun-plugin</artifactId>

         <version>1.7</version>

       </plugin>

     </plugins>

    </pluginManagement>

    <plugins>

     <plugin>

       <artifactId>maven-antrun-plugin</artifactId>

       <executions>

         <execution>

           <phase>process-resources</phase>

           <goals>

             <goal>run</goal>

           </goals>

           <configuration>

             <tasks>

               <zip destfile="target/das-example.car">

                 <zipfileset dir="das-capp" />

               </zip>

             </tasks>

           </configuration>

         </execution>

       </executions>

     </plugin>

    </plugins>

 </build>

</project>

You can build above using mvn clean install and find the capp artifact within target/ directory. Then we can upload this deployable artifact to WSO2 DAS using management console.

[1] https://docs.wso2.com/display/DAS301/Packaging+Artifacts+as+a+C-App+Archive

Configure WSO2 server to start automatically after reboot

I have tested following within a RHEL box, but with a slight modification to the run-level, same script can be used within other Linux distros.

Assume we have WSO2 DAS server within /carbon/wso2/das directory and JDK installed in /carbon/java/ directory. Make sure to update these two according to your environment.

 1. Copy following startup-script to the /etc/init.d directory.
 2. Execute chmod a+x and a+r on the script.
 3. Set run level using "sudo chkconfig dasserver on"
 4. Recheck above using "chkconfig --list dasserver" This should output ,

 "dasserver       0:off   1:off   2:on    3:on    4:on    5:on    6:off"

Startup script

#! /bin/sh
#
# dasserver          Start up the WSO2 DAS server
#
# chkconfig: 2345 55 25
# description: WSO2 Data Analytics Server is a comprehensive enterprise data analytics platform.

export JAVA_HOME="/carbon/java/jdk1.8.0_65"

startcmd='/carbon/wso2/das/wso2das-3.0.0/bin/wso2server.sh start > /dev/null &'
restartcmd='/carbon/wso2/das/wso2das-3.0.0/bin/wso2server.sh restart > /dev/null &'
stopcmd='/carbon/wso2/das/wso2das-3.0.0/bin/wso2server.sh stop > /dev/null &'

case "$1" in
start)
   echo "Starting the WSO2 DAS Server ..."
   su -c "${startcmd}" wso2usr
;;
restart)
   echo "Re-starting the WSO2 DAS Server ..."
   su -c "${restartcmd}" wso2usr
;;
stop)
   echo "Stopping the WSO2 DAS Server ..."
   su -c "${stopcmd}" wso2usr
;;
*)
   echo "Usage: $0 {start|stop|restart}"
exit 1
esac

Invoke Java method from Jaggery.js

Lets assume we have a Java class with login() and logout() methods. login() takes two parameters username, password and use AuthenticationAdmin adminservice internally then returns sessionCookie.

So in this can I will have following package declaration and imports within the class.

package org.wso2.carbon.session.cookie;

import org.apache.axis2.context.ServiceContext;
import org.apache.axis2.transport.http.HTTPConstants;
import org.wso2.carbon.authenticator.stub.AuthenticationAdminStub;
import org.wso2.carbon.authenticator.stub.LoginAuthenticationExceptionException;
import org.wso2.carbon.authenticator.stub.LogoutAuthenticationExceptionException;
import java.rmi.RemoteException;

Then the login and logout methods.

public String login (String username, String password) throws RemoteException, LoginAuthenticationExceptionException {

authenticationAdminStub = new AuthenticationAdminStub("https://localhost:9443/services/AuthenticationAdmin");

String sessionCookie = null;
if (authenticationAdminStub.login(username, password, "localhost")) {
System.out.println("Login Successful");
ServiceContext serviceContext = authenticationAdminStub.
_getServiceClient().getLastOperationContext().getServiceContext();
sessionCookie = (String) serviceContext.getProperty(HTTPConstants.COOKIE_STRING);
}
return sessionCookie;
}

public void logout () throws RemoteException, LogoutAuthenticationExceptionException {
authenticationAdminStub.logout();
System.out.println("Logout successful");
}

Inorder to manage dependencies and packaging I'm using maven in this sample.
following is my repositories and dependencies section of the project pom.xml.

<repositories>
<repository>
<id>wso2-nexus</id>
<name>WSO2 internal Repository</name>
<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
<releases>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>ignore</checksumPolicy>
</releases>
</repository>
<repository>
<id>central</id>
<name>Maven Repository Switchboard</name>
<layout>default</layout>
<url>http://repo1.maven.org/maven2</url>
<releases>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>ignore</checksumPolicy>
</releases>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.wso2.carbon</groupId>
<artifactId>org.wso2.carbon.authenticator.stub</artifactId>
<version>4.2.0</version>
</dependency>
</dependencies>

I'm using wso2IS-5.0 distribution to test this. Make sure to use maven packaging property as following,

<packaging>jar</packaging>

You can find the complete project at  https://github.com/udarakr/authenticator

Build org.wso2.carbon.session.cookie.gen using mvn clean install command.

Lets copy session.cookie.gen-1.0-SNAPSHOT.jar located within target directory to <IS_HOME>/repository/components/lib directory.

Then create out Jaggey application, authenticator jaggery application consists of one jag file index.jag with following content,

<%
 var SessionCookieGen =org.wso2.carbon.session.cookie.SessionCookieGen;

 var SessionCookieGen = new SessionCookieGen();
 var sessionCookie = SessionCookieGen.login('admin', 'admin');
 print(sessionCookie);
 %>

Then copy authenticator application to the <IS_HOME>/repository/deployment/server/jaggeryapps/ directory.

NOTE :- Since this is for testing purpose only we are using the same IS node to host our application.

Then start the IS node, go to  <IS_HOME>/bin/ directory and run sh wso2server.sh within your command-line. After server start open your web browser and go to the https://localhost:9443/authenticator/

You can see,

If you don't have a complex logic within the Java class(simple method without any imports) you can follow this post published by Madhuka as a reference.

Find more information about jaggery.js from here

Change location of the WSO2 Carbon server logs

I'm using WSO2 AM-1.8.0 in this post. Since AM-1.8.0 released in Carbon-4.2.0 same steps apply to all products within this carbon version.

By default all log files are stored in <CARBON_HOME>/repository/logs/ directory.

Lets assume we need to move all these logs to /var/logs/wso2 directory.

1. Open log4j.properties file resides within <CARBON_HOME>/repository/conf/ directory and update following properties as mentioned below.


log4j.appender.SERVICE_APPENDER.File
log4j.appender.TRACE_APPENDER.File
log4j.appender.CARBON_LOGFILE.File
log4j.appender.ERROR_LOGFILE.File
log4j.appender.AUDIT_LOGFILE.File
log4j.appender.ATOMIKOS.File

log4j.appender.SERVICE_APPENDER.File=/var/logs/wso2/${instance.log}/wso2-apigw-service${instance.log}.log
log4j.appender.TRACE_APPENDER.File=/var/logs/wso2/${instance.log}/wso2-apigw-trace${instance.log}.log
log4j.appender.CARBON_LOGFILE.File=/var/logs/wso2/${instance.log}/wso2carbon${instance.log}.log
log4j.appender.ERROR_LOGFILE.File=/var/logs/wso2/${instance.log}/wso2-apigw-errors.log
log4j.appender.AUDIT_LOGFILE.File=/var/logs/wso2/audit.log
log4j.appender.ATOMIKOS.File = /var/logs/wso2/tm.out 

2.  configure HTTP Access log file by changing <CARBON_HOME>/repository/conf/tomcat/catalina-server.xml

<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="/var/logs/wso2"
prefix="localhost_access_log_sample."
suffix=".log"
pattern="%{xxx}i %{xxx}o"
resolveHosts="false"/>

 You may face few hick-ups if you need to move ALL logs from default location.

Eg: - patches.log, wso2carbon-trace-messages.log

At the moment there is no direct way to configure store location for above logs.These properties exist within <CARBON_HOME>/lib/org.wso2.carbon.server-4.2.0.jar and patch applying process take place even before the carbon server start. So we have bundled log4j.properties file within org.wso2.carbon.server-4.2.0.jar.

I will note down a workaround here.

Go to <CARBON_HOME>/lib/ Directory. Open the org.wso2.carbon.server-4.2.0.jar with an archive manager. Open the log4j.properties using a text editor and modify following properties.

log4j.appender.CARBON_LOGFILE.File
log4j.appender.CARBON_TRACE_LOGFILE.File
log4j.appender.CARBON_PATCHES_LOGFILE 

Enabling secure vault in WSO2 BPS

You can enable secure vault in any WSO2 product, which prevents us keeping plain text password in carbon configurations using WSO2 Carbon Secure Vault documentation.

But in BPS, <BPS_HOME>/repository/conf/datasources/master-datasources.xml is bit different from other products. This includes only WSO2_CARBON_DB related data-source configurations(may be other data-source definitions according to your deployment).

We have a separate <BPS_HOME>/repository/conf/datasources.properties file with the bps related data-source configs.

At the moment there is no direct way to enable secure vault for this config. But we can move config data within datasources.properties in to the
master-datasources.xml and follow the default guidelines.

1. Update existing master-datasources.xml with following data-source configuration.

<datasource>
    <name>BPS_DS</name>
    <description></description>
    <jndiConfig>
        <name>bpsds</name>
    </jndiConfig>
    <definition type="RDBMS">
        <configuration>
        <url>jdbc:mysql://localhost:3306/bps?autoReconnect=true</url>
        <username>bps_user</username>
        <password>bps_password</password>
        <driverClassName>com.mysql.jdbc.Driver</driverClassName>
        <maxActive>150</maxActive>
        <maxWait>360000</maxWait>
        <minIdle>5</minIdle>
        <testOnBorrow>true</testOnBorrow>
        <validationQuery>SELECT 1</validationQuery>
        <validationInterval>30000</validationInterval>
        <jdbcInterceptors>QueryTimeoutInterceptor(queryTimeout=30)</jdbcInterceptors>
        <timeBetweenEvictionRunsMillis>60000</timeBetweenEvictionRunsMillis>
        <numTestsPerEvictionRun>15</numTestsPerEvictionRun>
        <testWhileIdle>true</testWhileIdle>
        </configuration>
    </definition>
</datasource>

make sure to update url, username, password, driverClassName according to your environment.

2. Remove existing datasources.properties file.

3. Comment following lines in attachment-management.xml which locates at <BPS_HOME>/repository/conf/ directory.

            <JNDIInitialContextFactory>com.sun.jndi.rmi.registry.RegistryContextFactory</JNDIInitialContextFactory><JNDIProviderUrl>rmi://localhost:2199</JNDIProviderUrl>

4. Comment following line in bps.xml which locates at <BPS_HOME>/repository/conf/ directory.

<tns:JNDI contextFactory="com.sun.jndi.rmi.registry.RegistryContextFactory" providerURL="rmi://localhost:2199"/>

5. Comment following lines in humantask.xml file which locates at <BPS_HOME>/repository/conf/ directory.

        <JNDIInitialContextFactory>com.sun.jndi.rmi.registry.RegistryContextFactory</JNDIInitialContextFactory><JNDIProviderUrl>rmi://localhost:2199</JNDIProviderUrl>

We are done with the data-source configuration.

There is b4p-coordination-config.xml configuration file with plain text password, which we need to secure. You can follow "Securing username/password with secure vault section" here[2].

There is a separate configuration to "Retired BPEL Package Cleanup" where we have plain text password. Since this is for a specific task which has no direct relationship to the BPS runtime we can remove plain-text password here. So you have put it back when you need to run process-cleanup command line tool(processcleanuptool.sh|processcleanuptool.bat for Windows).

Note:- All above configuration changes work well in a BPS-3.2.0 deployment.

[1] https://docs.wso2.com/display/Carbon420/WSO2+Carbon+Secure+Vault
[2] https://docs.wso2.com/display/BPS320/Advanced+Configurations+for+Human+Task+Coordination

Publish assets using the API-Postman-WSO2 Enterprise Store

At the moment there are two ways to publish an asset to the ES back-office.

1. Using the UI

Eg: - Browse https://localhost:9443/publisher/asset/ebook
You can find the following UI and add the new asset(ebook in this case)

2. Using the API

This is the subject that I'm going to talk in this post. I'm going to use Postman- REST client for google chrome and CURL to execute this API invocation.

First lets try out with Postman,

Prerequisite :
a) google chrome browser
b) Postman chrome-extension

Steps

i) Browse https://localhost:9443/publisher/ and login in to the back-office.
ii) Browse chrome://apps/ and launch Postman REST client.
iii) Refer following screen-shot and create the POST form-data accordingly.

Note
URL :  https://localhost:9443/publisher/api/asset/ebook
Type : POST

iv) Now you can invoke the API :)

You will receive the following output if it works right..

Lets browse the newly added ebook asset.

I will come up with a separate post on the topic POST multipart/form-data using CURL soon. So you can invoke the same above asset add API using CURL.

Fronting WSO2 Management Console UI with Nginx

I'm going to set up WSO2 API Manager & WSO2 BAM in Linux environment for this exercise.

Since I'm going to run both products within a single machine need following configuration change,

1. Update port offset configuration as follows within <BAM_HOME>/repository/conf/carbon.xml.

<Offset>1</Offset>

 For API Manager I'm going to use the default configurations.

2. Update /etc/hosts with following and update IP address according to your environment.

10.100.0.128 am.wso2.org
10.100.0.128 bam.wso2.org

 3. Use following configuration within Nginx and update  proxy_pass according to your environment.

server {
    listen 443;
    server_name am.wso2.org;
    ssl on;
        ssl_certificate /etc/nginx/ssl/server.crt;
        ssl_certificate_key /etc/nginx/ssl/server.key;

    location /carbon {
            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://10.100.0.128:9443;
        }
    location /t {
            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://10.100.0.128:9443;
        }
 }

server {
    listen 443;
    server_name bam.wso2.org;
    ssl on;
        ssl_certificate /etc/nginx/ssl/server.crt;
        ssl_certificate_key /etc/nginx/ssl/server.key;

    location /carbon {
            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://10.100.0.128:9444;
        }
    location /t {
            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://10.100.0.128:9444;
        }
 }

So in this configuration I'm having two server directives, one for API Manager and one for BAM.

Read this post if you need help on creating SSL certificates.

I'm done with the configuration now, lets browse our management console now.

If you type https://am.wso2.org/carbon you will get the API Manager Admin Console UI.

 
After logging using defualt username:admin ,password:admin you may create a new tenant using Home > Configure > Multitenancy > Add New Tenant.

Now try to log-in to that tenant. You will get the following,

Ok, Let's try the BAM admin console now. Browse https://bam.wso2.org/carbon ,

Log-in, create a tenant and try to login using those tenant credentials.

Hope this will help to configure any WSO2 Product with Nginx !!

Use cqlsh terminal to browse cassandra | WSO2 ES 1.0.0

We have used WSO2-BAM’s event stream architecture to store data on Cassandra for social aspects of the WSO2 Enterprise Store.

I have to do few direct Cassandra querying while adding a new feature to the social application within ES distribution. Find following steps I followed in this activity.

1. Download Apache Cassandra 1.1.3 from here[1].
2. Unzip and browse apache-cassandra-1.1.3/bin directory using terminal.
3. Give following command to get the cqlsh terminal. Since I'm using default configuration in my local deployment I'm using admin as the both username and password, localhost as the hostname and 9160 as the port.

./cqlsh localhost 9160 -u admin -p admin

udara@thinkPad:~/Downloads/apache-cassandra-1.1.3/bin$ ./cqlsh localhost 9160 -u admin -p admin
Connected to Test Cluster at localhost:9160.
[cqlsh 2.2.0 | Cassandra 1.1.3 | CQL spec 2.0.0 | Thrift protocol 19.32.0]
Use HELP for help.
cqlsh>

4. Select key-space, in my deployment "EVENT_KS".

cqlsh> use EVENT_KS;

5. Select data from the column family "org_wso2_social_activity".

cqlsh:EVENT_KS> SELECT * FROM org_wso2_social_activity;

To learn more CQL follow this official document[2].

[1]. http://archive.apache.org/dist/cassandra/1.1.3/
[2]. http://cassandra.apache.org/doc/cql/CQL.html

Set up WSO2 BAM with Cassandra cluster

First blog post for year 2014, in this post I'm going to set up a single WSO2-BAM node to work with a cluster of three Cassandra nodes. To better understand the setup please refer following diagram.

I have 3VM's with Ubuntu up and running inside my virtual box, VM1 with IP address 192.168.56.101, VM2 & VM3 with 192.168.56.102,192.168.56.103.

Lets download and set up our Cassandra cluster first. You can find latest version of Cassandra from here[1]. Note that I'm going to use Cassandra 1.1.3 for this exercise. Lets assume we have apache-cassandra-1.1.3 directory within /home/udara/cassandra/ directory on all three nodes.

First im going to configure Cassandra inside node1. Lets browse apache-cassandra-1.1.3/conf/ directory and open cassandra.yaml in a text editor. Make sure to update following parameters according to your environment. Before updating we need to generate tokens for our Cassandra ring using the tokengentool here[2].

cluster_name: Test Cluster
initial_token: 0
seed_provider:        
- seeds: "192.168.56.101" 
listen_address: 192.168.56.101
rpc_address: 192.168.56.101
rpc_port: 9160

Update cassandra.yaml within our other nodes as well(VM2 and VM3).

cluster_name: Test Cluster
initial_token: 56713727820156410577229101238628035242
seed_provider:        
- seeds: "192.168.56.101" 
listen_address: 192.168.56.102
rpc_address: 192.168.56.102
rpc_port: 9160

cluster_name: Test Cluster
initial_token: 113427455640312821154458202477256070485
seed_provider:        
- seeds: "192.168.56.101" 
listen_address: 192.168.56.103
rpc_address: 192.168.56.103
rpc_port: 9160

Now we are good to init our cluster, just run bin/cassandra -f within  cassandra-1.1.3 directory in all three nodes. But in my setup I have to fulfill some other requirements as well.

1. Update JVM_OPTS="$JVM_OPTS -Xss280k" within conf/cassandra-env.sh.
2. Create /var/log/cassandra/system.log file & /var/lib/cassandra/ directories.

Lets check the status of our Cassandra cluster. Fulfill this task I'm going to use NodeTool by default shipped with Cassandra.

Run /nodetool -h 192.168.56.101 ring within apache-cassandra-1.1.3/bin directory,  and you will see something similar to this.

node1@node1-VirtualBox:~/apache-cassandra-1.1.3/bin$ ./nodetool -h 192.168.56.101 ring
Address         DC          Rack        Status State   Load            Effective-Ownership Token                                      
                                                                                                                                            6148914691236517205                        
192.168.56.101  datacenter1 rack1       Up     Normal  838.62 KB       100.00%             0                                          
192.168.56.102  datacenter1 rack1       Up     Normal  815.04 KB       100.00%             3074457345618258602                        
192.168.56.103  datacenter1 rack1       Up     Normal  823.84 KB       100.00%             6148914691236517205


Lets configure of BAM node inside VM1 now, download WSO2-BAM latest version from here[3]. I'm going to use WSO2 BAM 2.4.0 latest at the moment.

Update <BAM_HOME>/repository/conf/etc/cassandra-component.xml with the following content.Configure nodes correctly according to your environment.

<Cassandra>
    <Cluster>
       <Name>Test Cluster</Name>
       <DefaultPort>9160</DefaultPort>
       <Nodes>192.168.56.101:9160,192.168.56.102:9160,192.168.56.103:9160</Nodes>
       <AutoDiscovery disable="false" delay="1000"/>
    </Cluster>
</Cassandra>

Update <BAM_HOME>/repository/conf/advanced/streamdefn.xml with the following content.

<StreamDefinition>
    <NodeId>1</NodeId>

    <keySpaceName>EVENT_KS</keySpaceName>
    <eventIndexKeySpaceName>EVENT_INDEX_KS</eventIndexKeySpaceName>

    <ReplicationFactor>3</ReplicationFactor>
    <ReadConsistencyLevel>QUORUM</ReadConsistencyLevel>
    <WriteConsistencyLevel>QUORUM</WriteConsistencyLevel>
    <StrategyClass>org.apache.cassandra.locator.SimpleStrategy</StrategyClass>
</StreamDefinition>

For load-balancing purpose you can define WSO2BAM_CASSANDRA_DATASOURCE datasource as, check for comma separated JDBC URLs.

<datasource>
            <name>WSO2BAM_CASSANDRA_DATASOURCE</name>
            <description>The datasource used for Cassandra data</description>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:cassandra://192.168.56.101:9160/EVENT_KS,jdbc:cassandra://192.168.56.102:9160/EVENT_KS,jdbc:cassandra://192.168.56.103:9160/EVENT_KS</url>
                    <username>admin</username>
                    <password>admin</password>
                </configuration>
            </definition>
</datasource>

Make sure to update hostname localhost with correct IP address, 192.168.56.101 in my setup inside <BAM_HOME>/repository/conf/datasources/master-datasources.xml.

Lets start WSO2 BAM now. Since we need to point BAM to the external Cassandra cluster rather than using embedded Cassandra, run following

sh wso2server.sh -Ddisable.cassandra.server.startup=true

This disable.cassandra.server.startup=true parameter will disable embedded Cassandra during carbon server startup.

Lets run few samples available here[4] and see our setup works properly,

[1] http://cassandra.apache.org/download/
[2] http://www.datastax.com/docs/1.1/initialize/token_generation
[3] http://wso2.com/products/business-activity-monitor/
[4] http://docs.wso2.org/display/BAM240/KPI+Monitoring+Sample