GENI Aggregate Manager (AM)

Server Deployment Guide

It is expected that you have already built the AggregateWS.aar file as described in the Source Code Compilation Guide before starting this procedure.

As described in the Overview and Architecture section, the GENI AM software is a Java-based Axis2 Web Service which requires access to a MySQL database to store data. In general, the procedure for setting up the server includes the following steps:

• Install MySQL
• Create aggregate database and populate tables with sample data
• Install Apache Tomcat
• Install Apache Axis2
• Install mysql-connector .jar
• Deploy AggregateWS.aar (the compiled GENI AM code) as an Axis2 Web Service
• Test deployment using various SOAP clients

---

MySQL

MySQL is the database used to maintain and track resources. You may install MySQL in one of two ways: manually, by installing a package downloaded from the MySQL website OR automatically, using your operating system's package manager.

MySQL Manual Installation

Download the MySQL package from the MySQL website at:

• http://dev.mysql.com/downloads/mysql

Installing MySQL in this manner is beyond the scope of this webpage but installation instructions may be found at:

• http://dev.mysql.com/doc

MySQL Automatic Installation with a Package Manager

Download and install MySQL through a package manager if your operating system runs such a service. A few common package managers are up2date (RedHat), apt-get (Debian), and yum. You may install MySQL using a command such as:

% up2date mysql-server

Consult specific package managers for the exact command and package name.

MySQL configuration

The GENI AM software contains an SQL schema file which will create a database called "aggregate" and the correct table structure. This file is called createTables.sql and can be found in the aggregate/AggregateWS/sql/ directory when you downloaded the code via Subversion (SVN). There is also a file called sampleData.sql which contains sample entries for the 'nodes' and 'capabilities' tables.

For example, if you downloaded everything to /usr/local/aggregate:

% ls -l /usr/local/aggregate/AggregateWS/sql/ total 20 -rw-r--r-- 1 root root 1286 2009-09-29 13:18 createTables.sql -rw-r--r-- 1 root root 14316 2009-09-29 14:23 sampleData.sql

Granting Privileges to a MySQL User

Creating the necessary databases requires a MySQL user account with proper privileges. The GENI AM uses a default MySQL username of "geniuser" and a password of "genipass" to access the database. The following commands will create the account if it does not exist and assign that account the proper privileges to access the database named "aggregate":

% mysql -p Enter password: [enter mysql root password] ... mysql> GRANT SELECT, INSERT, CREATE, INDEX, UPDATE, DELETE, DROP ON aggregate.* TO geniuser@localhost IDENTIFIED BY 'genipass’;

If you would like to change the default username and password that are used by the GENI AM, please take a look at the AggregateWS/src/net/geni/aggregate/services/core/AggregateState.java file, particularly the init() and initPrefs() function. You can search for 'geniuser' and 'genipass' to find the place where these attributes are being set. This software uses Java's systemPrefs to store information such as the MySQL username and password in prefs.xml files. These files are typically found in a directory like /etc/.java/.systemPrefs on some Linux systems, but you may find them in /usr/local/java6/jre/.systemPrefs if you use the method described above for installing the JDK.

Create the aggregate Database

Execute the following command on the server to create the 'aggregate' database and corresponding tables:

% mysql -u geniuser -p < sql/createTables.sql Enter password: genipass %

You may wish to load the sample data into the 'nodes' and 'capabilities' tables to get familiar with how the GENI AM functions.

Please note that you will need to customize these INSERTs for your own instantiation, these are only examples!

Execute the following command on the server to load the sample data:

% mysql -u geniuser -p < sql/sampleData.sql Enter password: genipass %

---

Java Development Kit (JDK)

Java is the programming language in which the GENI AM software was created and provides the environment in which it runs. In addition to running the software, the JDK also contains utilities required for compiling the source code and generating user certificates. This section details installation and configuration related to this package.

Many systems come pre-installed with Java. To install the GENI AM, your system must not only have Java Runtime Environment (JRE) version 5 but also the various compilers and utilities. To verify that you have the necessary Java environment, issue the following command:

% javac –version

If the first line of output reads javac 1.5.0_X, you should not need to install the Java Development Kit and may skip to the section titled "Setting the JAVA_HOME Environment Variable". If you get "command not found" or the version number is less than 1.5, you may need to install JDK 5.0 and should proceed to "Download and Installation".

Download and Installation

You may download JDK 6.0 from Sun’s web site at:

• http://java.sun.com/javase/downloads/index.jsp

It is recommended that you download the latest update of JDK Version 6. You do not need to download the bundled versions — simply click "Download" next to JDK 6 Update ##. Choose the package most suitable for your operating system.

Once downloaded, unpack the file — this is typically done by setting it as executable and running the binary. This should create a new folder named something similar to "jdk1.6.0_XX". The final step of installation is to move this folder to an easily accessible place. We recommend renaming the folder to java6 in /usr/local with the following command:

% sudo mv jdk1.6.0_XX /usr/local/java6

The location may be anywhere you choose – just make sure you note the location as it is required for setting the JAVA_HOME environment variable in the next section.

Setting the JAVA_HOME Environment Variable

Once Java is installed, you need to set the JAVA_HOME environment variable with its location. This variable is required by the Tomcat web server (see the section titled "Apache Tomcat") to run. To set this environment variable, issue these commands:

% JAVA_HOME=/usr/local/java6 % export JAVA_HOME

You may permanently set this variable (recommended) by adding the above commands to the profile file in your home directory (i.e. .bash_profile or .profile).

---

Apache Tomcat

Tomcat is a Java-based application container in which the GENI AM software runs. This section details installation and basic configuration of Tomcat.

Download and Installation

You may download Tomcat from the project’s web site at:

• http://tomcat.apache.org/download-60.cgi

It is recommended you download Tomcat Version 6.0.

Once downloaded, unpack the downloaded file; this should create a new folder named something similar to "apache-tomcat-6.0.XX". The final step of installation is to move this folder to an easily accessible place. We recommend renaming the folder to tomcat in /usr/local with the following command:

% sudo mv apache-tomcat-6.0.XX /usr/local/tomcat

The location may be anywhere you choose – just make sure you note the location as it is required for setting the CATALINA_HOME environment variable in the next section.

NOTE: It is NOT RECOMMENDED that you download Tomcat with a package manager such as up2date, yum, or apt-get. You are likely to encounter difficulty with this method. If you install Tomcat using this method be aware that some of the environment variables and other settings may vary from what is contained within this webpage.

Setting the CATALINA_HOME Environment Variable

Once Tomcat is installed, you need to set the CATALINA_HOME environment variable with its location. This variable is required by the Tomcat web server to run. To set this environment variable, issue these commands:

% CATALINA_HOME=/usr/local/tomcat % export CATALINA_HOME

You may permanently set this variable (recommended) by adding the above commands to the profile file in your home directory (i.e. .bash_profile or .profile).

Starting/Stopping the Tomcat Server

You may start Tomcat with the following command:

% $CATALINA_HOME/bin/startup.sh

You shutdown the Tomcat server with the following command:

% $CATALINA_HOME/bin/shutdown.sh

Verifying a Successful Installation

To verify installation was successful, startup the Tomcat server with the following command:

% $CATALINA_HOME/bin/startup.sh

After starting the server, point a web browser to port 8080 of the machine on which you installed Tomcat with the following URL:

• http://your-machine-name:8080

If installation was successful, a web page will load with the Tomcat logo and a message that reads "If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!"

Configuring Tomcat for SSL

You may configure Tomcat to use SSL so that all requests and responses to the server are encrypted. This is not required but highly recommended. Information on this process can be found at:

• http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html

---

Apache Axis2

Axis2 provides the GENI AM with a web service framework. It is installed in Tomcat as its own web application. This section details installation and configuration of Axis2.

Download and Installation

Download Axis2 from the project’s web site at:

• http://ws.apache.org/axis2/download/1_4_1/download.cgi

You only need to download the WAR (Web Archive) Distribution of the software. You MUST download version 1.4.1 for the GENI AM to function properly.

Unpack and install the downloaded components with the following commands:

% unzip –d axis2-1 axis2-1.4.1-war.zip % mv axis2-1/axis2.war $CATALINA_HOME/webapps

After moving the WAR file to the correct location, restart the Tomcat server:

% $CATALINA_HOME/bin/shutdown.sh % $CATALINA_HOME/bin/startup.sh

Verifying a Successful Installation

To verify installation of Axis2 was successful, point a web browser to port 8080 of the machine on which you installed Tomcat with the following URL:

• http://your-machine-name:8080/axis2 OR https://your-machine-name:8443/axis2 (if SSL is configured)

If installation was successful, a web page will load with the Axis2 logo and a message that reads "If you can see this page you have successfully deployed the Axis2 Web Application."

---

Install MySQL Connector/J

MySQL Connector/J is the library which provides the com.mysql.jdbc.Driver class — the JDBC driver for MySQL.

Download and Installation

Download MySQL Connector/J from the project’s web site at:

• http://dev.mysql.com/downloads/connector/j/

Unpack and install the downloaded components with the following commands:

% unzip mysql-connector-java-5.1.10.zip % mv mysql-connector-java-5.1.10/*.jar /usr/local/tomcat/webapps/axis2/WEB-INF/lib

---

Deploy Axis2 Web Service Application (AggregateWS.aar)

We will now copy the AggregateWS.aar file which you built by following the Source Code Compilation Guide to the Tomcat server.

In our environment, we develop and build the code within the NetBeans IDE running under Mac OS X. The compiled code (the .AAR Axis Archive file) is then copied to a Linux PC running Apache Tomcat and Axis2. Here is an example of how to deploy the AggregateWS.aar file using the scp application:

% scp /usr/local/aggregate/AggregateWS/build/axis2/WEB-INF/services/AggregateWS.aar \ user@your-machine-name:/usr/local/tomcat/webapps/axis2/WEB-INF/services

It is typically not necessary to stop/start the Apache Tomcat server at this point. However, you may want to try running Tomcat in the foreground mode using the following technique:

% $CATALINA_HOME/bin/shutdown.sh % $CATALINA_HOME/bin/catalina.sh run [...] [INFO] Deploying Web service: AggregateWS.aar - file:/usr/local/tomcat/webapps/axis2/WEB-INF/services/AggregateWS.aar AggregateWS init... [...] INFO: Server startup in 2561 ms

This can be helpful for debugging problems if the tests below fail. For example, you will see something like this if GENI AM could not connect to the database:

[INFO] Deploying Web service: AggregateWS.aar - file:/usr/local/tomcat/webapps/axis2/WEB-INF/services/AggregateWS.aar AggregateWS init... mysql connection failed... java.sql.SQLException: Access denied for user 'geniuser'@'localhost' (using password: YES) at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1055) [...]

Or, if you have not correctly deployed the MySQL Connector/J JDBC driver, you may see something like this:

[INFO] Deploying Web service: AggregateWS.aar - file:/usr/local/tomcat/webapps/axis2/WEB-INF/services/AggregateWS.aar AggregateWS init... java.lang.ClassNotFoundException: Class Not found : com.mysql.jdbc.Driver at org.apache.axis2.deployment.!DeploymentClassLoader.findClass(DeploymentClassLoader?.java:86)

The first error would indicate that you have correctly loaded the MySQL Connector/J JDBC driver, but you have a permission problem — check to make sure that you executed the SQL GRANT statement correctly.

The second error would indicate that you have not correctly deployed the MySQL Connector/J JDBC driver — check that you deployed the mysql-connector-java-5.1.XX-bin.jar file to the correct location under /usr/local/tomcat.

Verifying the AggregateGENI Web Service API Installation

You may verify that the web service API has been deployed via the Axis2 administrator interface by doing the following:

• Open http://your-machine:8080/axis2/axis2-admin/ in your web browser
• Log-in to the page that loads (default user: admin, default password: axis2)
• Click “Available Services” on the left-hand side of the screen
• You should see an entry for "AggregateGENI" on the page that loads, followed by a list of web service calls

This indicates that installation was successful.

If you do not see it, try re-installing the GENI AM. You could also check the Tomcat log files for warnings/errors. These are located in the $CATALINA_HOME/logs/ directory.

---

Test Deployment

Assuming you have loaded the sample data, you may now begin to test the Web Service API using any SOAP client. We provide examples below using a generic SOAP client for Mac OS X as well as an example using Perl scripts that are included in the GENI AM Subversion repository.

Test with SOAP Client.app

If you are using Mac OS X, you can download a simple SOAP client at http://ditchnet.org/soapclient/.

When you launch this application, you will be presented with a simple window that looks something like the following. In the example below, we have typed in the address to the WSDL file for the AggregateGENI Web Service. This WSDL file defines the API — at this point, the SOAP Client application does not know anything about the GENI AM API:

When we click the 'Parse' button, the SOAP Client application downloads the WSDL file, parses it, and now it understands the API. The screen below shows the various method functions that are exported by our GENI AM API:

Let's select the 'ListCapabilities' method and click the 'Pretty Response' tab on the bottom pane, then click the 'Execute' button:

This response indicates that the GENI AM we are talking to may control resources which have a number of different types of capabilities. As shown in the response, these capabilities include nodes with access to dynamic network provisioning, virtualized compute resources, OpenFlow switches, etc.

Now let's ask the GENI AM to give us a list of nodes with a particular capability — PlanetLab virtualized compute resources.

Select the 'ListNodes' method, and copy/paste the capabilityURN descriptor associated with the PlanetLab capability into the 'Parameters' box (this allows you to filter give a list of capabilities):

Click 'Execute' to see a list of nodes with this capability:

Four nodes have been returned, but we are only viewing the details about one particular node known as PLANETLAB2. We can see that it has a hostname of planetlab2.dragon.maxgigapop.net. This node actually has more than one capability — although we asked for all nodes with PlanetLab capability, it is always possible that a node may have additional capabilities. In this case, the node known as PLANETLAB2 not only offers virtualized compute resources (meaning it can be slices in terms of CPU/disk/memory), but it also has the DRAGON capability. This indicates that dynamic Layer 2 VLANs may be provisioned directly to an Ethernet interface on this host.

The output also includes a controllerURL field. This field points to the component manager for that particular capability. For example, with the DRAGON capability, it points to a SOAP API called OSCARS on another host known as idc.dragon.maxgigapop.net. This is the interface that you would want to talk to if you were interested in provisioning dynamic circuits to this end system. For PlanetLab services, a URL is provided to the PlanetLab API which can take care of provisioning a virtual machine on this node.

Test with Example Perl Script

The GENI AM software includes an example Perl script that can communicate with the Web Service API.

This script is located at AggregateAttic/soap/ws_client.pl. There are several XML files in the AggregateAttic/soap/ directory. One is called caps.xml, which is designed to call the ListCapabilities method. Another is called nodes.xml, which is designed to call the ListNodes method.

First, run ./ws_client.pl --help to become familiar with the command-line arguments of the script.

Next, edit the caps.xml file and insert the IP address or hostname of your server on the line beginning with "Host:".

Now launch the Perl script using ./ws_client.pl -x caps -s 10.211.55.6:8080:

The output is identical to what you would see in the 'Raw Request' tab on the bottom pane of the graphical SOAP Client application we demonstrated earlier.

If you would like output that is a bit easier to read, you can pass the --prettier option to ws_client.pl:

Finally, the script allows us to specify multiple capabilityURNs to the -caps command-line option. Let's ask for all nodes which have both the OpenFlow and DRAGON capability by specifying two capabilityURNs:

Only nodes that have both capabilities will be returned in the list.

Now would be a good time to examine the SQL INSERTs in the sampleData.sql which provided the backend data that provided this output.

---

Conclusion

At this time, the GENI AM implementation includes all the functions planned for in the design. These are categorized into the following four groups:

• Compute Slice Services include CreateSlice, DeleteSlice, QuerySlice, UpdateSlice, StartSlice and StopSlice.
• VLAN Networking Services include CreateSliceVlan, DeleteSliceVlan and QuerySliceVlan.
• RSpec-Based Slice Services include CreateSliceNetwork, DeleteSliceNetwork and QuerySliceNetwork.
• Resource Information and Topology Services include ListCapabilities, ListNodes ListSlices and GetResourceTopology.

A document describing how to use the MAX GENI Aggregate Manager Control Framework is available here:

• MAX GENI Aggregate Manager Control Framework Usage Document

Other functions or services could also be added. We plan to used these services and see what new features are indicated by users and use cases. Additional updates will be posted to this website and to the Subversion code repository. Please contact us if you have any questions, comments, patches or improvements to this software.