Copyright ? 2011 Green Energy Corp. All Rights Reserved.
?
Document Control #: 02.004.000.000.000
Release Date: 20111220
Before running Reef, you'll need working installations of Apache Qpid and PostgreSQL. Refer to the following pages for instructions on settings up these dependencies.
Note: If you are running Ubuntu and would like to avoid some of the headache of installing of these components separately you can check out our Sprinkle Based install.
You will need to install a current java 6 version.
Windows: Download and install from java.com
Ubuntu:
sudo apt-get install sun-java6-jdk
We're currently running against Qpid 0.8. For longer running deployments, we recommend the Qpid C++ broker, but installation is not streamlined for all platforms. There is currently no debian package for Qpid requiring a build from source.
If you're just evaluating Reef or doing light development, the Java version of the broker is a viable, easy to install, alternative.
Go to http://qpid.apache.org/download.cgi and download and extract qpid-java-broker-0.8.tar.gz file. Then run the appropriate script in the bin directory. qpid-server or qpid-server.bat
Windows: Download the prebuilt binaries and install.
If running on windows you will need to update the "org.totalgrid.reef.cfg" file to set the "org.totalgrid.reef.amqp.user" and "org.totalgrid.reef.amqp.password" fields to a valid windows user.
Ubuntu: Build from source using the instructions on Qpid site.
We have also created a set of experimental scripts to automate the setup of a Reef node including installing qpid. We will be dedicating more resources to improving the install process in the future, but for now THESE SCRIPTS ARE PROVIDED AS IS WITH NO WARRANTY. Once the scripts have completed you will need to run through this PostgreSQL configuration. Specifically pay attention to the section about pre-populating the database. Successful execution of these scripts will have installed all of the necessary dependencies to operate Reef you can proceed immediately to downloading the reef-karaf distribution for your OS.
We use the open source postgresql database engine, it easy to install and use on all major platforms.
Windows: Download and install from postgresql.org
Ubuntu:
sudo apt-get install postgresql-8.4
You will need to configure a user and database table for Reef to use. The schema is initialized later with an OSGI command, all we need to do externally is create the user and database. The following script will setup the user/databases for running and testing with default settings. If on windows copy the block starting with "CREATE USER" into the "SQL Shell (psql)" application (after logging in). If on linux you should be able to copy/paste the whole script into a command shell.
rm -f postgres.sql
cat > postgres.sql
If you plan to use Reef w/ DNP3 support you'll have to install a separate library before adding the dnp3 protocol from the Karaf shell.
Download and extract the shared library for your platform from: http://code.google.com/p/dnp3/downloads/list
Windows: Copy the file to your windows system 32 directory. 64bit users copy the 64bit library to systemWow64.
Ubuntu: Copy the library to /usr/lib:
sudo cp libdnp3java.so /usr/lib/libdnp3java.so
To enable DNP3 support in Reef you need to install the dnp3 "feature".
karaf@root> features:install reef-dnp3
Reef is packaged as a redistribution of Apache Karaf. A basic understanding of OSGi and the Karaf shell will be helpful. The following modifications are made to Karaf for Reef:
Addition of repo.totalgrid.org to the maven repository list
Modification of the logging configuration
Rebranding of the Karaf shell
Reef "feature" file is included
Reef bundles are pre-loaded into the distribution
Sample system models in the "samples" directory
After all of the prerequisites have been installed vist the Reef Download page and get the reef-karaf server for your OS. When the download is complete unpack the archive in your working directory.
Upon installation, Reef deployments come with the core software installed but the running system components disabled.
When a Reef deployment is not pointed at an existing Reef installation (in the database), users must perform a one-time installation process. To load a Reef configuration file and activate the Reef node, run the following command from the Reef base directory:
Linux:
./install_config.sh
Windows:
install_config.bat
The "install_config" command resets the database, starts a running instance of Reef, and loads the specified configuration file.
When a Reef deployment is pointed at an existing Reef installation (in the database), all that needs to be done is to activate the node. The following command in the Reef base directory will start Reef and activate the services and front-end:
Linux:
./activate_node.sh
Windows:
activate_node.bat
Now that we have an activated deployment pointing at an active configuration, we can log into the Reef console. The installation and activation scripts both leave a running instance (the equivalent of the Karaf "bin/start" command), so to access the running instance we use the "bin/client" command.
When there is not an active instance running in the background, we can start Reef using the "bin/reef" command.
Either of these options brings up the Reef console:
To start Reef in interactive mode:
bin/karaf
To start Reef in the background:
bin/start
To connect to a backgrounded Reef shell:
bin/client
To shutdown the Reef Node:
karaf@root> shutdown
To see a list of modules installed:
karaf@root> list START LEVEL 100 , List Threshold: 50 ID State Blueprint Level Name [ 44] [Active ] [ ] [ 60] Reef Dependencies Bundle (0.2.3.SNAPSHOT) [ 45] [Active ] [ ] [ 60] Reef Utility Library (0.2.3.SNAPSHOT) [ 46] [Active ] [ ] [ 60] Reef Metrics Provider (0.2.3.SNAPSHOT) [ 47] [Active ] [ ] [ 60] Reef Core (0.2.3.SNAPSHOT) [ 48] [Active ] [ ] [ 60] Reef AMQP Messaging (0.2.3.SNAPSHOT) [ 49] [Active ] [ ] [ 60] Reef Protocol Buffers Library (0.2.3.SNAPSHOT) [ 50] [Active ] [ ] [ 60] Reef API (0.2.3.SNAPSHOT) [ 51] [Active ] [ ] [ 60] Reef API Request Library (0.2.3.SNAPSHOT) ... [ 58] [Active ] [Created ] [ 70] Reef Proto Shell Extension (0.2.3.SNAPSHOT) [ 59] [Active ] [Created ] [ 80] Reef Admin Shell Extension (0.2.3.SNAPSHOT) [ 60] [Active ] [Created ] [ 90] Reef Benchmark Protocol (0.2.3.SNAPSHOT) [ 61] [Active ] [ ] [ 91] Reef Services (0.2.3.SNAPSHOT) [ 62] [Resolved ] [ ] [ 100] Reef Front-End Processing (0.2.3.SNAPSHOT) [ 63] [Active ] [ ] [ 100] Reef Measurement Processing (0.2.3.SNAPSHOT)
To start/stop/restart a module, find id from list command (for example in the above listing the front-end has id 62 and is stopped):
karaf@root> start 62
See log messages (also logged to data/log/karaf.log):
karaf@root> ld .... 13:52:18,515 | INFO | Thread-19 | PublishingSubscriptionActor | 45 - org.tota lgrid.reef.util - 0.2.3.SNAPSHOT | Published event: REMOVED to command_access_events key = 1.ALLOWED.core 13:52:18,515 | INFO | Thread-19 | PublishingSubscriptionActor | 45 - org.tota lgrid.reef.util - 0.2.3.SNAPSHOT | Published event: MODIFIED to command_events key = 9.Apex-CB11001-Trip.9>
To see runtime stats of the Reef issue:
karaf@root> info Karaf Karaf home C:\code\scada\reef\reef-karaf-windows-0.2.3-SNAPSHOT-dist Karaf base C:\code\scada\reef\reef-karaf-windows-0.2.3-SNAPSHOT-dist OSGi Framework org.apache.felix.framework - 3.0.8 JVM Java Virtual Machine Java HotSpot(TM) Server VM version 14.0-b16 Version 1.6.0_14 Vendor Sun Microsystems Inc. Uptime 12 minutes Total compile time 9.695 seconds Threads Live threads 55 Daemon threads 32 Peak 60 Total started 65 Memory Current heap size 80,740 kbytes Maximum heap size 504,896 kbytes Committed heap size 110,592 kbytes Pending objects 0 Garbage collector Name = 'PS Scavenge', Collections = 54, Time = 0.747 seconds Garbage collector Name = 'PS MarkSweep', Collections = 4, Time = 0.476 seconds Classes Current classes loaded 7,493 Total classes loaded 7,493 Total classes unloaded 0 Operating system Name Windows XP version 5.1 Architecture x86 Processors 2