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:
-
Install all WebSubmit supporting software (see Software
Requirements).
-
Install WebSubmit source code (Tcl library and CGI
scripts)
-
Compile Tcl extensions
and utilities distributed with WebSubmit
-
Configure source code for your site
-
Configure HTTP servers for use with WebSubmit
-
Configure remote systems of WebSubmit cluster
-
Set up WebSubmit master and authentication databases
-
Set up WebSubmit link and message files
-
Establish a Certificate
Authority for your system
-
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:
-
$wsRootDir
-
bin
-
nbin
-
lib
-
doc
-
...
-
user
-
$uid1
-
$host1
-
$module1
-
$module2
-
...
-
$modulem
-
$host2
-
...
-
$hostn
-
$uid2
-
...
-
$uidp
-
install
-
extensions
-
cert
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
-
Download the source code from websubmit.nist.gov
-
Create a directory to hold the WebSubmit package (hereafter referred to
as $wsRootDir)
-
Move the source code archive (websubmit.tar.gz)
to $wsRootDir
-
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:
-
$wsRootDir/bin:
Directory containing all master CGI scripts and configuration information
-
$wsRootDir/nbin:
Directory containing CGI scripts for access by unregistered users
-
$wsRootDir/lib: Directory
containing Tcl library code and databases
-
$wsRootDir/doc: Directory
containing HTML documentation, images, JavaScript code, and Java code
-
$wsRootDir/user: Directory
hierarchy for user configuration and session directories
-
$wsRootDir/install: Directory
containing Configuration Manager and code to configure WebSubmit for your
site
-
$wsRootDir/extensions:
Directory containing WebSubmit extensions used by WebSubmit
-
$wsRootDir/cert: Directory
containing certificate decoding utilities
Compile Tcl Extensions and
Utilities
Several extensions and utilities are distributed with WebSubmit:
-
A certificate utility (certutil)
to perform certificate decoding when needed ($wsRootDir/cert)
-
The Tcl extension MD. hash construction ($wsRootDir/extensions/tclbin-1.2)
-
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:
-
cd $wsRootDir/install
-
./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:
-
Physical directories must be mapped to URLs using the above scheme for
your HTTP and HTTPS servers.
-
A dash (-) for a URL indicates that the corresponding physical directory
should not be accessible from the relevant server.
-
HTML documentation, images, JavaScript,and Java code can be placed in directories
already accessible by your server (for example, the server document root).
This should not create any problems, as long as there are no clashes between
filenames. In general, however, unless you have a compelling
reason to move the WebSubmit doc
directory, it is perhaps best to leave it in $wsRootDir.
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.
-
By-Directory: Configure the server
so that all files retrieved from the directory $wsRootDir/doc/download
get
the MIME type application/octet stream
-
Netscape Enterprise Servers: MIME types
can be forced on a per directory basis using an objective
directive in obj.conf. A
sample directive would appear as follows:
Object ppath="/websubmit/root/doc/download/*">
objective fn="type-by-exp" type="application/octet-stream"
exp="*"
</Object>
-
Apache Servers: Unfortunately, MIME
types on Apache servers cannot be configured on a per directory basis.
-
By-Extension: Configure the server
so that files with a specific extension (chosen by the WebSubmit administrator)
receive the application/octet-stream MIME
type. The MIME extension specification is specified by the variable
mime
Extension contained in $wsRootDir/lib/webSubmit.tcl,
and can be configured using the Configuration Manager. For example,
you could configure your server so that files with the extension .ws
would be treated as application/octet-stream
by default.
-
Netscape Enterprise Servers: MIME types
can be added on Enterprise server using the Enterprise Server administration
tool, or by modifying the mime.types
file.
-
Apache Servers: MIME types on Apache
servers can be modified using the Add
Type directive in srm.conf.
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:
-
An SSH1 daemon (sash) on the WebSubmit
server machine, along with the utilities ssh
and scp.
-
An SSH1 daemon (ssh) on each
remote machine, along with the utilities ssh
and scp
-
The SSH public key for each remote machine must be placed in /etc/ssh_known_hosts
on the WebSubmit server machine
-
In the HOME directory of each WebSubmit
user on each remote machine, there must be a .shosts
file that allows the WebSubmit HTTP server user to execute commands on
this system as the specified user. For example, if the WebSubmit
HTTPS server user is nobody, then
the .shosts file on each remote
machine will have the single line
secure.websubmit.ex.org nobody
where secure.websubmit.ex.org
is the name of the machine on which the secure or HTTPS server is running.
This
.shosts file must have permissions
400 (user read-only = -r--------)
or 600 (user read write = -rw-------).
-
The default configuration of SSH daemons is to enable RhostsRSAAuthentication,
which uses a combination of .rhosts
(.shosts) authentication and RSA-based
host authentication. This means that if login is permitted by .shosts
- the .shosts file allows the WebSubmit
server account (nobody) to log
in from the SSH client - here the WebSubmit server - and the
client's host key can be verified, then access is granted.
Verification of the client's host key is accomplished by storing the client's
host key from /etc/ssh_host_key.pub
on the WebSubmit server in /etc/ssh_known_hostson
each remote machine in the WebSubmit cluster. Please refer
to the SSH manual page on your system for the details of setting up /etc/ssh_known_hosts.
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:
-
ssh and scp
must both be in the path examined by ssh.
The default search path is given in /usr/include/paths.h.
Additional paths can be added at the time ssh
is compiled using the --with-path=PATH
directive in the SSH configure
script.
-
If ssh is configured to listen
on a port other than 22 (the default
port for SSH), then $wsRootDir/wsNetwork.tcl
must be modified to reflect this non-standard configuration.
-
It is very important that the user shell initialization files on the remote
system are configured to check whether they are running in non-interactive
shells. If these initialization scripts generate any output in non
interactive shells, scp will not
work properly. This is an unfortunate property that scp
inherits from the rcp protocol.
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.