= Installing the Open Grid Scheduler package =

== Installation and updating ==

 1. Download the latest `opengrid-x.y.tar.gz` file from the [wiki:net.sf.basedb.opengrid Open Grid Scheduler main page].
 2. Unpack the downloaded file to a directory of your choice.
 3. Copy the `opengrid.jar` file to your BASE plug-ins directory. Look in your 
    `base.config` file if you don't know where this is. 
 4. If this is a FIRST-TIME INSTALLATION:
   A. Copy the `opengrid-config.xml` to your BASE `WEB-INF/classes` directory.
   B. Configure your installation (see below).
 5. If this is an UPDATE INSTALLATION:
   A. Check the documentation for the current release if any configuration changes are needed.
   B. Update your `opengrid-config.xml` if needed.
 6. Log in to BASE as an administrator and go to the '''Administrate->Plug-ins & Extensions->Overview''' page.
 7. Run the installation wizard and select `opengrid.jar` for installation.
 8. Go to '''Administrate->Services''' and check that the ''Open Grid Scheduler service'' is running.
 
== Configuration ==

Configuration settings are stored in the `opengrid-config.xml` file which should be located in the BASE `WEB-INF/classes` directory. The file is an XML file with a top-level `<opengrid>` tag and then one or more `<cluster>` tags. Each `<cluster>` tag defines a unique user + Open Grid Cluster combination. The following attributes are defined for the `<cluster>` tag:

|| '''Attribute''' || '''Required''' || '''Description''' ||
|| name || yes || A readable name that is intended to be used in interfaces with users. ||
|| address || yes || Network address or IP number to the master host of the Open Grid Cluster. ||
|| port || no || Port number that accepts SSH connections (default value is 22) ||
|| fingerprint || yes || SSH fingerprint formatted as a 16 two-digit hexadecimal numbers separated with ':' ||
|| user || yes || Username to use when connecting to the Open Grid Cluster. ||
|| password ||yes || Password to use when connecting to the Open Grid Cluster. ||

Example:
{{{
<cluster
  name="Open Grid"
  address="grid.example.com"
  port="22"
  fingerprint="6a:b1:88:54:78:34:a9:60:ef:81:95:79:6a:c8:49:8a"
  user="griduser"
  password="gridpassword"
>
}}}

You may add as many `<cluster>` tags as you like if you have more than one Open Grid Cluster or if you want to configure access for multiple users to the same cluster. The only restriction is that the combination of `user`, `address` and `port` must be unique. Internally, an ID for each definition is created by combining the three values. Note that the port number is always included even if it is not present in the configuration file. The example about will get an ID like `griduser@grid.example.com:22`. The ID is important since this is what other extensions have to use in order to find the correct Open Grid Cluster and to be able to connect to it and submit jobs.

Inside each `<cluster>` tag there are also several sub-tags that need to be configured:

|| '''Sub-tag''' || '''Required''' || '''Default value''' || '''Description''' ||