Modules
Overview
Modules (or application modules) are the functional components of WebSubmit,
allowing users to accomplish tasks on remote systems. Each module
is presented as an HTML form to the user. They fill out this form
as needed and submit it to the WebSubmit server, which then processes the
data (using a support script or the module itself) and then forwards any
command requests to the desired remote system. Each WebSubmit module
is dynamically generated by a CGI script; this script either comes with
the distribution, is automatically generated using a database specification
for the form, or was created in some other fashion (and possibly in another
development language).
The master database controls what modules appear to users when they
try to access the system. This database also specifies the way in
way in which the module is built (i.e., whether it is hand-written or automatically
generated). All module scripts reside in a special directory hierarchy
(see Installation notes) $wsRootDir/modules/$hostName/$moduleName,
where $hostName is the host that
corresponds with the module, and $moduleName
is the key used for the given module in the master database. The
processor script is typically located in this directory as well, although
it need not be. The following sections discuss additional aspects
of modules and their use in WebSubmit.
Features of Tcl Modules using WebSubmit
The characteristics discussed in this section are common to many of the
WebSubmit modules provided with the distribution. If a developer
is interested in creating new Tcl modules to add to the system, then some
of the following features might be included in these modules.
WebSubmit Library and websubmit.conf
(required for WebSubmit scripts)
WebSubmit code is contained in a series of Tcl packages. In order
to access these packages from a Tcl script, the packages have to be loaded
using the Tcl package require
command. package require
traverses a directory hierarchy contained in the Tcl variable auto_path
looking for the desired packages. Loading the WebSubmit package(s)
requires modifying the auto_path
appropriately and then issuing the proper package
require command. The file $wsRootDir/bin/websubmit.conf
contains the necessary modifications to auto_path
for your site, and issues the package
require command. In addition, websubmit.conf contains the
calls to the authentication routines. Every WebSubmit module should
issue the command
source $wsRootDir/bin/websubmit.conf
to load the WebSubmit libraries. The scripts that come with the distribution
will have this command, provided the distribution has been installed properly
using the installation tools that come with WebSubmit. NOTE:
sourceing websubmit.conf is absolutely essential for loading the WebSubmit
package and performing the required authentication.
Session Manager (optional)
Any module that uses WebSubmit session management techniques needs
to be carefully configured. The Session Manager should be present
on the form, and the module processing should be set up appropriately.
More information on using session management with scripts can be found
in the section on Session Management.
Online Help (optional)
The footer provided by websubmit.cgi is used to contain help information
about specific elements within an application module. The help text
for the application module is currently hard-coded within the script.
The template modules provide examples of how the help information is entered
and activated using the javascript code provided with WebSubmit.
Basically, an array is defined that contains the help data for individual
elements, and a list of these elements must be provided in HELP(elementList).
Elements are indexed based on the names of the corresponding for element
variable, where possible. After the help information is entered,
helpSetup is called with the name of the help data array as its only argument.
Then, within the script definition itself, links are defined that
access the indexed help information.
Creating New Tcl Modules for WebSubmit
The process of creating a new Tcl module for use in WebSubmit basically
involves writing the code and adding the necessary calls to WebSubmit routines.
WebSubmit CGI scripts use the cgi.tcl library to generate the desired HTML
code. It is not necessary to use this library in your own scripts,
although it would allow other WebSubmit modules to be used as templates.
The only basic requirement for writing a Tcl script that uses all the features
of WebSubmit is to load the WebSubmit library using websubmit.conf
as detailed above. Once the script is written and debugged, it can
be added to the WebSubmit hierarchy of modules using the installation algorithms
above.
Installing Tcl Modules in the System
It should not be difficult to add Tcl modules to the WebSubmit system,
since it has been designed with modularity and flexibility in mind.
However, there are a few considerations that need to be kept in mind when
installing scripts that do not come with the distribution.
Installation Algorithm
To install a Tcl module in the WebSubmit system, the following algorithm
should be utilized. For the purposes of illustration, we will assume
that the module script file is called newModule.cgi
and that there are no other modules by the same name. When installing
your own module (with a different name), adjust the required actions in
the algorithm accordingly.
-
Create directory $wsRootDir/modules/hostName/newModule
with permissions necessary for CGI accessibility (755 on a UNIX system)
-
Copy or move newModule.cgi
to $wsRootDir/modules/hostName/newModule
-
Change file permissions on newModule.cgi
so that it can be executed in a CGI context (755 on a UNIX system)
-
Move processing scripts for newModule.cgi
into $wsRootDir/modules/hostName/newModule
if necessary and change permissions as needed
-
Add an entry in the master database ($wsRootDir/lib/master.db)
with key newModule and data
appropriate to the module for the master page
Security Considerations
The WebSubmit security architecture is used to verify users before
providing them access to modules. If a module is installed in the
system that does not utilize the WebSubmit package, it is possible that
users can simply subvert the verification procedure and access the module
directly (without passing through the main WebSubmit entry point).
If the script is written in Tcl, the WebSubmit verification process can
be automatically activated by simply loading the WebSubmit package and
then sourcing websubmit.conf.
Installing non-Tcl Modules in the System
In principle, any CGI script (e.g., written in Perl) may be accessed through
WebSubmit, although the level of security enabled depends on exactly how
the module is accessed.
Case I: No Special Security Precautions
Non-Tcl modules that are accessed without special precautions will
not ensure that a given user is registered with WebSubmit. If the
administrator decides that such measures are not needed for a particular
script, then it may simply be placed somewhere within the module directory
hierarchy as described above. Provided the master database is configured
properly to locate the script, it can be run as usual.
Case II: Non-Tcl script Wrapped inside WebSubmit
authentication
If a developer or administrator wants a non-Tcl script to have WebSubmit
authentication performed, then the script can be wrapped using a Tcl wrapper
utility that comes with the distribution ($wsRootDir/bin/formWrapper.cgi).
In order to prevent direct access to the non-Tcl script, it should be placed
somewhere below $wsRootDir/wrap
(assuming this directory cannot be accessed directly by your server).
The algorithm for installation of secure, non-Tcl modules is as follows.
Assume that a module called foobar.pl
(a Perl script) is to be added to the system.
-
Determine the desired location for the module in the module hierarchy.
Modules are categorized as either host-specific, or generic. If host-specific,
create the directory $wsRootDir/modules/$host/foobar.
If generic, then create the directory $wsRootDir/modules/generic/foobar.
-
Create a symbolic link called formWrapper.cgi
within the newly created directory that points to $wsRootDir/bin/formWrapper.cgi.
-
Create another directory: $wsRootDir/wrap/foobar
-
Place foobar.pl inside $wsRootDir/wrap/foobar
and change its permissions to 755.
-
Add an entry to the master database (master.db,
master.txt) for foobar.pl;
its build attribute in master.db
should be set to WRAP.
-
Access the module as you would any other WebSubmit module.
The URL for this non-Tcl module will invoke formWrapper.cgi in the foobar
directory. formWrapper.cgi determines the name and location of its
parent script (the one being wrapped) using the directory from which it
was invoked. Hence, it is imperative that the correspondence between
directory names and script names is maintained. An example of a non-Tcl
script running underneath WebSubmit authentication is provided in $wsRootDir/wrap/testPerl.