OSCARS Reservation Manager Design Specification

Year 3 Update (DRAFT)

David Robertson, Chin Guok
ESnet

September 29, 2006

Introduction

This document focuses on the design decisions made for implementing the requirements for the reservation manager (RM) portion of OSCARS. This update, when completed, will include the design decisions made as part of the process of porting OSCARS to Java.

NOTE: at this point, specification of items remaining to be done this year is not complete.

Portions of this document are taken from the OSCARS project summary. Specifications have been updated based on lessons learned thus far. Items with a (*) remain to be done this year.

Design specifications take into account the fact that security is absolutely essential, for reasons stated in the requirements. During the following discussion of the RM's components, security implications are postponed until the final section.

The Internet2 BRUW Web pages, including CGI forms, were originally used as the starting point for the interface design and necessary functionality. Currently ESnet and Internet2 staff are collaborating on a single code base (active work is now in the Java language, with only bug fixes on the Perl branch).

Use of Web Services

A primary design decision is to implement the RM as a Web service. Web services (WS) standards are used wherever possible, including SOAP for transport, and WSDL for the service description.

Given the complexity of WS, existing support for them has to be used as much as possible. OSCARS was originally coded in Perl. Perl provides functionality such as mod_perl, SOAP::Lite, Perl DOM packages, etc., and is not strongly typed, allowing for rapid development of a prototype. Currently, most of the required functionality for the components of the RM has been implemented, and prototype interdomain functionality has been implemented. Successful interdomain tests have been run using OSCARS, Internet2, and TeraPaths.

However, most of our collaborators have developed complex WSDL service descriptions. Perl's handling of automatic code generation from complex WSDL is immature. Better coding tools have also become necessary, because more functionality will be added to OSCARS, including more complex and functional interdomain reservation setup.

Given this, OSCARS is in the process of being ported to Java (*). Java has more mature support for WSDL and other WS standards, and extensive tools to develop Web applications. Java allows the use of the Tomcat container, standard coding tools and helper applications such as Eclipse and Hibernate, and libraries such as Axis (which provide for code generation from complex WSDL).

RM

The RM consists of a Tomcat server, two databases within a MySQL 5.1 server as described below, and a set of Java Server Faces pages, which handle servlet functionality. Two types of clients for the Tomcat server are implemented, one using browser-based Web forms, and the other using programmatic submission via an API. The Tomcat server runs behind a firewall, and is accessible via proxying through an open Apache Web server (security implications are discussed below).

Transport

Browser-based clients send requests via Ajax submission. When Tomcat receives a request via the Apache server, it dispatches it to the associated servlet based on the URL of the request. The servlet extracts the parameters from the request using a standard mechanism.

The API client uses SOAP to make requests. When Tomcat receives a SOAP request via the Apache server, Tomcat uses the URL to dispatch it to the appropriate servlet, which uses the Axis library to extract the parameters.

SOAP requests made via the API must conform to the Web Service Definition Language (WSDL) specification of the OSCARS service. WSDL provides for definitions of data types for message arguments using XML Schema, and definitions of request and response messages. A service description is only publicly available for public BSS requests (done). Internal methods are also described via WSDL, for documentation and consistency, but this latter description is only for internal use (*).

The mapping of a URL to a servlet is done via Tomcat XML configuration files. Examples of the appropriate configuration are provided with the OSCARS distribution (*).

After the servlet has extracted the parameters, processing continues in an identical fashion, regardless of the type of client performing the request.

Database

The MySQL 5 database server is used. Within the MySQL server, there is a main OSCARS database, and a topology database describing the current ESnet routers.

Much of the complexity of using a strongly typed language such as Java, with the loading and storing of objects to database tables, is hidden using the Hibernate object/relational mapping application. Hibernate greatly simplifies persisting Java objects to the MySQL database, eliminating the need for porting a significant portion of the corresponding level of Perl code, which uses the Perl DBI (the conversion to Hibernate is in progress).

Browser-based Client

The interactive user interface to the RM is a Web-Based User Interface (WBUI), i.e., a browser. The specific mode of interaction is via form submission to the Apache server, which in turn forwards the requests to the Tomcat server.

All forms have three areas: a banner area, a status area, and a main area for the primary functionality, with a line of navigation tabs at its top.

If an error occurs during the processing of a user request, a SOAP faultstring is returned to the entity which made the SOAP call. This error message is displayed in the status area, and the main area is unchanged. If no error occurred, new information is displayed in the main area depending on which form was submitted.

Clicking on a tab on the navigation bar takes the user to a corresponding form. The requests listed in the requirements are mapped to forms as follows:

Authentication, Authorization, and Auditing (AAA) forms

Bandwidth Scheduler Subsystem (BSS) forms

API Client

Requests made via the API must conform to the OSCARS WSDL description. All requests listed in the requirements that indicate they can use the API are exposed. All other methods are accessible only for testing purposes on the machine where the OSCARS server is running.

Clients send SOAP messages to the Apache server, which forwards them to the Tomcat server. If an error occurs during the processing of a client request, a SOAP faultstring is returned to the client which made the call.

Reservation Request Handling

The process of making and scheduling a reservation is as follows:

  1. Interactive interface:

  2. API:

  1. At this point, the steps are the same for both types of clients. After authorization, the Tomcat server uses the URL in the SOAP request to dispatch the request to the associated BSS servlet.

  2. After checking for valid fields, the BSS executes a traceroute to find the path to take within ESnet, based on the source and destination. During that process, the BSS finds the ingress and egress ESnet routers, if they have not already been specified by a client that has the network engineer permission.

  3. Before entering the reservation in the BSS's database, the BSS checks to make sure that none of the links in the path are oversubscribed. If they are, an error message is returned to the client.

  4. The BSS next creates a row in the database containing the information for the reservation. Reservations are identified to the client by unique tags which are generated by concatenating a user's email address, the date and time, and the primary key of the row in the database.

  5. Upon successfully entering the reservation, the BSS returns a "success" message and an identifier for the reservation back to the client.

A cron script periodically polls the database to see if reservations have become current, in which case the Path Setup Subsystem (PSS) library is called to set up the label-switched path (LSP). The script also polls to see if a reservation has expired, at which point a call is made to the PSS library to tear down the LSP.

The PSS uses Junoscript to configure Juniper routers. If it becomes necessary to configure Cisco routers, RANCID will be used. The PSS sets up the LSP, checks for non-valid paths, and tears down the LSP.

Security

The Apache Web server runs on an open ESnet machine, and forwards all requests to the internal Tomcat server through the ProxyPass and ProxyPassReverse configuration directives. This forwarding process is transparent to the end user.

The Tomcat server runs on a machine for which a firewall filter has been set up. Only ESnet and LBNL personnel's machines are included in the acl's. The Tomcat server only accepts requests from the Apache server.

If a URL contains the string 'OSCARS' at the start of its path, the request is originating from the API. The Tomcat server uses the presence or absence of this string to determine how to perform authentication, which is described below.

The Apache and Tomcat servers only accept https connections. Their associated processes run as an unprivileged user without a login shell. Server startup and shutdown are handled by rc.d scripts.

Database server processes run as an unprivileged user without a login shell. The database server only accepts requests from database clients running on the same machine as the Tomcat server. MySQL is configured with the --skip-networking option to ensure this. Database server startup and shutdown are handled by rc.d scripts.

Authentication

Browser-based client

Users currently must have an OSCARS account to use the interactive interface. They must provide their user name and password via the initial login form. The Tomcat server makes a call to the oscars database to see if the user's name exists, and whether the password matches. If so, the user's DN is returned to the calling entity, and stored using a session. The cookie sent to the browser contains a reference to that information, rather than the information itself. The cookie times out after 8 hours.

After successful login, subsequent form submissions retrieve the user's DN from the cookie. The DN is passed along in the Ajax request to the Tomcat server. The server requires the DN for anything besides login requests.

API client

Signed SOAP messages are required for all API requests. The Tomcat server runs openssl code to validate the certificate and extract the associated user's DN. Upon successful authentication, the next step is authorization, using the user's DN.

Authorization

The Resource Oriented Authorization Manager (ROAM) is taken as the model for handling authorization. Authorization is handled using the Users, Resources, ResourcePermissions, and Authorizations tables. Current resources are "Users", "Reservations", "Domains", and individual routers. Current permissions are "manage", "persistent", "set", and "view". The Authorizations table contains triplets of user/resource/permission combinations. A lookup is done against the authorizations table, given the user's login, to see if that user has a specific permission to use a particular resource.

All operations that require authorization require an OSCARS account. Only about 15 to 20 people are anticipated to require use of these operations.

Auditing

The RM uses ESnet production tools to monitor usage (*). Notifications of successful reservation creation, and LSP setup and tear down are done via email to the appropriate ESnet personnel.

Risks

As simple as possible a solution has been chosen for security, while attempting to minimize risk. If OSCARS is difficult to use, or difficult to install, then it won't be used.

The primary risks are the open machine running the Apache server being compromised, and/or the session ID for the cookie containing a user's DN being discovered and used to execute OSCARS operations.

The Securing FreeBSD guidelines will be followed for the OSCARS machine. A firewall filter is set up to only allow access from a specific port on the machine running the Apache server to the machine running the Tomcat server.

The cookie will initially be set to timeout after eight hours to limit the exposure from a compromised session key.