Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

Installing and configuring an OurGrid site

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. You can check your Java version running 'java -version' in
the console. If Java is installed, this command will prompt the Java version.
See the following table for instructions on how to install Java:

Windows Using apt-get (some Linux distributions)

Download and Download the JRE from Type the command

http://www.java.com/getjava/
Install Java 'apt-get install sun-java6-jre'
and follow the wizard instructions.

Type the command 'find ./ -name java'

Find Java Informed in the wizard. The
This command will list all the java files in your file
location on default place is system.
disk 'C:\Program Files\Java\jre1.6.xxx' Choose any java path which contains 1.6. If you
are not root, use sudo before the find command.

Define JAVA_HOME and PATH

My Computer > Properties >
Advanced System
Settings > Environment
Put Java in the Variables...
PATH Define the variable JAVA_HOME
pointing to your java location.
Edit your PATH variable to include
%JAVA_HOME%\bin
'export JAVA_HOME=/your_jdk_location'
'export PATH=$JAVA_HOME/bin:$PATH'
or
Use Alternatives
'alternatives --install /usr/bin/java java
/your_jdk_is/java 100'
'alternatives --config java'

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.

1 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

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. Details on how to configure SRV records may be
found here.

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

2 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

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 exists, it is 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 has started successfull, 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 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 to
connect all the community peers. It is located in the address lsd-ds@xmpp.ourgrid.org. This e-mail address is being protected from

3 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

spambots. You need JavaScript enabled to view it . However, 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.

4 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

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 VMWare Server, for
Windows and Linux.

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. To use VMWare Server, set VMWARE both in Linux or
Windows. 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 VMWare Server (see instructions here);

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

Workers are distributed with the virtual environment they use. It is required
around 2 GB of disk space for the complete installation of a Worker. It is
important to notice that this great amount of disk space needed to install a
Disk space Worker is not due to the worker itself, but due to the virtual environment it uses
for security purposes. Besides, the amount of available disk space for the user
account running the Worker will determine how much space there will be
available for the tasks that will run on the machine.
OS Linux or Windows
Connectivity All grid machines must be able to connected to a XMPP server
Other tools unzip

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

5 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

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:

6 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

export JAVA_HOME=/YOUR_JDK_HOME
export PATH=$JAVA_HOME/bin:$PATHecho "Starting OurGrid Worker 4.0"
su username #You should 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 adduser 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

7 de 8 11-02-2011 18:50
Installing and configuring an OurGrid site http://www.ourgrid.org/index.php?view=article&i...

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.

8 de 8 11-02-2011 18:50