Implementing Web/RCS under Oracle OWS for UNIX

Alan Davis

The RCS source code management system is commonly shipped as part of many UNIX distributions. Additionally, it is available from the Free Software Foundation as part of the GNU toolset. RCS is a set of programs that may be used to manage revisions of all types of files -- program source code, executable binaries, graphics files, etc. Tracking the changes between different versions of files created by many users in a dynamic environment is a difficult task at best. Web/RCS makes this process easier by presenting a graphical, Web-based interface to the documents managed by RCS. It uses a subset of full RCS functions, and it allows access to the documents from any computer that can run a modern Web browser.

The Web/RCS Perl CGI front-end to the GNU RCS source code control system was presented in Sys Admin magazine in December, 1998. This article describes the changes required to port it to Oracle Corporations's OWS Web server, a few enhancements that have been made, and some tricks that enhance the usefulness of Web/RCS for Oracle Applications and Forms development. The configuration detailed here assumes that OWS is being used in an Oracle Applications 11.0 environment.

The original release of Web/RCS by Richard S. Smith was developed for Perl 5.004 and the Apache Web server. The OWS included in the 8.0.4 release of the Oracle Enterprise Server for UNIX bundles the 5.003 release of Perl. There are minor edits required to accomodate the older release. The largest difference for running Web/RCS under Oracle's Web server is in the area of password authentication. (A full description of OWS authentication methods is beyond the scope of this article.)

Installation

Installation of the Web/RCS is simply a matter of untarring the package in an appropriate directory that is accessible to OWS. To eliminate any conflicts with Oracle's installation tools during upgrades or patches, it's recommended that the files aren't installed under $ORACLE_HOME. The /usr/local tree or other hard-mounted directory is appropriate. The configuration described here assumes the files have been placed in the /usr/local/webrcs directory.

Configuration

The README file included with the Web/RCS package describes configuration for the Apache Web server. The OWS configuration steps are to configure the Web listener for the Web/RCS directories, and set up the security information to provide password protection as well as username and group ID for the Web/RCS users. The configuration for the users at the operating system level is unchanged from the original version of Web/RCS.

Configuration of OWS: Details

The OWS provides a Web-based configuration system that is accessed by connecting to the admin listener on the OWS host system. This interface makes it easy to configure the many files that make up the OWS configuration. Connect to the admin Web interface using a Web browser. Select “Web Application Server Manager”, then select “Oracle Web Listener”. On the Oracle Web Listener Home Page, scroll down and select the “Configure” for the Web listener that will handle Web/RCS.

Using the Navigation bar on the left of the screen, select the “Directory” configuration section. There are three new entries to make to this section. Each entry consists of a File-System Directory, a Flag setting, and a Virtual Directory. The three entries are:

File-System Directory           Flag            Virtual Directory
/usr/local/webrcs/src           CN              /webrcs/
/usr/local/webrcs/html          NR              /webrcs_frame/
/usr/local/webrcs/icons         NR              /webrcs_icons/

The first Flag is C or N for CGI or non-CGI, the second is R or N for recursive or non-recursive directory mapping. If Web/RCS was not installed in /usr/local/webrcs, replace that part of each path with the actual installation path. The directory configuration is the equivalent of the AddHandler and Alias directives in the Apache Web server installation. Select one of the Modify Listener buttons to save these changes to the configuration files.

Select “Security” from the navigation bar. The default .htaccess authentication method used by the Apache Web server is similar to the Basic authentication in OWS. For each Web/RCS user, enter the UNIX username and password under Basic Users. The password doesn't have to be the same as the UNIX login password.

Next add a new group for Web/RCS under Basic Groups and list all the Web/RCS users. The Basic Realms are used in the Protection section to define the actual authentication methods used. Enter the new Web/RCS group and assign it a realm name. Scroll down to the Protection section. The entries here are the Virtual Path /webrcs/, Access Mode R for read-only, “Basic” authentication type, and the Realm name assigned for Web/RCS.

Configuration of OS Users

Each Web/RCS user must have a UNIX user account and must belong to the group defined in Basic Groups. Select one of the “Modify Listener” buttons to save these changes to the configuration files. The Web listeners must now be restarted for the changes to take effect.

Configuring the Wrapper

Web/RCS must run as a setuid, or privileged, program in order to modify the ownership of files that are checked in and out. Follow the instructions in the README file for creating the proper wrapper binary and installing it in the CGI directory.

It may be possible to configure Web/RCS to use the Perl cartridge of Oracle Application server. The Web listener would have to run as root, presenting some especially difficult security issues. In order to minimize the risks associated with Web/RCS and OWS, the Perl cartridge method was not used.

Required Modifications to the Web/RCS Script

There are three modifications to the script that are required to run under the Perl interpreter distributed with Oracle OWS. The first is to modify the bang-path to point to the Oracle Perl interpreter. The Oracle db manager account will have in its environment the variable ORAWEB_HOME that points to the top of the OWS installation. The Perl binary is found in the directory $ORAWEB_HOME/perl/bin/perl.

The next two changes are to modify the require statement from 5.004 to 5.003, and to comment out the line that begins “delete @ENV(”, since that feature changed between the two versions of Perl.

New Features

In addition to the changes required to work under OWS, several new features have been added. When files are copied to a user's directory, the default location in the original release was a single subdir named rcs. If the RCS repository is set up as multiple subdirectories or as several trees of subdirectories, all the files copied will go into this one location and will lose the uniqueness of the repository tree. Updates have been made to the file copy routines to preserve the original tree structure of the repository. This enables Web/RCS to be used more easily with larger projects, or for several projects under a single repository.

Directory Example :

        $RCSROOT = "/data/rcs/repository"
        Project 1 = $RCSROOT/proj1
                    $RCSROOT/proj1/bin
                    $RCSROOT/proj1/doc
        Project 2 = $RCSROOT/proj2
                    $RCSROOT/proj2/bin
                    $RCSROOT/proj2/doc

        $RCS_USER_DIR = "rcs"
        $HOME = "/usr/home/edgar"

Files from proj1 would be copied to /usr/home/edgar/rcs/proj1 and files from proj2 would be copied to /usr/home/edgar/rcs/proj2. Directories are created as needed during the copy operation. The original release would display an error page if the file being copied already existed in the working directory. A new configuration variable RENAME_ON_COPY has been added. If this variable is not blank, the file already in the working directory will be renamed by appending .old to the filename. This feature should be used with caution, as it will overwrite changes to a working file that have not been checked in.

The group id of files copied out of Web/RCS originally retained the group id of the RCS group. This has been changed to ensure that files copied are owned by the user's id and group id.

The original release didn't provide any way of adding a new file to the repository. A “New File (Upload)” button has been added to each page displayed below the RCSROOT. Additional functions to manage the directory structure and to add files to the repository from the UNIX working directories have yet to be added.

A basic mail agent handler has been incorporated to allow administrative monitoring of Web/RCS use. Each page displays the name of the currently authenticated user.

Using Web/RCS in the Oracle Environment

Web/RCS is helpful in organizing and deploying Oracle Applications programs, SQL files, control files, and Concurrent Programs. The users develop the sources in their own working directories, using Web/RCS to manage the file revisions. The development environment for Oracle has the restriction of tightly controlled locations from which programs may be executed. The normal edit/compile/test cycle is made more difficult by the need to place the programs under test into the proper directories with specific ownership.

Web/RCS may be used to deploy files to the proper directories as the correct user using links from the dbms or application instance manager's account to the correct locations under the application's directory structure. Using the same directory structure as the earlier example, the application will be deployed to directories called $PROJ1_TOP and $PROJ2_TOP. The links are set up in the application instance manager's account as :

$HOME = "/usr/home/appdevl"
$USER_RCS_DIR = "rcs"
$PROJ1_TOP = "/data/app/appdevl/custom/inv"

In the RCS directory is a symbolic link from the RCSROOT name to the appropriate directory in the applications directories:

/usr/home/appdevl/rcs/proj1 -> $PROJ1_TOP

Files from proj1/bin would be copied to:

/data/app/appdevl/custom/inv/bin/

By using a Web browser logged in as the user, files may be checked out locally for modification. Then, the user exits the browser to clear the authentication and logs back into Web/RCS as the applications or dbms manager. A simple copy then deploys the files to the correct directory and sets the required ownership.

A command-line utility has been added that allows a user to quickly add files and directories to the repository, without having to remember the full paths or the several commands necessary to create the directories, set the permission and ownership, and then copy the files. The utility is called webrcs_put. It's simple usage statement is:

Usage:
webrcs_put -d <target dir> file ...
webrcs_put -c <target dir>
webrcs_put file ...
webrcs_put -h
Put file[s] in webrcs <target dir> for checkin via web i/f.

The first form copies the file to the specified directory. If the directory doesn't exist, it will be created under the /data/rcs/repository directory. The second form only creates the directory. The third form examines the current working directory and uses the pathname relative to $HOME/my_src as the target directory. The -h switch prints this message and exits.

Acknowledgement and Credits

I'd like to thank Edgar Kline for his inspiration and feature suggestions. The email Perl code was adapted from the Chklogs package by D. Emilio Grimaldo T. The Web/RCS program was originally published in Sys Admin (December, 1998) and is still maintained by Richard S. Smith.

About the Author

Alan Davis is UNIX systems administrator with over 12 years of experience in many different flavors of UNIX. His interests lie mainly in the areas of process automation and administrative tools. He may be reached via email at Davis_Consultants@att.net.