HP OpenVMS Systems

Version 2.1-1 for OpenVMS Alpha, based on Apache 2.0.52
CPQ-AXPVMS-CSWS-V0201-1-1.PCSI_SFX_AXPEXE

Version 2.1-1 for OpenVMS I64, based on Apache 2.0.52
HP-I64VMS-CSWS-V0201-1-1.PCSI_SFX_I64EXE

This document contains information about installing and configuring the HP Secure Web Server for OpenVMS. It also includes information about running the web server, security information, and how to build and debug loadable Apache modules.

Software Version
Secure Web Server for OpenVMS Version 2.1-1

Hewlett-Packard Company
Palo Alto, California

Chapter 1 Installation Requirements and Prerequisites

1.1 Hardware Requirements

     1.1.1 ODS-5 Disk

     1.1.2 Disk Space

     1.1.3 Stream_LF File Format No Longer Required

1.2 Software Requirements

     1.2.1 MultiNet and TCPware Network Products

     1.2.2 CSWS_JAVA Requirements

     1.2.3 CSWS_PHP Requirements
     1.2.4 CSWS_PERL Requirements

     1.2.5 Building the Apache HTTP Server from Source Code

Chapter 2 Installation and Configuration

2.1 Read the Release Notes

2.2 Install the Secure Web Server

     2.2.1 Sample Installation

2.3 Configure the Secure Web Server

     2.3.1 Configuration Menu

     2.3.2 Configuring a Single Server

     2.3.3 Sample Configuration of a Single Server

     2.3.4 Configuring Multiple Servers

     2.3.5 Sample Configuration of Multiple Servers

     2.3.6 Delete Server Instance

     2.3.7 Managing suEXEC

     2.3.8 Running the OpenSSL Certificate Tool

     2.3.9 Converting Files to Stream_LF

     2.3.10 Starting and Stopping the Secure Web Server

     2.3.11 Showing the Status of an Apache Instance
     2.3.12 Adding a Node to CSWS in a Cluster Environment

     2.3.13 Managing Multiple Servers

          2.3.13.1 HTTPD.CONF

          2.3.13.2 APACHE$SETUP.COM and LOGIN.COM

     2.3.14 Viewing the OpenSSL Certificate

2.4 Post Configuration Checklist

     2.4.1 Configure CSWS_JAVA

     2.4.2 Check the CSWS_PERL Configuration

     2.4.3 Check the CSWS_PHP Configuration

     2.4.4 Run AUTOGEN

     2.4.5 Check Disk Quota

     2.4.6 Check for SET TERMINAL/INQUIRE

2.5 Test the Installation

     2.5.1 Browser Test

     2.5.2 TELNET Test

     2.5.3 Troubleshooting

2.6 What's Next

2.7 Merge Changes to Files You Have Customized

2.8 Installing Optional Modules at a Later Time

Chapter 3 Running the Secure Web Server on OpenVMS

3.1 Starting and Stopping the Server

     3.1.1 Starting the Server

     3.1.2 Stopping the Server

          3.1.2.1 Stopping the Server Using the Server Process Name

3.2 Server Log File

3.3 Performance Considerations

     3.3.1 Limits and Quotas

     3.3.2 Server Experiencing Medium to High Usage

     3.3.3 Global Pages and Global Sections

     3.3.4 Excessive File Build Up

3.4 Customizing the Server Environment

3.5 Modules and Directives

     3.5.1 Apache Modules

     3.5.2 Apache 1.3 Modules Not Included

     3.5.3 OpenVMS Directives

     3.5.4 Command Line Options

     3.5.5 Virtual Host Support

     3.5.6 Dynamic Shared Object Support

     3.5.7 File Handlers

     3.5.8 Content Negotiation

     3.5.9 Apache API

     3.5.10 WebDAV (Distributed Authoring and Versioning) Support

          3.5.10.1 Testing DAV Operation

     3.5.11 suEXEC Support
     3.5.12 MOD_SSL
     3.5.12.1 Setting up a Galaxy Shared-Memory SSL Session Cache

     3.5.13 Running MOD_OSUSCRIPT

3.6 File Formats

3.7 Managing File and Directory Access Controls

     3.7.1 Outbound Access to Non-CSWS Files and Directories

     3.7.2 Inbound Access to SWS Files and Directories

3.8 Logical Names

3.9 OpenVMS Cluster Considerations

     3.9.1 Individual System vs. Clusterwide Definition

     3.9.2 Mixed-Architecture (Alpha and VAX) Cluster

3.10 Common Gateway Interface (CGI)

     3.10.1 CGI Environment Variables

     3.10.2 Referencing Input

     3.10.3 Executing CGI

     3.10.4 Logicals for Debugging CGI Scripts

     3.10.5 Displaying Graphics with CGI Command Procedures

Chapter 4 Security Information

4.1 Process Model

4.2 Privileges Required to Start and Stop the Server

4.3 File Ownership and Protection

4.4 Authentication Using OpenVMS Usernames and Passwords (MOD_AUTH_OPENVMS)

     4.4.1 The require group Directive

     4.4.2 The require user Directive

     4.4.3 Hiding Accounts

     4.4.4 MOD_AUTH_OPENVMS Security Considerations

     4.4.5 MOD_AUTH_OPENVMS Examples

4.5 Server Extensions (CGI Scripts, PHP Scripts, Perl Modules)

4.6 suEXEC in the Secure Web Server

     4.6.1 suEXEC Security Model

     4.6.2 Configuring suEXEC

          4.6.2.1 Using Paths with Logicals in UserDir Directive

          4.6.2.2 Using Paths with Device Names in UserDir Directive

4.7 Protecting Server Certificate Keys

Chapter 5 Building and Debugging Loadable Apache Modules for the Secure Web Server

5.1 The Apache API, Run-Time Library, and HTTP Request Processing

5.2 Building a Module

     5.2.1 Defining Your Apache Module Data Structure Symbol

     5.2.2 Compiling a Module

     5.2.3 Linking a Module

     5.2.4 Example: mod_rewrite

     5.2.5 Debugging a User-Built Apache Module

          5.2.5.1 Preparing to debug your module

          5.2.5.2 Debugging your module

Chapter 6 Open Source Licenses

Chapter 1
Installation Requirements and Prerequisites

Before you can install the Secure Web Server for OpenVMS (based on Apache), verify that your system meets the minimum hardware and software requirements described below.

You can install the Secure Web Server for OpenVMS on any AlphaServer system running OpenVMS Version 7.3-2 or higher, or any Integrity server system running OpenVMS I64 Version 8.2 or higher.

HP requires that you install the Version 2.1-1 kit on an ODS-5 enabled disk.

You must install the V2.1-1 kit on an ODS-5 target volume. If you attempt to install this kit on an ODS-2 volume, the installation will fail.  If you had an existing CSWS V1.3 installation, the failed operation will leave it in a corrupt state.

Verify that the destination device is an ODS-5 volume by entering a command similar to the following, where DISK$DKA200 is the disk where you want to install the Secure Web Server:

$ SHOW DEV DISK$DKA200/FULL

Disk VARMIT$DKA200:, device type COMPAQ BB00923468, is online, mounted, file-oriented device, shareable, available to cluster, error logging is enabled.

Volume Status:  ODS-5, subject to mount verification, file high-water marking, write-back caching enabled.

The Secure Web Server for OpenVMS Alpha compressed file contains 19,887 blocks. The expanded PCSI file requires approximately 45,000 blocks of working disk space to install.

The Secure Web Server for OpenVMS I64 compressed file contains 25,645 blocks. The expanded PCSI file requires approximately 65,000 blocks of working disk space to install.

The Secure Web Server Version 2.1-1 no longer requires that all served files must be in Stream_LF format. See Converting Files to Stream_LF for information about a command procedure included in the kit that automatically converts your files if you choose to do so.

The Secure Web Server requires the following software:

·         HP OpenVMS Alpha Version 7.3-2 or higher
– or – 
HP OpenVMS I64 Version 8.2 or higher

Be sure that your system has the latest required ECOs, available from HP Services Software Patches

·         HP TCP/IP Services for OpenVMS Version 5.4 or higher (for SWS on OpenVMS Alpha Version 7.3-2)
– or – 
HP TCP/IP Services for OpenVMS Version 5.5 or higher (for SWS on OpenVMS Alpha and OpenVMS I64 Version 8.2 or higher)

If you are using MultiNet or TCPware from Process Software Corporation instead of HP TCP/IP Services for OpenVMS, you should be aware of the following information.

The Secure Web Server has been tested and verified using HP TCP/IP Services for OpenVMS. There are no known problems running the Secure Web Server with other TCP/IP network products such as MultiNet and TCPware, but HP has not formally tested and verified these other products.

MultiNet and TCPware currently support IPv4 only. If you want to take advantage of the IPv6 support in the Secure Web Server, you must use HP TCP/IP Services for OpenVMS Version 5.3 or higher.

MultiNet and TCPware require ECO kits for the Secure Web Server. These ECO kits are subject to change. For the latest ECO kit information, contact Process Software and ask for the ECO kits required to run the Secure Web Server for OpenVMS. Send network connectivity questions regarding the Secure Web Server on TCPware and MultiNet via email to support@process.com.

CSWS_JAVA includes the following Apache Jakarta technologies: Tomcat (JavaServer Pages 1.2, Java Servlet 2.3, MOD_JK, and MOD_JK2) and Ant. (Note: Ant is a partial implementation of the Jakarta Ant subproject and its use is limited to building the included sample web applications and simple user-written web applications for Tomcat.)

CSWS_JAVA V3.0 provides Java Servlet 2.4 and JSP 2.0 technology, while CSWS_JAVA V2.x provides Java Servlet 2.3 and JSP 1.2 technology.

CSWS_JAVA has retired support for CSWS_JSERV. If you want to continue JSERV support, download CSWS_JAVA Version 1.1 from the CSWS_JAVA for HP Secure Web Server for OpenVMS web site at http://h71000.www7.hp.com/openvms/products/ips/apache/csws_java.html.

See the CSWS_JAVA for HP Secure Web Server for OpenVMS web site for CSWS_JAVA requirements.

PHP is a server-side, cross-platform, HTML embedded scripting language that lets you create dynamic web pages. PHP-enabled web pages are treated the same as regular HTML pages, and you can create and edit them the way you normally create regular HTML pages.

See the CSWS_PHP for HP Secure Web Server for OpenVMS web site at http://h71000.www7.hp.com/openvms/products/ips/apache/csws_php.html for CSWS_PHP requirements.

Perl has become the premier scripting language of the Web, as most CGI programs are written in Perl. The Secure Web Server for OpenVMS supports an optional kit, CSWS_PERL. CSWS_PERL includes MOD_PERL, an interface between Perl and the Secure Web Server which lets you write modules entirely in Perl.

See the CSWS_PERL for HP Secure Web Server for OpenVMS Installation Guide and Release Notes for CSWS_PERL requirements.

The Secure Web Server Version 2.1-1 kit is based on Apache 2.0.52. The Secure Web Server source code can be found at the Secure Web Server for OpenVMS web site at http://h71000.www7.hp.com/openvms/products/ips/apache/csws_source.html.

The build instructions are guidelines only and will require modification and customization for the OpenVMS environment used for the build. Other build prerequisites, such as compilers, might also exist.

Installation and configuration consists of the following steps:

1.       Read the release notes

2.       Install the server and optional modules

3.       Configure the server

4.       Review the post configuration checklist

5.       Test the installation

Detailed instructions for completing each of these steps are provided in the following sections.

Before you begin the installation, you should read the HP Secure Web Server for OpenVMS Release Notes available at http://h71000.www7.hp.com/openvms/products/ips/apache/csws_relnotes_211.html.

The following kits are intended to work together:

·     Secure Web Server for OpenVMS (CSWS) Version 2.1 and higher -or- 1.3-1

·     CSWS_PHP Version 1.3 or higher

·     CSWS_PERL Version 2.1 or higher and PERL for OpenVMS Version 5.8.6 or higher

·     CSWS_JAVA Version 3.0 or higher

Earlier versions of these optional kits will not work with Secure Web Server Version 2.1-1.
Current versions of these optional kits will not work with Secure Web Server Version 2.0.

You can install the Secure Web Server by itself or with one or more of the optional modules. You can install the optional modules later if you choose.

Before you begin, do the following:

1.       Decide what you want to install.

2.       Review the software requirements for the server and each optional module you are installing.

3.       Decide where you want to install the kit.

The Secure Web Server and CSWS_PHP must be installed in the same directory (required).

By default, the Secure Web Server and CSWS_PHP are installed in SYS$COMMON. However, HP recommends that you specify another location.

CSWS_JAVA can be installed into a different disk or directory from the Secure Web Server.

HP recommends that you shut down the Secure Web Server (and Tomcat, which runs as a separate process) before installing a new version of any component: CSWS, CSWS_PHP, CSWS_PERL, or CSWS_JAVA (Tomcat).

Follow these instructions to install the Secure Web Server by itself or with the optional modules.

1.       The Secure Web Server for OpenVMS kit is provided as a compressed, self-extracting file. To download it from the OpenVMS web site, fill out and submit the registration form at Secure Web Server for OpenVMS web site at http://h71000.www7.hp.com/openvms/products/ips/apache/csws.html.

Download any optional modules you want to install.

Download CSWS_JAVA from http://h71000.www7.hp.com/openvms/products/ips/apache/csws_java_relnotes.html

Download CSWS_PHP from http://h71000.www7.hp.com/openvms/products/ips/apache/csws_php_relnotes.html

Download CSWS_PERL from http://h71000.www7.hp.com/openvms/products/ips/apache/csws_modperl_relnotes.html

Download PERL for OpenVMS from http://h71000.www7.hp.com/openvms/products/ips/apache/csws_perl_relnotes.html

2.       Log in as a privileged OpenVMS user (for example, SYSTEM).

3.       Select UIC group and member numbers for the APACHE$WWW account that will be created by the installation procedure. HP recommends that you use an empty or new UIC group (without current members). Servers typically use the highest unused UIC group (for example, [370,1]).

To ensure that the UIC you chose for APACHE$WWW has READ and WRITE access to the intended login device, use the SHOW DEVICE/FULL command.

In the SHOW DEVICE/FULL output, the important piece of information is towards the bottom of the output: Vol Prot.

The APACHE$WWW UIC must have RWD access to the volume as indicated in the Vol Prot field and at least E access to the destination directory on that volume where Apache is installed.

For example, if Apache is installed to DISK$APPS:[000000], then APACHE$WWW must have at least RWD access to the DISK$APPS disk volume and at least E access to the DISK$APPS:[000000]000000.DIR directory.

For example:

$ SHOW DEVICE/FULL DKB0:

Disk $DKB0:, device type COMPAQ BD03664545, is online, mounted, file-oriented device, shareable, available to cluster, error logging is enabled

    Owner process
                
""    Owner UIC                      [SYSTEM]

    Owner process ID        00000000   
Dev Prot            S:RWPL,O:RWPL,G:R,W

    Reference count               29    Default buffer size                 512

    Total blocks            71132000   
Sectors per track                   254

    Total cylinders            14003   
Tracks per cylinder                  20

    Volume label            "BUILD1"    Relative volume number                0

    Cluster size                   3   
Transaction count                    25

    Free blocks             52293678   
Maximum files allowed           8891500

    Extend quantity                5   
Mount count                           1

    Mount status              System   
Cache name     "_ALPHA$DKA300:XQPCACHE"

    Extent cache size             64   
Maximum blocks in extent cache  5229367

    File ID cache size            64   
Blocks in extent cache             2703

    Quota cache size               0   
Maximum buffers in FCP cache       1730

    Volume owner UIC        [SYSTEM]   
Vol Prot    S:RWCD,O:RWCD,G:RWCD,W:RWCD

Volume Status:  ODS-5, subject to mount verification, write-back caching enabled, access dates enabled, hard links enabled.

      4. Decompress the server kit with one of the following command, depending on
            which platform on which you will install the kit:

$ RUN CPQ-AXPVMS-CSWS-V0201-1-1.PCSI_SFX_AXPEXE ! for Alpha
$ RUN HP-I64VMS-CSWS-V0201-1-1.PCSI_SFX_I64EXE  ! for I64

The system expands the file and names it CPQ-AXPVMS-CSWS-V0201-1-1.PCSI or
HP-I64VMS-CSWS-V0201-1-1.PCSI.  Do not rename the file.

      5. If you are upgrading from a previous version of the Secure Web Server and you modified
            the file [APACHE.CONF]MIME.TYPES, copy the file to another location before you begin
            the installation. This file is removed during the installation. (HP recommends that you use
            the AddTypes directive instead of modifying the MIME.TYPES file.)  See the
            Merge Changes to Files You Have Customized section for more information.

Start the installation with the PRODUCT INSTALL command. Use the /DESTINATION qualifier to specify a target device and directory for the installation. If you do not specify a destination, the software will be installed in SYS$COMMON. HP recommends that you specify another location.

Once you enter a PRODUCT INSTALL CSWS/DESTINATION=[destination] command, you cannot change the installation location unless you remove CSWS and then reinstall it. To change the installation location when you upgrade to a new version of CSWS, you must first enter the PRODUCT REMOVE CSWS command, then enter PRODUCT INSTALL CSWS/DESTINATION=[new-destination].

Review the software requirements for the server and each optional module you are about to install. To prevent installation problems, make sure the required software is installed before you enter the PRODUCT INSTALL command.

To install the server, enter the following command:

     $ PRODUCT INSTALL CSWS /DESTINATION=device:[directory-name]

To install the server and one or more of the optional modules, specify CSWS and the CSWS_nnnn kit name on the PRODUCT INSTALL command line separated by commas. For example, to install the server and CSWS_PHP, use the following command:

  $ PRODUCT INSTALL CSWS, CSWS_PHP /DESTINATION=device:[directory-name]

The installation proceeds and displays product information as well as post-installation instructions. The installation is finished when you see the DCL prompt ($).

After the installation, you must configure the Secure Web Server.

Do not attempt to start the server or configure any optional modules before you have configured the server.

Following is an example of the Secure Web Server product installation.

$ PRODUCT INSTALL CSWS /DESTINATION=DKB300:[000000]

The following product has been selected:

    CPQ AXPVMS CSWS V2.1-1                   Layered Product

Do you want to continue? [YES]

Configuration phase starting ...

You will be asked to choose options, if any, for each selected product and for

any products that may be installed to satisfy software dependency requirements.

CPQ AXPVMS CSWS V2.1-1

    Hewlett-Packard Company & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:

    CPQ AXPVMS CSWS V2.1-1 USER$DISK3:[000000.]

Portion done: 0%...10%...20%...30%...40%...50%...60%...70%...90%...100%

The following product has been installed:

    CPQ AXPVMS CSWS V2.1-1                   Layered Product

CPQ AXPVMS CSWS V2.1-1

    Release notes are available in SYS$HELP:CSWS0201.RELEASE_NOTES.

    HP highly recommends that you read these release notes.

    For the most up-to-date documentation, including release notes,

    Frequently Asked Questions (FAQs), and information about configuring

    and running the HP Secure Web Server, please see the web pages at:

http://h71000.www7.hp.com/openvms/products/ips/apache/csws.html

    Post-installation tasks are required for the HP Secure Web Server.

    The OpenVMS Installation and Configuration Guide gives detailed directions.

    This information is a brief checklist.

    Configure OpenVMS aspects of the HP Secure Web Server by:

        $ @SYS$MANAGER:APACHE$CONFIG

    If the OpenVMS username APACHE$WWW does not exist, you will be

    prompted to create that username.  File ownerships are set to UIC

    [APACHE$WWW], etc.

    After configuration, start the HP Secure Web Server manually by

    entering:

        $ @SYS$STARTUP:APACHE$STARTUP

    Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to

    SYS$OUTPUT:.  Look especially for a

        $ SET TERMINAL/INQUIRE

    Start the HP Secure Web Server at system boot time by adding the

    following lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

        $ file := SYS$STARTUP:APACHE$STARTUP.COM

        $ if f$search("''file'") .nes. "" then @'file'

    Shutdown the Apache server at system shutdown time by adding the

    following lines to SYS$MANAGER:SYSHUTDWN.COM:

        $ file := SYS$STARTUP:APACHE$SHUTDOWN.COM

        $ if f$search("''file'") .nes. "" then @'file'

    Test the installation using your favorite Web browser.

    Replace host.domain in the following URL (Uniform Resource Locator)

    with the information for the HP Secure Web Server just installed,

    configured, and started.

    URL http://host.domain/ should display the standard introductory page

    from the Apache Software Foundation. This has the bold text "It

    Worked! The Apache Web Server is Installed on this Web Site!" at the

    top and the Apache server logo prominently displayed at the bottom.

    If you do not see this page, check the HP Secure Web Server

    release notes, particularly the Frequently Asked Questions section.

    If you'd like to use secure connections with the HP Secure Web Server

    then you'll need to create a server certificate.  We recommend that

    you start by creating a 30 day self signed certificate using the

    following certificate tool:

In general, you can run the Secure Web Server on OpenVMS as you would run Apache with MOD_SSL on any platform. However, there are some exceptions. This chapter describes the functions that behave differently or are not available, as well as any enhancements that are specific to OpenVMS.

Starting and stopping the Secure Web Server requires enhanced privileges (DETACH, SYSNAM, WORLD, etc.). Start and stop the server from a privileged account such as SYSTEM.

Start the Secure Web Server with the following command:

    $ @SYS$STARTUP:APACHE$STARTUP [startup-value] [configuration-file]

Startup-value is optional and can have the following values:

 
Configuration-file is an optional file specification for a configuration file. If you do not specify a value for configuration-file, HTTPD.CONF is the default.

To automate the startup of the Secure Web Server when the system is booted, add the following commands to the SYS$MANAGER:SYSTARTUP_VMS.COM file:

    $ FILE := SYS$STARTUP:APACHE$STARTUP.COM

    $ IF F$SEARCH("''FILE'") .NES. "" THEN @'FILE'

You can shut down the Secure Web Server with the following command:

    $ @SYS$STARTUP:APACHE$SHUTDOWN [startup-value] [configuration-file]

Startup-value is optional and can have the following values:

Configuration-file is an optional file specification for a configuration file. If you do not specify a value for configuration-file, HTTPD.CONF is the default.

To automate the shutdown of the Secure Web Server when the system is shut down, add the following commands to the SYS$MANAGER:SYSHUTDOWN.COM file:

    $ FILE := SYS$STARTUP:APACHE$SHUTDOWN.COM

    $ IF F$SEARCH("''FILE'") .NES. "" THEN @'FILE'

The Secure Web Server will not shut down as long as the APACHE$WWW process is running.
 

If you are unable to shut down the server, use the following command to check whether APACHE$WWW processes are still running:

    $ SHOW SYSTEM/OWNER_UIC=[APACHE$WWW]

If you are unable to shut down the server using the APACHE$SHUTDOWN command, and APACHE$WWW is still running, you can use the server PID to stop it. To determine the server PID, enter the following command (or choose Option 9 from the configuration menu):

    $ SHOW SYSTEM/PROCESS=APACHE$tag

Server processes have a process tag of the form APACHE$ssss, where ssss is up to four alphanumeric characters defined in the VmsServerTag directive. The default is APACHE$SWS.