Version 68 (modified by chase, 9 years ago)



Software prerequisites

Build ORCA from source

Understanding container configuration: ORCA_HOME, ORCA_LOCAL, and all that

Actor configuration

Deploying GENI-ORCA

Orca actors run within containers (JVMs). We assume that your orca container is a Tomcat web application server.

Install Tomcat and create the initial database

1. Download the Tomcat tar file. ORCA uses a customized Tomcat, so using standard Tomcat is not recommended

2. Create a directory for the install. We install into /opt/orca/tomcat, and put the orca-related configuration files into /opt/orca. Since the configuration files are there, /opt/orca is ORCA_HOME. Note: the ORCA source may be somewhere else.

3. Untar the contents of the tomcat tar file into its install directory (e.g., $ORCA_HOME).

4. Edit tomcat/ and to set CATALINA_HOME to point to the tomcat directory. Also in and set ORCA_HOME to the directory with the container configuration files (e.g., /opt/orca).

export ORCA_HOME=/opt/orca

5. Edit tomcat/conf/server.xml and tomcat/server/classes/webauth.xml to change references to '/shirako' to the new location of the directory you created (e.g., /opt/orca). Only do this step if you are using webauth authentication. If you are not sure, then you are not. Webauth authentication requires significant setup from your identity provider.

6. Execute tomcat/

7. Make sure MySQL is running on your system.

NOTE 2: For Mac OS X you can use fink to install mysqld and then

$ cd /sw/bin
$ sudo ./mysqld_safe

This will make sure mysqld is running as long as you don't exit this shell

8. Create a mysql database and populate it These instructions help set up a local Tomcat container with an example inventory of substrate that allows ORCA to run in emulation mode. This step is highly recommended before running with real resources to make sure your setup is correct.

9. Give ANT more heap space. This can be added to ~/.profile

$ export ANT_OPTS="-XX:MaxPermSize=512m -Xms40m -Xmx1024m"

Generating the GENI-ORCA container configuration files

The actor-independent configuration files for the container reside in ORCA_HOME. These config files include a security configuration, with certificates and a keystore.

1.2 and following releases (Bella)

Starting from release 1.2 ORCA no longer packages config/ or runtime/ directories into the webapp. Note also that in the initial release of Bella (2.0) has a directory called webapp2/ for the new configuration framework. If your source pool has a directory webapp2/, then use webapp2/ instead of webapp/ in the instructions below.

1. Generate a security configuration.

$ cd tools/config
$ ant security.create.admin.config

This command creates a directory called runtime/ in the current directory (tools/config) and places the generated files in there. NOTE: if there is an existing runtime/ directory, first move it out of the way.

2. Define ORCA_HOME (e.g. export ORCA_HOME=/opt/orca) and copy the config to $ORCA_HOME.

$ cp -r runtime $ORCA_HOME
$ cp -r scripts $ORCA_HOME

3. Edit the configuration files ( etc.) under webapp/ and copy it to $ORCA_HOME. Note: you might want to copy it first, rather than editing it in place. Please do not check modified configuration files into the source pool.

$ cd ../../webapp
$ vi config/
$ cp -r config $ORCA_HOME

4. Optional: configure actors for your container by installing a config.xml in your ORCA_LOCAL. The config.xml is installed to ORCA_LOCAL by editing it in webapp/actor_configs/config.xml, then deploying the webapp (see below).

1.1-alpha and previous releases

If your filesystem supports symbolic links, simply use the provided ant task:

$ ant prepare.use

This task will generate the admin security configuration and place links to it in the relevant directories. It will also initialize and link other directories needed to build/test drivers.

If your file system does not support symbolic links or you want more control over the process you can try the following steps:

1. Create the security configuration by going to tools/config and running

$ cd tools/config
$ ant security.create.admin.config

NOTE: Make sure there is no existing runtime directory before you run this command unless you know what you are doing.

2. Copy or softlink the resulting runtime/ directory to the orca/webapp directory.

Generating the GENI-ORCA web application

1. Create the webapp with this command:

$ mvn package

in orca/webapp.

2. Deploy into an already running tomcat instance on the local machine by typing

$ cd <orca>/webapp
$ ant deploy

Before packaging the webapp, the webapp config directory should be populated with configuration files for ORCA_LOCAL, as described above. Before deploying the webapp, the tomcat container should be configured with a proper ORCA_HOME populated with configuration files as described above.

3. Wait until the actors start ticking before you log into the portal. Check in the log file (tomcat/logs/log) or just wait 30-45 seconds. Tomcat has an annoying race condition during webapp initialization. If you try to log in too early, ORCA will fail to start up correctly.

4. Log into the portal at http://localhost:8080/orca with username "admin" and no password, unless you changed the defaults.

NOTE: as of Bella 2.0 container administrator login/password credentials are located in

5. If the app did not come up as expected, then the container (ORCA_HOME) and actors (ORCA_LOCAL) are likely misconfigured. There is no easy way to debug configuration errors. Check the container logs in tomcat/logs/orca*.log. You can add more information to these logs by editing the log4j properties in ORCA_HOME/config/, e.g., to add "%C %M %L" to the ConversionPattern to print the class, method, and line number for each log message. It is also possible to load config.xml directives into the running web GUI, under the admin tab, which gives additional error reporting through the GUI. Config processing is not atomic or idempotent: if config processing fails, some directives may have completed successfully.

Feature: claim processing for exported tickets (advertisements/delegations) must be done manually after the container stands up, since it requires inter-actor communication. Go to the broker tab, create an inventory slice, and claim the delegation, using the GUID for the exported ticket, which is visible under the site tab (view exported tickets).

Feature: if you restart tomcat, it will recover your previous container state. If you redeploy, or undeploy and redeploy, it will reinitialize the container to its fresh state, and delete state about existing slices and reservations from the database. Note also that tomcat does not always stop cleanly: sometimes it is necessary to kill the process. This case may lead to problems on recovery due to an unidentified bug. If you don't need to recover, then re-deploy. If you want to be sure your tomcat is clean, you might first remove the tomcat/webapps/orca* directories before restarting the server and redeploying.