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

Stopping all processes
Below is a description of each process.

1. Tomcat
   • Description: This process runs the web service (SOAP/XML) interfaces and web browser user interface (WBUI). In previous versions the core logic that reserved and managed circuits also lived in Tomcat. Version 0.5 splits the interface from the core logic. The interfaces remain in Tomcat but the core has separate processes (see below). In the future, this division will better allow OSCARS to support multiple versions of the protocol on the same IDC instance. The goal is that this will allow backward compatibility between software versions even as the protocol changes.
   • Process Name: An example of the process name as displayed by the command ps aux is shown below:

     /usr/local/java5/bin/java -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file=/usr/local/tomcat/conf/logging.properties -Djava.endorsed.dirs=/usr/local/tomcat/common/endorsed -classpath :/usr/local/tomcat/bin/bootstrap.jar:/usr/local/tomcat/bin/commons-logging-api.jar -Dcatalina.base=/usr/local/tomcat -Dcatalina.home=/usr/local/tomcat -Djava.io.tmpdir=/usr/local/tomcat/temp org.apache.catalina.startup.Bootstrap start

2. OSCARS Core
   • Description: This process schedules and manages circuits. It can be thought of as the IDC logic. Some of its primary tasks include publishing topology, calculating paths, checking for oversubscription, forwarding requests to other domains, scheduling circuits, and contacting a path setup component (i.e. the DRAGON VLSR).
   • Process Name: An example of the process name as displayed by the command ps aux is shown below:

     java -Dcatalina.home=/usr/local/tomcat -Djava.endorsed.dirs=lib/endorsed -Djava.net.preferIPv4Stack=true net.es.oscars.bss.OSCARSRunner

3. NotificationBroker Core
   • Description: This process routes notifications of IDC activity to subscribers of notifications. It is not specific by the IDC and may be used by other services. The primary interface into the core is web service interface that lives in Tomcat.
   • Process Name: An example of the process name as displayed by the command ps aux is shown below:

     java -Dcatalina.home=/usr/local/tomcat -Djava.net.preferIPv4Stack=true net.es.oscars.notifybroker.NotifyBrokerRunner

4. AAA Core
   • Description: This process authenticates users and checks their permissions to perform certain tasks. It is used by the interfaces, OSCARS core, and NotificationBroker through a Java Remote Method Invocation (RMI) interface. In future versions of the software a web service interface will be built for this component.
   • Process Name: An example of the process name as displayed by the command ps aux is shown below:

     java -Djava.net.preferIPv4Stack=true net.es.oscars.aaa.AAARunner

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

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:

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:

• Configuration files do not have to be moved each time you upgrade Tomcat
• You can run the shell scripts under the idc and idc/tools/utils directory from anywhere on the file system
• The core processes can use this variable if Tomcat runs on another machine

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
   • Optionally you may now add $OSCARS_HOME and $OSCARS_HOME/tools/utils to the PATH environment variable so the scripts can be run like a standard UNIX command.

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:

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.