This document explains the preparation and basic usage of DIXI. If you have difficulties, please consult 7. Troubleshooting.

Table of contents:

1. Prerequisites
	1.1 Getting Java
	1.2 Getting Ganglia monitoring daemon
	1.3 Getting libxos_common.so.0
2. Compiling DIXI from command line
	2.1 Deploying DIXI
3. Importing the source code into Eclipse
	3.1 Defining the user library XOSLIBS
4. Running DIXI
	4.1 Running XOSd
		4.1.1 Eclipse
		4.1.2 Command line
	4.2 Configuring the XOSD
5. Running client programs
	5.1 Running the XConsole
6. Deploying VOPS using ant
	6.1 Source
	6.2 Binary
7. Troubleshooting

The following are instructions on how to run the key components of the AEM package and how to import the AEM projects into Eclipse to compile and run the framework. Please refer to README for further details.

1. Prerequisites
================

 * Sun Java JDK >= 1.6 
 * Eclipse IDE >= 3.2.0 (for compiling and running from Eclipse).
 * ant (for compiling without Eclipse)
 * Ganglia monitoring daemon (for the AEM ResourceMonitor)
 * XtreemOS library libxos_common.so.0 (for the AEM ExecMng)
 
1.1 Getting Java
----------------

 * Obtain and install the sun-java6-bin package
 
	$ sudo apt-get install sun-java6-bin
	
 * Ensure the proper version of java is in the path. In Ubuntu, the /etc/alternatives/java* might point to the wrong binary.
   * /etc/alternatives/java -> /usr/lib/jvm/java-6-sun/jre/bin/java
   * /etc/alternatives/javac -> /usr/lib/jvm/java-6-sun/bin/javac

1.2 Getting Ganglia monitoring daemon
-------------------------------------

 * The daemon is needed for AEM's ResourceMonitor service which is required only on the nodes that will run the jobs.
 * Obtain and install the ganglia-monitor package
 
	$ sudo apt-get install ganglia-monitor

1.3 Getting libxos_common.so.0
------------------------------

 * The daemon is needed for AEM's ExecMng service which is required only on the nodes that will run the jobs.
 * The steps are as follows (summarised from  https://scm.gforge.inria.fr/svn/xtreemos/WP2.1/T2.1.3/trunk/releases/PAM/v0.06/README ):
   * Check out the xosmd-vosupport:
	   https://scm.gforge.inria.fr/svn/xtreemos/WP2.3/xosmd-vosupport/
   * Build the binaries
   
   	$ make
   
   * Install the libraries
   
   	$ sudo make install
   
   * Ensure the libraries are visible for runtime linking:
   	* In RedHat/FC, edit or create /etc/ld.so.conf.d/xos.conf and save it with the following lines as its contents:
   		/lib
   		/usr/lib
   		/usr/local/lib
   	* In Ubuntu, edit the /etc/ld.so.conf, adding the same lines:
   		/lib
   		/usr/lib
   		/usr/local/lib
	* In all of the above cases, update the dyamic linker run-time bindings:
	
		$ sudo ldconfig
		
	* If the above do not replay, then update the LD_LIBRARY_PATH variable:
	
		$ export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH
		
2. Compiling DIXI from command line
===================================

We develop DIXI using Eclipse. However, for various reasons one might want to compile the source in the command line and without Eclipse. For these cases we have provided the build.xml ant build file in the root of the package. Hence, to compile the projects, one simply needs to cd into the root folder of the projects (the one containing the build.xml and this file), and invoke ant:

	$ ant
	
The script will compile the java files into classes. To build a jar file, it is possible to use the build-jar target:

	$ ant build-jar
	
This will produce the DIXI.jar file which, however, contains only the internal dependencies.

2.1 Deploying DIXI
------------------

To put all the built files and the external libraries into one place, use the deploy ant target:

	$ ant deploy
	
This creates a Support/deploy folder and copies DIXI.jar, the libraries and all the other files and folders needed by the projects in the run-time. Additionally, the folder will contain the scripts convenient for running dixi and clients from the command line.

It is possible to use the scripts from Support/deploy directly or move them elsewhere on the home folder.
  
3. Importing the source code into Eclipse
=========================================

 * Open Eclipse. 
 * Click Window -> Open perspective -> Other. The Open perspective window is opened. 
 * Select SVN Repository Exploring and click OK. 
 * On the left side of the perspective, you should see the SVN Repository tab. 
 * Right-click somewhere inside it, and select New -> Repository Location. 
 * Set up the connection to your SVN repository and wait for the view in the SVN Repository tab to be updated. 
 * Expand the location of your repository, and select all of the projects there. 
 * Right-click on them, and select Checkout. 
 * Click Next, if you wish, set an alternate location and click Finish.
 
3.1 Defining the user library XOSLIBS
-------------------------------------

The project will not compile yet because it is missing the path to the libraries. We provide them through a user library XOSLIBS.

 * Right-click on one of the newly checked-out projects (e.g., XUtilities) and select Properties. The Properties window is opened. 
 * Select Java build path, then the Libraries tab. 
 * Click Add Library. 
 * Select User Library and click Next. 
 * If the library XOSLIBS doesn't exist in the list yet, click User libraries, New enter XOSLIBS and click OK. 
 * Select the XOSLIBS library and click Add JARs. 
 * Navigate to Support/libs directory, and select all JARs there. Click OK. 
 * Click OK, then Finish.
 
4. Running DIXI
===============

The framework is roughly divided into two parts:

 * XOSd is the "server", the collection of daemons which stage and run the services. XOSds on different nodes can communicate if configured properly.
 * Clients that use XATI to connect to a designated XOSd. These include XConsole and any custom programs that bind XATI.
 
Each XOSd and client program needs to run in its own process. The following instructions describe running DIXI components in Eclipse and in command line.

4.1 Running XOSd
----------------

4.1.1 Eclipse
.............

To start up XOSd in Eclipse, configure eu.xtreemos.xosd.XOSd class in the XOSd project to run as a Java Application:

 * Select Run / Open Run Dialog...,
 * Create a new Java Application (double-click on Java Application or select Java Application item on the tree-view on the left, then click the New launch configuration from the toolbar on the top left),
 * In the Main tab:
	 * Project: XOSd
	 * Main class: eu.xtreemos.xosd.XOSd
 * (optionally) click on Arguments and enter the values in the Program arguments text box,
 * Click Apply and Close to just save the configuration, or Run to run it.
 
4.1.2 Command line
..................

Use the xosd.sh shell command:

	$ ./xosd.sh
	
The shell command also accepts command-line parameters, e.g.:

	$ ./xosd.sh -s 192.168.0.34

4.2 Configuring the XOSd
------------------------

Regardless of how the XOSd is being run, it uses the parameters stored in a configuration file. If the configuration file does not exist, it will be created with the default values. 

By default, the configuration file will be stored in XOSdConfig.conf. However, if we would like to place the configuration file elsewhere, we can use the 

-c path/to/file.config

parameter.

(TODO: explain the options in the .config files)

4.3 Connecting multiple XOSd nodes
----------------------------------

Before the ADS is in place, the discovery of the nodes running XOSd and their services need to register with a designated XOSd in order to list the available nodes and the services running on each node. One of the XOSds is a "root" XOSd, while the XOSds running on the other nodes need to register with the "root" XOSd. For example:

 * On node with IP 192.168.0.1 we run the designated "root" XOSd:
 
 	user@192.168.0.1$ ./xosd.sh
 	
 * On node with IP 192.168.0.21 we run an XOSd that connects to the "root", the address of which we provide as a command-line parameter:
 
 	user@192.168.0.21$ ./xosd.sh -s 192.168.0.1
 	
 * On node with IP 192.168.0.55 we run an XOSd that connects to the "root", the address of which we provide in the configuration file (note: rootaddress.externalAddress needs to be the node's externally visible IP, and all the nodes running on the same subnet have to have the same value in their config files):
 
 	user@192.168.0.55$ more XOSdConfig.conf | grep rootaddress
 	rootaddress.host=/192.168.0.21
	rootaddress.xmlport=55000
	rootaddress.externalAddress=/194.249.173.88
	rootaddress.port=60000

	user@192.168.0.55$ ./xosd.sh
 
5. Running client programs
==========================

5.1 Running the XConsole
------------------------

5.1.1 Eclipse
.............

The new XConsole is under development and will be ready for use soon. To see the technology demo, create a run configuration for project XConsole, main class eu.xtreemos.xconsole.tests.XConsoleTest.

To run the OLD XConsole, create another run cofiguration for project XATI, main class eu.xtreemos.xati.test.XATItest and provide -c as an argument.

5.1.2 Command line
..................

 * Ensure XOSd is running on your node.
 * Open another terminal shell window, change to Support/runscript and run the client by running the bashcsript xconsole.sh:
 
	 $ cd Support/runscript/
	 $ ./xconsole.sh
 
 * In the XConsole, one can now execute commands like listing all nodes:
 
 	$ xrs -a

 * Press Ctrl+C to stop the xosd.
 * In a text editor, open XOSdConfig.conf and edit the line containing rootaddress.host to point to the address of the first node. 
 * Re-run the xosd_run.sh.


 
6. Deploying VOPS using ant
===========================

In the root of the project resides ant file - build.xml. There exist three rules
regarding VOPS deployment:

	o build-vops-jar (depends on build) 
 	o deploy-vops-src
	o deploy-vops-bin

Former packages binaries needed by VOPS to run as a standalone service. Jar file
"vops.jar" is created under root directory. This package is needed when deploying
VOPS binary.

6.1 Source
----------

The second rule (deploy-vops-src) creates new directory containing source code for 
developing VOPS as standalone service. Default location for deploying VOPS source
is ./WP35-VOPS but can be changed manually by changing next line inside build.xml
ant file:

	<property name="VOPSSrcDestination.location" value="./WP35-VOPS" />

value can be arbitrary directory. Directory structure is as follows:

./CDAMng - cda service (VOPS depends on several classes, this will change)
./Daemons - service has to be included, XOSd depends on this service
./VOPS - main source code of the VOPS
./Support - dependencies 
./XOS_SEDA - communication libraries (part of DIXI)
./XServices - services' definitions (part of DIXI)
./XOSd - DIXI (part of DIXI)
./XOSdCommon common classes used by services
./XUtilities common utilities


6.2 Binary
----------

The third rule creates deployvops directory under Support directory where all
files needed by the VOPS are copied:
	o Support/libs - dependencies
	o Support/runscript - scripts for running vops
	o VOPS/files - contains VOPS storage

Structure under Support/deployvops is created as follows:

.
./libs
./log4j.properties
./VOPS
./VOPS/files
./vops.jar
./xosd.sh

It is high likely that when trying to run xosd.sh for the first time, you will 
get an exception message. If not already there, new files will be created. 

./XOSdConfig.conf
./VOPSConfig.conf

Edit them and see that they resemble the following code:

	o XOSdConfig.conf

#Properties File for the client application
#Mon Apr 07 14:47:04 CEST 2008
rootaddress.xmlport=55000
rootaddress.host=/192.168.0.233
useSSL=false
rootaddress.port=60000
services.size=11
services.0=eu.xtreemos.xosd.vops.service.VOPSHandler
services.1=eu.xtreemos.xosd.daemon.DaemonGlobal
rootaddress.externalAddress=/192.168.0.233
certificateLocation=../test_keystore.cert
xosdRootDir=..

xosdRootDir should point to directory where vops.jar resides.

	o VOPSConfig.conf

#Properties File for the client application
#Mon Apr 07 14:47:04 CEST 2008
globalVOPS.port=60000
globalVOPS.host=/192.168.0.233
policyStorage=/home/ales/eclipse-workspaces/AEM_GFORGE/trunk/Support/deployvops/VOPS/files/policy/test3

Make shure that policyStorage point to location on your policy storage (where
XACML files are stored).

If everything has been set up successfully, your server should start normally when 
running xosd.sh. 

7. Troubleshooting
==================

If the projects still would not compile, it is very likely that the Eclipse is not set to Java 6.0 compliance, and the JRE is set to other than 1.6.

To change the compiler:

 * Click Window -> Preferences. The Workspace preferences window is opened. 
 * From the structure on the left, select Java -> Compiler. 
 * Make sure that in JDK compliance dropdown on the right, 6.0 is selected. If not, select it. 
 * Click OK.
 
To change the JRE:

 * Right-click on any of the newly checked-out projects and select Properties. The Properties window is opened. 
 * Select Java build path, then the Libraries tab. 
 * Make sure that the first entry in the window is the 1.6 JRE, not the 1.4.x. 
 * If not, select it and click Edit. Edit library window is opened. 
 * Select Alternate JRE and click Installed JREs. 
 * Click Add. 
 * Click Browse and navigate to the 1.6 JRE installation directory, then click OK. 
 * Click OK, Finish and OK. 
 * Clean and rebuild your workspace.
 
If there are still projects that would not compile:
 * Try to refresh the whole workspace:
    * fold all projects so that only project names appear in the Package Explorer,
    * click on the topmost project to select it,
    * scroll to the bottom of the Package Explorer list,
    * Shift-click the bottommost project to select all the projects,
    * right-click the selection and select Refresh (or press F5).
 * Try to rebuild the project:
    * click Project / Clean..., 
    * select Clean all projects,
    * check Start a build immediately (the option only appears if no Project / Build Automatically is not selected),
    * click OK.
 * Eclipse may take a while to compile all the projects. 
 * Sometimes, for unknown reasons, Eclipse fails to load the jar list of the user libraries in some of the projects. If a project is marked with errors, 
    * click the arrow next to the project's name in the Package Explorer to open the project's contents,
    * one of the entries in the project's list is the XOSLIBS library. The entry should have an arrow for listing the jar files associated with the library. If the arrow is not there or if the entry shows empty contents, then
    	* right-click the project's name,
    	* select Close Project,
    	* right-click the project's name again,
    	* select Open Project,
    	* have the workspace compile (either wait for the compilation to finish if set to Build Automatically, or select Project / Build All).
 
I get the following error when running xosd.sh:

   Exception in thread "main" java.lang.UnsatisfiedLinkError: /home/matej/workspace/xOSV2/ExecMng/JNI/libXExecMng.so: libxos_common.so.0: cannot open shared object file: No such file or directory
   
 * The ExecMng service depends on the libraries that are a result of other workpackages, namely WP2.1 which, in turn, depends on WP2.3. Please refer to 1.3 Getting libxos_common.so.0 for instructions.

Who do I contact if I have problems not listed here?

 * matej.artac@xlab.si: general DIXI, XATI, XOSd, ResMng, ResourceMonitor, RCA*
 * marta.garcia@bsc.es: C-XATI ("XATICA"), ExecMng, JobMng
 * ales.cernivec@xlab.si: XATI, VOPS, DIXI
 * The code related to the problem should contain the name/e-mail of the author in its header.
 
