|
- Installing
OSCARS
- Hardware requirements
- Software Prerequisites
- Setting-up the MySQL Database
- Download OSCARS
- 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 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.
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.
If this user does not already exist, it will be created and granted "ALL
PRIVILEGES ON aaa.* and
bss.* "
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 use the following commands.
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.
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.
Quick Start
If you have installed Tomcat, Ant, jta.jar and MySQL, and have
started the MySQL server, 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 database and compile
the distribution.
If you want to see if things are working so far, start the Tomcat
server 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 deploy.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.
|