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
• Install Apache Tomcat
• Install Apache Axis2
• Deploy AggregateWS.aar (the compiled GENI AM code) as an Axis2 Web Service
• Test deployment using API client

---

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_HOME/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 $AGGREGATE_HOME = /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 do that in $AGGREGATE_HOME/AggregateAttic/conf/aggregate.properties.

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 %

Upon start, the AM will load default infrastructure users, nodes and capabilities etc. into the aggregate database from $AGGREGATE_HOME/AggregateAttic/conf/repo/crdb.xml

---

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

---

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.

A Convenient Deployment Command

If you just want to compile code and deploy to local system, instead of the above complicated commands, here is an all-in one command you can run right after exporting the code from SVN repository.

# cd $AGGREGATE_HOME/AggregateWS/ # ant axis2-deploy-local

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 can start downloading the API client package and run the example test clients against the deployed services.

Please see the API Client Guide for information on how to proceed.

---

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.