CX Web Server

CX Web Server

Installation Guide

Copyright (c) 2002 Jenzabar, Inc. All rights reserved. You may print any part or the whole of this documentation to support installations of Jenzabar software. Where the documentation is available in an electronic format such as PDF or online help, you may store copies with your Jenzabar software. You may also modify the documentation to reflect your institution's usage and standards. Permission to print, store, or modify copies in no way affects ownership of the documentation; however, Jenzabar, Inc. assumes no responsibility for any changes you make. Filename: inwebsrv Distribution date: 7/10/2002 Contact us at www.jenzabar.com

Jenzabar CX and QuickMate are trademarks of Jenzabar, Inc. INFORMIX, PERFORM, and ACE are registered trademarks of the IBM Corporation Impromptu, PowerPlay, Scenario, and Cognos are registered trademarks of the Cognos Corporation UNIX is a registered trademark in the USA and other countries, licensed exclusively through X/Open Company Limited Windows is a registered trademark of the Microsoft Corporation All other brand and product names are trademarks of their respective companies

i

JENZABAR, INC. CX WEB SERVER INSTALLATION GUIDE

TABLE OF CONTENTS

SECTION 1 - INTRODUCTION .................................................................................................................... 1 Beginning to Set up the Jenzabar CX Webserver...................................................................................... 1

Overview................................................................................................................................................. 1 Purpose of This Guide............................................................................................................................ 1 Intended Audience.................................................................................................................................. 1

Webserver Basics....................................................................................................................................... 2 Introduction............................................................................................................................................. 2 Apache Web Site.................................................................................................................................... 2 Other Information about Apache ............................................................................................................ 2 Default Directory for Examples............................................................................................................... 2 User Name When Accessing the Webserver......................................................................................... 2 Setting Up the New webadmin User ...................................................................................................... 2 Setting Up the webadmin Group ............................................................................................................ 3 Commands for Starting and Stopping the Webserver............................................................................ 3 Webserver Log Files............................................................................................................................... 4 Assessing the Apache Server Statistics and Status .............................................................................. 4 Removing or Reinitializing the Log Files ................................................................................................ 4 Source and Installed Directories for Web Applications .......................................................................... 5 Web Directories ...................................................................................................................................... 6

Jenzabar CX Webserver Basics ................................................................................................................ 8 CGI Script Log File: ................................................................................................................................ 8 User Options Files .................................................................................................................................. 8 User Authentication Files........................................................................................................................ 9 dbmmanage Command .......................................................................................................................... 9 setup_web_dbm Command ................................................................................................................. 10 Image Files ........................................................................................................................................... 10

SECTION 2 - SETTING UP THE WEBSERVER........................................................................................ 11 Introduction........................................................................................................................................... 11 Tasks Prior to Installation ..................................................................................................................... 11 Using Plibdata.pm Perl5 to Access the Database................................................................................ 11 Verifying the Plibdata Setup ................................................................................................................. 11 Example Setup and Linking for Plibdata .............................................................................................. 11 Setting up TEST and LIVE Webservers ............................................................................................... 12 Setting Up a Single Webserver ............................................................................................................ 13 Ensuring the Existence of SERVER_INSTPATH Directories .............................................................. 14 Webserver Directories .......................................................................................................................... 14

Macro Setup for the Jenzabar CX Webserver ......................................................................................... 15 Modifying Configuration Macros........................................................................................................... 15 Modifying Server Path Macros ............................................................................................................. 15 Modifying the Jenzabar CX ODBC Driver Path.................................................................................... 15 Modifying the Perl Directory Path......................................................................................................... 16

Final Installation Steps ............................................................................................................................. 17 Introduction........................................................................................................................................... 17 Setting Up the ODBC (cisinf and cisaps) Services .............................................................................. 17 Determining the Port Numbers of the New Services............................................................................ 17

Installing Apache Webserver Software .................................................................................................... 18 Overview............................................................................................................................................... 18 Verifying the Webserver Has Started ................................................................................................... 18

Directory Structure of the Apache Webserver.......................................................................................... 20 Introduction........................................................................................................................................... 20

Accessing Data Using the Webserver.................................................................................................. 20 Configuration Files................................................................................................................................ 21

Completing the Installation Process......................................................................................................... 22 Verifying Permissions and Installing Files ............................................................................................ 22

Web Authentication .................................................................................................................................. 24 Authenticating Students........................................................................................................................ 24 Creating PIN Numbers ......................................................................................................................... 24 Setting Up the Authentication File for Student Access......................................................................... 24 Setting Up the Authentication File for Faculty Access ......................................................................... 24 Authenticating Faculty Users................................................................................................................ 25 Regenerating the Authentication File ................................................................................................... 25

Verifying Your Installation......................................................................................................................... 27 Introduction........................................................................................................................................... 27 TEST and LIVE Servers in the Verification Process ............................................................................ 27 Determining the Port Number of the Webserver .................................................................................. 27 Verifying Access to the First Page of the Webserver........................................................................... 27 Verifying Student Authentication Setup................................................................................................ 27

Errors and Troubleshooting During Webserver Setup ............................................................................. 29 Introduction........................................................................................................................................... 29

APPENDIX - SETTING UP A DUAL WEBSERVER.................................................................................. 31 Issues ....................................................................................................................................................... 31

Introduction........................................................................................................................................... 31 Configuration Requirements for IBM Systems ..................................................................................... 31 Configuration Requirements for HP Systems ...................................................................................... 31 Macro Setup for Dual Webservers ....................................................................................................... 31 Macro Locations ................................................................................................................................... 31

Installing Web Modules ............................................................................................................................ 32 Source Code Location .......................................................................................................................... 32 Database Access.................................................................................................................................. 32 Web User Authentication...................................................................................................................... 32 Security Issues ..................................................................................................................................... 32

Implementation Issues ............................................................................................................................. 33 Before You Begin ................................................................................................................................. 33 Recreating $CARSPATH and Other Directory Paths on the Webserver............................................. 33 Copying Directories Between Servers.................................................................................................. 34 Other Replication Issues ...................................................................................................................... 35

Modifying make on the Database Server ................................................................................................. 36 Introduction........................................................................................................................................... 36 Modifying make on the Database Server Using the ftp/rsh Method (for AIX) or the ftp/remsh Method (for HPUX) ............................................................................................................................................ 36 Changes to $CARSPATH/system/Make/user/Cmdscripts/install......................................................... 36 Changes to $CARSPATH/system/Make/user/Make/cinstall ................................................................ 38 Modifying make on the Database Server Using the ssh Method ......................................................... 40 Installing and Running the ssh Daemon............................................................................................... 40 Preliminary Steps for Configuring sshd ................................................................................................ 41 Changes to $CARSPATH/system/Make/user/Make/cinstall ................................................................ 42 Changes to $CARSPATH/macros/user/Web ....................................................................................... 44 Activating Remote Webserver Capability ............................................................................................. 44

Files Requiring Special Handling ............................................................................................................. 45 Introduction........................................................................................................................................... 45 Special Handling for Certain Files ........................................................................................................ 45 Setting Fileperms of Apache config Files ............................................................................................. 46 Installing setup_web_dbm.................................................................................................................... 46 Fileperms.............................................................................................................................................. 46

Setting up User Authentication................................................................................................................. 48

iii

Running setup_web_dbm..................................................................................................................... 48 Setting up webadmin to Update profile_rec ......................................................................................... 48

Errors and Troubleshooting During Dual Webserver Setup..................................................................... 49 Introduction........................................................................................................................................... 49 Student Photos ..................................................................................................................................... 49 Restoring LIVE Web to the Database Server....................................................................................... 49

INDEX ......................................................................................................................................................... 51

CX Webserver 1 Introduction

SECTION 1 - INTRODUCTION

Beginning to Set up the Jenzabar CX Webserver

Overview The purpose of the Jenzabar CX webserver is to provide students, faculty, and constituents access to various types of information about your institution via the World Wide Web.

Purpose of This Guide Use this guide to install the CX webserver. The information in this guide can help you during the installation and also if you intend to use dual webservers at your institution.

Intended Audience This guide is for use by the system users in your institution’s computer center. System users include the Jenzabar system coordinator, Jenzabar system administrator, and programmer/analysts.

Introduction 2 CX Webserver

Webserver Basics

Introduction This section contains information you need to get started setting up the Jenzabar CX webserver, including file locations, examples, tips, and other fundamentals.

Apache Web Site The Apache Web site is www.Apache.org. Refer to this site for more detailed information about the products and services of the Apache Foundation.

Other Information about Apache Documentation is available at no cost on the following Apache webserver website:

http://www.Apache.org

Another resource is the Apache Quick Reference Card, available at http://www.refcards.com, a source of downloadable reference cards related to Web software.

A variety of commercially produced manuals are also available to help you use the Apache Webserver.

Other Information about Mod Perl, Mod SSL, and Accelerator Cards The internet provides other resources so you can learn more about Mod Perl, Mod SSL, and accelerator cards. Refer to the following:

Mod Perl Web Site The Mod Perl Web site is http://perl/apache.org/guide. Refer to this site for more detailed information about the installation and configuration of mod_perl, etc.

Mod SSL Web Site The Mod SSL Web site is http://www.modssl.org. Refer to this site for more detailed information about Mod SSL.

Other Information about SSL Search the web for “cryptographic accelerator cards”, and then select a vendor site (e.g., http://www.rainbow.com/cryptoswift/index.html). Refer to one of these sites for more detailed information about hardware accelerator cards for use with OpenSSL. An accelerator card will enable your system to encrypt and decrypt secure data more quickly.

Default Directory for Examples This section contains a variety of examples to illustrate the structure and setup of the CX webserver. All examples assume the following default directory: /opt/apache.

User Name When Accessing the Webserver The webserver always runs as the user webadmin, regardless of who is using it. For example, when faculty members access the server to add course information, the server interprets them as the user webadmin. Likewise, if a student accesses the server to register for a class, the server interprets the student as the user webadmin. As a result, it is important that database permissions be set up correctly for the webadmin user.

Setting Up the New webadmin User The CX webserver has been designed with the expectation that your administrative webserver will be run as webadmin and that this user account be set up as a non-loggable account (i.e., no


user can log in directly as webadmin). The webadmin user should be added to the common, admissions, student, and registrar groups and also be granted privileges to connect to the database. Use addlogin and dbadmin to accomplish this setup.

Setting Up the webadmin Group The webadmin group limits who may reinstall the webserver configuration files that are located under $CARSPATH/web/etc. The suggested group number for webadmin is 999. Add only those users who should update the webserver configuration files to this group, using the following commands:

1. Enter % SU csh to become superuser.

2. At the prompt, enter your superuser password.

3. At the superuser prompt (#), enter vi /etc/group. The group file opens.

4. Enter <Shift-g> to go to the end of the file.

5. Enter <i> to go into Insert mode.

6. In Insert mode, type webadmin::999:webadmin,your_login_name. Respond Yes to the prompt, is 999 available?

7. Enter :wq to save your edits to the file.

8. Enter # exit to leave superuser status.

9. After you complete the above procedure, login again to add webadmin to your list of groups by entering % login.

10. Verify that you are in the webadmin group by entering % groups.

11. Add the user webadmin to the following database tables: regperm_table (to enable Web registrations to take place) audperm_table (to enable faculty to enter grades through the Web)

Commands for Starting and Stopping the Webserver The server must be started as root; it automatically changes the user name to webadmin whenever any user accesses the server.

The following commands cause the server to start, stop, and restart. Consider placing these commands in the appropriate startup and shutdown scripts for your system.

# /opt/Apache/sbin/apachectl start Starts server

# /opt/Apache/sbin/apachectl startssl Starts server in SSL mode

# /opt/Apache/sbin/apachectl stop Stops server

# /opt/Apache/sbin/apachectl restart Restarts server

Note: If the authentication screen does not appear when accessing the student or faculty options, reinitialize the setup and the Apache webserver using the following commands:

% cd web/etc % make reinstall F=ALL

You can then bounce the server using the stop and start commands above.


Webserver Log Files The webserver directory /opt/apache contains the following files that log the actions and reactions of the webserver. All these files should be emptied and/or archived regularly using the commands in the section Removing or Reinitializing the Log Files.

access_log Collects information about who has accessed the system, and what was accessed.

agent_log This log file collects information about the browser used to access the webserver.

error_log This log collects all errors that are created by the webserver. It is useful in debugging error conditions, as it contains information about who was accessing the system and what occurred when the error took place. Use the tail command on this file to show the most recent errors.

referer_log This log file collects the browser references and what location was referenced by the call.

sslaccess_log, sslengine_log, sslerror_log, sslrequest_log

These log files relate to information generated while apache is running in SSL mode.Assessing the Apache Server Statistics and Status

For information about the usage and status of the webserver, use a Web browser to access the following URL:

http://carseduc/server-status This site displays server information, including the status of the engine and processes currently operating. It must be enabled in the httpd.conf apache configuration file. In addition, if enabled, you can access this from within the firewall:

http://carseduc/server-info

Removing or Reinitializing the Log Files Because of the way Apache maintains files, you cannot simply archive the log files and then remove them from the system. Apache will continue writing to the logfile at the same offset as before the logfile was removed, resulting in a new logfile that is as large as the old one, but with thousands of null characters at the beginning of the file.

The correct procedure is to move the logfile, then signal Apache to reopen the logfiles. Since Apache is signaled using the SIGHUP (-1) signal, use the following commands if you want to save the log files:


% SU csh Password for <user>: # mv access_log access_log.old # mv agent_log agent_log.old # mv error_log error_log.old # mv referer_log referer_log.old # mv sslaccess_log sslaccess_log.old # mv sslengine_log sslengine_log.old # mv sslerror_log sslerror_log.old # mv sslrequest_log sslrequest_log.old # kill -1 `cat ../run/httpd.pid` # exit

Source and Installed Directories for Web Applications The following file structure represents the structure maintained by the make processor from the CX source directories:

• $CARSPATH/web • $CARSPATH/modules/<track>/cgi • $CARSPATH/modules/<track>/html • $CARSPATH/modules/<track>/lib ( new Web.pm modules )

The cgi directory files under the web subdirectory path contain the web browser menu items. The installed files are stored under /opt/apache/carsi-<test or live>/share/cgi-bin. The $CARSPATH/modules/<track>/cgi files are also stored under /opt/apache/carsi-<test or live>/share/cgi-bin.

The $CARSPATH/web files are similar to the menu and menu option paths in other areas of Jenzabar CX. The *.cgi files in this file layout are very small and contain pointers to the installed .cgi files that are stored under the respective tracks of $CARSPATH/modules. The following diagram shows the relationships of the files.

The lib directory files under the modules subdirectory path contain scripts which were originally in the cgi directory that have been converted to use the Web.pm module. These scripts, with the help of Web.pm, will run properly under mod_perl.


CARSPATH Web Server Source

finaid(menu.cgi)

(*.cgi)

faculty(frame.cgi)(menu.cgi)

(*.cgi)

modules(htaccess.hid)(nsconfig.hid)

student(frame.cgi)(menu.cgi)

(*.cgi)

cgi html(index.htm)

etc(srm.conf)

(httpd.conf)(access.conf)

$CARSPATH/web

public(menu.cgi)

(*.cgi)

ia(frame.cgi)(menu.cgi)

(*.cgi)

stuadv(frame.cgi)(menu.cgi)

(*.cgi)

campaign(frame.cgi)(menu.cgi)

(*.cgi)

constituent(frame.cgi)(menu.cgi)

(*.cgi)

estate(main.cgi)

(*.cgi)

register(menu.cgi)

(*.cgi)

finaid(menu.cgi)

(*.cgi)

plangvg(plangvg.cgi)

(*.cgi)

reporting(main.cgi)

(*.cgi)

grants(main.cgi)

(*.cgi)

(*.js)(*,css)

Web Directories The source files that control Web processing are located under $CARSPATH and are under full RCS control. The cgi language used for the applications is Perl. Two directories have been added to the modules that support the Web applications: cgi (file type .cgi) and html (file type .htm).

The cgi directory contains the Perl scripts that display, compute and collect the data from the person accessing the server. The Perl scripts dynamically create html statements that are processed by the user’s browser.

The html directory contains the help files that can be referenced from the Web pages. The name of the help file is the same as the cgi file name. The help button appears automatically on the browser page created by the cgi file of the same name.

The extensions to the $CARSPATH/modules directory are:

• common

• regist

• finaid

• admit

• develop


$CARSPATH Source Directory

. . .

Perl scripts*.cgi

cgi

help

html reports screens lib

regist . . .

$CARSPATH/modules

Help documents*.htm

Perl modules*.pm


Jenzabar CX Webserver Basics

CGI Script Log File: The cgi log files are maintained in the following file:

/opt/apache/carsi-*/var/cgi-logs/YYYYMMDD.log

Each day, the server creates a new cgi log file. The cgi log file contains information about the execution of a cgi script, including:

• When the script was run

• Which script was run

• Who ran the script

• What the script provided (e.g., a query form, data result, or no data from the given query)

• What parameters were used

The file format is pipe-delimited, designed to load easily into a database for analysis of script usage.

Note: If you want more than an activity log (i.e., more in-depth debugging information), use the CGI::Carp module contained in the Web.pm module.

User Options Files Individual Authenticated User options are maintained in /opt/apache/carsi-*/var/useroptions/NA/NAME.{dat,idx}. These files require 1K per user and should be considered when deciding how much space will be required for deploying Web services. These files are currently DBM files that are easily accessible using Perl.

Note: If you access the web pages from the Unix command line via Perl, and the options file did not exist before, the owner will be the logged-in user, not webadmin. You must then access the user options directory and run “fileperms –u *” on the files. Or create a cron job, if you plan to do a lot of command line testing.


User Authentication Files By default, CX is using the DBM authentication mechanism available in the Apache server. This requires creating separate DBM file(s) that are used by the server to grant access privileges. Inherently, this approach will create some time delay between changing a system password or student pin number and those being used by the webserver.

The location of the authentication files is: /opt/apache/carsi-*/var/authdb/.

Note: To add logout functionality, create a DBM file with all the users (e.g., faculty and students), without any passwords. Then create a directory directive in the Apache access.conf file with the same AuthName as the original faculty or student (e.g., “Faculty Access” or “Student Access”). When the authorization dialog pops up, click the OK button. Since the password field is empty, the next time the user accesses the original faculty or student page, he/she will need to complete the popup containing the authorization dialog for the full password.

dbmmanage Command You can use the $CISPATH/dbmmanage command to view and maintain these files. A usage message is available by typing 'dbmmanage -,'. This command verifies that a dbm file exists and has entries in it.

The command is located in: $CARSPATH/modules/cisc/commands

To use the command, you must be in the authentication directory where the authentication files exist. The files are student.{pag,dir} and faculty.{pag,dir}.

To view all of the entries in one or the other of the authentication files: % cd /opt/apache/carstrain-test/var/authdb % dbmmanage student view % dbmmanage faculty view

To view just one entry: % dbmmanage faculty view jdoe

To check that the password is working: % dbmmanage faculty check jdoe Enter password: ____________ password ok (assuming you entered the correct password)

The same commands apply for the student authentication files.

The output will be the user name, a :, and the encrypted password for the view option.

You can use the adduser and delete commands to add a new person to the authentication file or to delete someone from the file. Note that this affects only the webserver and no changes are made to the database. To make your changes permanent, you must add the person to the userid_table or remove (date inactivate) the person so the next time the setup_web_dbm process is run, this data would come from the database to the authentication file.


To use the adduser command to add an individual to the authentication file with an encrypted password:

% dbmmanage faculty adduser newone New password: Re-type new password:

To delete a user: % dbmmanage faculty delete newone

For more information about the dbmmanage command, see Jenzabar CX Technical Manual - Implementation and Maintenance.

setup_web_dbm Command The $CISPATH/setup_web_dbm command is a single command that regenerates either the student or faculty authentication files. This command regenerates the complete faculty or student authentication files based on the SQL statements within the script. The easiest way to maintain which students are selected would be to control which students have PINs specified in the profile_rec. If you should want to alter the selection process, the source location of setup_web_dbm is $CARSPATH/modules/cisc/commands/setup_web_dbm.

Image Files The CX webserver supports two image files, driven by macro settings in macros/custom/web. One is for the institutional logo and the other is the page background image. These are not provided by Jenzabar for the product given as they are intended to reflect your unique needs. However, to eliminate the need to make any modifications to the webserver configuration files, these image files should be placed in /opt/apache/cars*-{test,live}/share/htdocs/images/.

If you have modified the Web macros related to the images, you can check the webserver's errors_log file to determine the path the webserver is searching for the images. Image files are retrieved from the /opt/apache/share/images directory. The directory is specified via the Apache Alias directive.

CX Webserver 11 Setup

SECTION 2 - SETTING UP THE WEBSERVER Introduction

The following tasks provide important information you need to know before you begin to install the Jenzabar CX webserver.

Tasks Prior to Installation You must accomplish the following general tasks at your institution before you install the Jenzabar CX webserver:

• Set up Plibdata • Set up Web.pm • Create a TEST and a LIVE server setup and ensure their directory structure is correct • Modify local configuration macros

Using Plibdata.pm Perl5 to Access the Database The Plibdata.pm Perl5 module is available for accessing the database. To use the module from the webserver, enter the following lines near the top of the Perl5 source file:

use lib "WEB_SERVER_ROOTPATH/WEB_CGIBIN/lib"; require Plibdata;

To use the module outside of the webserver, include the following lines near the top of the Perl5 source file:

use lib "$ENV{'CARSPATH'}/install/lib"; require Plibdata;

Verifying the Plibdata Setup The installed file Plibdata contains the library functions used by the Perl programs. To ensure it functions correctly, do the following:

• Check to see that the files have the proper permissions. • Check to see that the shared library is linked. The file with the .sl extension is the

shared library.

The linked library is created with the following command: % ln -s Plibdata.sl Plibdata.1

After you execute this command, the directory should look similar to what is shown in the following example.

Example Setup and Linking for Plibdata The following is the Plibdata setup and the linking of the libraries. Note: The -> is an example of linking.

-r-xr-xr-x 1 bin bin 292892 Jul 13 17:00 Plibdata.1 -rw-rw-r-- 1 carsu carsprog 1663196 Jul 13 16:59 Plibdata.a -rw-rw-r-- 1 carsu carsprog 26390 Jul 13 16:59 Plibdata.pm lrwxrwx--- 1 bin bin 10 Jul 13 17:00 Plibdata.sl -> Plibdata.1

Setup 12 CX Webserver

Web.pm Requirements There have been several releases of the Web.pm module, including one release in each of the following SMOs:

SMO 12614 – Web Infrastructure Upgrade

SMO 12659 – Web Security Infrastructure – (apply PA for this SMO)

SMO 12686 – Web Look and Feel Enhancements

When SMO 12614 was installed on your system, the DBI Perl module was added automatically. If there were errors installing this component of Perl, the Web.pm module will not work correctly. To verify that DBI is installed correctly, execute the following command:

perldoc perllocal

or $CARSPATH/software/perl5-modules/Procedures/pmlist -s

Example Setup for Web.pm A copy of Web.pm should exist for both TEST and LIVE, as in the following example directory/file path:

/opt/apache/${CARSV}[test|live]/share/cgi-bin/lib/CARS/Web.pm If not, reinstall the Web.pm module from the web/cgi/lib/CARS directory. % cd web/cgi/lib/CARS % make reinstall F=Web.pm % make reinstall F=Web.pm WEBSERVER=LIVE

Setting up TEST and LIVE Webservers Many institutions maintain both a TEST webserver for testing new documents and cgi scripts, and a LIVE webserver that contains only files already tested and ready for general use. The TEST server is the server that will be used by default for make smoreinstalls or make reinstalls. The TEST server is expected to be on your Jenzabar CX host machine.

The LIVE server may be local or remote to your Jenzabar CX host. If the LIVE server is on a remote machine, it is expected that ftp access between the Jenzabar CX host to the LIVE server is available for code installation. If your LIVE server is going to be on the Jenzabar CX host along with the TEST server, then be sure to specify different installation paths for the two.

The locations of the TEST and LIVE webservers are specified in the $CARSPATH/macros/custom/web macro file.

By default, the install targets for cgi and htm type directories will install under the TEST webserver. To install files under the LIVE webserver, you should specify 'WEBSERVER=LIVE' on the Make command line, as in the following example:

% make smodoproc –w LIVE % make smoreinstall WEBSERVER=LIVE % make reinstall F=ALL WEBSERVER=LIVE Since some macro definitions are different depending on whether you are installing into the TEST or the LIVE webserver, make does a separate translation of the files for each webserver.

Specifying Dotree=Y in a cgi or htm type directory causes make to perform the install for the current directory and all of its subdirectories rather than just the current directory.


Setting Up a Single Webserver The following procedure assumes the following:

1. Your institution has two databases (cars and train).

2. Your institution has two releases (carsi and carstrain).

3. The releases have shared source directories.

4. You want to implement the webserver on the current Jenzabar CX administration computer.

5. You do not need both a test and live webserver because you have a train and live release.

6. You want to install a single webserver for carstrain that accesses the train database and a single webserver for carsi that accesses the cars (live) database.

By default, all Web file installations use the WEB_SERVER_TEST macros and you must specify WEBSERVER=LIVE to use the WEB_SERVER_LIVE macros.

To set up the system to only install a single webserver per release, do the following:

1. Modify the WEB_SERVER macros to remove the -test and -live components so that under the /opt/apache/ directory you will have only the CARSV subdirectories of carsi/ and carstrain/. This will make it easy to determine with which webserver you are working and eliminate any confusion that carsi-live/ and carstrain-test/ and other extraneous directories could cause.

2. Make the following local customization. % cd macros/custom % make co F=web % vi web

3. Remove all of the -test and -live strings that follow the CARS_V macros in the file. The following list shows the lines you must modify, and how they will appear after modification: m4_define(`WEB_LIVE_HTDOCS', `CARS_V-live/share/htdocs') m4_define(`WEB_LIVE_CGIBIN', `CARS_V-live/share/cgi-bin') m4_define(`WEB_LIVE_USROPT', `CARS_V-live/var/useroptions') m4_define(`WEB_LIVE_CGILOG', `CARS_V-live/var/cgi-logs') m4_define(`WEB_LIVE_AUTHDB', `CARS_V-live/var/authdb') m4_define(`WEB_TEST_HTDOCS', `CARS_V-test/share/htdocs') m4_define(`WEB_TEST_CGIBIN', `CARS_V-test/share/cgi-bin') m4_define(`WEB_TEST_USROPT', `CARS_V-test/var/useroptions') m4_define(`WEB_TEST_CGILOG', `CARS_V-test/var/cgi-logs') m4_define(`WEB_TEST_AUTHDB', `CARS_V-test/var/authdb') will become: m4_define(`WEB_LIVE_HTDOCS', `CARS_V/share/htdocs') m4_define(`WEB_LIVE_CGIBIN', `CARS_V/share/cgi-bin') m4_define(`WEB_LIVE_USROPT', `CARS_V/var/useroptions') m4_define(`WEB_LIVE_CGILOG', `CARS_V/var/cgi-logs') m4_define(`WEB_LIVE_AUTHDB', `CARS_V/var/authdb') m4_define(`WEB_TEST_HTDOCS', `CARS_V/share/htdocs') m4_define(`WEB_TEST_CGIBIN', `CARS_V/share/cgi-bin') m4_define(`WEB_TEST_USROPT', `CARS_V/var/useroptions') m4_define(`WEB_TEST_CGILOG', `CARS_V/var/cgi-logs') m4_define(`WEB_TEST_AUTHDB', `CARS_V/var/authdb')


4. Use the following command to check in your changes under RCS: % make cii F=web L='Remove the test and live directory qualifiers'

5. Reinstall the Make system in order for the macro changes to take place. This is most easily done by reinstalling all of the Make with the following commands: % cd $CARSPATH/system/Make % make reinstall F=ALL

6. Modify the Apache server configuration files to reference the release specific directories. In order to minimize the modifications needed to the files, temporarily redefine the TEST and LIVE macro definitions making them each specific to a carstrain or carsi release. % cd $CARSPATH/web/etc % make co F='httpd.conf access.conf'

7. Add the following m4 macro definitions at the top of both of these files: m4_define(`WEB_LIVE_HTDOCS', `carsi/share/htdocs') m4_define(`WEB_LIVE_CGIBIN', `carsi/share/cgi-bin') m4_define(`WEB_LIVE_USROPT', `carsi/var/useroptions') m4_define(`WEB_LIVE_CGILOG', `carsi/var/cgi-logs') m4_define(`WEB_LIVE_AUTHDB', `carsi/var/authdb') m4_define(`WEB_TEST_HTDOCS', `carstrain/share/htdocs') m4_define(`WEB_TEST_CGIBIN', `carstrain/share/cgi-bin') m4_define(`WEB_TEST_USROPT', `carstrain/var/useroptions') m4_define(`WEB_TEST_CGILOG', `carstrain/var/cgi-logs') m4_define(`WEB_TEST_AUTHDB', `carstrain/var/authdb')

8. Use the following command to check in your changes under RCS: % make ci F='httpd.conf access.conf' L='Add macro definitions for carsi and carstrain directories to be used'

Ensuring the Existence of SERVER_INSTPATH Directories If you are implementing both a TEST and LIVE server, you must make sure the directories exist for both.

Create the needed directories using the following commands: cd macros/custom % grep SERVER_INSTPATH web % set instpath = "/opt/httpd" (The path is returned by grep; its default is /opt/apache) % mkdir $instpath % mkdir $instpath/cgi-logs % mkdir $instpath/useroptions

Webserver Directories Webserver directories on the local machine must exist to prevent the creation of fileperms error messages. You must therefore ensure that the SERVER_INSTPATH directories exist. If you are implementing both a TEST and LIVE server, make sure the directories exist for both.

To create the required directories, enter the following commands: % grep SERVER_INSTPATH web % set instpath = "/opt/apache" % mkdir $instpath % mkdir $instpath/cgi-logs % mkdir $instpath/useroptions


Macro Setup for the Jenzabar CX Webserver

Modifying Configuration Macros As delivered, the ENABLE macros for all the Jenzabar CX Web applications are set to Y. If you do not intend to implement all the components of the Jenzabar CX webserver, then set the values of the ENABLE_MOD_WEB macros accordingly, using the following commands:

1. Access the web macro file as follows: • % cd $CARSPATH/macros/custom • % make co F=configure • % vi configure

2. Set the ENABLE macros to reflect the intentions of your institution.

3. Save your changes as follows: % make cii F=configure L='Make local customizations'

Modifying Server Path Macros As delivered, default values in macros/custom/web are set up to run Apache in conjunction with Jenzabar CX for both the TEST and LIVE webserver. Under most conditions, the value of MAK_HOSTNAME for the WEB_EDVANTA_HOSTNAME macro should not need to change. MAK_HOSTNAME is determined automatically, based on 'uname -n'.

For a default webserver installation, only the WEB_DOMAIN_NAME macro should be changed in the macros/custom/web file.

Modify the paths as indicated in the following procedure:

1. Access the web macro file as follows: • % cd $CARSPATH/macros/custom • % make co F=web • % vi web

2. Customize the macros to fit your institutional setup.

3. Save your changes as follows: % make cii F=web L="Modified macros for site conditions''

Note: Complete this step before continuing so all remaining files to be installed are placed in the right order with the desired directories used. If you change any values in macros/custom/web later, reinstall the following:

• system/Make/user/{Common,cgi,htm}, • system/Make/prog, • system/lib/fileperms.s, and • web/cgi/lib/cisweb.ph

Modifying the Jenzabar CX ODBC Driver Path By default the installation location is outside of CARSPATH in /opt/cisodbc. If you want to change that location, customize the CIS_ODBC_PATH macro value as follows:

1. Access the macros/util/paths file using the following commands: • % cd macros/util • % make co F=paths • % vi paths

2. Locate the macro and modify it to indicate the location you want to use for your ODBC


drivers using the following command: (Chris: What the heck is this: ++Doug: I think it should say modify the following macro NOT using the following command) /CIS_ODBC_PATH

3. Make the change, save the file, then check the file in using the following command: % make cii F=paths

Modifying the Perl Directory Path You must make sure the directory in which perl is installed is defined in the macro PERL_DIR. To make this change, customize the appropriate macros/system file as follows:

1. Access the appropriate macros/system file using the following commands: • % cd macros/system • One of the following two commands, depending on whether you are running an HP or

IBM computer: • % make co F=aix • % make co F=hpux

• % vi <the checked out file> 2. Locate the macro PERL_DIR and modify it to indicate the location where perl is installed.

3. Make the change, save the file, then check the file in using the following command: % make cii F=<the checked out file>

Customizing the Navigation Menu Jenzabar provides a javascript navigation menu. This menu is more flexible than the old style button navigation menu. The look of the navigation menu is similar to Windows Explorer. It displays folders for submenus; clicking on the plus sign causes the submenus to expand.

1. Change the active directory to the macros file containing the custom settings. • % cd macros/custom • % make co F=web • % vi <the checked out file>

2. Change the the following macros: • WEB_MENU_BGROUND - Navigation menu image background • WEB_MENU_BGCOLOR - Background color of menu items • WEB_MENU_FGCOLOR - Foreground color of menu items • WEB_HMENU_BGCOLOR - Highlighted background color of menu items • WEB_HMENU_FGCOLOR - Highlighted foreground color of menu items

Note: For a listing of values to use for these macros, access the following website:

http://www.lynda.com/hexh.html

3. Make the appropriate changes, save and install the new changes. % make cii F=<the checked out file>


Final Installation Steps

Introduction To complete the installation of your webserver, you must:

• Set up the ODBC services • Determine port numbers

Setting Up the ODBC (cisinf and cisaps) Services Jenzabar recommends all customers use the same port numbers for the ODBC back-end services. Use the following script to define port numbers. If the numbers 9050, 9051, 9055, and 9056 are available, the system will use them. If they are not available, the script will search for other groups of available ports. Ports 9054 and 9059 should be reserved for remote support from Jenzabar, in accordance with its firewall configuration.

Note: In the setup_odbc command below, the webadmin parameter is used to allow anonymous authentication to the ODBC back-end from a perl cgi script running on a separate machine from Jenzabar CX. You do not need to use the webadmin parameter if your webserver will be residing on the same box as Jenzabar CX.

% rehash % SU setup_odbc webadmin |& tee setup_odbc.Out Password for user:

Note: If you have multiple databases, you must execute the setdb command and reissue the setup_odbc script, as follows:

% setdb train1 % SU setup_odbc webadmin |& tee setup_odbc..traini.Out

The setup_odbc script edits the /etc/services and /etc/inetd.conf files (saving original copies of the files), and restarts the inetd process in order to add the Jenzabar CX database and app server services to the system. It will also setup the modules file in /opt/cisodbc/$CARSV to provide access to app servers.

Determining the Port Numbers of the New Services Port numbers reside in the /etc/services file. To identify the port numbers for the new services, use the following command:

% grep '^cis' /etc/services Record the following port numbers that will be needed to configure the ODBC driver running on the PC. Note that SYSID is typically 'carsi'.


Installing Apache Webserver Software

Overview The webserver installation process relies on the setup_apache script to extract the Apache product source code from $CARSPATH/software/apache into the /opt/apache/ (or WEB_TEST_INSTPATH) directory. This setup script:

• Executes the configuration script • Builds the code with make • Performs a make install • Installs the $CARSPATH/web/etc directory that holds the configuration files for Apache • Starts the Apache webserver

Before you run the script, review the definitions of the macros contained in $CARSPATH/macros/custom/web. That file maintains the Web addresses the script will use to store the elements of the Apache webserver.

To use the script, enter the following commands:

% cd $CARSPATH/smo/12294a-ip % rehash % SU csh Password for user: # $CISPATH/setup_apache >& setup_apache.Out (See note below) # exit

Notes:

• The output in the setup_apache.out file will be large. You need not check this file if the webserver is started successfully.

• You can execute either of the following two scripts. Select the script that matches your requirements.

• setup_apache script (as shown in the above example)

• setup_apache+mod_perl (to extract the appropriate Apache & mod_perl source code)

• setup_apache+perl+ssl (to extract the appropriate Apache & mod_perl & mod_ssl source code)

• setup_apache_standalone (to extract the appropriate Apache only)

Verifying the Webserver Has Started To verify that the webserver has been started, enter the following command:

% ps -ef | grep webadmin The system will confirm that some /opt/apache/sbin/httpd processes are running. You can verify their presence with the following command:

% ps -ef | grep httpd Using the following tail command on the error_log file will also confirm that the server has started.

% tail /opt/apache/var/log/error_log One of the last lines of the error log will contain the following:

“….. resuming normal operations”


Note: The system may generate a message referencing carsdevi/betai, similar to the following. This warning is harmless at this phase of the installation process.

"Warning: DocumentRoot [/opt/Apache/carsdevi7-live/share/htdocs/] does not exist"


Directory Structure of the Apache Webserver

Introduction The setup_apache script creates the following file structure. Note that names enclosed in parentheses ( ) are files, while names without parentheses are directories.

This structure serves as the install path for the Apache webserver.

The macros (in $CARSPATH/macros/custom/web) that define the root path as /opt/apache are: • WEB_TEST_SERVER_INSTPATH • WEB_TEST_SERVER_ROOTPATH • WEB_LIVE_SERVER_INSTPATH • WEB_LIVE_SERVER_ROOTPATH

Accessing Data Using the Webserver To access data using the webserver, open your browser, enter the URL for your website, and then execute the search for the site. This informs the httpd daemon (the server on your system) that someone has requested contact with your website. The Apache server takes over and begins to communicate with the browser.

From the installed /opt/apache/etc/srm.conf file, the following line indicates the directory that contains file information. The source for srm.conf is located in $CARSPATH/web/etc.

DocumentRoot WEB_SERVER_ROOTPATH/share/htdocs

Also from the srm.conf file, the following line contains the name of the desired file, under the assumption the browser will display an HTML file on the screen. In this example, the information in DirectoryIndex is telling the server to pass a file called index.htm or index.html to the browser.

# DirectoryIndex: Name of the file or files to use as a pre-written HTML # directory index. Separate multiple entries with spaces. DirectoryIndex index.htm index.html

If the DocumentRoot and DirectoryIndex are defined, the process will continue. If they are not defined, you must enter the port address on the http: line of the browser (e.g., http://carseduc:9040/). The port address is the location the httpd daemon monitors to determine if any activity present exists.

The port addresses are defined in the installed version of httpd.conf located in /opt/apache/etc. The source file is located in $CARSPATH/web/etc. Use the make processor to maintain both the srm.conf and http.conf files.

Apache Install Path Directory Structure

(dbmanage)(htdigest)(htpasswd)

bin

(access.conf)(httpd.conf)(mime.types)(srm.conf)

etc

c-code includestatements

include

Various manpages

man

(httpd)(apachectl)

sbin

htdocs(index.html)

cgi-bin

common(newcis.gif)institution logo

images(background.gif)(instlogo.gif)

icons

share src

proxy run(httpd.pid)

log(access_log)(error_log)

var carsi-test carsi-live

/opt/apache


Configuration Files The files httpd.conf, srm.conf and access.conf are the configuration files. The server reads these three files for configuration directives. Any directive may appear in any of the files. The names of the files are assumed to be relative to the server root.

The server daemon is called httpd, and its location is /opt/apache/sbin/httpd.

In general, these files contain the following information:

httpd.conf Contains directive that control the operation of the server daemon.

srm.conf Contains directives that control the specification of documents that the server can provide to clients.

access.conf Contains directives that control access to documents.

The webserver currently appends the three files when it is started.

For more information about the directives in the three files, see Apache Core Features on the Apache website at http://www.apache.org/docs/mod/core.html.


Completing the Installation Process

Verifying Permissions and Installing Files You must install the files not requiring root privileges, after ensuring that permissions are correct on the ODBC backend directory.

To reinstall the files, use the following commands:

% fileperms -u /opt/cisodbc/$CARSV % make smoreinstall >& Install.Out % cd $CARSPATH/modules % make T=reinstall S=cgi F=ALL > make.out (for the TEST WEBSERVER) % make T=reinstall S=cgi F=ALL WEBSERVER=LIVE > makel.out (for the LIVE WEBSERVER) % cd $CARSPATH/web % make T=reinstall S=cgi F=ALL > make.out (for the TEST WEBSERVER) % make T=reinstall S=cgi F=ALL WEBSERVER=LIVE > makel.out (for the LIVE WEBSERVER)

Note: Make sure you resolve any errors in the Install.Out file before continuing. You can ignore compile warning messages containing the following text:

• "Runtime error is possible..."

• "Current declaration of..."

• "/* detected in comment..."

• "Optdriver: Exceeding compiler..."

You must also install the files not requiring root privileges, using the following commands: % cd $CARSPATH/smo/12294a-ip % make smoreinstall Revtr=RevtrWEB >& InstallWEB.Out

Note: If you are also running the live webserver on the Jenzabar CX computer, enter the following commands:

% cd $CARSPATH/smo/12294a-ip % make smoreinstall Revtr=RevtrWEB WEBSERVER=LIVE \ >& InstallWEBLIVE.Out

Resolve any errors in the InstallWEB.Out file before continuing.


New

As of SMO 12686, the perl scripts in the:qqq

• web/cgi/student/… e.g. web/cgi/student/finaid

• web/cgi/faculty/… e.g. web/cgi/faculty/stuadv/finaid

directories, will reference the perl modules in:

• modules/common/lib

• modules/regist/lib

• modules/finaid/lib

Note: Anthony will this work? So, in addition to the reinstall step above:

% cd $CARSPATH/modules % make T=reinstall S=pm F=ALL >> make.out (for the TEST WEBSERVER) % make T=reinstall S=pm F=ALL WEBSERVER=LIVE >> makel.out (for the LIVE make


Web Authentication

Authenticating Students The Apache webserver can authenticate any user wanting to use the Web products. The Faculty/Student Directory and Registration require some form of authentication to use the products. The use of a Personal Identification Number (PIN), similar to those used for ATM access, is used to authenticate a user. The PIN numbers are stored in the profile_rec.password table.column name.

Creating PIN Numbers Two menu items exist on the Jenzabar CX menu to create PIN numbers: Set PIN Number - Admitted and Set PIN Number - Registered. Both menu options reside under the Student Management/Registrar/Registration/Web Maintenance menu path.

The PIN numbers consist of the birth month and the last two digits of the year of birth. The SQL scripts that create the PINs, setpinadm and setpinreg, exist under $CARSPATH/modules/regist/informers. You can use these scripts as a pattern if you want to use a different algorithm to produce the PIN value.

Note: Creating the PIN in the database does not automatically make it available to the Apache webserver. The webserver requires its own dbm files to authenticate the user.

The students authenticate with their student ID numbers as the username and their PINs as their passwords.

Setting Up the Authentication File for Student Access You must also set up the authentication file for student access to Apache Test server. The following setup_web_dbm command generates the DBM file used by Apache for webserver authentication for students. In order for students to be activated for webserver access, they must have a pin# stored in the profile_rec.password column and an entry in the prog_enr_rec. By default, students authenticate with their student ID numbers as their usernames and their personal identification numbers (pin numbers) from profile_rec.password as their passwords.

The student password file is generated using the following select statement: select profile_rec.id user_name, password, profile_rec.id id_no, fullname from profile_rec, id_rec where profile_rec.id = id_rec.id and profile_rec.password is not null and profile_rec.password != " ") and (profile_rec.id in (select id from prog_enr_rec) or profile_rec.id in (select id from adm_rec))

Before executing the following command, set up at least one test student to have a PIN number. Student ID: _________ Pin#: _________

% rehash - make sure setup_web_dbm is found % SU csh Password for user: # setup_web_dbm student (Note: To set up LIVE DBM files, append “LIVE” at the end of this command) # exit

Setting Up the Authentication File for Faculty Access You must generate the DBM file used by Apache for webserver authentication using the setup_web_dbm command. In order for faculty members to be activated for webserver access,


they must have a PIN number stored in the profile_rec.password column and an entry in the userid_table. Faculty members authenticate with their usernames as they appear in the userid_table.user_name column. The password used is specified in the profile_rec.password column.

The following setup_web_dbm command generates the DBM file: % SU csh Password for user: # setup_web_dbm faculty (Note: To set up LIVE DBM files, append “LIVE” at the end of this command) # exit

The faculty password file is generated using the following select statement: select user_name, password, id_no, fullname from userid_table, profile_rec, id_rec where userid_table.id_no = profile_rec.id and userid_table.id_no = id_rec.id and (user_name is not null and user_name != " ") and (userid_table.id_no is not null and userid_table.id_no > 0) and (profile_rec.password is not null and profile_rec.password != " ")

Note: If you are also running the live webserver on the Jenzabar CX computer, then you must use the following command:

% SU csh Password for user: # setup_web_dbm faculty LIVE # exit

Authenticating Faculty Users When faculty members log in to the webserver, they enter their login name or e-mail name, as well as the PIN that has been assigned and resides in profile_rec.password column in the database.

This login window cannot be changed with the exception of the Realm phrase that is defined in the $CARSPATH/web/etc/access.conf file. The following lines define the phrase.

<Directory WEB_SERVER_ROOTPATH/CARS_V-test/share/cgi-bin/faculty> AllowOverride None Options None AuthType Basic AuthName "Faculty Access"

Regenerating the Authentication File The setup_web_dbm command enables you to regenerate either the student or faculty authentication file in a single command. This command regenerates the whole faculty or student authentication file based on the SQL statements within the scripts.

The easiest way to maintain which students are selected would be to control which students have PIN numbers specified in the profile_rec table. If you want to alter the selection process, the source location of the setup_web_dbm is:

$CARSPATH/modules/cisc/commands/setup_web_dbm Execution is one of the following for faculty:

% SU setup_web_dbm faculty % SU setup_web_dbm faculty LIVE

Or one of the following for students:

% SU setup_web_dbm student


% SU setup_web_dbm student LIVE


Verifying Your Installation

Introduction Verifying your installation ensures the webserver will function as expected in a production environment. Verification includes:

• Determining the port number of the webserver • Verifying access to the first page of the webserver • Verifying Student authentication setup

TEST and LIVE Servers in the Verification Process The following verification steps assume that the TEST server was installed on the Jenzabar CX computer. If the LIVE server was also installed on the Jenzabar CX computer, then these steps should be repeated using LIVE in place of TEST.

Determining the Port Number of the Webserver By default, the webserver is installed using a non-standard port. You need to know the port number to gain access to the server. To determine the port numbers, use the following command:

% grep 'PORT' $`M4PATH'/custom/web.m4 Record the Port specified: TEST: ______ LIVE:_______

Verifying Access to the First Page of the Webserver Verify access to the webserver as follows:

1. Start your Web browser.

2. Specify URL of http://hostname:PORT/. The result should be a page with options of Faculty, Student, and Admissions Application. If the page does not display:

• Re-check that server is running.

• Consider network connectivity issues (e.g., firewall or proxy server).

• Check errors_log file for errors.

Verifying Student Authentication Setup To complete verification, you must determine the server works correctly with a valid student ID and pin number. To verify your setup of student authentication:

1. Obtain the test student id and pin: Student ID# __________ PIN# _________

2. Select Student Link. You should get an Authentication Dialog Box. This indicates that the webserver was properly configured to protect the student area. If you do not get an Authentication Dialog, then a problem exists with the configuration files for the Apache server. Recheck local modifications in $CARSPATH/web/etc, then reinstall the files in web/etc, and then restart the webserver.

3. Enter the student# and pin# for the username/password. A student menu should display, indicating:

• The student authentication file was set up as expected

• You have entered a valid student and PIN

• The cgi script was executable and had access to the database as needed.


A. If the username/password dialog reappears, then:

• Verify that the student dbm file exists by using the command % ll /opt/Apache/carsi-test/var/authdb/. If the student dbm file does not exist, repeat the setup_web_dbm student step.

• Verify that the student ID is in the file.

% cd /opt/Apache/carsi-test/var/authdb % dbmmanage student view <student_id#>

If the student ID is not in the file, revisit the setup_web_dbm student step with special attention on the select statement used to determine who will be in the student selection.

B.If an error page is displayed, then you probably have passed the authentication step and are having a problem with executing the cgi script. Do the following:

• Check the error_log file.

• Attempt to run the following perl2db tests.

• perl2db DATABASE id_rec • perl2db SQLAPS guid_aps • As webadmin, run perl2db DATABASE id_rec • As webadmin, run perl2db SQLAPS guid_aps

Some typical problems are:

1) webadmin does not have execute permissions on perl. 2) Need to copy Plibdata.pm and Plibdata.s? from $LIBPATH to: /opt/Apache/CARSV-{test,live}/share/cgi-bin/lib

4. Try the different student options.

5. Perform similar testing strategies for the faculty access.


Errors and Troubleshooting During Webserver Setup

Introduction This section provides information about correcting problems when setting up your institution's webserver.

Permission denied The execution of setup_web_dbm may generate an error similar to: "/usr/carsi/install/cis/setup_web_dbm: Permission denied."

If so, you must verify that permissions on the file are correct using fileperms. Also verify that the perl program permissions are set correctly. The command head -1 $CISPATH/setup_web_dbm will list the path of the perl executable that it is attempting to use.

SQLAuthenticateAny() - Guest login not permitted This message indicates that the odbc set-up was not done allowing webadmin to be a guest user. Execute the following command: setup_odbc -n webadmin

Path does not exist The execution of setup_web_dbm may generate an error similar to: "Path to authentication dbm file (...) does not exist." If so, you must verify the path is correct. It should be similar to /opt/Apache/carsi-test/var/authdb if no changes were made to the Web macros. If it appears correct, then execute mkdirs on the missing directories followed by fileperms -u dirname.

Example: % mkdir /opt/Apache/carsdevi7-test/var % fileperms -u /opt/Apache/carsdevi7-test/var

Can't locate object method "TIEHASH" The execution of setup_web_dbm may generate an error similar to: "Can't locate object method "TIEHASH" via package..."

If so, then the perl program may need re-compiled. The following commands should correct the problem:

% cd /opt/perl5/src/perl5.003 % rm -f config.sh % sh Configure -d % make % make test % make install Note: If you are also running the live webserver on the Jenzabar CX computer, then you must also use the following commands:

% SU csh Password for user: # setup_web_dbm student LIVE # exit

CX Webserver 31 Dual Servers

APPENDIX - SETTING UP A DUAL WEBSERVER

Issues

Introduction This section provides information to help you set up dual webservers at your institution. The use of two webservers improves both security and response time.

Setup issues include: • Machine configuration • Macros

CAUTION: Information contained in this section is provided to assist you in your dual webserver setup. However, since all Jenzabar CX installations are unique, this section is not intended to be a comprehensive guide for all the issues that can arise in the setup process. If you encounter difficulties in completing your dual webserver setup, contact Jenzabar consulting for assistance.

Configuration Requirements for IBM Systems The instructions in this section assume the following configuration for IBM systems:

For the webserver:

• Apache webserver

• AIX 4.3

Configuration Requirements for HP Systems The instructions in this section assume the following configuration for HP systems:

For the webserver:

• Apache webserver

• HPUX 11.00

Macro Setup for Dual Webservers Jenzabar CX recognizes when your institution is running a separate webserver machine by comparing the macro value for WEB_EDVANTA_HOSTNAME against either of the following:

• WEB_LIVE_SERVER_HOSTNAME

• WEB_TEST_SERVER_HOSTNAME

As delivered, all these macros have the value "MAK_HOSTNAME", an m4 macro that expands to the command uname -n. This command returns the name of the server on which the uname command executes. Therefore, all the Web macros are initially set to point to the same hostname, that of the database server.

If the value of WEB_EDVANTA_HOSTNAME is different from either of the webserver hostname macros, then the Jenzabar CX product assumes that you are running a separate webserver, and other macros appropriate to a dual server environment are included and expanded during make installs of the Jenzabar CX Web modules. CX uses the values of these macros in several areas.

Macro Locations The three macros are located in $CARSPATH/macros/custom/web.

Dual Servers 32 CX Webserver

Installing Web Modules

Source Code Location In a dual server configuration, Web module source code (e.g., code for cgi scripts) is stored and maintained in the $CARSPATH on your database server, as is your other source code (ACE reports, PERFORM screens, etc.). The make processor uses the comparison between WEB_EDVANTA_HOSTNAME and WEB_LIVE (or _TEST) _SERVER_HOSTNAME to determine whether to install a Web-oriented file to the remote webserver when you perform a make install with WEBSERVER=LIVE. In Jenzabar's partial implementation, the make processor was set up to use either ftp or rsh to copy the translated source file to the install target directory on the remote webserver. For more information about using either of these protocol methods, see Modifying make on the Database Server in this guide.

Database Access

The Jenzabar Web product uses the Jenzabar CX ODBC driver to connect to the database. The file $CARSPATH/web/cgi/lib/services defines the connections, using either named pipes (for local access) or tcp sockets (for remote database access). When the services file is installed using make, the WEB_SERVER_HOSTNAME (derived from WEB_LIVE/TEST_SERVER_HOSTNAME) and WEB_EDVANTA_HOSTNAME macros are compared to see if their values are identical. If so, then services are set up for local access. If not, then services are set up for remote access. More specifically, if these two macros are different (indicating that a separate webserver is in use), the services file defines the 'DATABASE' macro as 'DATABASE_SOCKET' (also 'SQLAPS' as 'SQLAPS_SOCKET'), providing access via tcp sockets. These latter macros, in turn, are used by the WEB_CGI_START macro (defined in $CARSPATH/macros/user/web) to allow any installed cgi scripts that include it to make a connection to the database or to app servers on a separate database server computer. In this way, Jenzabar Web product cgi scripts running on a remote webserver can connect to the database server computer to retrieve and return data.Web User Authentication

The files used by Apache to authenticate Web users in the Jenzabar Web product (located in /opt/apache/$CARSV/var/authdb) are created by the setup_web_dbm Perl script (source: $CARSPATH/modules/cisc/commands/setup_web_dbm). This script pulls Web usernames and passwords from the Jenzabar CX database and stores them on the webserver machine's file system in dbm hash files. The setup_web_dbm script uses a call to the cis_opendb(DATABASE) function to connect to the database server. On a dual server configuration, the file $CARSPATH/Web/cgi/lib/services interprets 'DATABASE' to mean 'DATABASE_SOCKET', giving the script access to a separate database server. Therefore, when you run setup_web_dbm on the remote webserver, the cgi script queries the database server for username and password information, then it builds the dbm hash files on the webserver.

Security Issues You can place your database server behind a packet filtering router to prevent all access from off campus to that server. For example, you may choose to have your webserver accessible to anyone for Web traffic, but protected from unauthorized access via telnet, ftp, and rsh by tcp wrappers. To maintain security, you can configure tcp wrappers to send a mail message (including the remote host's finger information if available) when an unauthorized host attempts to use a protected service. You may also want to remove most user accounts from the webserver and disabled unneeded services which might be vulnerable to unauthorized users.

Finally, in cases where Jenzabar CX code requires you to execute a program remotely on the database server (see Web grade entry ), you can use a secure shell (ssh) and host-based authentication between the Web and database servers.


Implementation Issues

Before You Begin Before you implement the remote webserver, you should add a user account for webadmin to the remote file server. By creating the account first, files and directories which currently are owned by webadmin on the database server will retain that ownership when they are copied to the remote webserver. Use the same group memberships, etc., as the webadmin account you created on your database server, then log in once as webadmin to set a permanent password.

Recreating $CARSPATH and Other Directory Paths on the Webserver What to replicate Replicate the entire $CARSPATH on the webserver, except for files and directories specific to running Informix. This includes the Apache server, Perl, CX ODBC driver, and developer home directories. The following files are replicated:

$CARSPATH/install/cis Needed for Jenzabar CX print queue aliases and other executables.

$CARSPATH/install/utl Needed for fileperms and timecmp commands, setup_web_dbm, and other executables.

$CARSPATH/install/sys Needed for fileperms table. Also contains Jenzabar CX proptions, printcap, and termcap/terminfo databases, which should be maintained until the impact of their deletion can be determined. These directories include:

$CARSPATH/install/mak

$CARSPATH/install/lib

$CARSPATH/install/inc

$CARSPATH/install/m4

$CARSPATH/macros

$CARSPATH/include $CARSPATH/system

This replication is required only if the prescribed changes to Make are not done. For more information about changing the Make processor, see Modifying Make on the Database Server in this document.

/opt/apache /opt/perl56 /opt/cisodbc home/carsids

You must copy these directories to the webserver.

$CARSPATH/install/utl If you intend to use Jenzabar CX print utilities to print from the webserver computer, this directory is required since it contains CX print queue executables (e.g., dplpr) and print queue filters.

$CARSPATH/spool/<spoolername>


Replicate only the queues you want to keep.

Copying Directories Between Servers Before you can copy directories, you must have full read privileges on the database server and full read/write privileges on the webserver (i.e., you must be root on both machines). To copy directories from one server to the other:

1. Log in to the database server as root.

2. Use tar and either rsh (for AIX) or remsh (for HPUX) to copy directories to the webserver.

Note: If you are running secure shell, you can use ssh instead of either rsh (for AIX) or remsh (for HPUX).

3. Manually ftp the installed fileperms table from the database server to the webserver and set its permissions appropriately. This is a manual task because the tar command string does not overwrite read-only files.

4. Temporarily add a .rhosts file to root's home directory on the webserver so that root can log in to the webserver computer using rsh. For more information about the requirements for the .rhosts file, see man rsh or man remsh. Ensure that .rhosts is chmod 600 for security.

5. Use the following syntax for copying data from the database server (local computer) to the webserver (remote computer):

For AIX: # cd /source/dir # tar cf - . | rsh Web-host-name 'cd /target/dir; tar xBf -' For HPUX: # cd /source/dir # tar cf - . | remsh Web-host-name 'cd /target/dir; tar xBf -' Where /source/dir is the directory on the database server from which you want to copy, Web-host-name is the hostname or IP address of the webserver, and target/dir is the directory on the webserver to which you want to copy. Example: Assume you want to create a subdirectory /opt/Apache on a webserver whose hostname is "carsweb". On the database server, as root or SU, enter these commands: # cd /opt/apache # tar cf - . | rsh carsweb 'cd /opt/Apache; tar xBf -' The tar command causes the target files to have the same file permissions and ownership as the source files, which is the desired outcome. For HPUX from a remote box: # cd /target/dir # remsh sourcehost “cd /source/dir; find. –print | cpio –oc” | cpio -icdamx

CAUTION: Be sure to remove the .rhosts file from root's home directory on the webserver when you are done.

After you replicate directories on the webserver, use ftp to manually transfer $CARSPATH/install/sys/lib/fileperms (the installed fileperms table) from the database server to the webserver, then set its mode and ownership appropriately. Although you can also complete this step for the fileperms table source file as well and then reinstall it while logged into the webserver, Jenzabar recommends you do not maintain code on the webserver.


Other Replication Issues You must edit /etc/services on the database server to include the following lines relevant to cisodbc, and also add other lines relevant to http operation and diagnostics. The contents of your institution's /etc/services directory will differ from this example.

diaghttp_port 3997/tcp diagdctrl_port 3998/tcp diagtask_port 3999/tcp dtspc 6112/tcp cisinf5 9030/tcp # For the Jenzabar CX ODBC Driver cisaps_carstrain 9050/tcp # CIS carstrain AppServer service cisaps_carstrain_dbg 9051/tcp # CIS carstrain Debug AppServer cisinf_carstrain 9055/tcp # CIS carstrain Database service cisinf_carstrain_dbg 9056/tcp # CIS carstrain Debug Database cisaps_carsi 9060/tcp # CIS carsi AppServer service cisaps_carsi_dbg 9061/tcp # CIS carsi Debug AppServer service cisinf_carsi 9065/tcp # CIS carsi Database service cisinf_carsi_dbg 9066/tcp # CIS carsi Debug Database service

You must edit /etc/inetd.conf on the database server to include the following lines relevant to cisodbc. Then, refresh inetd with the command refresh -s inetd (HP/UX users will have to send a SIGHUP to the inetd process.). Note that each line ending in a backslash was concatenated to the line following it. Your institution's values will differ from this example.

cisaps_carstrain stream tcp nowait root \ /opt/cisodbc/carstrain/cisaps.env cisaps.env

cisaps_carstrain_dbg stream tcp nowait root \ /opt/cisodbc/carstrain/cisaps.env.dbg cisaps.env.dbg

cisinf_carstrain stream tcp nowait root \ /opt/cisodbc/carstrain/cisinf.env cisinf.env

cisinf_carstrain_dbg stream tcp nowait root \ /opt/cisodbc/carstrain/cisinf.env.dbg cisinf.env.dbg

cisaps_carsi stream tcp nowait root \ /opt/cisodbc/carsi/cisaps.env cisaps.env

cisaps_carsi_dbg stream tcp nowait root \ /opt/cisodbc/carsi/cisaps.env.dbg cisaps.env.dbg

cisinf_carsi stream tcp nowait root \ /opt/cisodbc/carsi/cisinf.env cisinf.env

cisinf_carsi_dbg stream tcp nowait root \ /opt/cisodbc/carsi/cisinf.env.dbg cisinf.env.dbg

cisinf5 stream tcp nowait root /bin/env env \ CARSPATH=/opt/carsi CARSDB=cars INFORMIXDIR=/opt/informix \ ONCONFIG=onconf.cars INFORMIXSERVER=rs6k /opt/cisodbc/bin/cisinf5


Modifying make on the Database Server

Introduction When installing Web modules on a dual server configuration, the objectives are to enable a user to use a make install target (e.g., make cii, make tinstall, make reinstall, or make smoreinstall) with WEBSERVER=LIVE on the database server, have the translated file copied to the appropriate install path on the remote webserver, and then run fileperms on the remote webserver to set permissions on the installed module. Two methods for accomplishing this are detailed below, one using ftp and rsh (remote shell), the other using ssh (secure shell). Most of the infrastructure needed to do this is already in the CX make processor implementation. The remote install code is triggered during a make only if the WEB_EDVANTA_HOSTNAME and WEB_LIVE/TEST_SERVER_HOSTNAME are different and (assuming that the remote server is your live webserver) only if you specify WEBSERVER=LIVE on the make command line.

Modifying make on the Database Server Using the ftp/rsh Method (for AIX) or the ftp/remsh Method (for HPUX)

Note: After you make the changes described in the following sections, when you make install WEBSERVER=LIVE you will be prompted for webadmin's password for each subdirectory whose contents you are installing. Also note that you cannot redirect make output to a file when using this modification with WEBSERVER=LIVE because you cannot see the password prompt and the install process will stay in a wait state indefinitely waiting for your input. This is particularly an issue when you are trying to do smoreinstalls.

Changes to $CARSPATH/system/Make/user/Cmdscripts/install Modify this file so the make processor will do the following when you issue a make install WEBSERVER=LIVE target from the database server:

• Prompt you to enter webadmin's webserver password. • Create a .netrc file on-the-fly in your database server home directory so that multiple

files can be ftp'd to the webserver. (Any existing .netrc file is backed up.) • Remove the .netrc file from your home directory and restore any backed up .netrc.

The source code changes for this file are shown in the following diff output. RCS file: RCS/install,v retrieving revision 8.2 diff -r8.2 install 136a137,202 > #------------------------------------------------------------------------+ > # Begin Local: | > # Changes to facilitate remote installation of Jenzabar CX Web files. | > # . | > # If the $Instdir contains a host prefix and the host is not the same as | > # the localhost, then assume that we'll have to ftp files to a remote | > # host. Under this assumption, prompt here for a password for webadmin | > # and use it to create a .netrc file in the installer's home directory. | > # This is so that the programmer only has to enter a password once | > # instead of for each installed file when F=ALL. The .netrc file should | > # be deleted after the install is complete. | > # . | > # Note: Some of this code borrowed from $CARSPATH/system/Make/user/Make\ | > # cinstall. | > #------------------------------------------------------------------------+ > #---------------------------------------------------------+ > # If installing on a remote system (hostname:pathname)... | > #---------------------------------------------------------+ > if ("$Instdir" =~ *:*) then > set owner = "webadmin" > set hostname = `echo $Instdir | tr : ' '` > set hostname = $hostname[1]


> set echo_c = "/usr/bin/echo" > onintr fixecho > stty -echo > #--------------+ > # Get password | > #--------------+ > $echo_c "Password for (${hostname}:${owner}):\c" > set PASSWD = "$<" > stty echo > onintr > $echo_c "" > if ("PASSWD" == "") then > $echo_c "Install cancelled\c" > exit 1 > endif > #--------------------------+ > # Create local .netrc file | > #--------------------------+ > if ("`groups $user`" !~ *carsctrl*) then > $echo_c "Only carsctrl group can remote install - Install cancelled\c" > exit 1 > endif > onintr fixnetrc > if (-e ~/.netrc) then # Backup existing .netrc if any > mv ~/.netrc ~/.netrc.save.$$ > endif > echo "machine $hostname login $owner password $PASSWD" > ~/.netrc > chmod 600 ~/.netrc > if ($status != 0) then > $echo_c "Error setting mode of .netrc - Install cancelled\c" > exit 1 > endif > #------------------+ > # Check for errors | > #------------------+ > if (! -e ~/.netrc) then > $echo_c " Error creating .netrc - Install cancelled\c" > exit 1 > endif > endif > #---------------+ > # End Local | > #---------------+ > 260a327,343 > #--------------------------------------------------------------------+ > # Begin Local: | > # Remove any on-the-fly .netrc that may have been created above and | > # restore any pre-existing .netrc to the installer's home directory. | > #--------------------------------------------------------------------+ > if ("$Instdir" =~ *:*) then > if (-e ~/.netrc.save.$$) then > mv ~/.netrc.save.$$ ~/.netrc > else if (-e ~/.netrc) then > rm -f ~/.netrc > endif > endif > onintr > #---------------+ > # End Local | > #---------------+ > 272a356,378 > > #---------------------------------+ > # Begin Local: Error checking | > #---------------------------------+ > fixecho: > #------------------------------------------------------------------+ > # Restore normal echo function onintr from password prompt, above. | > # Borrowed from $CARSPATH/system/Make/user/Make/cinstall. | > #------------------------------------------------------------------+ > stty echo > exit 0 >


> fixnetrc: > #---------------------------------------------------------+ > # Restore backed up .netrc file (if there is one) onintr. | > #---------------------------------------------------------+ > if ("$Instdir" =~ *:*) then > if (-e ~/.netrc.save.$$) mv ~/.netrc.save.$$ ~/.netrc > endif > exit 0 > #---------------+ > # End Local | > #---------------+

Changes to $CARSPATH/system/Make/user/Make/cinstall CAUTION: The file named above is not under revision control. Before you make any changes to it, be careful to back it up to a reliable medium.

The cinstall script is called by $CARSPATH/system/Make/user/Cmdscripts/install for each file that is being installed. Modify this file so that it will automatically do the following if installing to a remote webserver:

• Build an on-the-fly ftp script for transferring the file. • Run ftp using the script as input. • Run remote shell (rsh) to remotely set fileperms on the newly installed file.

Note that in order for your Web developers to be able to run rsh from your database server, they must each have a .rhosts file in their home directories on the webserver. The file should at a minimum contain a single line similar to the the following (substitute values appropriate for your institution):

your-dbserver-hostname your-user-name

The .rhosts file should be set chmod 600. See man rsh for more information about .rhosts.

The source code changes made to this file are shown in the following diff output. diff cinstall.orig cinstall.new 96,110c96,143 < # Get FTP user < if (! $?owner) then < set askown < set owner="" < if ($?USER) set owner="$USER" < echo " - Name (${hostname}:${owner}):\c" < set new_owner="$<" < if ("$new_owner" != "") then < set owner="$new_owner" < endif < if ("$owner" == "") then < echo " Install cancelled\c" < exit 1 < endif < endif --- > #-------------------------------------------------------------------+ > # Begin Local: | > # Use /usr/bin/echo instead of shell echo to accomodate \c syntax. | > # This also means using a variable instead of echo in the following | > # lines where a \c comes at the end of the echo'd string. | > #-------------------------------------------------------------------+ > set echo_c="/usr/bin/echo" > #------------------------------------------------------------------+ > # Comment out the owner and password request sections to | > # accomodate use of .netrc to automate ftp transfers. Using .netrc | > # makes it unneccessary to enter the webadmin password umpteen | > # times when installing F=ALL to WEBSERVER=LIVE. | > #------------------------------------------------------------------+ > #------------------------------------------------------------+ > # # Get FTP user | > # if (! $?owner) then | > # set askown |


> # set owner="" | > # if ($?USER) set owner="$USER" | > # $echo_c " - Name (${hostname}:${owner}):\c" | > # set new_owner="$<" | > # if ("$new_owner" != "") then | > # set owner="$new_owner" | > # endif | > # if ("$owner" == "") then | > # $echo_c " Install cancelled\c" | > # exit 1 | > # endif | > # endif | > # | > # # Get FTP password | > # if (! $?PASSWD || $?askown) then | > # onintr fixecho | > # stty -echo | > # if (! $?askown) $echo_c " - \c" | > # $echo_c "Password for (${hostname}:$owner):\c" | > # set PASSWD="$<" | > # stty echo | > # onintr | > # if ("$PASSWD" == "") then | > # $echo_c " Install cancelled\c" | > # exit 1 | > # endif | > # endif | > #------------------------------------------------------------+ > #---------------+ > # End Local | > #---------------+ 112,126d144 < # Get FTP password < if (! $?PASSWD || $?askown) then < onintr fixecho < stty -echo < if (! $?askown) echo " - \c" < echo "Password for (${hostname}:$owner):\c" < set PASSWD="$<" < stty echo < onintr < if ("$PASSWD" == "") then < echo " Install cancelled\c" < exit 1 < endif < endif < 145c163,174 < echo "user $owner $PASSWD" | cat - $ftpin | ftp -v -n $hostname >& $ftpout --- > # echo "user $owner $PASSWD" | cat - $ftpin | ftp -v -n $hostname >& $ftpout > #-----------------------------------------------------------------+ > # Begin Local: | > # Changed the above ftp command to accomodate automated ftp via | > # .netrc. Specifically, removed the 'user' command, removed '-' | > # from the cat command to prevent reading from stdin, and removed | > # the '-n' parameter from ftp. | > #-----------------------------------------------------------------+ > cat $ftpin | ftp -v $hostname >& $ftpout > #---------------+ > # End Local | > #---------------+ 151c180 < echo ": install failed - see $errfile\c" --- > $echo_c ": install failed - see $errfile\c" 158a188,200 > #------------------------------------------------------------+ > # Begin Local: | > # Use remsh to set fileperms on installed file. This implies | > # that an up to date fileperms table must be kept on the | > # remote webserver and that a proper .rhosts file exists in | > # the home directory of the person doing the make install. | > #------------------------------------------------------------+ > else


> remsh $hostname -n "fileperms -u $filename" > #------------------------------+ > # Need to test for errors here | > # End Local | > #------------------------------+

Modifying make on the Database Server Using the ssh Method One advantage to using ssh instead of ftp/rsh to install files from the database server to the webserver is that ssh allows you to use host-based authentication over password authentication. With this authentication method, the ssh daemon running on the webserver checks to see whether the user on the database server has a copy of a matching key signature. The presence of that key is sufficient to allow login to occur; no password for the webserver is required. This simplifies make installs to the webserver. In particular, it allows you to use make install WEBSERVER=LIVE targets while redirecting output to a file without fear of hitting a password prompt and having the process hang while waiting for input. The key signature files must be properly set up and secured for all applicable users (the programmers) on both servers.

Installing and Running the ssh Daemon You can install and run the ssh daemon on both the webserver and the database server to resolve two issues: make installing files from the database server to the webserver, and remotely running the grdbatch program for Web grade entry on the database server (see the section on fixing problems with Web grade entry).

Use the following instructions on each server to install ssh:

1. Obtain ssh-2.2.0.tar.gz from http://commerce.ssh.com. Note that you can follow the links to apply for a (free) license for academic use before downloading the correct version.

2. Untar, ungzip, etc. the archive.

3. Complete the following preliminary steps before compiling the program:

• Compile tcp wrappers support into ssh. This enables you to control who can connect to the daemon by making changes to /etc/hosts.allow and /etc/hosts.deny on the server. To do this, copy libwrap.a and tcpd.h from an existing copy of tcp wrappers to the server. Install libwrap.a in /usr/local/lib and copy tcpd.h to the include directory in the ssh source directory. If you do not have tcp wrappers but want this functionality in sshd, you must download and compile tcp wrappers first to obtain the libwrap.a and tcpd.h files.

• Add /usr/lpp/X11/bin (AIX) or /usr/bin/X11 (HP) to your $PATH variable so the configure script can find the xauth binary. Your xauth may be stored in a different location on your system, so check verify the location first.

• Setenv CFLAGS to "-DSSH_ALLOW_CPLUSPLUS_KEYWORDS" so the configure script can create the Makefile properly.

4. Configure the makefile in the source directory, build the program, and install it using the following commands:

% cd ssh-2.2.0 % ./configure --with-libwrap=/usr/local/lib/libwrap.a % make >& make.out & % SU tcsh Password for <your login name>: # make install

Note: Binaries are installed in /usr/local/bin and /usr/local/sbin. Configuration files are installed in /etc/ssh2 and man pages in /usr/local/man.

5. To start sshd, run the daemon as root using the following command: # /usr/local/sbin/sshd


Preliminary Steps for Configuring sshd To configure sshd, complete these preliminary steps on both servers as root:

1. Create symbolic links from /usr/local/bin/ssh* to /usr/bin. Otherwise, users without /usr/local/bin in their path (e.g., webadmin) will not be able to find the ssh binaries.

2. Add a line that runs /usr/local/sbin/sshd to /etc/rc.local (AIX) or to /sbin/init.d with links to sbin/rc2.d/S925sshd and sbin/rc1.d/K095sshd so that sshd will run automatically the next time the server is rebooted.

3. Edit /etc/ssh2/sshd2_config and set PermitRootLogin to "no". User root can still run ssh with a "command" option using public key authentication, which if useful for doing backups between hosts.

4. For improved security, change /etc/ssh2 to mode 755 and owner root:system (default was 770 and root:common). Also change all of the contents of /etc/ssh2 to owner root:system.

Note: At this point, the two servers are distinct; one is local and the other is remote. For purposes of make installing files to the webserver, the database server is the "local" machine and the webserver is the "remote" machine. If you are running grdbatch remotely, reverse those roles.

On the remote machine, do the following as root:

1. Edit /etc/ssh2/sshd2_config to add "hostbased" to the list of AllowedAuthentications.

2. Restart sshd, using one of the following commands: For AIX: # kill -HUP `cat /etc/ssh2/sshd2_22.pid` For HPUX:

ps -ef | grep sshd # <pid returned> kill -HUP pid

3. If you do not have your database server on DNS, edit /etc/hosts to add the fully formed domain name of the local machine to the appropriate line (e.g., 192.12.345.67 carsbox carsbox.myschool.edu

4. Change the mode on the home directories of all CX users who will be installing files to the webserver so the home directories are only writable by those users (change to 750 instead of 770 in our case).

5. Still on the remote machine, log in as yourself. Note: Each user who will be installing files to the webserver will need to have these steps done.

6. Create ~/.ssh2 (mode 755).

7. Do one of the following: For AIX: % cd ~/.ssh2 % mkdir knownhosts % chmod 700 knownhosts For HPUX: % cd ~/.ssh2 % mkdir hostkeys % chmod 700 hostkeys

8. Create a file ~/.shosts containing one line with the fully formed local hostname and your


username (e.g., carsbox.myschool.edu jdoe)

9. Change the mode of ~/.shosts to 0400.

10. On the local machine, while logged in as root, edit /etc/ssh2/ssh2_config to add "hostbased" to the list of AllowedAuthentications, and also to add a DefaultDomain setting that is appropriate for your institution (e.g., "myschool.edu").

11. While logged in as myself, use ftp to tranmit the /etc/ssh2/hostkey.pub file from the local computer to the remote computer as ~/.ssh2/knownhosts/carsbox.myschool.edu.ssh-dss.pub.

12. Test host-based authentication from the local machine with the following command: ssh carsbox.myschool.edu

If you are successful, you will see the message "Authentication successful." and be logged in to the remote machine as if you are running telnet but without having had to supply a password.

Note: For more information about using ssh, read the man pages or see the FAQ at http://www.onsight.com/ssh/faq/ssh-faq.html.

Changes to $CARSPATH/system/Make/user/Make/cinstall CAUTION: The file named above is not under revision control. Before you make any changes to it, be careful to back it up to a reliable medium.

You must modify this file so it contains the following changes:

• The useftp flag (at approximately line 9) is set to "N" to reflect the use of ssh instead of ftp.

• The section using rsh (at approximately lines 207-223) uses ssh instead.

• Permissions on the installed file are set by remotely executing fileperms instead of chmod, chgrp, etc.

• Revised echo syntax so that feedback from the make install process looks nicer on screen.

The source code changes made to this file are shown in the following diff output. diff cinstall.orig cinstall.new 9c9 < set useftp=Y --- > set useftp=N 96,110c96,116 < # Get FTP user < if (! $?owner) then < set askown < set owner="" < if ($?USER) set owner="$USER" < echo " - Name (${hostname}:${owner}):\c" < set new_owner="$<" < if ("$new_owner" != "") then < set owner="$new_owner" < endif < if ("$owner" == "") then < echo " Install cancelled\c" < exit 1 < endif < endif --- > #-------------------------------------------------------------+ > # Begin Local: | > # Use /bin/echo with \c syntax to make line ends look OK. | > # Note the use of $echo_c in what follows to accomodate this. | > #-------------------------------------------------------------+ > set echo_c="/usr/bin/echo"


> # Get FTP user > if (! $?owner) then > set askown > set owner="" > if ($?USER) set owner="$USER" > $echo_c " - Name (${hostname}:${owner}):\c" > set new_owner="$<" > if ("$new_owner" != "") then > set owner="$new_owner" > endif > if ("$owner" == "") then > $echo_c " Install cancelled\c" > exit 1 > endif > endif 112,125c118,134 < # Get FTP password < if (! $?PASSWD || $?askown) then < onintr fixecho < stty -echo < if (! $?askown) echo " - \c" < echo "Password for (${hostname}:$owner):\c" < set PASSWD="$<" < stty echo < onintr < if ("$PASSWD" == "") then < echo " Install cancelled\c" < exit 1 < endif < endif --- > # Get FTP password > if (! $?PASSWD || $?askown) then > onintr fixecho > stty -echo > if (! $?askown) $echo_c " - \c" > $echo_c "Password for (${hostname}:$owner):\c" > set PASSWD="$<" > stty echo > onintr > if ("$PASSWD" == "") then > $echo_c " Install cancelled\c" > exit 1 > endif > endif > #---------------+ > # End Local | > #---------------+ 146d154 < 151c159 < echo ": install failed - see $errfile\c" --- > $echo_c ": install failed - see $errfile\c" 158a167,180 > #-------------------------------------------------------------+ > # Begin Local: | > # Use ssh to set fileperms on installed file. This implies | > # that an up to date fileperms table must be kept on the | > # remote webserver and that a proper .shosts file and public | > # host key resides in the remote home directory of the person | > # doing the make install. | > #-------------------------------------------------------------+ > else > ssh $hostname -n "fileperms -u $filename" > #------------------------------+ > # Need to test for errors here | > # End Local | > #------------------------------+ 165a188,194 > #----------------------------------------------------------------+ > # Begin Local: | > # Use ssh and scp instead of rsh and rcp to install on remote | > # system. This assumes that ssh has been set up properly for the | > # person installing the file. I've commented out the old remsh |


> # code below. | > #----------------------------------------------------------------+ 167,168c196,213 < remsh $hostname -n "rm -f $filename; umask 2; mkdir -p $filename:h" < rcp $src ${hostname}:${filename} --- > #---------------------------------------------------------------------------+ > # remsh $hostname -n "rm -f $filename; umask 2; mkdir -p $filename:h" | > # rcp $src ${hostname}:${filename} | > # if ($keepsrc == N) then | > # /bin/rm -f $src | > # endif | > # if ($?group) then | > # remsh $hostname -n "chgrp $group $filename" | > # endif | > # if ($?owner && "`whoami`" == root) then | > # remsh $hostname -n "chown $owner $filename" | > # endif | > # if ($?mode) then | > # remsh $hostname -n "chmod $mode $filename" | > # endif | > #---------------------------------------------------------------------------+ > ssh -q $hostname -n "umask 2; mkdir -p $filename:h" > scp $src ${hostname}:${filename} > /dev/null 172,180c217,220 < if ($?group) then < remsh $hostname -n "chgrp $group $filename" < endif < if ($?owner && "`whoami`" == root) then < remsh $hostname -n "chown $owner $filename" < endif < if ($?mode) then < remsh $hostname -n "chmod $mode $filename" < endif --- > ssh -q $hostname -n "fileperms -u $filename" > #---------------+ > # End Local | > #---------------+

Changes to $CARSPATH/macros/user/Web Because you must supply a fully formed hostname for sshd, you must also change the WEB_LIVE_SERVER_FULLPATH macro definition so that it uses the same fully formed hostname for the LIVE webserver.

Therefore, the following change is required:

WEB_LIVE_SERVER_HOSTNAME:WEB_LIVE_SERVER_INSTPATH

to:

WEB_LIVE_SERVER_HOSTNAME.WEB_DOMAIN_NAME:WEB_LIVE_SERVER_INSTPATH

You must then reinstall files in the following make directories:

• $CARSPATH/system/Make/user/Common

• $CARSPATH/system/Make/user/cgi

• $CARSPATH/system/Make/user/htm

• $CARSPATH/system/Make/user/prog

Activating Remote Webserver Capability The remote webserver implementation is activated when the value of the macros WEB_EDVANTA_HOSTNAME and WEB_LIVE (or TEST) _SERVER_HOSTNAME are different and all dependent Jenzabar CX modules are reinstalled. Do the following on your database server to set your remote webserver machine as the LIVE CX webserver:


1. Check out $CARSPATH/macros/custom/web.

2. Change the value of WEB_LIVE_SERVER_HOSTNAME to the hostname of your remote webserver.

3. Check in and install $CARSPATH/macros/custom/web.

4. Reinstall the following files on the database server: $CARSPATH/macros/user/web $CARSPATH/system/Make/user/Common $CARSPATH/system/Make/user/cgi $CARSPATH/system/Make/user/htm $CARSPATH/system/Make/prog

5. Reinstall the Jenzabar CX modules in the following directories using WEBSERVER=LIVE on the make command line:

$CARSPATH/web $CARSPATH/modules/common/cgi/ $CARSPATH/modules/regist/cgi/ $CARSPATH/modules/finaid/cgi/ $CARSPATH/modules/admit/cgi/ plus any other cgi modules in your $CARSPATH/modules source path.

Files Requiring Special Handling

Introduction Several files require special handling for the dual servers to work correctly. They are:

$CARSPATH/Web/etc/httpd.conf $CARSPATH/Web/etc/access.conf $CARSPATH/modules/cisc/commands/setup_web_dbm $CARSPATH/system/lib/fileperms.s

Special Handling for Certain Files Pointing httpd.conf and access.conf to the Correct Webserver When you first install httpd.conf and access.conf (source: $CARSPATH/web/etc) to the live webserver, you may find that the installed files incorrectly point to the TEST webserver instead of the LIVE one. This is because the system uses a test between the WEB_LIVE/TEST_SERVER_HOSTNAME macro and the results of 'uname -n' (the macro MAK_HOSTNAME) to determine whether to include LIVE webserver configuration directives, TEST webserver directives, or both. The macros are expanded before the config file is sent to the LIVE webserver (which has a different 'uname -n'), so the macros always end up pointing to the database server box, where the TEST webserver resides.

To correct this:

1. Edit the httpd.conf and access.conf source files on the database server.

2. Replace all m4 comparisons between MAK_HOSTNAME and WEB_LIVE/TEST_SERVER_HOSTNAME with a comparison between WEB_SERVER and the string LIVE. The WEB_SERVER macro is set as needed via $CARSPATH/system/Make/user/common/var.mak when you use the WEBSERVER=LIVE directive with make, causing the macro to expand correctly to configure the LIVE server when you want LIVE, and the TEST server when you want TEST, ignoring the name of the current host (e.g., m4_keepif (WEB_SERVER, LIVE)).

3. Reinstall httpd.conf and access.conf to both webservers (LIVE and TEST) and stop and start Apache (a restart will not work).


Note: This procedure only works for as long as you want the TEST and LIVE servers on separate computers. If you want them on the same computer, you must reverse these changes.

Setting Fileperms of Apache config Files When you first attempt to reinstall httpd.conf and access.conf, you may encounter an error (source: $CARSPATH/web/etc) to the remote webserver. The Fileperms table gives these files owner:group settings of webadmin:webadmin, prohibiting anyone who is not a member of the webadmin group from installing them. However, you cannot log in as webadmin and install the files from the database server because webadmin is not a member of the carsctrl or carsprog groups which control the source directories. The solution is to change the Fileperms table to use carsctrl group ownership for these files.

If you choose to change the Fileperms table entries for WEB_TEST_CONFIG and WEB_LIVE_CONFIG to use group carsctrl, you must then run fileperms -u on /opt/Apache/etc on the remote webserver.

Installing setup_web_dbm Because the make processor deals with different source path types in different ways, you may encounter difficulties when you try to make install the setup_web_dbm script (source: $CARSPATH/modules/cisc/commands/setup_web_dbm) using WEBSERVER=LIVE. For example, the procedure that is supposed to copy the file to the remote webserver does not execute. This is an issue because setup_web_dbm must be installed using the WEBSERVER=LIVE directive or the macros will not be expanded properly in the installed script.

To resolve this issue, you can modify and make install setup_web_dbm on both servers when necessary. For example, if you need to reinstall setup_web_dbm on the remote webserver, telnet to that machine first, check out the file, make the changes, then make install WEBSERVER=LIVE. This approach assumes that you have replicated at least part of $CARSPATH/modules on the webserver. Alternately, you can install the script WEBSERVER=LIVE on the database server, then manually transmit it to the webserver using ftp and then make any additional changes needed to the installed file there.

Fileperms You must resolve some issues with the fileperms program on the remote webserver before you can use the make processor to install files from the database server.

If you are running different versions of UNIX on your computers, the fileperms and timecmp binaries you copy from the database server may not work on the webserver.

The errors you may encounter are:

• 0509-037 System error - error data is: fileperms

• 0509-023 Symbol __mod_init in csh is not defined.

• 0509-023 Symbol __crt0v in csh is not defined.

• 0509-026 System error: Cannot run a file that does not have a valid form

If you continue, any installed files end up with incorrect fileperms on the webserver.

The solution is to recompile both fileperms and timecmp (source: $CARSPATH/system/Make/user/Make/src) on the remote webserver and install the new binary objects (install path: $CARSPATH/install/utl) using the following commands as root:

# cd system/Make/user/Make/src # make cleanup reinstall # <-- Places binary in ./.. # cd .. # make fileperms # <-- Places binary in install path # make timecmp


Note that at this time the fileperms table (source: $CARSPATH/system/lib/fileperms.s) must be installed on the database server, and then you must transmit the the translated file to the remot webserver manually using ftp . If you try to modify the fileperms table and make install it all on the webserver box, you will create a zero byte target file in the install path ($CARSPATH/install/sys/lib/fileperms). Also, you may want to manually comment out lines in the installed fileperms table on the webserver machine which refer to non-existent parts of $CARSPATH. If you do not comment out the lines, the system will generate a harmless error message when you do a make install WEBSERVER=LIVE from the database server.


Setting up User Authentication

Running setup_web_dbm In a separate webserver configuration, the setup_web_dbm script should run on the remote webserver computer and query the database server for username and password information before building the Apache dbm hash files. Jenzabar, Inc. wrote the setup_web_dbm script (source: $CARSPATH/modules/cisc/commands/setup_web_dbm) to use the same cis_opendb(DATABASE) call that is used for the Jenzabar CX cgi scripts. This means that if you have completed all steps in the Implementation section up to this point, all you have to do is reinstall setup_web_dbm from the database server with the WEBSERVER=LIVE directive.

However, note the following:

When reinstalling the setup_web_dbm script on the remote webserver, you must use the WEBSERVER=LIVE argument or the Web macro values will not be interpreted properly. This is true despite the fact that when you do so the make processor does not return the target path of the installed script after you run make as it does with the other Web modules. If you have two databases, two install paths, and one source path, you might mistakenly build the dbm file from the wrong data. Note that the current setdb on the remote webserver when setup_web_dbm is run determines which database the data comes from by virtue of separate webserver path macros pointing to different service files in /opt/Apache, which in turn point to different database sockets on the database server (one for one database, one for the other).

Separately, however, the keyword 'LIVE' used with the setup_web_dbm command determines the target webserver path (LIVE or TEST) where the dbm hash file will go. For example, if your two databases are called "cars" and "train", and your target webserver paths are /opt/Apache/train-test and /opt/Apache/cars-live, then:

If you issue this command… … with webserver setdb…

… the dbm file ends up in…

… with data from…

OK* # setup_web_dbm student train train-test train

# setup_web_dbm student LIVE train cars-live train

# setup_web_dbm student cars train-test cars

OK* # setup_web_dbm student LIVE cars cars-live cars

* The lines marked "OK" are the desired situations.

Setting up webadmin to Update profile_rec Although not strictly an issue with running a separate webserver, the setup of webadmin to enable it to update the profile_rec requires that webadmin has update permissions on profile_rec.password. Without this permission, the password setting cgi script will not work. Appropriate permissions are also required for any other user whom you want to run setup_web_dbm.


Errors and Troubleshooting During Dual Webserver Setup

Introduction This section provides information about correcting problems when setting up dual webservers.

Student Photos The Jenzabar blobload utility for use with img.cgi (source in $CARSPATH/common/cgi) is a stripped binary that does not use Plibdata to access the profile_rec. As a result, it will not transfer the student image between servers in a dual server configuration. The binary is stored in $CARSPATH/install/utl.

The solution is to store the student images on the local file system of both servers. Change the img.cgi script to just point a filehandle to the existing image file without using the intermediary step of running blobload.

The following diff output shows how to make this change. To make this example more understandable, the system command is divided into separate lines ending in a backslash.

RCS file: RCS/img.cgi,v retrieving revision 8.2 diff -r8.2 img.cgi 20c20,27 < print "Content-type:image/gif\n"; --- > #-----------------------------------------------------------------------+ > # Begin Local: | > # -- Use jpg instead of gif. | > # -- Use images stored in photos subdirectory rather than profile_rec. | > # -- Don't use blobload utility. | > # -- Use bishop.jpg if no photo exists. | > #-----------------------------------------------------------------------+ > print "Content-type:image/jpeg\n"; 23c30 < $fh = "WEB_TEST_SERVER_ROOTPATH/share/images/" . $id . ".gif"; --- > $fh = "WEB_SERVER_ROOTPATH/share/images/photos/" . $id . ".jpg"; 25c32 < system "$ENV{'CARSPATH'}/install/utl/blobload -f $fh -d $db \ -t profile_rec -b photo -k id $id -o -q"; --- > # system "$ENV{'CARSPATH'}/install/utl/blobload -f $fh -d $db \ -t profile_rec -b photo -k id $id -o -q"; 26a34,40 > if (! -e $fh) { > $fh = "WEB_SERVER_ROOTPATH/share/images/bishop.jpg"; > } > #---------------+ > # End Local | > #---------------+ > 34d47 < unlink $fh;

Restoring LIVE Web to the Database Server If the remote webserver failed and you wanted to run the Jenzabar CX Web products from your database server machine:

1. Change the value of the WEB_LIVE_SERVER_HOSTNAME macro from the hostname of the remote webserver to a value that matches WEB_EDVANTA_HOSTNAME, then reinstall the following (in order) using the WEBSERVER=LIVE directive:

• $CARSPATH/macros/custom/web


• $CARSPATH/macros/user/web

• $CARSPATH/system/Make/user/{Common,cgi,htm}

• $CARSPATH/system/Make/prog

• $CARSPATH/modules/cisc/commands/setup_web_dbm

• $CARSPATH/Web/cgi/lib/cisweb.ph

2. After the above files are reinstalled, you must also reinstall the following modules:

• $CARSPATH/Web

• $CARSPATH/modules/regist/cgi/

• $CARSPATH/modules/finaid/cgi/

• $CARSPATH/modules/admit/cgi/

• Other cgi modules

3. Edit the httpd.conf and access.conf source files on the database server machine, replacing all comparisons between WEB_SERVER and the string 'LIVE' with a comparison between MAK_HOSTNAME and WEB_LIVE_SERVER_HOSTNAME, then reinstall httpd.conf to both TEST and LIVE webservers. Check the installed files to make sure all macros were expanded to point to the correct webserver install paths.

4. Run setup_web_dbm student/faculty with the LIVE parameter on the database server machine to build the authentication hash files. Check the time stamps on the resulting files to make sure that they are correct. Also, if you have two databases, two install paths, and one source path, test a login using dbmmanage to verify that the authentication data was pulled from the correct database.

5. As root, restart Apache on the database server, as follows: # /opt/Apache/sbin/apachectl graceful

6. Test the browser connection to the LIVE webserver port, and then test authenticated access to both faculty and student areas.

7. Contact your webmaster, if necessary, have him/her update the pointers on your school's home page. Also, if needed, contact your network administrator to update your name server and that of your ISP.

CX Webserver 51 Index

INDEX

A access_log, 3 accessing webserver

verification, 23 addlogin

to add webadmin, 2 adduser command, 8 agent_log, 3 Apache

Web site, 2 apache directories, 16 Apache directories, 17 audience

for guide, 1 authenticating

students, 23 authentication, 7

for faculty, 21 for students, 20 with dual servers, 28

authentication, 20 authentication file

regenerating, 21

B bouncing

webserver, 3

C Can't locate object method "TIEHASH"

message, 25 cgi files, 5 cgi log files, 7 commands

dbmmanage, 7 configuration files, 18 configuration macros, 13

D dbadmin

to add webadmin, 2 dbmmanage command, 7 determining

port numbers, 23 directories, 4, 5

Apache, 17 for apache, 16

dual servers, 27 access.conf, 42

activating the remote server, 41 authentication, 28 configuration requirements, 27 database access, 28 directory paths, 41 fileperms, 43 httpd.conf, 42 installing wetup_web_dbm, 43 macro setup, 27 modifying make on the database server, 33 replication issues, 32 restoring LIVE Web to the database server,

45 running setup_web_dbm, 44 security issues, 29 source code location, 28 student photos, 45 troubleshooting, 45 using webadmin to update profile_rec, 44

E error_log, 3

F files

access_log, 3 agent_log, 3 cgi, 5 cgi logs, 7 configuration, 18 error_log, 3 htm, 5 image, 8 initializing, 4 installing, 19 logs, 3 referer_log, 3 removing, 4 user authentication, 7 user options, 7

G groups

webadmin, 2 guide, purpose of, 1

H htm files, 5

Index 52 CX Webserver

I image files, 8 installation

tasks prior to, 9 installation verification, 23

L LIVE webservers, 9, 23 log files

initializing, 4 removing, 4 webserver, 3

M macros

configuration, 13 for dual servers, 27 for ODBC driver path, 13 for Perl directory path, 14 server path, 13

messages Can't locate object method "TIEHASH", 25 Path does not exist, 25 Permission denied, 25 SQLAuthenticateAny() - Guest login not

permitted, 25

O ODBC driver, 15 ODBC driver path macros, 13

P Path does not exist message, 25 Perl, 5, 9 Perl directory path macros, 14 Permission denied message, 25 permissions

verifying, 19 personal identification numbers. See PIN

numbers PIN numbers, 20 plibdata, 9 port numbers

determining, 23 pre-installation tasks, 9 profile_rec

updating, 44

R referer_log, 4 regenerating

authentication files, 21

S scripts

setup_apache, 16 server path macros, 13 setup_apache script, 16 setup_web_dbm command, 8 SQLAuthenticateAny() - Guest login not

permitted message, 25 starting

webserver, 3 status

of Apache server, 4 stopping

webserver, 3 student photos

with dual servers, 45

T TEST webservers, 9, 23 testing

your installation, 23 troubleshooting, 25

V verifying

your installation, 23

W webadmin, 2

group, 2 webserver

basics, 2 directories, 12 log files, 3 starting and stopping, 3

webserver, purpose of, 1 webservers

LIVE or TEST, 9, 23

CX Web Server

Documents

Transcript of CX Web Server