|
- Installing
OSCARS
- Hardware requirements
- Software Prerequisites
- Download OSCARS
- Setting-up the MySQL Database
- Quick Start
- Creating OSCARS users
- Setting up Server Keystores
- Setting up Client Keystores
- 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.4 to 0.5. 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.
If you already have a certificate and key in a pkcs12 file, use tools/utils/copyKeyto
import it as a keyEntry.
tools/utils/copyKey.sh -alias yourName -inpkcs12 yourPkcs12file -outjks examples/javaClients/repo/OSCARS.jks
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 using one of the tools
in tools/utils/ 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.
build-all
build all the OSCARS artifacts:oscars-core,aaa-core,notifybroker-core,
oscars-aar,oscars-war,notify-aar
deployall copies
OSCARS.aar and Notify.aar. to $CATALINA_HOME/webapps/WEB_INF/services, and OSCARS.war
to $CATALINA_HOME/webapps. It also copies
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.
If Tomcat is running at the
time of the deploy and is configured to dynamically deploy services,
the new OSCARS.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.
New versions of the aars require Tomcat to be restarted.
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.
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.
Use the script oscars.sh to
run the rmi servers: oscars-core, aaa-core and notifybroker-core.
|