Installation

This page contains  instructions for the installation of the WebSubmit package on your site.  Unless otherwise specified, instructions refer to software that must be installed on the WebSubmit server machine.  The number of things to be done on the WebSubmit remote systems is fairly limited.

The basic installation procedure is as follows:

  1. Install all WebSubmit supporting software (see Software Requirements).
  2. Install WebSubmit source code (Tcl library and CGI scripts)
  3. Compile Tcl extensions and utilities distributed with WebSubmit
  4. Configure source code for your site
  5. Configure HTTP servers for use with WebSubmit
  6. Configure remote systems of WebSubmit cluster
  7. Set up WebSubmit master and authentication databases
  8. Set up WebSubmit link and message files
  9. Establish a Certificate Authority for your system
  10. Miscellaneous Additional Tasks

Installation of Source Code

WebSubmit requires its source code to be contained in a WebSubmit directory hierarchy.  The distribution (available as a gzipped  tar file) contains the source code, etc., arranged in the properly named and relatively located directories; renaming directories or moving them, apart from changing the location of the WebSubmit root directory ($wsRootDir) in your file system, will require code modification.  The basic directory structure is as follows: WebSubmit Directory Structure: Directories indicated with a $ have names that are determined by the configuration at a given site.  For example, module directories indicated as $module1 ... $modulem will have names that match those of the modules installed at the site.

Caveat: For the moment HTML documentation, images, JavaScript code, and Java code are all stored in the doc directory.

Unpacking the Source Code Archive

  1. Download the source code from websubmit.nist.gov
  2. Create a directory to hold the WebSubmit package (hereafter referred to as $wsRootDir)
  3. Move the source code archive (websubmit.tar.gz) to $wsRootDir
  4. Unpack the archive
On most UNIX systems, the procedure above could be accomplished as follows:

    1> mkdir $wsRootDir
    2> mv websubmit.tar.gz $wsRootDir
    3> cd $wsRootDir
    4> gzcat websubmit.tar.gz | tar xvf -
 

Source Code Distribution
The following is a brief listing of the directories contained in the distribution and their purposes:

Compile Tcl Extensions and Utilities

Several extensions and utilities are distributed with WebSubmit:
  1. A certificate utility (certutil) to perform certificate decoding when needed ($wsRootDir/cert)
  2. The Tcl extension MD. hash construction ($wsRootDir/extensions/tclbin-1.2)
  3. cgi.tcl library ($wsRootDir/extensions/cgi.tcl-0.7)
A Makefile is provided with the distribution that will compile Tcl and the certificate utility.  Edit the Makefile to adjust the paths to WS_ROOT_DIR and TCL_CONFIG_DIR, and to set up any special flags that need to be passed to your C compiler (cc).  Once this is done, simply invoking 'make' in the WebSubmit root directory ($wsRootDir) will build the necessary code.  Note that cgi.tcl has already been configured, so there is no real need to install it on your site.

Configuration of Source for Site

Certain information in the WebSubmit package depends on the site where it is installed.   Site specific information is configured quite easily using a combination of a configure script and a Configuration Manager provided with WebSubmit (WebSubmit Configuration Manager).  The configure script is run using the Makefile in $wsRootDir; if you compiled the Tcl extensions and utilities, it was already invoked.  If you have not, typing 'make wsconfig' in $wsRootDir will build the necessary configuration file.  Once the configuration file ($wsRootDir/install/websubmit.paths) has been created, you can use the Configuration Manager to set up the remainder of your configuration variables and to update the WebSubmit code with these settings.  The Configuration Manager is invoked as follows:
  1. cd $wsRootDir/install
  2. ./wsManager.tcl
The Configuration Manager within this interface allows you to set all of the site specific variables within WebSubmit.  This is performed using the first three tabs within the Configuration Manager notebook.  The last tab, Update, will update all of the files in the distribution with the information you have provided in the other tabs.  Make sure you enter all of the information correctly before updating your distribution.  The Manager creates the file $wsRootDir/install/websubmit.site, which contains all of the information for your site.  If you make an error during configuration, you can always just rerun the update.

HTTP Server Configuration

WebSubmit uses two separate HTTP servers.  A secure server (running on port 443) handles HTTPS requests to WebSubmit proper, in which  user access is authenticated based on a digital certificate submitted by the user.   The first submission of a certificate notifies the WebSubmit administrator to consider adding the new user to the WebSubmit authentication database.  A regular server (running on port 80 as usual) handles HTTP requests for unsecured documentation, including information on how to obtain a recognized digital certificate.   For purposes of illustration, we will assume that the names of your two servers are regular.websubmit.ex.org and secure.websubmit.ex.org.  They can actually have the same name, which is what we do.   Both servers reside on a single system called the WebSubmit server system.

Server URL-to-Directory Mapping
There are three groups of files that need to be accessible via your two servers.  Part of server configuration involves setting up URL-to-physical directory mappings that makes the files accessible via URLs.  Two classes of content are served by each of your two servers: CGI scripts and other material (HTML documents, images, JavaScript and Java code).  In fact, only the CGI scripts differ with the server.  The other materials are shared.  The resulting three sets of material are kept in bin and nbin directories (for the CGI scripts) and a doc directory (for the other material). The mappings to serve these three sets of material are given in the following table .
 
 

Physical Directory
Content Type
HTTP URL
host=regular.websubmit.ex.org
HTTP URL
host=secure.websubmit.ex.org
$wsRootDir/bin CGI - https://$host/$serverBinAlias
$wsRootDir/nbin CGI http://$host/$nServerBinAlias -
$wsRootDir/doc Other http://$host/$nServerDocAlias https://$host/$serverDocAlias
 
NOTES: Secure (HTTPS) Server Configuration
In order for authentication to work properly with WebSubmit, there are several features of the HTTPS server that must be configured properly.

Enable SSL on server:
The Secure Sockets Layer is used to authenticate users and obtain certificate data.  SSL must be active on your HTTPS server, and it must insist on bi-directional authentication (client-to-server and server-to-client) for all directories in the WebSubmit hierarchy ($wsRootDir/*).  Your server documentation will provide information on how to perform access control.
 

Direct server to place Client Certificate in CGI Environment:

Update HTTPS server to accept client certificates signed by WebSubmit  CAs
Authentication in WebSubmit relies on certificates that are signed by valid WebSubmit Certificate Authorities (CAs).  There may be one or more authorities that you want your system to recognize as valid issuers of certificates.  Certificates for these CAs must be loaded into your HTTPS server in order for the server to accept them as CAs allowed to sign client certificates.  See your server documentation for details on how this is achieved.  The section on Certificate Authorities below contains more information.

Update MIME Types
WebSubmit supports transfer of files between the client and remote systems.  Transfer from client to remote system is done with the standard HTML file selection mechanism.  Transfer from remote to client systems is done with the aid of a Java file browser.  The file selected is then transferred to the WebSubmit server, and from there to the browser as a redirect.  Normally such a file would be viewed by the browser with the appropriate viewer.  This might be particularly awkward if the file was an executable or some other file type that inappropriately invoked a text viewer.   But, in general, viewing of any sort would be inappropriate, because what is desired is to save the file, not view it.  In order to force the browser to bring up a Save As dialog, retrieved remote files should be delivered with the MIME type application/octet-stream.   This can be achieved with either a by-directory or a by-extension strategy, though the former is probably easier.

Configuration of Remote Machines in WebSubmit Cluster

Configuring Secure Shell
WebSubmit is used to access computing resources on a collection of remote machines.  At present, this access is accomplished by secure remote command execution with version 1 of Secure Shell (ssh) and Secure Copy (scp), i.e., SSH1. It is suggested that you install v1.2.26 or greater of SSH1 for greater interpretability with future versions.  However, so far we do not support SSH2, as we are dependent on .shosts files.  Support for SSH2 is pending.

In order to use SSH1 with WebSubmit, the remote machines must be configured properly.  This will most likely require some interaction between the WebSubmit server administrator and the system administrators on these remote systems.

SSH1 configuration requires the following:

IMPORTANT NOTES:  If the SSH daemons and execution environment are not configured properly on the backed systems, WebSubmit will not work properly.  The following are things to be aware of: Additional Remote System Configuration
If you are using the modules that support the Gaussian 9x application, and particularly if you using more than one version of this application, you may wish to access the application on the remote systems with the aid of a wrapper script, to ensure that the user's environment is properly set up for the particular version of Gaussian you wish to use.  The current Gossip modules are hard coded to offer a choice between Gaussian 94 and Gaussian 98.  A model wrapper script  ($wsRootDir/doc/gauss) is supplied that can be adapted to either version.

Two of the batch queue query modules ($wsRootDir/bin/llQstat.cgi and $wsRootDir/bin/lsfQstat.cgi) make use of an auxiliary script jmsum on the remote system.  Samples $wsRootDir/doc/jmsum.ll and $wsRootDir/doc/jmsum.lsf are provided.  The first of these depends on the availability of the Load Leveler auxiliary jm_stat.  The latter uses the Load Sharing Facility command bjobs.

You must hand edit these scripts to adapt them to your remote systems.

Configuration of WebSubmit Master and Authentication Databases

The final step in configuration of WebSubmit is the setup of the master and authentication databases to be used on your system.  The master database $wsRootDir/lib/master.db (with auxiliary file $wsRootDir/lib/master.txt) contains the list of modules that users have access to on your system.  A sample copy of this, called master.db.example (with master.txt.example) is supplied.  These are organized in a hierarchical fashion according to system, function, or whatever the administrator desires.  The authentication database $wsRootDir/lib/auth.db (sample copy auth.db.example) contains information about valid  administrators and registered users.  It is essential that this file be configured properly for secure operation of the system.  Details on the construction of these files can be found in the sections on the Master Database and Authentication.

Configuration of Documentation and Message Files

WebSubmit master page's link bar ($wsRootDir/(n)bin/linkbar.cgi) provides standard links to two auxiliary pages.  Link Information, $wsRootDir/bin./links.cgi (sample copy links.cgi.example) contains links to subject matter that may be of interest to your WebSubmit users, e.g., system home pages, system batch queuing  policy pages, batch queuing system home pages, and application home pages.   Link Message, $wsRootDir/lib/motd.txt (sample copy motd.txt.example) contains HTML text offering a WebSubmit system message-of-the-day.   You must hand edit and rename the examples.

WebSubmit Certificate Authority

WebSubmit relies on the use of digital certificates to authenticate users and to establish a user's unique identification number.  In order to utilize the full security provided by WebSubmit, you will need to have a certificate authority (CA) that you trust to issue certificates to your users.  Your HTTP server must be configured to trust certificates signed by this authority, and users' browsers must also be configured to trust the CA.  WebSubmit digital certificates should be X509.v3 compliant, and should be capable of being used to perform SSH client authentication.  Many commercial CAs exist that can issue certificates (for example, Verisign).  If you don't trust a third party vendor to issue certificates, then you will need to set up your own CA .  The public domain version of SSH libraries (SSLeay) contains a certificate authority that can be used to issue SSH client certificates.  For more information on obtaining and installing this public domain code, please refer to the SSLeay FAQ.  For more information on certificates, certificate authorities, and public key infrastructures, refer to the links at http://www.xcert.com/~marcnarc/PKI.  The subjects of publicly cryptography and certificate authorities are beyond the scope of this document.

Additional Tasks

Cleanup File Download Directory
When users download files from remote systems to their client systems, these files are temporarily stored on the WebSubmit server in $wsRootDir/doc/download. In order to avoid having files in this directory unnecessarily consume disk space, it is suggested that you either symbolically link this directory to /tmp, or set up a cron job to delete files from it periodically.