In order to install an OurGrid site, you should follow these steps:

1. Set up the environment

2. Download and install the XMPP Server

3. Download, configure and start the OurGrid Peer

4. Connect the OurGrid community

5. Download and configure the OurGrid Workers

6. Create the worker account and start the worker

7. Add the local users and start the OurGrid Broker

8. Connect the broker with the Peer

9. Running a Job

 

1. Setting up the environment [top]

The Ourgrid middleware requires Java Runtime Environment 1.6 or later installed on your system.

You can check your Java version installed on your system by opening a terminal console and running the following command:

'java -version'

If Java is installed, this command will prompt the Java version.

If the machine does not have Java 1.6 (or later) installed, you must manually install it (it is recommended that you use the Sun JRE distribution available at http://www.java.com).

The table below provides the basic Java installation steps:

2. Download and install the XMPP Server [top]

Since version 4.0, OurGrid uses a new communication infrastructure, named Commune.

Commune, in turn, is built on top of XMPP (Extensible Messaging and Presence Protocol). Thus,

every communication between OurGrid components are intermediated by an XMPP server.

OurGrid components are certified to work with the OpenFire server (formerly WildFire), although

other servers may also work. You can find below a detailed guide on how to obtain, install and

set up the OpenFire server to work with OurGrid.

You can download the Openfire at the following link: http://www.igniterealtime.org/downloads/index.jsp

Steps to install the Openfire server

1. Download the Openfire tarball from the website

2. Extract the tarball

3. Get into the created directory, named 'openfire' and start the server with 'bin/openfire start'.

In a few seconds the server will be running and it will be possible to access its Web administration

console to set it up. To access the console point your browser to 'http://host:9090';  where 'host'

is the name of the machine on which the server was just installed. If you are on the same machine

as Openfire, the following URL will usually work: 'http://127.0.0.1:9090'. Then you will set the

first server setup screen.

Server Setup

On 'Language settings' choose English.

On 'Server settings', fill domain with the fully qualified name or IP address of the server machine.

On 'Database settings' choose 'Embedded database'. An external database can be used although

this option has been not tested by the OurGrid team.

On 'Profile settings' choose 'Default'.

On 'Administrator account', fill your e-mail address and choose a administrator password.

The initial setup is now done. Restart your openfire server and now you can login to the admin

console using username 'admin' and the password you have just chosen.

Server configuration

On 'Language Selection' choose English.

On 'Server settings', fill the "Domain" field with the fully qualified name or IP address of the server

machine. On 'Database settings' choose 'Embedded database'. An external database can be used

although this option has not been tested by the OurGrid team.

On 'Profile settings' choose 'Default'.

On 'Administrator account', fill the "Admin Email Address" with the administrator e-mail address and

choose an administrator password.

The initial setup is now done. Restart your openfire server and now you will be able to login to the

admin console using username 'admin' and the password you have just set.

Server configuration

Most of the Openfire default properties are suitable for OurGrid. However, some Server Settings

should be changed. Remember to click 'Save Settings' after modifying a configuration section.

Server Manager > System Properties:

- Add new property: Property Name: xmpp.server.certificate.verify. Property Value: false

Server Settings > Server to Server:

- Be sure that server to server communication is 'Enabled'. It is recommended that you keep

the default value for server-to-server port (5269).

If you need to use a non standard port, you will need to add an SRV record to the DNS.

Server Settings > Registration & Login:

- On section 'Inband Account Registration', we recommend that you disable automatic

account creation by clients. By leaving this option enabled you would allow anyone to

create accounts without your permission. However, this is interesting while you are

installing the OurGrid site, because the XMPP accounts are created automatically when

you start the OurGrid components in the first time. If you disable this property during

installation, you must manually create the XMPP accounts for the Peer, Workers and

Brokers, under the section "Users/Groups > Create New User".

- On the 'Change Password' section, choose 'Disabled'.

- On the 'Anonymous Login' section, choose 'Disabled'.

Server Settings > Resource policy :

- On the 'Resource Policy' section, choose 'Never kick'

Server Settings > Offline messages:

- On the 'Offline Message Policy' section, choose 'Drop'.

Server Settings > Security Settings:

- On the 'Client Connection Security' section, choose 'Custom' and them mark

'Not Available' for both Old SSL and TLS methods.

- On the 'Server Connection Security' section, choose 'Optional'.

Firewall Tips

XMPP uses the 5222 and 5223 ports between the server and the clients, and

uses the 5269 port among the servers. So, if you choose to install an XMPP

server in your LAN, you should open the 5222 and 5223 ports from all the clients

to the server, and open the 5269 from your server to the world.

If you use an external XMPP Server, you should open the 5222 and 5223 ports

from all the clients to the external server.

3.Download, configure and start the OurGrid Peer [top]

Download the latest peer version here.

Unpack the downloaded package.

The resulting unpacked tree looks like this:

• certification/ - Stores X.509 certificates

• lib/ - Jars

• COPYING - License file

• COPYING.LESSER - License file

• example.sdf - An example of a Site Description File

• log4j.cfg.xml - Logging configuration

• peer - Unix script

• peer.bat - Windows script

• peer.poperties - Peer configuration

• testjvm - Unix script used to find Java

You can use the Peer Console or the Peer GUI. In order to run the Peer GUI, double click the

peer.bat file (Windows) or type 'bash peer gui' (Linux). You will see a GUI like this:

The GUI automatically suggests the XMPP user name, password and server name. You may

change the user name to the name of your peer. If you are using other XMPP server (for example,

if you have installed one in your site), change the server name property.

Important: The server name must match the exact address set in the Openfire's xmpp.domain property.

To view the value of this property, open the Openfire admin console and go to

Server > Server Manager > System properties > xmpp.domain

The XMPP server can be configured to create an account on its first login. In this case, if the account

does not exist, it will be created in that XMPP server with the user name and password used in the login.

You can test your connection pushing the "Test Connection" button. Remember, if the server allows,

this tests can automatically create your XMPP account. If your connection fails, follow these steps:

- Verify if the XMPP server is UP;

- Create the user account or allow the server to create them automatically;

- Test the connection again;

After changing the peer properties, click the "Save" button to store the values in the peer.properties file.

The next time you run the Peer GUI, the new values will be shown. Now you are ready to start the Peer

agent. So, click the "Start peer" link. When the peer is started successfully, the "Start peer" link will be

disabled and the "Stop peer" link will be enabled.

If you choose to run the Peer via console, you must open the peer.properties file to edit the XMPP

properties. You must define the commune.xmpp.username, commune.xmpp.servername and

commune.xmpp.password properties. Now you can start the peer agent, typing 'bash peer start' in the

console. The peer will prompt the success message or the error cause. You may need to use the

'chmod +x peer' command, to enable the execution of the peer script.

4. Connect to the OurGrid community [top]

If you want to consume workers from other sites, you need to join an OurGrid community. So, in the

community you can share your idle workers and receive the remote idle workers when you need.

By default, the peer is configured to connect to the the official OurGrid Discovery Service, which is the

component responsible for connecting all the community peers. It is located in the address

This e-mail address is being protected from spambots. You need JavaScript enabled to view it . This e-mail address is being protected from spambots. You need JavaScript

enabled to view it . Although you can join other OurGrid communities, changing the Discovery Service

address, or you can simply choose not to join the community, unmarking the "Join community?"

check box. Do not forget to save your updates with the "Save" button.

If you use the Peer GUI, the Discovery Service configuration is in

"Peer Configuration > Basic > Discovery Service settings". You can click in the "Test connection"

button to ping the Discovery Service.

The Discovery Service configuration can also be set using the peer.properties file, by simply setting the

peer.joincommunity and peer.ds.network properties respectively to "yes" and

"ds-username@ds-servername".

Since you have started the peer, you can check the Discovery Service connection and see the other

community peers in the "Community" tab of the Peer GUI. (See below)

In the console, you can check the Discovery Service connection typing the

'bash peer status' command.

5. Download and configure the OurGrid Workers [top]

The Worker is the OurGrid component that receives remote tasks submitted by the grid users. These

tasks are run by the Executor module. As a site administrator, you should secure your machines from

malicious grid users. So, you should define an Executor that meets your security requirements.

If you trust all the grid users (for example, in a private community), you can use the Executors that run

the tasks directly in the Operational System (Linux or Windows).

However, if you do not trust the grid users, you should use an Executor with Virtualization. So, in this

case, the tasks run inside of a virtual machine without network access. This is a very secure option,

because a hacker can damage the virtual machine, but its state is reset every time the worker is

allocated. There are two options of virtualized Executors: VServer, for Linux; and Worker Vbox,

for Windows.

The executor is configured in the worker.executor property of the worker.properties file. If this property

is empty, the Executor will run directly on the OS. To use VServer, define the property with VSERVER.

This functionality brings a new requirement:

• For Workers that run on Linux you should install the Linux VServer (see instructions here) or the

VMWare Server;(see instructions here)

• For Workers that run on Windows you should install the Worker VBox (see instructions here);

Besides all the system requirements above mentioned, machines where the Workers will be installed

must have:

Download the latest worker version here and (for each grid machine):

• unzip worker-4.x.y.zip

• cd worker-4.x.y/

• And perform the instructions in the two following sections.

6.Create the worker account and start the worker [top]

The Peer is the manager of an OurGrid site. The administrator will set the site's Workers using the Peer.

He can set all the workers together in a SDF - Site description file - or can set each worker separately.

Using a SDF

Use the text editor of your preference to create a mysite.sdf file that will contain the description of all

workers of your site. An SDF file containing three workers looks like this:

workerdefaults:
    site : mylab.org
       os : linux
worker:
      username : machine1
      servername : xmpp.mylab.org
worker:
      username : machine2
      servername : xmpp.mylab.org
worker:
      username : machine3
      servername : xmpp.mylab.org 

You can create a similar SDF by just replacing the "worker" sections. The mandatory properties,

"username" and "servername", refer to the XMPP username and servername respectivelly. You can

define any property in the SDF, e.g. javaversion : 1.6, hasGenomaDB : true. The properties

defined in the workerdefaults section are applied to all the workers in the site.

In the Peer GUI, click the "Import workers from file" link and choose the SDF file:

In the Peer console, use this command:

'bash peer setworkers file.sdf'

Setting each worker separately

In the Peer GUI, click in the "Add worker" link and fill the panel's fields.

In the Peer console, use the command:

'bash peer addworker username@servername'

Please remeber,  the username and servername values must be equal to the XMPP values for this worker.

Check the Workers

In order to check if the workers were successfully added and view their state, you can use the "Workers"

tab in the Peer GUI or use the command:

'bash peer status'

Starting a Worker

Edit the worker.properties file and update the basic Commune properties

commune.xmpp.username, commune.xmpp.servername and commune.xmpp.password to

configure the connection to the XMPP server. The commune.xmpp.username and

commune.xmpp.servername properties must match the values set in the Peer for

this Worker.

You should also copy the Peer's public key (commune.publickey property in peer.properties file)

to the worker.peer.publickey property of worker.properties file (Notice that you won't be

able to start a Worker if its commune.publickey property is not set up).

Run:

'cd /YOUR_WORKER_HOME/'

'bash worker start'

At this point the Worker should be up and running. Use 'bash worker status' to check its status. You

may need to use the 'chmod +x worker' command to enable the execution of the worker script. Although

the OurGrid Worker should run as a service on each machine. We suggest you to create a script like the

one below and set up your PC to to run it on boot:

export JAVA_HOME=/YOUR_JDK_HOME

export PATH=$JAVA_HOME/bin:$PATH

echo "Starting OurGrid Worker 4.0"

su username #Use this line in order not to start the Worker as 'root' user

cd /YOUR_WORKER_HOME/

bash worker start

7.Add the local users and start the OurGrid Broker [top]

The Peer is the manager of an OurGrid site. The administrator can define the site's local users in the

Peer GUI or console. Each site user should have a XMPP account (with username, servername and

password), which will be used to run a Broker. Before starting the Broker, the user account should also be

registered in the Peer with the same data used in the XMPP account. In the Peer GUI, there is a

"Add peer user" link, which opens a window with the necessary user data: user name, server name and

password. In the console you can use the adduser command:

'bash peer addbroker username@servername password'

Important: the data you used when adding the user must be the same data you use in the Broker

(broker.properties file).

Download and Start the Broker

Each user that will run an application on the grid will use a Broker instance. An instance of a Broker must

be installed into a home machine, and must be set up to connect to the site's Peer.

Download the latest broker version here and (for each grid machine you want to send jobs from):

• Unzip broker-4.x.y.zip

• Go to broker-4.x.y/ folder

• Type 'broker gui' or double click the broker.bat file.

These commands will open the Broker GUI. But, if you want to use the console, you can use the 'broker'

shell script to perform the same commands.

The Broker configuration data will be stored in the broker.properties file, that is located in:

• ~/.broker for Linux;

• C:\Documents and Settings\USER\.broker for Windows XP;

• C:\Users\USER\.broker for Windows Vista.

After defining the XMPP user name, server name and password, in the Broker GUI or directly editing the

broker.properties file, you can start the Broker, clicking in the 'Start' link of the GUI or

using the command:

'bash broker start'

You may need to use the 'chmod +x broker' command, to enable the execution of the broker script.

8. Connect the Broker to its Peer [top]

Use your favorite text editor to create a description file containing the Peers to which your Broker should

request Workers. Typically, you'll use a single Peer, which will be the manager of your site. This Peer will

be responsible for communicating with the rest of the community on your behalf to obtain resources

for your use.

This is an example of a grid description file mypeer.gdf:

peer:

username: mylabpeer

servername: xmpp.mylab.org

label: Peer of my lab

The username and servername properties should contain the same data of the Peer XMPP account.

The Broker GUI has a "Set grid" link, which opens a window to choose a GDF file. There is also a setgrid

command on broker console:

'bash broker setgrid mypeer.gdf'

If the Broker has successfully logged in the Peer, you will see a green circle near the peer's name, in the

"Peers" tab of Broker GUI. You will also see the user with a green circle, in the "Peer users" tab of Peer GUI.

9. Running a Job [top]

A simple example job is available in the Broker package. To run the job click on the "Add job" link into your

Broker GUI and give the JDF you want to submit to OurGrid. Use the "Jobs" tab to monitor your job's status.

If you prefer a command line interface, type:

'bash broker addjob examples/addJob/simplejob.jdf'

'bash broker status' (to monitor the job status)

Tip: in order to learn how to write OurGrid jobs, click here.