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 is also a shell script included in the distribution, do_build.sh, that will attempt to download axis2 and rampart and build a properly configured axis2.war file. If mysql is found on your PATH, it will also create and populate the databases and tables that OSCARS uses.

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, testaaa and testbss, create the IDC user if it does not already exist, and grant it "ALL PRIVILEGES" on the four 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 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:
Check to see that examples/server/oscars.properties:hibernate.connection.user/password are set correctly (see above)  and then 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 Keystores


It is recommended that you read the message security page for an general explantion of the various keystores and properties files that you will need to edit.

Before a client can connect to your server using the web services API you will need to edit the files  $DOMAIN_HOME/server/{sec-server.properties, sec-server.jks}. Java keystores can be edited using the keytool command.

In sec-server.properties the keystore type and name can remain the same, but the password field should be changed.

After you change the password given in the properties file, you will need to change the password on the keystore file: sec-server.jks.

    keytool -storepasswd -keystore sec-server.jks -storepass password -new 'new-password'

You will then need to add a trustedCertEntry for the issuer of any certificate that will be used by an authorized user to connect to your OSCARS web service. When you add a new user to the system, you should get his certificate and the certificate for the issuer of his certificate. Then add the DN of the subject and issuer to the aaa:users table certSubject and certIssuer and add the issuer certificate to $DOMAIN_HOME/server/sec-server.jks, followed by ant setupServer to copy it to $CATALINA_HOME/shared/classes/server.

Use the following command to add a trustedCertEntry for the CA represented by cert.pem to the keystore sec-server.jks.

     keytool -import -keystore sec-server.jks -file 'cert.pem' -trustcacerts -alias 'CAname'

Setting up Client Keystores


axis2.xml -
edit the line

<user>alice</user>

to set name of the user who will be making requests tothe OSCARS service. The user name should be the alias that is in the keystore.

sec-client.properties - As in the case of the server, this should  be edited to have to change the  password for the keystore file (sec-client.jks).

sec-client.jks - Change  the password as above if you have edited sec-client.properties. Add a keyEntry for the client making web service requests to the OSCARS server. (see keytool for several ways to do this.)

ssl-keystore.jks -If you will be connecting to a server other than:

oscars.es.net, oscars-dev.es.net - signed for by
CN=ESnet SSL Server Certificates, OU=Certificate Authorities, DC=ES, DC=net
ndb3-blmt.abilene.ucaid.edu -signed for by
CN=DCSTest, OU=DCS Test, O=DCS Test, L=Ann Arbor, ST=Michigan, C=US

you will need to add either the site certificate or the issuer's certificate of  the Tomcat server to which the client will be connecting. The password for conf/examples/ssl-keystore.jks is "oscars".
(see keytool for suggestions on how to find the site certificate for a https enabled website.)

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.