Installing the cluster manager.

Currently, Faucets requires that the cluster job scheduling system be
the Adaptive Queuing System (aka cluster manager) we have
developed. In later versions we plan to support other scheduling
systems such as PBS, DQS, etc.


Most of the code for the cluster manager is present in the faucets
installation. The cluster manager has four components that need to be
installed. They are :

1) MySQL database
2) Charm components for adaptive jobs
3) Scheduler
4) OPTIONAL: Rsh wrapper

To install MySQL, if an installation does not exist, download it from
www.mysql.com. Download and install the charm++ module from
charm.cs.uiuc.edu.


Setting Up Charm:
---------------

Follow the Charm++ documentation and install and build Charm++.  The
default values in config.sh presume it is installed in
/etc/faucets/charm, but you can place it elsewhere and alter the
config.sh charm variables accordingly.


Setting Up the Cluster Manager
-----------------------------

All the cluster manager files are in faucets/cluster_manager/

Step 0: ./configure --prefix=/path/to/where/youwant/faucets/installed

Step 1: Edit the configuration file faucets/cluster_manager/config.sh
and specify the correct values for the variables. In particular :
	- Edit Database to match <dbname> you intend to use in MySQL.
	- Edit PORT to point to port of the scheduler
	- Edit DATABASE_HOST DATABASE_USER and DATABASE_PASSWD to 
	point to the database host <user> and <passwd>
	- NODELIST points to the nodelist for the scheduler

Step 2: The faucets cluster manager currently stores all the
executables and scripts in /etc/faucets. Create this directory if it
does not exist. It should be a directory available on all the
nodes. It certainly can be a symlink to an NFS mounted directory.

Step3: Compiling the scheduler
	cd faucets/cluster_manager;
	make;

Step4: Installing the cluster manager
	cd faucets/cluster_manager;
	sudo make install;

Then proceed to:

Step 5: Configuring the MySQL database.

Step 6: Starting the cluster manager

Step 7: Testing

As described in detail below.


Configuring the MYSQL Database 
-------------------------------------

MySQL installation, follow the instructions from the mysql website to
install a mysql server. Having started the server connect to it using
the mysql client, and execute the following commands.

If you have already setup config.sh, you can use the provided script
to create the faucets database.


     sh sqlwriter.sh | mysql --user=root --password=rootpass 


Or you can do the same thing manually as described below:

mysql> create database <dbname>;
mysql> use <dbname>;

mysql> create table jobInfo ( 
  id mediumint primary key NOT NULL DEFAULT '0' auto_increment, 
  name varchar(255),
  pid mediumint,
  type smallint,
  minpe mediumint,
  maxpe mediumint,
  createTime TIMESTAMP,
  bitmap varchar(128), 
  status tinyint not null,
  fd mediumint,
  argbuf varchar(255),
  port mediumint,
  userName varchar(32),
  stdout   varchar(255),
  stderr   varchar(255),
  stdin    varchar(255),
  pwd      varchar(255),
  allocatedTime mediumint,
  startTime int,
  flags     int,
  email     varchar(255),
  display    varchar(255),
  exitCode   int,
  ppn       smallint 
);

mysql> grant all on *.* to <user> identified by <passwd>;    
			#chage code to take password from config file later



Launching the Cluster Manager
------------------------------

Step5: Starting Up the Cluster Manager
	-cd /etc/faucets/bin;

	- if you want to run the cluster manager as root
	>su
	>chown root scheduler
	>chmod +s scheduler

	- Create a nodelist with hostnames of the nodes in the
cluster. The nodelist should look something like this.
	host cool1;
	host cool2;
	host cool3;
	----
	---
	
	- To start the scheduler
	> ./startScheduler 
	
	- To abort the scheduler 
	> ./abortScheduler

	- To shutdown the scheduler gracefully
	> ./fshutdown


Testing the Cluster Manager
---------------------------
To test the cluster manager, try using the faucets scripts.

example:
	>./fjobs
	#should print out an output like

UserId    JobId     Processors    MinPE     MaxPE     Status    Name      
CURRENTLY 8 NODES FREE

	See faucets/doc/COMMANDS.txt for more commands regarding
running jobs on faucets.


OPTIONAL: SETTING UP RSH
-----------------------

Finally after the scheduler is running, to enforce optimal cluster
usage and prevent node sharing, we have provided a wrapper for rsh
that looks up a nodelist and allows rsh only if the user has
previlages for it.

In our model of the cluster, it contains a head node and a bunch of
compute nodes. For a non-previleged user the compute nodes are only
accessable from the head nodes. Each of the compute nodes should have
the head node and the other compute nodes in their /etc/hosts.equiv
file. 


	*Run the provided rsh_maker.sh script as root.*

	* or run make install_rsh_wrapper as root *


Or do everything yourself as described below.

The following steps need to be done on the head node and the compute
nodes.

Step1 : Create a username and a group for faucets. 
	We recommend faucets:faucets.

Step2: Relocating rsh

    
	cd /etc/faucets/bin;
	chown faucets:faucets rsh_wrapper;
	chmod +s rsh_wrapper;	

	cd /etc/faucets;
	mkdir rsh_protected;
	chown faucets:faucets rsh_protected;
	cmod 750 rsh_protected;

	cd /usr/bin;
	mv rsh /etc/faucets/rsh_protected;	
	ln -s /etc/faucets/bin/rsh_protected rsh

Step3: Setting up /etc/hosts.equiv

	Insert the headnode and the compute nodes in the
/etc/hosts.equiv file.  Use of full qualified domain names is highly
recommended for security but may or may not be necessary depending on
your system's exposure to DNS.