Features and Changes

Full Backward Compatibility with 0.4

The version of the IDC protocol is 100% backward compatible with version 0.4 of the software. There are no protocol changes between version 0.4 and 0.5. Those who upgrade to version 0.5 of the software will be able to interact with other domains' IDCs still running version 0.4 of the software with no additional effort.

New Internal OSCARS Architecture

OSCARS version 0.5 splits the interface from the core logic and splits the core logic into functionally separate processes. See the OSCARS 0.5 Architecture page for a detailed description. For administrators the most visible change is that OSCARS should now be started and stopped with the oscars.sh command instead of running $CATALINA_HOME/bin/startup.sh and $CATALINA_HOME/bin/shutdown.sh. The scripts in $CATALINA_HOME/bin/ start and stop the Tomcat web server but OSCARS now consists of three other Java processes in addition to Tomcat: the OSCARS core, NotificationBroker core, and Authentication, Authorization, and Accounting (AAA) core. The new start and stop commands will control Tomcat AND the other three processes. The commands are shown below:

Starting/Restarting all processes

% ./oscars.sh

Stopping all processes

% ./oscars.sh stop

Below is a description of each process.

  1. Tomcat
  2. OSCARS Core
  3. NotificationBroker Core
  4. AAA Core

In addition each process may be started, restarted, and stopped individually using the oscars-core.sh, aaa-core.sh, and notifybroker-core.sh scripts with the same parameters as oscars.sh. Use the -h option for more information on the scripts.

Improved Web Browser User Interface Reporting

Error reporting in the web browser user interface (WBUI) is greatly improved. In version 0.4 many errors were not reported due to changes in the IDC protocol that made operations more asynchronous. The WBUI has been adapted to those changes and error messages are displayed. Also, the WBUI now automatically refreshes reservation status meaning frequent pressing of the "Refresh" button on the reservation details page is no longer required.

Running updateToplogy.sh Not Required

In version 0.4 and earlier administrators were required to run tools/utils/updateTopology.sh each time they made a change to the tedb-intra.xml file. Users that publish their topology with the topology service can set the external.service.topology.updateLocal=1 property in oscars.properties and have their topology automatically updated within 60 seconds of a change to tedb-inter.xml occurring (Note that you should now be editing tedb-inter.xml NOT tedb-intra.xml if you use this property). The do_upgrade.sh will prompt those upgrading from 0.4 if they'd like to add this property and new users will have this set by default.

Simplified Interdomain Peering

Assuming you publish your topology, use the lookup service, and the perfSONAR pathfinder (which is the default and most common configuration) there are only three steps to peering with a new domain:

  1. Add the link to the new domain in tedb-inter.xml
  2. Associate the domain with an institution with tools/utils/idc-siteadd
  3. Create a user account for your peer through the web browser or with tools/utils/idc-useradd

There is no longer a requirement to add downstream domains with idc-domainadd and subscriptions will automatically be created as needed eliminating the need to restart the IDC.

New Log File Locations

Since OSCARS no longer exists entirely in Tomcat the logs are organized differently now. In 0.4 everything was logged in the $CATALINA_HOME/logs/catalina.out file. Now logs can be found in the following locations by default:

NOTE: Unless explicitly set as an environment variable OSCARS_HOME will be dcn-software-suite-0.5/idc

Component

Log Location

Types of Messages

OSCARS Web Browser User Interface

$CATALINA_HOME/logs/catalina.out

Invalid logins to the WBUI, problems reaching the OSCARS or AAA core (i.e. a process died), problems with cookies

OSCARS Web Service

$CATALINA_HOME/logs/catalina.out

Certificate authentication failures, invalid incoming messages from other IDCs or web service clients, problems reaching the OSCARS or AAA core (i.e. a process died)

NotificationBroker Web Service

$CATALINA_HOME/logs/catalina.out

Certificate authentication failures, invalid incoming messages, problems reaching the NotificationBroker or AAA core (i.e. a process died)

OSCARS core

$OSCARS_HOME/logs/oscars.log

Information about scheduling the circuit, finding a path, contacting another domain, and setting up a circuit (including DRAGON command-line output)

AAA core

$OSCARS_HOME/logs/oscars.log

Information and errors related to authentication and authorization

NotificationBroker core

$OSCARS_HOME/logs/oscars-nb.log

Information and errors related to sending notifications to others and creating/managing subscriptions

New Utilities

A number of new utility scripts have been added to aid in managing your IDC. All of these scripts can be found under the dcn-software-suite-0.5/idc/tools/utils directory. They are as follows:

Script Name

Purpose

idc-domainmod

Manually modifies the URL that points to a domain's IDC. This is useful if a neighbor is not in the Lookup Service but their IDC url changes or contains a typo.

idc-domainview

List all the domains and their IDC URL that are currently in the local database

idc-servicemod

Manually modifies the URL that points to a domain's NotificationBroker. This is useful if a neighbor is not in the Lookup Service but their NotificationBroker URL changes or contains a typo

idc-serviceview

Lists all the services such as NotificationBrokers and their current URL

notifybroker-subscriptions

Lists the current subscribers to notifications and the types of notifications the wish to receive. This can help debug issues when circuit reservation or setup fails due to a timeout error.

Advanced Features

Setting the OSCARS_HOME Environment Variable

You may OPTIONALLY set the OSCARS_HOME environment variable to point to the location where configuration files and third-party libraries are kept related to OSCARS. You will need to set OSCARS_HOME to the location of the dcn-software-suite-0.5/idc directory or equivalent (i.e. if you moved dcn-software-suite-0.5/idc to /usr/local/oscars you should set OSCARS_HOME to /usr/local/oscars). This has the following advantages:

If you are doing a new installation (i.e. no previous versions of the software exist on your system) you may set OSCARS_HOME before running ./do_build.sh and continue the process as documented. If you are upgrading you will need to run do_upgrade.sh, set OSCARS_HOME, and then complete the following:

  1. Run do_install.sh
  2. Move the file $CATALINA_HOME/shared/classes/repo/OSCARS.jks to $OSCARS_HOME/conf/axis-tomcat/OSCARS.jks.
  3. Move the file $CATALINA_HOME/shared/classes/repo/ssl-keystore.jks to $OSCARS_HOME/conf/axis-tomcat/ssl-keystore.jks.
  4. Move $CATALINA_HOME/shared/classes/server/oscars.properties to $OSCARS_HOME/conf/properties/oscars.properties
  5. Open $OSCARS_HOME/conf/axis-tomcat/rampConfig.xml and change the <ramp:user> tag to the alias of your IDC certificate and <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password"> to your keystore password.
  6. Restart OSCARS with ./oscars.sh

Stand-alone NotificationBroker

You may install the NotificationBroker as a standalone component. Installation instructions can be found on the page Installing the NotificationBroker.

Contacting an External Policy Engine

Version 0.5 of OSCARS contains support for contacting an external policy engine behind a web service. This allows custom policy engines to be pluggable into OSCARS. You may activate this feature be setting the following in oscars.properties:

policy.useService=1 #Activate service
policy.service.url=http://policy-host/path-to-service #URL of service

Currently a policy engine is under development by Internet2 and will be released in the coming months. If you wish to write your own policy engine or are interested in learning more about the protocol implemented please see the page OSCARS Policy Interface.