= 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 `` tag and then one or more `` tags. Each `` tag defines a unique user + Open Grid Cluster combination. The following attributes are defined for the `` 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: {{{ #!xml }}} You may add as many `` 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 `` tag there are also several sub-tags that need to be configured: || '''Sub-tag''' || '''Required''' || '''Default value''' || '''Description''' || || `` || yes || || The path to a folder on the Open Grid Cluster that BASE can use to send job scripts and data files to/from the cluster. This folder must be accessible from all nodes in the cluster. A unique subfolder is created for each job that is submitted to the cluster. Job scripts may access this subfolder using the `${WD}` variable. Files are NOT automatically deleted after the job has finished. || || `` || no || ${TMPDIR} || The path to a directory for storing temporary working data. It is recommended that the path is to a local disk on each node. The default value is to use the folder assigned by the Open Grid Cluster. Job scripts may access this subfolder using the `${TMPDIR}` variable. This folder and all files within it is typically deleted once the job has finished. || || `` || no || || Alternative temporary folder that is used when submitting jobs with the debug flag. This can for example be set to a location that is not deleted automatically. If no value is specified the regular temporary folder is used. || || `` || no || date +'%Y-%m-%d %T' || A command to run on the Open Grid Cluster to get the current date and time. This information is used for correcting the running time of jobs if the clocks are different on the BASE server and Open Grid Cluster. The command must return the date and time in YYYY-MM-DD hh:mm:ss format (for example: 2017-01-12 10:40:15) || || `` || no || uname -srmo || A command to run on the Open Grid Cluster to get information about the operating system. It is used only for informational purposes. || || `` || no || qstat -help | head -n1 || A command to run on the Open Grid Cluster to get information about the Open Grid software. This is currently only used for informational purposes, but in the future this information may be used for feature-detection. || || `` || no || || Links the Open Grid Cluster to a job agent that is defined in BASE via the external ID. When this value exists the job agent is used as a proxy for access permissions. BASE users need to have USE permission for the job agent in order to use this Open Grid Cluster. Note that the job agent is not used for anything else. Do not set a server and/or port. The job agent software should not be installed on the Open Grid Cluster. Open Grid Clusters that are not linked to a job agent proxy can be used by all users. || || `` || no || || A list with one or more `` elements identifying individual nodes in the Open Grid Cluster. Individual nodes are not used by this extension, but may be required by other extensions for doing Open Grid related tasks that can't be scheduled as jobs (for example, parsing out data from result files that should be stored in BASE). The list of nodes that can be used for this is configured here simply as a service for other extensions. Typically, one or two nodes can be set aside for this and it is recommended that actions are quick and not too resource consuming. Extensions that require access to nodes should document this requirement. ||