NGASI AppServer Manager SaaS/ASP Hosting Automation for Cloud Computing Administrator and User Guide

NGASI AppServer Manager SaaS/ASP Hosting Automation for Cloud Computing Administrator and User Guide

NGASI SaaS Hosting Automation is a JAVA SaaS Enablement infrastructure that enables web hosting services to provide value added services to customers. By using NGASI SaaS Automation Infrastructure Technology, Web Hosting Providers, can target customers that are in the business of providing Software-as-a-Service (SaaS) to their clients. Such businesses are also referred to as Application Service Providers (ASP), who provide hosted Software-on-demand instead of the traditional software licensing distribution model. For ASPs with JAVA Applications, the NGASI SaaS Automation engine automates the deployment and per customer customization tasks, thus saving time and money. The Guide utilizes a use-case scenario, and is broken down into two main sections. The first is the Administrator Guide which is meant for the Web Hosting provider and the second section, meant for the SaaS Provider or ASP, is the User Guide. The example is based on a Linux environment comprised of MySQL for the Database, and Tomcat as the Application server. This is by no means the limitations of NGASI SaaS Automation. It is just an example to illustrate the process as you are able to use other Databases and Application Servers. Administrator Guide User Guide

Administrator Guide Overview This section is intended for the Web Hosting service provider. This entity provides the JAVA SaaS Hosting Automation Infrastructure Service to the SaaS User. The SaaS User in turn provides the actual SaaS service to their customers using a typical Software-on-Demand or Application Service Provider model. NOTE the Administrator and User may be part of the same company. The following use-case example illustrates how to setup a NGASI user account to be SaaS Automation enabled. NOTE: Assumption is that NGASI AppServer Manager has already been installed. (http://www.ngasi.com/zp/ngweb/ngdownloads.zul) The Specific steps to enable a SaaS User are: Create NGASI SaaS Group Add System User to NGASI SaaS Group Add IP Address Pool to NGASI Account Create MySQL Administrator Properties Configure Email Properties These steps are detailed in the following sections below. Create NGASI SaaS Group The Group determines the type of privileges accessible to the NGASI SaaS User. We will create the group from the command line interface in this case. So you should first download and install the NGASI Command Line Interface (NCLI) from the following URL: http://www.ngasi.com/zp/ngweb/ngdownloads.zul Using the Administrator (login as admin user) login information, we will create the SaaS Group. The Maximum JVMs for the Group in this example is set to 3. Create the SaaS Group from the command line like so:

/usr/ngasi/apiclient/bin/ncli.sh -command=addgroup -name=saasplan1 -maxjvms=3 -maxmemory=384m -user=admin -password=coolgeek -url=http: //localhost:8666 NOTE: The above command assumes the NCLI was installed under /usr/ngasi/apiclient/. NOTE: The NCLI comes with the default installation of NGASI AppServer Manager and is located under /usr/ngasi/apiclient. However if on another machine, follow the steps below to install NCLI. While logged in to the system, execute the following command: mkdir /usr/ngasi/apiclient cd /usr/ngasi/apiclient wget http://downloads.ngasi.com/misc/apiclient.zip unzip -q -o -a apiclient.zip dos2unix /usr/ngasi/apiclient/bin/ncli.sh chmod 700 /usr/ngasi/apiclient/bin/ncli.sh edit the JAVA_PATH in the file /usr/ngasi/apiclient/bin/ncli.sh to suit your environment. The NCLI is Licensed as FREE-to-use-software. Here we have created a SaaS Group named saasplan1, with maximum JVMs of 3, and total maximum RAM memory for all the JVMs of 384MB (128MB RAM per each JVM or customer). Add System User to NGASI SaaS Group The SaaS User is essentially a system user with access to NGASI AppServer Manager. In this case we will use a System user called mysaasacc1. NOTE: If the user does not exists, it can be created from a Linux/Unix shell like so: useradd -d /home/mysaasacc1 mysaasacc1 Then set the password like so: passwd mysaasacc1 Set the password to coolgeek for the purposes of this example. This SaaS user (mysaasacc1) information should be provided to the SaaS User most likely via a confirmation email. Add the System User to the SaaS Group (saasplan1) from the command line like so: /usr/ngasi/apiclient/bin/ncli.sh -command=addaccount -group=saasplan1 -account=mysaasacc1 -user=admin -password=coolgeek -url=http: //localhost:8666

Add IP Address Pool to NGASI Account For the purpose of this exercise, we will make 3 IP Addresses available to the SaaS User account (mysaasacc1). Each of the JVM will bind to one of the IP Addresses on Port 8080. NOTE: Under Linux, only root can bind on a IP Port with a value of less than 1024. If the standard HTTP port 80 is required, then under Linux there are 2 options to make this happen. The first is to set the system root user as a NGASI SaaS User. This option would only work if both the Administrator and User are of the same company because of the obvious security risks. The second option is to create a VPS for the SaaS User and assign the system root of the VPS as the SaaS User (using the vpsid parameter option). A user from a configured Remote Server may also be used with the remoteserverid option. In this example we use the following IP Addresses: 172.16.0.35,172.16.0.36, and 172.16.0.37. Set the IP Address Pool for the SaaS User account from the command line like so: /usr/ngasi/apiclient/bin/ncli.sh -command=setippool -iplist=172.16.0.35/3 -account=mysaasacc1 -user=admin -password=coolgeek -url=http: //localhost:8666 NOTE: If the IP Addresses have not been configured, they may be created from a Linux/Unix shell like so: ifconfig eth0:35 172.16.0.35 ifconfig eth0:36 172.16.0.36 ifconfig eth0:37 172.16.0.37 NOTE: The IP Address Pool info should be provided to the SaaS User. Create MySQL Administrator Properties NOTE: You can skip this step for the SaaS engine to use either Derby or HSQLDB instead of MySQL. Sample Database configuration files are located under /usr/ngasi/webapps/root/web-inf/ngasi/dbs/. Edit accordingly. Be sure to set the disabled value to false.

Create a MySQL database user with create privileges for the purposes of dynamically creating databases for deployed applications. In this example we use a MySQL database. We will log into MySQL as the mysql superuser or any other user with superuser privileges. We will then create a user with create database and user privileges called mydbadmin with password coolgeek. We will execute the following SQL script to accomplish this: GRANT ALL PRIVILEGES ON *.* TO mydbadmin@"%" IDENTIFIED BY 'coolgeek' WITH GRANT OPTION; GRANT ALL PRIVILEGES ON *.* TO mydbadmin@localhost IDENTIFIED BY 'coolgeek' WITH GRANT OPTION; Now add the following DB Properties to /usr/ngasi/webapps/root/web-inf/ngasi/dbs/mysql.properties datasource_driver=com.mysql.jdbc.driver datasource_user_url_root=jdbc:mysql://localhost:3306/ datasource_admin_url=jdbc:mysql://localhost:3306/mysql datasource_admin_user=mydbadmin datasource_admin_password=coolgeek The name on the left of.properties (mysql) of the database properties file, is the Database ID as in db_source_id in the application properties file. NOTE: The Database ID mysql should be provided to the SaaS User. NOTE: For databases other than MySQL, PostgreSQL, HSQLDB, and Derby, the drivers would need to be placed under /usr/ngasi/common/lib

Configure Email Properties An email configuration with valid properties are required to send email confirmations, check there is a valid email entry in your ROOT.xml configuration file. (/usr/ngasi/conf/catalina/localhost/root.xml) If SMTP Authentication is required edit the Mail entry to look like: <Resource /> name="mail/mailsession" auth="container" type="javax.mail.session" mail.transport.protocol="smtp" mail.smtp.host="localhost" mail.smtp.auth="true" mail.smtp.user="me@joe.com" mail.smtp.password="tiger" That is it. You have completed the Administrator's task for enabling a SaaS User. The next section is the User Guide to be used by the SaaS user to deploy the SaaS application for customers.

User Guide SaaS, which is normally offered by Application Service Providers, uses an on-demand software model to provide hosted software services to customers. The SaaS/ASP User Guide is based on the use-case mysaas example. NOTE: The files for the entire use-case example is located under the examples directory of the NCLI (http://downloads.ngasi.com/misc/apiclient.zip). The NGASI SaaS Automation engine allows you to automate the deployment of an application across multiple application server installations or within the same JVM (via a technique called cloning). At the same time isolating the dynamic aspects of the application, such as Datasource database access and authentication realm configuration. NGASI SaaS Enablement infrastructure is so sophisticated, that it has intelligent logic build in, to configure application resources separately for each customer. In short, NGASI SaaS Automation leaves the management of the dynamic aspects of the application to another entity (the NGASI SaaS Automaton engine). NGASI SaaS engine utilizes an open application packaging format called SWAR (SaaS Web Application Packaging ). The SWAR steps and format are detailed below. There are 4 specific steps to SaaS enable your Application. Application Assembly (WAR) Database Setup Script SaaS Properties Application Deployment These steps are detailed in the sections below. Application Assembly (WAR) For the purpose of this exercise, we will create a simple Java Web Application and package it into a WAR file. The JAVA application example uses a jdbc Datasource object to increment the value of a field in a database table. Access to the application will require authentication via jdbc Realm. The Directory structure of the Web Application will look like: webapp/index.jsp webapp/web-inf/web.xml

First create the index.jsp file and add the following: <%@ page import="java.sql.*" %> <%@ page import="java.io.*" %> <html> <body> <% ResultSet results = null; Connection Conn = null; Statement Stmt = null; javax.naming.initialcontext ctx = new javax.naming.initialcontext(); javax.sql.datasource ds = (javax.sql.datasource)ctx.lookup("java:comp/env/jdbc/genericdatasource"); String action = request.getparameter("action"); Conn = ds.getconnection(); Conn.setAutoCommit(true); if (action!= null ) { if (action.equals("clear")) { Stmt = Conn.createStatement(); Stmt.execute("UPDATE testable SET countf=0 where name = 'counter'"); } } Stmt = Conn.createStatement(); int ct = 0; boolean tf = Stmt.execute("select countf from testable where name='counter'"); if (tf) { results = Stmt.getResultSet(); if (results!= null && results.next()) ct = results.getint(1); } ct++; PreparedStatement pstmt = Conn.prepareStatement("UPDATE testable SET countf=? where name = 'counter'"); pstmt.setint(1,ct); pstmt.execute(); Conn.close(); out.println("db Counter Value: " + ct); %> <form method=post> <input type=submit value="increment" name="action"><input type=submit value="clear" name="action"> </form> <p> This JAVA JSP example uses a jdbc Datasource object to increment the value of a field in a table. </p> </body> </html>

Next create the WEB-INF/web.xml and add the following: <?xml version="1.0" encoding="utf-8"?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> <security-constraint> <display-name>mysaas Security Constraint</display-name> <web-resource-collection> <web-resource-name>mysaas Protected Area</web-resource-name> <!-- Define the context-relative URL(s) to be protected --> <url-pattern>/*</url-pattern> <!-- If you list http methods, only those methods are protected --> <http-method>delete</http-method> <http-method>get</http-method> <http-method>post</http-method> <http-method>put</http-method> </web-resource-collection> <auth-constraint> <!-- Anyone with one of the listed roles may access this area --> <role-name>mysaasuserrole</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>basic</auth-method> <realm-name>authentication Area</realm-name> </login-config> <security-role> <role-name>mysaasuserrole</role-name> </security-role> </web-app> The final stages in the Application Assembly process include packaging the application from the directory as specified above into an application archive (WAR). Name the WAR file webapp.war. Now copy the webapp.war to the server. In this example, the SaaS user is the system user named mysaasacc1. Copy the file while logged in as mysaasacc1 to the following directory: /home/mysaasacc1/appservers/applications/mysaas Create the directory if not exists. The name of the deployed application context will be mysaas as that is the name of the sub directory under applications

Database Setup Script The mysaas application will require access to a database for the application itself as well as for user authentication. We will make an SQL script available to NGASI SaaS Automation to execute during the Application setup stage. The SQL script contains relevant tables, as well as populating a default user info for authentication. The SQL script also includes a tag for NGASI SaaS Automation to generate a random encrypted password. While logged in as mysaasacc1, create /home/mysaasacc1/appservers/applications/mysaas/db.sql and add the following: CREATE TABLE realm_user ( realm_username varchar(20), realm_passphrase varchar(20), PRIMARY KEY (realm_username) ) ; CREATE TABLE realm_userrole ( realm_username varchar(20), realm_rolename varchar(20), PRIMARY KEY (realm_username,realm_rolename) ) ; INSERT into realm_user (realm_username,realm_passphrase) values ('#SAASE_RANDOM_1#','#SAASE_RANDOM_2_SHA#'); INSERT into realm_userrole (realm_username,realm_rolename) values ('#SAASE_RANDOM_1#','mysaasuserrole'); create table testable (name varchar(18),countf int); INSERT into testable (name,countf) values ('counter',0); SaaS Properties Next, NGASI Saas Automation will need a SaaS Properties file which contains information that will tell it specific instructions on how to deploy and configure the application for individual customers. While logged in as mysaasacc1, create /home/mysaasacc1/appservers/applications/mysaas/saas.properties

and add the following: #edit accordingly application_name=my SaaS Application email_confirm=true from_email=support@mysaas.com confirm_email_sender_name=mysaas Tech Support cc_email=support@mysaas.com email_confirm_subject=welcome to My SaaS Application datasource_name=genericdatasource #from mysql.properties created by Administrator #db_source_id=mysql #instead of DB source id, use any MySQL available from Administrator #default available is derby and hsqldb db_source_types=derby,hsqldb,mysql,postgresql #sql_encoding=default drop_db_if_exists=true #appservername Tomcat=true Tomcat_version=6.0.14 #Jetty=false #Jetty_version=6.1.3 #JBoss=false #JBoss_version=4.2.0 jdkversion=jdk6.0.03 start=true # for jdbc Realm jdbcrealm=true jdbc_realm_user_table=realm_user jdbc_user_field=realm_username jdbc_password_field=realm_passphrase jdbc_realm_role_table=realm_userrole jdbc_role_user_field=realm_username jdbc_role_field=realm_rolename digest=sha javamail=session mail.smtp.host=localhost #optional if SMTP Authentication required #mail.smtp.user=me@samiam.com #mail.smtp.password=tiger NOTE:The values of the saas.properties can be overriden by passing them as parameters in the ncli script or as properties in the JAVA API.

NOTE: instead of separately uploading webapp.war, db.sql, and saas.properties, you can archive them into an archive file called mysaas.swar and place under the applications directory. Application Deployment For the purpose of this exercise, we will be installing 3 separate instances of the mysaas application for 3 different customers via 3 different methods (script, JAVA API, and web console). Deployment with NCLI We will install the application for the first customer from the command line interface. So you should first download and install the NGASI Command Line Interface (NCLI) from the following URL: http://www.ngasi.com/zp/ngweb/ngdownloads.zul NOTE: Follow the steps below to install NCLI. While logged in to the system as mysaasacc1, execute the following command: mkdir /home/mysaasacc1/apiclient cd /home/mysaasacc1/apiclient wget http://downloads.ngasi.com/misc/apiclient.zip unzip -q -o -a apiclient.zip chmod 700 /home/mysaasacc1/apiclient/bin/ncli.sh edit the JAVA_PATH in the file /home/mysaasacc1/apiclient/bin/ncli.sh to suit your environment. Using the SaaS User (login as mysaasacc1 user) login information, we will install the mysaas application to JVM 1 (Customer 1) from the command line (script) like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=installapplication -applicationname=mysaas -jvmid=1 -email_to=customer@name. com,accounting@mysaashosting.com -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666 NOTE: The above command assumes the NCLI was installed under /home/mysaasacc1/apiclient/.

The application would have been installed under a Tomcat 6 install located in /home/mysaasacc1/appservers/apache-tomcat-6x/ There are a number of variable information that may be of interest pertaining to the specific application deployment after installation is completed. NOTE: You are able to install multiple applications in the same JVM assuming the same application server is specified in the application properties files of each application. In addition, you may install the same application multiple times in the same JVM under different appservernames via the -clonedfrom parameter option. 1)Database Information: Since a Datasource is specified in the saas.properties file, for each JVM installation or application install, a separate Datasource is created for each application instance. The Database name and user are randomly created (with the same value) and may be retrieved via the NCLI like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=getdbuser -applicationname=mysaas -jvmid=1 -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666 The Database password is randomly created and may be retrieved via the NCLI like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=getdbpassword -applicationname=mysaas -jvmid=1 -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666 The Database URL may be retrieved via the NCLI like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=getdburl -applicationname=mysaas -jvmid=1 -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666 2)Assigned IP Address: The assigned IP Address may be retrieved via the NCLI like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=getassignedaddress -applicationname=mysaas -jvmid=1 -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666

3)Random Values: In the db.sql, we had placed a couple of Random Tags named #SAASE_RANDOM_1# and #SAASE_RANDOM_2_SHA# as part of the script template. The value of #SAASE_RANDOM_1# is the default user and for #SAASE_RANDOM_2_SHA# it is the password for the default user. This random value may be retrieved via the NCLI like so: /home/mysaasacc1/apiclient/bin/ncli.sh -command=getrandomvalue -randomid=1 -applicationname=mysaas -jvmid=1 -user=mysaasacc1 -password=coolgeek -url=http://localhost:8666 Assuming the assigned IP address was 172.16.0.35 for JVM 1 installation, the access URL for the mysaas application would look like: http://172.16.0.35:8080/mysaas The default user name is the value receive from the getrandomvalue command with randomid 1. The password would be the value received from the getrandomvalue command with randomid 2. Our next deployment of the mysaas application for customer 2 will be done differently. First we will include an email confirmation with relevant application information by adding an email_confirm.tpl template file. And we will use the JAVA API within a JAVA program to execute the deployment commands. Email Confirmation: The naming convention of the email confirmation template looks like: email_confirm.tpl The file is place in the saas application directory. In the email confirmation template, you are able to include several tokens that are parsed and substituted with the appropriate values by NGASI SaaS Automation engine. The following are the possible Template tokens: #SAASE_IP_ADDRESS# #SAASE_APPLICATION_NAME# #SAASE_HTTP_PORT# #SAASE_HTTPS_PORT# #SAASE_APP_DIR# #SAASE_RANDOM_1# #SAASE_RANDOM_2_SHA#... #SAASE_RANDOM_10# #SAASE_DB_PASSWORD# #SAASE_DB_USER#

#SAASE_DB_URL# #SAASE_DB_DRIVER# #SAASE_DB_NAME# #SAASE_DATASOURCE_NAME# NOTE: A RANDOM token ending with SHA indicates the stored value will be encrypted with the SHA encryption algorithm. For example for storing user passwords in a database. Also, the plain value of the random variable is displayed in the confirmation email (if the token is included in the email template). For this example, we will create /home/mysaasacc1/appservers/applications/mysaas/email_confirm.tpl and add the following: Thank you for subscribing to MySaaS Application. To access MySaaS, logon to one of the following URL (depending on setup): http://#saase_ip_address#:#saase_http_port#/#saase_application_ NAME# (Secured Access) https://#saase_ip_address#:#saase_https_port#/#saase_applicatio N_NAME# Enter the following User and Password when prompted: User: #SAASE_RANDOM_1# Password: #SAASE_RANDOM_2_SHA# Now the following information is not recommended in the real world for obvious security reasons but since this is just an example here it is: Database user: #SAASE_DB_USER# Database Password: #SAASE_DB_PASSWORD# Database URL: #SAASE_DB_URL# Deployment with JAVA API The second deployment method will utilize the JAVA API. So we will be able to do so directly from within a JAVA program. Create a sample JAVA source file, /home/mysaasacc1/apiclient/examples/mysaasexample.java and add the following:

import ngasi.automationapi.ngapiclient; import java.io.*; import java.util.*; public class MySaaSExample { public static void main(string args[])throws Exception { Properties properties = new Properties(); //general properties.put("url","http://localhost:8666"); properties.put("user","mysaasacc1"); properties.put("password","coolgeek"); //application properties.put("applicationname","mysaas"); properties.put("jvmid","2"); properties.put("email_to","customer@emailaddress.com"); //install application command properties.put("command","installapplication"); String result = NGAPIClient.exec(properties); System.out.println("Install Application Result: " + result); //Database Password command properties.put("command","getdbpassword"); result = NGAPIClient.exec(properties); System.out.println("Application Database Password: " + result); //Database URL command properties.put("command","getdburl"); result = NGAPIClient.exec(properties); System.out.println("Application Database URL: " + result); //Assigned IP Address command properties.put("command","getassignedaddress"); result = NGAPIClient.exec(properties); System.out.println("Application Assigned IP Address: " + result); }} //Application Default User Password command properties.put("command","getrandomvalue"); properties.put("randomid","1"); result = NGAPIClient.exec(properties); System.out.println("Application Default User Password: " + result);

Compile the JAVA source file like so (edit the paths accordingly): export JAVA_PATH=/usr/java/jdk1.6.0_03/bin/ export NG_HOME=/home/mysaasacc1/apiclient export CLASSPATH=$NG_HOME/classes/:$NG_HOME/lib/activation.jar:$NG_HOME/li b/mail.jar:$ng_home/lib/ngasi-axis.jar $JAVA_PATH"javac" -classpath $CLASSPATH $NG_HOME/examples/MySaaSExample.java Next, deploy the application for Customer 2 by running MySaaSExample like so: export JAVA_PATH=/usr/java/jdk1.6.0_03/bin/ export NG_HOME=/home/mysaasacc1/apiclient export CLASSPATH=$NG_HOME/classes/:$NG_HOME/lib/activation.jar:$NG_HOME/li b/mail.jar:$ng_home/lib/ngasi-axis.jar:$ng_home/examples/ $JAVA_PATH"java" MySaaSExample NOTE: The above exmples assumes the NCLI was installed under /home/mysaasacc1/apiclient/. The application for Customer 2 would have been installed under a Tomcat 6 install located in: /home/mysaasacc1/appservers/apache-tomcat-6x-2/ Deployment with NGASI AppServer Manager Web Control The third deployment method is via the NGASI AppServer Manager Web Control. Login to NGASI AppServer Manager (the URL should have been provided by the Administrator). The default URL is: https://localhost:8663 Select JVM Id 3. Then Install Application. The application for Customer 3 would have been installed under a Tomcat 6 install located in: /home/mysaasacc1/appservers/apache-tomcat-6x-3/

Summary By using NGASI SaaS Automation, you are able to concentrate on just your application development, and not have to worry about deploying and maintaining many installations of your application. You are able to develop your application using standard designs and frameworks without worrying about customization to fit in a hosted environment. In addition, using either the script or JAVA API methods, enables seamless integration with your existing CRM or web site portal. For example a hook to NGASI AppServer Manager's commands can be easily injected into your e-commerce shopping cart checkout system if the purchase was successful.