home > Installing OSCARS

Installing OSCARS





  1. Installing OSCARS
    1. Hardware requirements
    2. Software Prerequisites
    3. Download OSCARS
    4. Setting-up the MySQL Database
    5. Quick Start
    6. Creating OSCARS users
    7. Setting up Server Keystores
    8. Setting up Client Keystores
    9. Description of major tasks in the build process

Hardware requirements


The OSCARS IDC software requires a single PC that will act as a web server for processing requests. Most modern PCs should be suitable for running the software. The following specifications are the minimum requirements for most installations:
  • 1Ghz Processor, 1GB memory
  • Linux/Unix Operating System (including MacOSX)
  • Basic Internet connectivity
  • System clock running the Network Time Protocol (NTP)
  • Access to a mail server to send mail
The IDC listens for http on port 8080 and https on port 8443 by default.

Software Prerequisites


The OSCARS software is written in Java 5.0 and depends on the following Java packages.
The persistent data for reservations, topology and user information is stored in MySQL tables so MySQL 4.1.2 or later must be installed.

Click through the links above for details on how to install and configure these packages. The DCN-Dragon-Suite Installation Manual also covers installation of these packages in section 1 and 2.

There are several shell scripts included in the distribution:
  • do_build.sh which will check for prerequsites,  download axis2 and rampart if they are  missing. build and deploy axis2.war, create and populate the databases and build a properly configured axis2.war file.
  • do_install.sh which is run after do_build and sets some OCSARS configuration variables in the deployed axis2, installs the OSCARS keystores, deploys the OSCARS.war, OSCARS.aar and OSCARSNotify.aar, and builds the tools/utils directory.
  • do_upgrade.sh which will upgrade a DCN release 0.3 to 0.4. It will update the
  • version of axis2 to 1.4.1, update OSCARS security configuration and keystores and update the mysql data bases.

Download OSCARS


See the Download page for instructions on how to download the OSCARS source code from either the code repository or from a tar file.

The distribution includes the OSCARS IDC code; a suite of test programs; a set of example Web Service client programs; a tools directory that includes a stand-alone scheduler program, some topology updating tools, a monitoring script that checks that the service is responding,  a script to do sanity checks on the databases; complete documentation including the JavaDoc and configuration files.

Setting-up the MySQL Database


If you let do_build.sh install your databases it will do the following things:

Prompt you for the privileged user and its password. (this should be the user and password that you set when you installed MySQL). It will use this to connect to your mysql server.

Prompt you for the name and password of the user that will be used by the IDC software to connect to the database. This  name and password must match what you put in the oscars.properties file as hibernate.connection.username and password.

Create databases named aaa, bss, notify, testaaa and testbss, create the IDC user if it does not already exist, and grant it "ALL PRIVILEGES" on the five databases. Initialize the aaa database with standard permissions, attributes and resources.

Do not confuse these two mysql users with the OSCARS users that you will be creating later. These users should have access to mysql only from localhost. The access control on these users is completely separate from that of the OSCARS users, so in order to preserve the integrity of the OSCARS system, the number of mysql users should be strictly limited to system administrators.

If you do not want to have do_build.sh create your databases  you can say no to the "Install databases" prompt and use the following commands instead.

Creating the aaa Database
The aaa database contains authentication, authorization, and accounting information. This includes user accounts and attributes. To create the database and populate it with some sample values, issue these commands:

cd sql/aaa
mysql –u root –p < populateDefaults.sql

This creates the aaa database and tables populated with the institutions, permissions, resources and attributes expected by the aaa component.

If you want to create empty tables use the sql/aaa/createTables.sql script.

Creating the bss Database
The Bandwidth Scheduling Subcomponent (BSS) reserves and manages network resources. The bss contains the list of reservations and enough local topology information to track the resources in use by those reservations. To create the database and a set of empty tables, issue these commands:

cd sql/bss
mysql –u root –p < createTables.sql

Do not run this command after you have added any topology to the database as it deletes all the existing tables and starts over. If you wish to just delete information about reservations use the cleanReservations.sql script.

Creating the notify Database
The notification server handles the notifications about reservation state changes between different IDCs and users. It  keeps a database of event publishishers, subscriptions and subscription filters. To create the database adn a set of empty tables  issue these commands:

cd sql/notify;
mysql -u root -p < createTables.sql


Creating and granting access to a user for the IDC

shell> mysql -u root
mysql> GRANT ALL PRIVILEGES ON aaa.* TO 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON bss.* TO 'user-name'@'localhost' IDENTIFIED BY 'password';

Once the IDC user has been added to the database either by do_build.sh or manually you must edit the file examples/server/oscars.properties to set the hibernate.connection.username and hibernate.connection.password to the user and password that were given for the IDC user.

Quick Start


If  you have installed Tomcat, Ant, jta.jar and MySQL, you can run the do_build.sh script;

It will check the installation of the items listed above, download and install axis2 with rampart if needed, setup the databases and compile the distribution.

Once do_build has completed building the tools and exited, you can try the following:  start the Tomcat server using

$CATALINA_HOME/bin/startup.sh

and use your browser to connect to

https://localhost:8443/ and/or http://localhost:8080/

which should show you a Tomcat page. Clicking on the status button, and giving it the Tomcat manager account and password that you set in $CATALINA_HOME/conf/tomcat-users.xml should bring up a page that lets you choose to list applications. Clicking on that should show axis2 as one of the services. Clicking on that should give you an axis2 welcome page.

At this point you can make a test deployment of OSCARs using the example users and credentials that are in the conf/examples directory or you can start setting up access for your real users.

To do the former:
Run the do_install.sh command and answer yes to the question about copying keyfiles and configuration files.

If this suceeds OSCARS should appear on the list of axis2 services and you should be able to connect to https://localhost:8443/OSCARS and see the OSCARS login page.

You should also be able to run

    ant test -Dt=aaa;

and see
   [testng] aaa.suite
   [testng] Total tests run: 28, Failures: 0, Skips: 0

At this point you need to setup your local users and import your local network topology before you can start making reservations.

Creating OSCARS users


Begin by creating a domain specific directory with two subdirectories: server and client.

Copy all the files in conf/examples/ to the new directories and set the environment variable DOMAIN_HOME to point to it.

Edit the $DOMAIN_HOME/server/oscars.properties to change aaa.salt before you add any users.

use ant setupServer to copy the new files to $CATALINA_HOME

Use the tools/utils/idc-useradd command to add a privileged OSCARS user. 
    cd tools/utils
    ant  (will build the tools)
    ./idc-useradd

The login field will be the user's primary identification and can not be changed later, all the other fields can be modified after the user has been created. The Cert Subject and Cert Issuer can be left blank for now. Select the OSCARS-engineer and OSCARS-administrator roles.

If you use this login name to login to the OSCARS web page you will be able to use the browser interface to create more users and eventually to create resesrvations.

Setting up Server Keystore


In order to make interdomain reservations or to use the SOAP api from the comand line clients in the examples directory, the OSCARS.jks keystore must have a keyEntry for the service.  It is recommended that you read the message security page for an general explantion of the various keystores and configuration files that are site specific. The ant task setupServer promted for the alias of the service . Now you must add a KeyEntry for this service user who will sign response message and forwarded messages.

You can add a user KeyEntry to the keystore in several ways. If you are running a standalone server, use tools/utils/idc-certadd and chose option 1. This will create a keyEntry with the alias you give and a self-signed certificate. If you are going to be connected to the Internet2 or ESnet IDC's you will need a certificate that is signed by a trusted CA. Use icd-certadd and chose option 2 which will add a keyEntry and also generate a certificate signing request that can be sent to a trusted CA.

Setting up Client Keystores


If you wish to use the command line clients in examples/javaClients you
will  need to setup the keystore there.

cd examples/javaClients
ant

Will copy and edit the axis2.xml and rampConfig.xml files into examples/javaClients/repo. If you answered y to the question

Do you wish to use the rampConfig.xml in the repo subdirectory in axis2.xml to be able to customize the user key (as opposed to using the default ? (y,n)

you will need to add a keyEntry to repo/OSCARS.jks. If you answered no, the clients will use the same keystore that the server uses.

Description of major tasks in the build process


prepare copies axis2 and tomcat libraries from the Tomcat deployed area, $CATALINA_HOME, into the distribution's lib directory, and the msql-connector jars from a maven repository.  It also copies some configuration files from the conf directory to the build area, from whence they will be put in the aar and war files.
Normally called by the compile task.

wsdl2java
checks to see if the web service stubs have been generated from the OSCARS.wsdl and if not runs the axis2 WSDL2Java program to generate them. The resulting Java files are put in src/net/es/oscars/wsdlTypes and src/org/ogf/schema/network/topology/ctrlplane/_20070626

compile depends on prepare and wsdl2java
compiles all the server classes into build/WEB-INF/classes.

aar ceates the build/OSCARS.aar file from the classes in build/WEB-INF/classes (excluding the servlet classes),  the jars in the lib directory and the wsdl, xsd and services.xml files in conf/server.

deployaar  copies OSCARS.aar to $CATALINA_HOME/webapps/WEB_INF/services, the log4j.properties file to $CATALINA_HOME/webapps/WEB_INF/classes where axis2 can find it, and a couple of jar files that need to be in $CATALINA_HOME/shared/lib.

wbui generates the JavaDocs for all the IDC classes and for just the client side classes. It copies all the static docs into the web/docs directory from which they are included in the OSCARS.war. It then builds the war from the classes in build/WEB-INF/classes (excluding the web services classes), the lib jars and the docs.

deploywbui  depends on wbui, compile, and copydocs
It just copies the OSCARS.war file to $CATALINA_HOME/webapps. If Tomcat is running at the time of the deploy and is configured to dynamically deploy services, the new war will immediately be deployed. If Tomcat is not running, you may need to delete the old deployed directory $CATALINA_HOME/webapps/OSCARS before the new war will be started.

setupServer copies a number of files to the $CATALINA_HOME/shared area where they are used by axis2 and rampart. We also have our own version of log4j.properties which we put in $CATALINA_HOME/common/classes for use by Tomcat. setupServer only needs to be run once per installation unless you change any of the copied configuration files.