Grant installation and quick start guide

• Install java runtime environnement.
• Get binaries from grant download page and extract the tarball anywhere on a local disk. All needed libraries are included. No more files are required.
• Test installation by invoking grant without any arguments. This should output quick command line help :

  > java -jar net.eduvax.grant.0.2.2/bin/net.eduvax.grant.0.2.2.jar
  Grant xmlrpc node server.
  Known commands :
  	start|stop|add|remove|status|submit
  	start [-port numPort] [-maxload max] : start node server on localhost.
  	stop [-node nodeURL] : send stop request to server.
  	add [-node nodeURL] -rnode rnodeURL : add rnodeURL to nodeURL's active nodes list.
  	remove [-node nodeURL] -rnode rnodeURL : remove rnodeURL frome nodeURL's active nodes list.
  	submit [-node nodeURL] -tasklet tasklet_spec [-targ tasklets_args] : schedule job.
  	>

  Launch script helpers can be found inside grant bin subdir.

  > net.eduvax.grant.0.2.2/bin/grant.sh

  > net.eduvax.grant.0.2.2/bin/grant.bat

  Add net.eduvax.grant.0.2.2 to your PATH env variable to avoid typing full paht each time you invoke grant.

Since there is not yet any security controle while running tasks, any tasklets can do anything to the node it is running on : read, write or send files on the net, add or remove neighbours nodes, stop the node itself... To prevent from serious dammages, it is recommanded to run grant node inside a "safe" environnement.

Always run grant as user without any privilege : grant only needs to write file in current directory and user home dir (this should be same, depending on the way grant is invoked) to maintain its configuration up to date, download tasklets to run and store tasklets outputs. All other locations should be read only for grant user.

To prevent tasklet to see systems or other users public files, one of the following setup is needed :

• setup a chroot jail : use the unix chroot command to hide other applications and data of your host. Just let required libraries for running your JVM and th JVM itself reside in the chrooted place.
• setup a virtual host. Several possibilities :
  • VMware
  • QEmu, Bochs
  • User Mode Linux
  • ...
• Use a dedicated host for grant ! May be you have no use old hardware ?

Just run grant with "start" argument :

> grant.sh start

This will start grant node service using default parameters. Standard output should print logs and a web server is started. To control node activity, browse http://localhost/, your browser should present you a XML content showing your node's status information.

If grant start fail, you are probably not allowed to open server socket on TCP port 80. May be a web server is already running and listening this port, or if you are using an unix system, you can't open port under 1024 as standard user. Try to use an alternet port to run grant :

> grant.sh start -port 8080

Then, node status information will be available from URL http://localhost:8080/

Once your node is started, you have to add neighbours to it (automatic neighbourg list fill is planned). Use the add commande :

> grant add -node xmlrpc+http://localhost:8080 -rnode xmlrpc+http://grant.eduvax.net:8080

For now you have to find yourself nodes URL. You may find some by digging your known nodes status information, if none, start from the grant's site one : take your browser to http://grant.eduvax.net:8080/

Use the "submit" command of grant. The required argument is the tasklet to run specs. The tasklet spec is the URL from where taslet jar file can be downloaded followed by the main tasklet classname. Then add tasklet proper args if required.

> grant.sh submit http://grant.eduvax.net/tasklets/fractal.jar#net.eduvax.grant.tasklets.fractal.Mandelbrot

This will submit tasklet execution query to the grant node runnin on localhost using defaults parameters. Depending on your installation, following switches may be required :

• Your grant node doesn't listening for TCP port 80, but 8080.

  > grant.sh submit -node xmlrpc+http://localhost:8080 <tasklet specs...>

• You may submit tasklet to any grant node. Just remember that tasklet may be runned anywhere. In most case, the specified node will only relay query to another node.

  > grant.sh submit -node xmlrpc+http://grant.eduvax.net:8080 <tasklet specs...>

Stop your node with the following command when it is listening to port 8080 :

> grant.sh stop -node xmlrpc+http://localhost:8080

By reading this you may think that you can stop any node just by knowing its URL. You are right ! This will change as soon as possible and this is another reason why grant is not secured enough to enter an operationnal stage.