HP Secure Web Server for OpenVMS (based on Apache)
November 2011
Version 2.2 for OpenVMS Alpha, based on Apache 2.0.63
Version 2.2 for OpenVMS Integrity servers, based on Apache 2.0.63 This document
contains information about installing and configuring the HP Secure Web Server
for OpenVMS. It also
Version 2.2 Installation and
Configuration Guide
CPQ-AXPVMS-CSWS-V0202--1.PCSI_SFX_AXPEXE
HP-I64VMS-CSWS-V0202--1.PCSI_SFX_I64EXE
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.
Hewlett-Packard Company
Contents
Chapter 1
Installation Requirements and Prerequisites
1.1.1
ODS-5 Disk
1.1.2
Disk Space
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.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.4.7
Disable Non-interactive Login Time
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.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.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 (SWS) for OpenVMS (based on
Apache), verify that your system meets the minimum hardware and software
requirements described below.
1.1 Hardware Requirements
You can install the SWS for OpenVMS on any
AlphaServer
system running OpenVMS Version 7.3-2 or higher, or any Integrity server system
running OpenVMS Integrity server Version 8.2 or higher.
HP requires that you install the Version 2.2 kit on an ODS-5 enabled disk.
Important
You must install the Version 2.2 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 SWS:
$ 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 SWS for OpenVMS Alpha compressed file contains 28,416 blocks. The expanded PCSI file requires approximately 45,000 blocks of working disk space to install.
The SWS for OpenVMS Integrity servers compressed file contains 54,848 blocks.
The expanded PCSI file requires approximately 65,000 blocks of working disk
space to install.
1.1.3
Stream_LF File Format No Longer Required
The SWS Version 2.2 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 SWS requires the following software:
·
HP OpenVMS Alpha Version 7.3-2 or higher
Or
HP OpenVMS Integrity server 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 Integrity
servers Version 8.2 or higher)
1.2.1 MultiNet and
TCPware
Network Products
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 SWS has been tested and verified using HP TCP/IP Services for OpenVMS. There
are no known problems running the SWS with other TCP/IP network products such as
MultiNet and TCPware, but HP has not formally tested and verified these
other products.
Note
MultiNet and TCPware currently
support IPv4 only. If you want to take advantage of the IPv6 support in the SWS,
you must use HP TCP/IP Services for OpenVMS Version 5.3 or higher.
MultiNet and TCPware require
ECO kits for the SWS. 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 SWS for OpenVMS. Send network connectivity questions regarding the SWS
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 SWS for
OpenVMS web site at
http://h71000.www7.hp.com/openvms/products/ips/apache/csws_java.html.
See the CSWS_JAVA for HP SWS for OpenVMS web site for CSWS_JAVA requirements.
1.2.3 CSWS_PHP 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 SWS for OpenVMS web site at
http://h71000.www7.hp.com/openvms/products/ips/apache/csws_php.html
for CSWS_PHP requirements.
1.2.4 CSWS_PERL Requirements
Perl has become the
premier scripting language of the Web, as most CGI programs are written in Perl.
The SWS for OpenVMS supports an optional kit, CSWS_PERL. CSWS_PERL includes
MOD_PERL, an interface between Perl and the SWS 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.
1.2.5 Building the Apache HTTP Server from Source Code
The SWS
Version 2.2 kit is based on Apache 2.0.63. The SWS source code can be found at
the SWS 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.
Chapter 2
Installation and Configuration
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_doc.html.
2.2 Install the Secure Web Server and Optional Modules
The following kits are intended to work together:
·
SWS for OpenVMS (CSWS) Version 2.2 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
Note
Earlier versions of these optional kits will not work with SWS
Version 2.2. Current versions of these optional kits will not work with SWS
Version 2.0.
You can install the SWS 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.
Note
The SWS and CSWS_PHP must
be installed in the same directory (required). By default, the SWS 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 SWS.
HP recommends that you shut down the SWS (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 SWS by itself or with the optional
modules.
1.
The SWS 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 SWS 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
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:
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-V0202--1.PCSI_SFX_AXPEXE ! for Alpha
$ RUN HP-I64VMS-CSWS-V0202--1.PCSI_SFX_I64EXE ! for I64
HP-I64VMS-CSWS-V0202--1.PCSI. Do not rename the file.
5. If you are upgrading from a previous version of the SWS 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.
Note
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]
$ PRODUCT INSTALL CSWS, CSWS_PHP /DESTINATION=device:[directory-name]
Note
Do not attempt to start
the server or configure any optional modules before you have configured the
server.
Following is an example of the SWS product installation.
$ PRODUCT INSTALL
CSWS /DESTINATION=DKB300:[000000]
The following
product has been selected:
CPQ AXPVMS CSWS V2.2
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.2
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.2
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.2
Layered Product
CPQ AXPVMS CSWS
V2.2
Release notes are available
in SYS$HELP:CSWS0202.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 SWS,
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:
$
@APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM
Once the certificate has been created
you'll need to uncomment the
following directive in the
APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.
Include /apache$root/conf/ssl.conf
Thank you for using the HP
Secure Web Server.
2.3 Configure the Secure Web Server
After you have installed
the SWS, you are ready to configure it. The configuration tool ensures that a
user account is available to run the server and that all of the files are owned
by that user. It also allows the system manager
flexibility in defining options for the installation.
The configuration procedure gives you the opportunity to separate the server
components —server application, server system files, and server content files —
and store them wherever it is most appropriate in your environment. By default,
they are all configured in SYS$COMMON or the destination you specified on the
PRODUCT INSTALL command line. During configuration you are asked if you would
like to specify different locations.
If you have an OpenVMS Cluster, see
OpenVMS Cluster Considerations before you
continue with the configuration.
2.3.1 Configuration Menu
Version 2.2 of the SWS
includes a configuration menu that allows you to choose configuration functions.
All of the functions listed can be run independently or through the menu driven
procedure. The menu also allows you to start and stop instances of the SWS.
To run the configuration
menu, enter the following command:
$ @APACHE$COMMON:[000000]APACHE$MENU
Following is an example
of the configuration menu:
Apache$Menu
1. Configure the SWS
2. Create an
Apache instance
3. Delete an
Apache instance
4. Manage suEXEC
users
5. Run OpenSSL
Certificate tool
6. Convert directory tree to Stream_LF
7. Start up an Apache instance
8. Shut down an Apache instance
9. Show status of an Apache
instance
10. Add a node to CSWS in a cluster
environment
11. Exit
Enter Menu Choice:
The menu choices correspond to running the following procedures or
commands from the DCL command line:
1. SYS$MANAGER:APACHE$CONFIG.COM
2. APACHE$COMMON:[000000]APACHE$CREATE_ROOT.COM
3. APACHE$COMMON:[000000]APACHE$DELETE_ROOT.COM
4. APACHE$COMMON:[000000]APACHE$MANAGE_SUEXEC.COM
5. APACHE$COMMON:[000000]APACHE$CERT_TOOL.COM
6. APACHE$COMMON:[000000]APACHE$CONVERT_STREAMLF.COM
7. SYS$STARTUP:APACHE$STARTUP.COM
8. SYS$STARTUP:APACHE$SHUTDOWN.COM
9. SHOW SYSTEM/PROCESS=APACHE$tag
10. APACHE$COMMON:[000000]APACHE$ADDNODE.COM
2.3.2
Configuring a Single Server
Choosing Option 1 from the SWS Configuration Menu starts the
following command procedure, which configures a single server:
Most users need only run a single server on a given system. When that server
configuration is started, it usually exists as a main process and multiple child
processes to handle multiple user requests. Those child processes may also
generate subprocesses to handle certain types of
requests (such as CGI scripts).
For information about
configuring multiple servers, see the
Configuring Multiple Servers section.
To configure a single server, enter one of the following commands:
$ @APACHE$COMMON:[000000]APACHE$MENU and select Option 1
2.3.3 Sample Configuration of a Single Server
This section shows a
sample configuration dialog.
$ @SYS$MANAGER:APACHE$CONFIG
HP Secure Web
Server for OpenVMS
[based on Apache]
This procedure helps you define the
operating environment
required to run the Secure Web Server on this system.
To operate
successfully, the server processes must have read access
to the installed files and read-write
access to certain other files
and directories. HP recommends that you use this procedure
to
set the owner UIC on the CSWS files and
directories to match the server.
You should do this each time the product
is installed, but it only has
to be done once for each installation on
a cluster.
Set owner UIC on CSWS files? [YES]
Do you want to enable the impersonation
features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.
Enable suEXEC?
[YES]
Setting ownership on files. This could take a minute or two. . . .
Enabling suEXEC
configuration. This could take a
minute or two. . . .
APACHE$MANAGE_SUEXEC
This procedure allows the system
manager to grant
users the ability to utilize the suEXEC feature of
the Secure Web Server. Users will be granted/revoked
VMS rights identifiers to allow
access.
Continue [YES]?
Enter '?' for help
Manage suEXEC
user accounts (SHOW/GRANT/REVOKE/DONE/?): [DONE] GRANT
Enter Username: USER1
%UAF-I-GRANTMSG,
identifier
APACHE$SUEXEC_USER granted to USER1
Manage suEXEC
user accounts (SHOW/GRANT/REVOKE/DONE/?): [DONE] GRANT
Enter Username: USER2
%UAF-I-GRANTMSG,
identifier
APACHE$SUEXEC_USER granted to USER2
Manage suEXEC
user accounts (SHOW/GRANT/REVOKE/DONE/?): [DONE]
Configuration is complete. To start the server:
$
@SYS$STARTUP:APACHE$STARTUP.COM
2.3.4 Configuring Multiple Servers
For some advanced
configurations it may be necessary to run two or more servers on the same
system. For example, you may decide to run multiple virtual hosts on the same
system and have each virtual host serviced by a separate server.
For each server process,
run the APACHE$CONFIG.COM command procedure to define the OpenVMS operating
environment. In particular, each server must have its own APACHE$SPECIFIC
directory into which it writes its output files.
Version 2.2 of the SWS
supports running multiple servers monitoring different ports. This is
accomplished by defining an alternate root that is defined as APACHE$SPECIFIC.
These instances are created by entering one of the following commands:
$
@APACHE$COMMON:[000000]APACHE$CREATE_ROOT
$
@APACHE$COMMON:[000000]APACHE$MENU
and select Option 2
This procedure defines a
new server root with a different user that runs the server, monitors a different
port, and has unique startup and shutdown procedures. The instance can also be
restricted as to what kinds of privileged routines can be accessed. The user
that is defined is automatically granted access to the APACHE$COMMON area.
2.3.5 Sample Configuration of Multiple Servers
Following is an example
of creating a new server root:
$ @APACHE$COMMON:[000000]APACHE$CREATE_ROOT
APACHE$CREATE_ROOT
Create a set of
directories and files where a Secure
Web Server can
run. You will be prompted for the
location of the root, the user to
run under, the
TCP/IP port to monitor, the unique
server tag, the
privileged
routines the user will be allowed to use,
and optional startup and shutdown procedures.
Continue [YES]?
Root location: Give the location of where to create the
directory
tree and configuration template
file for the new instance of the server.
e.g.
USER2:[SMITH.CSWS]
This will create a series of directories
under the USER2:[SMITH.CSWS]
directory.
This will become the new APACHE$SPECIFIC location.
$ DIRECTORY
USER2:[SMITH.CSWS]
Directory
USER2:[SMITH.CSWS]
BIN.DIR;1
CGI-BIN.DIR;1 CONF.DIR;1
HTDOCS.DIR;1
ICONS.DIR;1
KIT.DIR;1
LOGS.DIR;1
MODULES.DIR;1
OPENSSL.DIR;1
Total of 9 files.
Root Location:
DISK1:[JOE.APACHE]
Username: Enter the user that will
own and control the content of
this root.
The ownership of the directories and files will be set
to the given user. The user must be a valid user in the
SYSUAF.
Username: JOE
The Secure Web Server has several
privileged routines to allow the
server to run in a basic fashion. These routines can be blocked from
other users of the web server to
run in a more restrictive mode.
These routines are protected by a
series of rights identifiers:
APACHE$APR_ALL
Allow access to all of the protected routines
APACHE$APR_CREMBX Allow
access to create a groupwide mailbox
APACHE$APR_GETPWNAM Allow access to
other user's information
APACHE$APR_SETSOCKOPT Allow user to set socket
options
APACHE$APR_SOCKET Allow
creation of a privileged socket
APACHE$APR_AUTH_OPENVMS Allow user to authorize using SYSUAF
APACHE$APR_GALAXY_GBLSEC Allow user to manage galactic memory sections
Grant access to ALL routines?
n
Grant access to
CreMbx? y
Grant access to
GetPwNam? n
Grant access to
SetSockOpt? n
Grant access to Create a
Priveleged
Socket? y
Grant authorization via SYSUAF? y
Grant user ability to access
galactic sections? y
Each instance of the Secure Web
Sever must have a unique TCP/IP port
to monitor as it runs. If you have not granted this user the
Socket
privilege, then the port must be
greater than 1024 (non-privileged).
Note that this routine does not
keep track of previously specified
ports to other instances. It is the system manager's responsibility
to
maintain this information.
Port number: 81
Each instance of the Secure Web
Server must have a unique tag associated
with it on the system. The tag is 1 to 4 characters (A-Z, 0-9).
Unique Tag:
Tst
The instance of Secure Web Server
can have a startup and a shutdown
command procedure defined to run
accordingly.
Define a startup or shutdown
procedure? y
Startup procedure filename [NONE]:
DISK1:[JOE.APACHE]Test_Start.com
Shutdown procedure filename [NONE]:
Granting rights to JOE UAF
account...
Creating directory tree under
DISK1:[JOE.APACHE]
Generating Apache configuration
file DISK1:[JOE.APACHE.CONF]httpd.conf
Updating the configuration database
Root created: DISK1:[JOE.APACHE]
Template server configuration file
created:
DISK1:[JOE.APACHE.CONF]httpd.conf
Please review this file for
accuracy.
The output of this
procedure is a directory tree that matches that found under APACHE$COMMON.
Populated in that tree are three files:
a template configuration file
a mime type file
an SSL configuration file
These are all placed in
the configuration directory and should be reviewed before attempting to start
the server.
2.3.6 Delete Server Instance
Choosing Option 3 from
the SWS Configuration Menu deletes an instance of the server. Choosing this
option starts the following command procedure:
APACHE$COMMON:[000000]APACHE$DELETE_ROOT.COM
An example of the output
from this procedure is as follows:
$ @APACHE$COMMON:[000000]APACHE$DELETE_ROOT
APACHE$DELETE_ROOT
Deletes a
previously defined set of directories and
all files contained therein. Also revokes all user
rights granted when the root was
created.
Continue [YES]?
Apache Instances available for deletion
1.
Tst DISK1:[JOE.APACHE.CONF]httpd.conf
2. Exit
Choice: 1
Revoking rights
from JOE UAF account...
Deleting all files under DISK1:[JOE.APACHE...]
Updating the configuration database...
Root deleted: DISK1:[JOE.APACHE]
2.3.7 Managing suEXEC
Choosing Option 4 from
the SWS Configuration Menu starts the suEXEC management command procedure:
APACHE$COMMON:[000000]APACHE$MANAGE_SUEXEC.COM
Part of the SWS
configuration involves enabling the suEXEC feature. If you enable suEXEC
during configuration, the accounts using the feature are managed from
APACHE$MANAGE_SUEXEC.COM. The APACHE$CONFIG.COM procedure automatically calls
the suEXEC management procedure.
This procedure can also
be run directly (by choosing Option 4) to add or subtract users with the ability
to use suEXEC.
See the
suEXEC in the SWS section for more information.
2.3.8 Running the OpenSSL Certificate Tool
Choosing Option 5 from
the SWS Configuration Menu starts the following command procedure, which runs
the OpenSSL
certificate tool:
APACHE$COMMON:[000000]APACHE$CERT_TOOL.COM
The
OpenSSL certificate tool enables you to view certificates and certificate
requests, create certificate requests, sign your own certificate, create your
own certificate authority, and sign client certificate requests. Additional hash
functions are included.
The
OpenSSL certificate tool is described in the
HP
SWS SSL User Guide.
2.3.9 Converting Files to Stream_LF
Choosing Option 6 from
the SWS Configuration Menu starts the following command procedure, which
converts your files to Stream_LF
format:
APACHE$COMMON:[000000]APACHE$CONVERT_STREAMLF.COM
Note
The SWS Version 2.2 no longer requires that all served files be in Stream_LF format. The EnableMMAP directive must be set to OFF to lift the Stream_LF restriction. In Version 2.2, EnableMMAP is set to OFF by default. (In Version 2.0, the default for EnableMMAP was ON.)
If you want your files in
STREAM_LF format, you can use the APACHE$CONVERT_STREAMLF command procedure to
recursively search down a directory tree for sequential files and convert them
to Stream_LF. The command procedure excludes some
sequential files; in particular, it ignores directory files, executable files
(such as command procedures, OpenVMS images, CGI, PHP, and Perl scripts), object
files, indexed files, and relative files.
The procedure is non-destructive and will create a newer version of the
converted file and leave the original in place. The results of the conversion
are stored in SYS$SCRATCH:CONVERT_DIR.LOG.
Note
The
APACHE$CONVERT_STREAMLF command procedure converts all sequential files (with
the exceptions listed above) to Stream_LF format,
including sequential files currently in Stream format. After you run the
procedure, be sure to check the SYS$SCRATCH:CONVERT_DIR.LOG
file for files that should not be in Stream_LF
format, and delete the newest version of those files.
The following is an
example output of the convert utility:
$ @APACHE$COMMON:[000000]APACHE$CONVERT_STREAMLF
Top Directory:
USER1:[APACHE.HTDOCS]
Starting
conversion of USER1:[APACHE.HTDOCS...]
This could take a
while...
Conversions
complete.
See
SYS$SCRATCH:Convert_Dir.Log
for a log of transactions.
2.3.10 Starting and Stopping the Secure Web Server
Choosing Option 7 and Option 8 from the SWS Configuration Menu runs the
following command procedures which start up and shut down instances of the SWS:
SYS$STARTUP:APACHE$STARTUP.COM
SYS$STARTUP:APACHE$SHUTDOWN.COM
See
Starting and Stopping the Server for more information.
2.3.11 Showing the Status of an Apache
Instance
Choosing Option 9 from
the SWS Configuration Menu runs the following command:
$ 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.
Similarly, child
processes have a process name of the form APACHE$ssssnnnn,
where APACHE$ssss is the server name and nnnn is the child server process number represented
as a hex value.
The SHOW SYSTEM/PROCESS=APACHE$tag command lists a menu of the current
instances of the server. You choose the instance for which you want to see
status
The following is an
example output showing the status of a running server:
Registered Apache Instances
1. SWS
APACHE$COMMON:[CONF]HTTPD.CONF
2. Exit
Choice: 1
Status of SWS
instance of Apache...
OpenVMS V7.3-2 on
node APSERV 1-AUG-2005 15:55:34.09 Uptime 67
Pid Process Name State Pri I/O
CPU
Page flts Pages
2020026D
APACHE$SWS
LEF 6
2526 0 00:00:11.35 839
1016
2020026F
APACHE$SWS0000 LEF 6
2556 0 00:00:12.69 824
979
20200270
APACHE$SWS0001 LEF 6
2530 0 00:00:09.41 834
1010
20200271
APACHE$SWS0002 LEF 6
2493 0 00:00:14.00 811
978
20200272
APACHE$SWS0003 LEF 6
2499 0 00:00:13.66 822
988
20200273
APACHE$SWS0004 LEF 6
2487 0 00:00:12.01 832
1002
20200274
APACHE$SWS0005 LEF 6
2501 0 00:00:15.22 810
994
End status.
The following is an
example output showing the status of a server that has been shut down:
Registered Apache Instances
1. SWS
APACHE$COMMON:[CONF]HTTPD.CONF
2. Exit
Choice: 1
Status of SWS
instance of Apache...
End status.
Choosing Option 10 from
the SWS Configuration Menu starts the following command procedure, which adds a
node to the SWS in a cluster environment.
APACHE$COMMON:[000000]APACHE$ADDNODE.COM
You must log into the system you want to add as a CSWS
cluster member before you choose Option 10. For example, perform the initial
installation and configuration of CSWS on NODE1.
Then log into NODE2 and enter the following commands:
$
@SYS$STARTUP:APACHE$LOGICALS
$ @APACHE$COMMON:[000000]APACHE$MENU
Apache$Menu
1. Configure the Secure Web Server
2. Create an Apache instance
3. Delete an Apache instance
4. Manage suEXEC users
5. Run OpenSSL Certificate
tool
6. Convert directory tree to Stream_LF
7. Start up an Apache instance
8. Shut down an Apache instance
9. Show status of an Apache instance
10. Add a node to CSWS in a cluster environment
11. Exit
Enter Menu Choice: 10
APACHE$ADDNODE
Create a set of directories and files on another node
in a cluster environment for the Secure Web Server. The node name used is that defined by
TCPIP$INET_HOST. A directory by that
name will be created under the APACHE$SPECIFIC: area. The top level directories under
APACHE$COMMON are essentially duplicated here.
A new version of HTTPD.CONF is created in
APACHE$ROOT:[CONF]. This will be
used by default. The common
configuration in APACHE$COMMON:[CONF] remains untouched. Remove this new
configuration if you wish to use the common one.
The rights identifiers for the user account
APACHE$WWW on this node are set to the defaults. If this is a common SYSUAF/RIGHTSLIST,
then the account should be checked as it might be changed.
Continue [YES]?
yes
Granting rights to APACHE$WWW UAF account...
Creating directory tree under
device:[000000.APACHE.SPECIFIC.node-name]
Generating Apache configuration file
device:[000000.APACHE.SPECIFIC.node-name.CONF]httpd.conf
Node node added
successfully
Node specific
directories created: device:[000000.APACHE.SPECIFIC.node-name]
Configuration
files created in: device:[000000.APACHE.SPECIFIC.node-name.CONF]
Please review
these files for accuracy.
Press return to continue...
Exit the configuration menu, and then enter the following
command to start the SWS on NODE2:
$ @sys$startup:apache$startup
2.3.13 Managing Multiple Servers
This section discusses
the issues you may encounter when managing multiple servers.
2.3.13.1 HTTPD.CONF
Because there are multiple servers at work, there must be some
differences in the HTTPD.CONF file for each server.
To create and maintain
multiple HTTPD.CONF files, you rely on the fact that each server has a separate
configuration-specific root directory. You can set the
processwide
logical name APACHE$SPECIFIC to the configuration-specific directory. You then
edit the file APACHE$SPECIFIC:[CONF]HTTPD.CONF.
2.3.13.2 APACHE$SETUP.COM and LOGIN.COM
APACHE$COMMON:[000000]APACHE$SETUP.COM is run for every server (parent and
child) and server instance. This command procedure defines the necessary Apache
symbols and executes any subsequent product setups if they exist (for example,
PHP and Perl). It also defines the CRTL logicals
needed to allow the SWS to run correctly with extended command parsing and file
specifications.
The APACHE$ROOT:[000000]LOGIN.COM command procedure is executed after
APACHE$SETUP.COM and is determined by the LGICMD stored in SYSUAF for the Apache
server user (for example, APACHE$WWW).
The SWS includes
APACHE$SETUP.COM so that each instance of the server can use its own LOGIN.COM
procedure, and not have to maintain server critical definitions.
2.3.14 Viewing the
OpenSSL
Certificate
You need a valid server
certificate to run the SWS in SSL mode. Configuration creates a self-signed
certificate and installs it. If you want to view the certificate before starting
the server, use the OpenSSL
Certificate Tool as described in the
HP SWS SSL User Guide.
After configuring the
SWS, do not start the server. Follow the instructions in the
Post
Configuration Checklist section.
2.4 Post Configuration Checklist
After you configure the
SWS, perform the following tasks to ensure a successful startup:
Configure CSWS_JAVA, if you have just installed it.
Optionally check the CSWS_PHP configuration now or later.
Optionally check the CSWS_PERL configuration now or later
Run AUTOGEN.
Check disk quota.
Check for SET TERMINAL/INQUIRE.
Disable non-interactive login time.
Each of these tasks is
explained below. Once you have completed them, you can test the installation by
starting the SWS.
2.4.1 Configure CSWS_JAVA
If you installed the
CSWS_JAVA module, you must configure it before you can start the server. For
instructions, see the
CSWS_JAVA for HP Secure Web
Server for OpenVMS Installation Guide and Release Notes.
2.4.2 Check the
CSWS_PERL Configuration
You are not required to
configure CSWS_PERL before starting the server. CSWS_PERL is preconfigured with
default values. If you want to change the default configuration, edit APACHE$COMMON:[CONF]MOD_PERL.CONF.
For more information, see
the
CSWS_PERL for HP Secure Web Server for OpenVMS
Installation Guide and Release Notes.
2.4.3 Check the CSWS_PHP Configuration
You are not required to
configure CSWS_PHP before starting the server. CSWS_PHP is preconfigured with
default values. If you want to change the default configuration, edit
APACHE$ROOT:[CONF]MOD_PHP.CONF.
For more information, see
the
CSWS_PHP for HP Secure Web Server for OpenVMS Installation
Guide and Release Notes.
2.4.4 Run AUTOGEN
After the installation,
run SYS$UPDATE:AUTOGEN.COM (AUTOGEN) to evaluate your
system parameters and make adjustments based on your hardware configuration and
system workload. Because of the SWS installation, AUTOGEN will probably increase
the page file size and the number of swap file pages.
2.4.5 Check Disk Quota
If the disk quota is too
low, the SWS will not start. Either raise the disk quota for the user account
APACHE$WWW, or grant the account the EXQUOTA privilege, thus allowing it to
bypass disk quota restrictions. Use the following commands:
$ SHOW QUOTA/USER=[server-uic]/DISK=device-name
$ SET DEFAULT SYS$SYSTEM
$ RUN AUTHORIZE
$
MOD APACHE$WWW/PRIV=EXQUOTA
$
EXIT
Stop and restart the SWS
so that the APACHE$WWW account picks up the new privilege.
2.4.6 Check for SET TERMINAL/INQUIRE
When the SWS for OpenVMS
is started, the command procedure APACHE$SETUP is executed. The following login
files are executed:
·
SYLOGIN.COM (system login file)
·
LOGIN.COM (login file for APACHE$WWW)
Check these files to make
sure that any SET TERMINAL/INQUIRE statements are executed only in INTERACTIVE
mode. For example:
$
IF F$MODE() .eqs
"INTERACTIVE" then $ SET TERMINAL/INQUIRE
Failure to do so might
result in ill-formed HTML intermittently being returned to clients. This problem
might also appear when executing CGI scripts.
2.4.7 Disable Non-interactive Login Time
To disable non-interactive login time update feature define the following logical:
$ DEFINE/SYSTEM APACHE$UAF_LOGINUPDATE_RATE -1
The SSL/TLS-aware
Apache webserver was
successfully
installed on this website."
The Apache logo is
displayed at the bottom.
2.5.2 TELNET Test
You can also use TELNET
on the local host to test the installation.
(In TCP/IP Services Version 5.3 for OpenVMS and higher, user input is not
echoed.
Use the following
procedure to test the installation.
Enter the following
command:
$
TELNET 0 80
The following text is
displayed:
%TELNET-I-SESSION, Session 01, host
localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
Press ENTER
and enter the following HTTP command:
HEAD / HTTP/1.0
Press ENTER twice. Text
similar to the following is displayed:
HTTP/1.1 200 OK
Date: Wed, 21 Sep 2005
Server: Apache/2.0.52 (OpenVMS) mod_ssl/2.0.52
OpenSSL/0.9.7d
Content-Location:
index.html.en
Vary:
negotiate,accept-language,accept-charset
TCN: choice
Last-Modified: Thu, 08 Sep 2005
ETag: "2e4550-5b2-b12cef40"
Accept-Ranges: bytes
Content-Length: 1458
Connection: close
Content-Type: text/html; charset=ISO-8859-1
Content-Language: en
%TELNET-S-REMCLOSED, Remote
connection closed
-TELNET-I-SESSION, Session 01,
host localhost, port 80
$
You should receive
several lines of text from the SWS.
2.5.3 Troubleshooting
If you do not receive a
response from the SWS, check the following:
Look in your SYLOGIN.COM file and make sure there is no SET TERMINAL/INQUIRE statement for NETWORK processes.
Make sure the APACHE$WWW account exists and is not disabled.
Look for the following files:
APACHE$ROOT:[000000]APACHE$tag
APACHE$ROOT:[LOGS]ERROR_LOG
If you have trouble starting the server, enable the logical
APACHE$SPL_DISABLED systemwide, then
restart the
server.
If you have trouble stopping the server using the APACHE$SHUTDOWN command and APACHE$WWW is still running, use the following command to stop it. You should then be able to shut down the server.
$ STOP PROCESS/ID=<apache-pid>
2.6 What's Next
After you have
successfully tested the installation, perform any of the following tasks that
are relevant for you:
·
If you are upgrading from a previous version of the SWS, you can
merge the previous versions of files commonly
modified by system administrators
with the newly installed versions of these files. See the
Merge
Changes to
Files You Have Customized section.
·
If you enabled MOD_SSL, follow the instructions for verifying SSL
in the
HP
Secure Web Server SSL User Guide.
·
Read
Chapter 3 for information on starting and
stopping the server, using HTTPD.CONF to customize the server
environment, and
other OpenVMS specific topics.
2.7 Merge
Changes to Files You Have Customized
If you have installed a
previous version or field test kit of the SWS, it is removed automatically
before the new kit is installed.
When the previous version
of the SWS is removed, the PCSI utility removes only the files and directories
it installed. Any files you have created are not affected.
Note
Files installed by the SWS that are commonly modified by system administrators are not removed. However, the new kit contains updated versions of these files. Be sure to transfer any edits you made to the previous versions of these files to the new versions.
These commonly modified
files are as follows:
·
[APACHE]LOGIN.COM
·
APACHE.HTDOCS]INDEX.HTML
·
[APACHE.CONF]HTTPD.CONF
If you modified the file
[APACHE.CONF]MIME.TYPES, you need to 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.)
The new kit contains an
updated version of this file. After you save your current version, restore the
file and incorporate your local modifications with the new version.
2.8 Installing Optional Modules at a
Later Time
If you did not install
the optional modules (CSWS_JAVA, CSWS_PERL, or CSWS_PHP) when you installed the
server, follow these instructions for installing them at a later time. Before
you begin, make sure:
·
You have installed the required software.
·
You have already installed the SWS.
· You install CSWS_PHP in the same directory as you installed the server. You do not need to install CSWS_JAVA or CSWS_PERL into the same disk or directory as the SWS.
Use the appropriate
command from the list below.
To install CSWS_JAVA, use the following command:
$ PRODUCT INSTALL CSWS_JAVA
/DESTINATION=device:[directory-name]
To install CSWS_PHP, use
the following command:
$ PRODUCT INSTALL
CSWS_PHP/DESTINATION=device:[directory-name]
To install CSWS_PERL, use
the following command:
$ PRODUCT INSTALL
CSWS_PERL/DESTINATION=device:[directory-name]
The installation is
complete when the dollar sign prompt ($) is displayed.
After you install
CSWS_JAVA, you must configure it. For more information, see
Configure
CSWS_JAVA.
CSWS_PHP and CSWS_PERL
are preconfigured, but you can change the configurations. For more information,
see
Check the CSWS_PHP Configuration and
Check the CSWS_PERL
Configuration.
Chapter 3
Running the Secure Web Server on OpenVMS
In general, you can run
the SWS 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.
3.1 Starting and Stopping the Server
Starting and stopping the
SWS requires enhanced privileges (DETACH, SYSNAM, WORLD, etc.). Start and stop
the server from a privileged account such as SYSTEM.
3.1.1
Starting the Server
Start the SWS with the
following command:
$
@SYS$STARTUP:APACHE$STARTUP [startup-value] [configuration-file]
Startup-value is optional and can have
the following values:
|
Value |
Description |
|
START
|
Creates the SWS as a detached network process; default value |
|
GRACEFUL
|
Sends a restart signal to the server, but existing client connections are
not interrupted. Idle child processes are immediately deleted and replaced.
Busy child processes are replaced when the connection is terminated |
|
RESTART
|
Sends a restart signal to the server to have it reread
APACHE$ROOT:[CONF]HTTPD.CONF
|
|
RUN
|
Runs the server on the current process |
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 SWS 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'
3.1.2
Stopping the Server
You can shut down the SWS
with the following command:
$
@SYS$STARTUP:APACHE$SHUTDOWN [startup-value] [configuration-file]
Startup-value is optional and can have
the following values:
|
Value |
Description |
|
GRACEFUL
|
Sends a restart signal to the server, but existing client connections are
not interrupted. Idle child processes are immediately deleted and replaced.
Busy child processes are replaced when the connection is terminated |
|
RESTART
|
Sends a restart signal to the server to have it reread
APACHE$ROOT:[CONF]HTTPD.CONF
|
|
SHUTDOWN
|
Stops the detached network process; default value |
|
STOP
|
Same as SHUTDOWN |
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 SWS 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'
Note
The SWS 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]
3.1.2.1 Stopping the Server Using the Server Process Name
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.
You should then be able
to shut down the server by entering the following command:
$
STOP PROCESS/ID=<apache-pid>
The server log file for APACHE$WWW is written to:
APACHE$SPECIFIC:[000000]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.
Similarly, child
processes have a process name of the form APACHE$ssssnnnn,
where APACHE$ssss is the server name and nnnn is the child server process number represented
as a hex value. For example:
Parent
APACHE$SWS
Child 1
APACHE$SWS0000
Child 2
APACHE$SWS0001
Child 3
APACHE$SWS0002
You should have prior
experience tuning the performance of the OpenVMS operating system. For general
information on OpenVMS performance, see the OpenVMS Performance Management
Manual in the OpenVMS documentation website.
Recommendations for
improving performance on a SWS are provided in the following sections.
3.3.1 Limits and Quotas
The following table shows
sample values for the APACHE$WWW system user account (SYSUAF) from a working and
exercised SWS with a light to moderate load. These values are presented as an
example of a system performing well within its context.
If you should experience
performance difficulties, refer to this table for guidelines in making
adjustments. For heavier loads, we point out which values, in our experience,
need to be increased as load increases. Keep in mind that no one set of values
will be appropriate for all situations.
|
Parameter |
Default |
On SWS |
|
ASTLM (NonPooled) |
250
|
610
Or BIOLM + DIOLM + 10 |
|
BIOLM (NonPooled) |
150
|
300
You might also need to
increase the SYSGEN parameter CHANNELCNT because it limits BIOLM,DIOLM, and
FILLM. |
|
BYTLM (Pooled) |
64000
|
200000
Increase this value for
a heavy load. |
|
DIOLM (NonPooled) |
150
|
300
You might also need to
increase the SYSGEN parameter CHANNELCNT because it limits BIOLM,DIOLM, and
FILLM. |
|
ENQLM (Pooled) |
2000
|
2000
|
|
FILLM (Pooled) |
100
|
300
Increase this value for
a heavy load. You might also need to increase the SYSGEN parameter
CHANNELCNT because it limits BIOLM,DIOLM, and FILLM. |
|
JTQUOTA (Pooled) |
4096
|
8192
|
|
PGFLQUO (Pooled) |
50000
|
250000
If you increase PGFLQUO,
you should monitor the free size of the system page and swap files; they may
need to be increased. |
|
PRCLM (Pooled) |
8
|
20
You should increase this
value for a heavy load. |
|
TQELM (Pooled) |
10
|
610
Or BIOLM + DIOLM + 10 |
To change the quotas for
the APACHE$WWW SYSUAF, use the system manager account and run the AUTHORIZE
utility. For example:
$ SET DEFAULT SYS$SYSTEM
$ RUN AUTHORIZE
UAF> SHOW APACHE$WWW
Username:
APACHE$WWW
Owner: APACHE WEBSERVER
...
Maxjobs: 0
Fillm: 100 Bytlm: 64000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm:
0
Prclm:
8 DIOlm: 150
WSdef: 2000
...
UAF>
MODIFY APACHE$WWW/FILLM=300/PRCLM=20
%UAF-I-MDFYMSG,
user record(s) updated
UAF>
EXIT
$
Periodically, check the
server’s log file for errors of the "cannot open" variety. Errors of this type
often indicate you need to modify system parameters. Try the following:
·
Set FILLM to limit the number of files a user's process can have
open.
·
Set the SYSGEN parameter CHANNELCNT to 1024 (unless it is already
set to a higher value).
Note
Whenever you change
system parameters, you must reboot the system to enable the new settings.
3.3.3 Global Pages and Global Sections
If a browser installation
stalls, this could be an indication that the number of global pages or global
sections is too low. Run AUTOGEN to evaluate the number of global pages and
global sections you need. Some browsers might need more.
3.3.4 Excessive File Build Up
A large number of .LOG
and .PID files can amass over time in the directories APACHE$ROOT:[000000]
and APACHE$ROOT:[LOGS]. Purging these files can become a burden on application
or system managers.
System managers should
manually use explicit SET DIRECTORY/VERSION commands on these two directories.
3.4 Customizing the Server Environment
The installation
procedure creates a file named HTTPD.CONF and places it in APACHE$ROOT:[CONF].
The HTTPD.CONF file stores information that the SWS uses to set up the server
environment. HTTPD.CONF has been tailored to use OpenVMS syntax, but its overall
functionality is essentially identical to HTTPD.CONF on the UNIX platform.
HTTPD.CONF contains an
explanation for each line that it can execute. You can refer to these
explanations when customizing the file for your environment. You can also refer
to any generally available Apache documentation on HTTPD.CONF.
Note the following about
HTTPD.CONF on OpenVMS:
·
No directives have been deleted or added to the Apache template
except an Include directive for MOD_SSL.
Installing CSWS_JAVA, CSWS_PHP, or
CSWS_PERL will also append Include directives specific to these
modules.
·
MOD_OSUSCRIPT has been added to enable CGI scripts originally
written for the OSU server.
·
MOD_AUTH_OPENVMS enables authentication using OpenVMS usernames and
passwords.
·
UNIX style path names are recognized by OpenVMS. You can use either
UNIX style or OpenVMS style path names in the configuration file. However, you
cannot intermix the two styles within a specification. HP recommends UNIX style
path names.
·
In an OpenVMS cluster, you can specify either
clusterwide
or system-specific files. For more information, see Individual System vs.Clusterwide Definition.
Following is a list of
the modules included in the SWS for OpenVMS Version 2.2 kit. The SWS Version 2.2
includes all of the Apache 2.0 modules and directives as well as two
OpenVMS-specific modules, MOD_AUTH_OPENVMS and MOD_OSUSCRIPT. The Apache modules
and directives function as documented in
Apache Version 2.0 Modules and
Apache Version 2.0 Directives.
The server documentation from the
Apache Software Foundation
provides the information needed to use the modules and directives.
Note
In SWS Version 2.2, many loadable modules are no longer loaded by default. You must uncomment the modules in httpd.conf to load them. (See the file httpd-vms.conf for other modules you may want to load.)
All modules are loadable,
with the exception of those that are marked as built into the server.
CORE
(Built into server)
HTTP_CORE
(Built
into server)
MOD_ACCESS
MOD_ACTIONS
MOD_ALIAS
MOD_AUTH_ANON
MOD_ASIS
MOD_AUTH
MOD_AUTH_DBM
MOD_AUTH_DIGEST
MOD_AUTH_KERB
MOD_AUTH_LDAP
MOD_AUTH_OPENVMS (OpenVMS
specific)
MOD_AUTOINDEX
MOD_CACHE
MOD_CASE_FILTER
MOD_CASE_FILTER_IN
MOD_CERN_META
MOD_CHARSET_LITE
MOD_CGI
MOD_DAV
MOD_DAV_FS
MOD_DEFLATE
MOD_DIR
MOD_DISK_CACHE
MOD_ECHO
MOD_ENV
MOD_EXAMPLE
MOD_EXPIRES
MOD_FILE_CACHE
MOD_EXT_FILTER
MOD_HEADERS
MOD_IMAP
MOD_INCLUDE
MOD_INFO
MOD_LOG_CONFIG
MOD_LOGIO
MOD_MIME
MOD_MIME_MAGIC
MOD_NEGOTIATION
MOD_OSUSCRIPT
(OpenVMS
specific)
MOD_PROXY
MOD_PROXY_CONNECT
MOD_PROXY_FTP
MOD_PROXY_HTTP
MOD_REWRITE
MOD_SETENVIF
MOD_SO
(Built into server)
MOD_SPELING
MOD_SSL
MOD_STATUS
MOD_SUEXEC
MOD_UNIQUE_ID
MOD_USERDIR
MOD_USERTRACK
MOD_VHOST_ALIAS
PREFORK
(Built into server)
3.5.2 Apache 1.3 Modules Not Included
The following modules
were part of the Apache 1.3 stream, but are not included in Apache 2.0.
Therefore, these modules are not included in the SWS Version 2.2 kit.
·
MOD_AUTH_DB
·
MOD_DEFINE
·
MOD_ISAPI
·
MOD_LOG_AGENT
·
MOD_LOG_REFERER
·
MOD_MMAP_STATIC
The following directives
are specific to the SWS for OpenVMS.
VMSServerTag
This directive is a
replacement for the APACHE$SERVER_TAG logical name used in the SWS Version 1.3.
This required directive distinguishes multiple instances of the Apache server,
and contains between 1 and 4 alphanumeric characters. This server tag will be
used in the server process names for the given instance (for example,
APACHE$SWS).
Default:
SWS
Example: VMSServerTag SWS1
VMSServerStartup
This directive is a
replacement for the APACHE$SERVER_STARTUP logical name used in the SWS Version
1.3. This optional directive specifies a user-developed command procedure that
should be executed prior to the activation of each Apache server process.
Default: none
Example:
VMSServerStartup APACHE$COMMON:[000000]APACHE$SERVER_STARTUP.COM
VMSServerShutdown
This directive is a
replacement for the APACHE$SERVER_SHUTDOWN logical name used in the SWS Version
1.3. This optional directive specifies a user-developed command procedure that
should be executed after the activation of each Apache server process.
Default: none
Example:
VMSServerShutdown APACHE$COMMON:[000000]APACHE$SERVER_SHUTDOWN.COM
This section describes
the command line options supported in the SWS. You must run APACHE$SETUP.COM
before using the command line interface or any other Apache image (such as
htpasswd), as follows:
$
@APACHE$COMMON:[000000]APACHE$SETUP
You can use the command
line interface for managing multiple servers or for performing complex
operations. HP recommends using the startup and shutdown procedures for simple
management of a single server environment. See Starting and Stopping the
Server for more information.
Use the following format
to enter a command line option:
$
HTTPD –option
where
-option is one of the following:
|
Option |
Description |
|
-D name |
Define a name for use in directives |
|
-d directory |
Specify an alternate initial ServerRoot |
|
-f file |
Specify an alternate ServerConfigFile |
|
-C "directive" |
Process directive before reading config files |
|
-c "directive" |
Process directive after reading config files |
|
-e level |
Show startup errors of level (see LogLevel) |
|
-E file |
Log startup errors to file |
|
-v |
Display the HTTPD version and its build date |
|
-V |
Display the HTTPD base version, its build date, and a list of compile
settings that influence the behavior and performance of the server |
|
-h |
Display a list of the HTTPD options |
|
-l |
Display a list of all modules compiled into the server |
|
-L |
Display a list of directives with expected arguments and places where the
directive is valid |
|
-t -D DUMP_VHOSTS |
Show parsed settings (currently only vhost settings) |
|
-S |
A synonym for -t -D DUMP_VHOSTS |
|
-t |
Run syntax check for config files |
Enter the following
command to see a list of available options, as follows:
$
httpd
-?
Usage:
dka200:[apache]apache$httpd.exe;1 [-D name] [-d directory] [-f file]
[-C "directive"]
[-c "directive"]
[-k
start|restart|graceful|stop]
[-v] [-V] [-h]
[-l] [-L] [-t] [-S]
Options:
-D name
: define a name for use in directives
-d directory : specify an
alternate initial ServerRoot
-f file
: specify an alternate ServerConfigFile
-C "directive" : process directive before
reading config files
-c "directive" : process directive after
reading config files
-e level
: show startup errors of level (see LogLevel)
-E file
: log startup errors to file
-v
: show version number
-V
: show compile settings
-h
: list available command line options (this page)
-l
: list compiled in modules
-L
: list available configuration directives
-t -D DUMP_VHOSTS : show parsed settings
(currently only vhost settings)
-S
: a synonym for -t -D DUMP_VHOSTS
-t
: run syntax check for config files
3.5.5 Virtual
Host Support
The term
virtual host
refers to the practice of maintaining a single server to serve pages for
multiple virtual hosts. Both IP-based and name-based virtual host support are
available on the SWS for OpenVMS.
Note
On OpenVMS, the security
profile of the running server is the same on all virtual hosts.
For more information, see
Apache Virtual Host Documentation.
3.5.6 Dynamic Shared Object Support
Dynamic shared object
support provides a way to format code so that it will load into the address
space of an executable program at run time. This functionality is supported on
OpenVMS.
For more information, see
Dynamic Shared Object (DSO) Support.
The SWS for OpenVMS
supports the ability to use file handlers explicitly.
3.5.8 Content Negotiation
The MOD_NEGOTIATION
module provides content negotiation. This module lets you specify language
variants of HTML files.
Note
Beginning with the SWS
Version 2.0, you must specify language variants on OpenVMS systems in the same
way as you do on UNIX systems, using multiple dots in the filename. For example,
the French variant of a filename is
filename.html.fr.
In previous versions of
the SWS, you would use an underscore instead of a dot before the language
extension (for example,
filename.html_fr).
For more information, see
Content Negotiation Documentation.
3.5.9 Apache API
You can use the standard
Apache API to write your own modules that will run on the SWS for OpenVMS. For
more information, see
Apache API Documentation.
The SWS for OpenVMS
includes MOD_DAV to provide DAV (Distributed Authoring and Versioning)
capabilities.
DAV is a set of
extensions to the HTTP protocol that allows users to collaboratively edit and
manage files on remote web servers using DAV-enabled client applications.
MOD_DAV is an Apache module that provides DAV capabilities (RFC 2518) for the
Apache web server.
Note
To change the database
manager type, set the logical name APACHE$DAV_DBM_TYPE so that it is visible to
Apache, such as in APACHE$COMMON:[000000]LOGIN.COM.
For more information, see the
MOD_DAV website.
3.5.10.1 Testing DAV Operation
You can test DAV
operation using Microsoft Internet Explorer.
Recent versions of
Windows come DAV-enabled. Older versions, such as Windows NT 4.0, require
Internet Explorer 5.5 or later. You may need to DAV-enable Internet Explorer 5.5
using the Control Panel application's Add/Remove Programs option. Double-click
on Microsoft Internet Explorer 5.5 and Internet Tools, and select Add Component
and click OK. Scroll down to Web Publishing Components and select Web Folders
and complete the configuration.
Run Internet Explorer and
select File/Open. Select "Open as web folder" and enter the URL of the DAV
folder (for example: http://your-server/webdav/). Internet Explorer will open
your DAV folder and display its contents. In addition, Windows Explorer may now
show a Web Folders folder that you can use like a local or network drive.
Note
Not all Windows
applications are DAV-enabled. Recent versions of Microsoft Word and Microsoft
Office are DAV-enabled, which may allow you to open and edit a DAV document
directly in the application. For other applications, you may need to copy the
DAV file to a local directory in Windows, edit the document and copy it back to
the DAV folder using Windows Explorer.
The
suEXEC feature provides the ability to run CGI programs under user IDs
different from the user ID of the calling web server.
See
suEXEC in
the SWS for configuration information.
3.5.12 MOD_SSL
You can improve SSL cache performance in a Galaxy cluster by
placing a memory-based SSL session cache in a Galaxy shared-memory partition.
After the partition is created, use the steps in the following section to
configure SWS to use the Galaxy partition for the session cache.
3.5.12.1
Setting up a Galaxy Shared-Memory SSL Session Cache
The SSLSessionCache directive on
all GALAXY members must be the same:
SSLSessionCache cshm:logs/ssl_scache(512000)
SSLMutex csem:<anythingyouwant>
These directives create the Galaxy global section APACHE$SSL_CSHM_logs/ssl_scache and use the
APACHE$SSL_CSHM_<anythingyouwant> mutex to synchronize access to the section. The number in
parentheses is the size in bytes of the cache.
These directives are supported only
when the system is running as both a Galaxy member and a member of a cluster.
3.5.13 Running MOD_OSUSCRIPT
The SWS for OpenVMS
provides a CGI script environment. However, it also includes MOD_OSUSCRIPT, an
optional module that enables the server to run scripts that were written for the
OSU http server's script environment (which is not CGI).
Note
Apache logical names must
be defined systemwide (not processwide) in order for MOD_OSUSCRIPT to work properly.
MOD_OSUSCRIPT does not
need to communicate with a running OSU server to work properly. It needs only
the following OSU http distribution files:
·
WWWEXEC.COM
·
CLI_ENV_RM.COM
·
CGI_SYMBOLS.EXE
·
MINIPERL.EXE
The
WWW_SYSTEM:MINIPERL.EXE image is required unless you use a different Perl
interpreter. To use the Perl interpreter provided with CSWS, define the
following foreign command in APACHE$ROOT:[000000]LOGIN.COM:
$ PERL :==
$PERL_ROOT:[000000]PERL.EXE
You can download and
install these files to run and test OSU scripts, as follows:
1. Create a directory for the OSU script
files with the following command. The
APACHE$WWW
username must be able to read this directory and its files.
$
CREATE/DIRECTORY device:[directory.BIN]
2. Create a logical name pointing to the OSU
script root directory, as follows:
$
DEFINE/SYSTEM WWW_ROOT device:[directory.]/TRANS=CONCEAL
3. Copy CLI_ENV_RM.COM and CGI_SYMBOLS.EXE
from an OSU system to the
following
location. (CLI_ENV_RM.COM can be extracted from the OSU source code
distribution
found at http://www.er6.eng.ohio-state.edu/www/targazer/, but
CGI_SYMBOLS.EXE must be compiled and linked.)
WWW_ROOT:[BIN]
4. Copy WWWEXEC.COM from an OSU system to
the following location, or extract it
from the OSU
source code distribution*:
APACHE$ROOT:[000000]
Note
The standard version of
WWWEXEC.COM does not support the use of Alias/<Directory> directives. You must
use a <Location> container with mod_osuscript.
5.
Use the SHOW SECURITY command to ensure that APACHE$WWW can read these
files. If needed,
use the SET SECURITY command to change the security settings.
6. Edit HTTPD.CONF to add the following
lines:
<Location /htbin>
SetHandler osuscript-handler
OSUscript
0::"0=WWWEXEC" www_root:[bin]
Order allow,deny
Allow from all
</Location>
DECnet
Phase IV node name.
$ SET DEFAULT SYS$SYSTEM
$ RUN AUTHORIZE
UAF>
ADD/PROXY node::APACHE$WWW
APACHE$WWW/DEFAULT
UAF> EXIT
If you are running
DECnet-Plus, replace
namespace:.abc.xyz with your system's full
name, for
example, DEC:.ZKO.NODE22::APACHE$WWW.
$ SET DEFAULT SYS$SYSTEM
$
RUN AUTHORIZE
UAF>
ADD/PROXY namespace:.abc.xyz::APACHE$WWW
APACHE$WWW/DEFAULT
UAF>
EXIT
8. To
use MOD_OSUSCRIPT, you must load the image during Apache startup by
uncommenting
the following line in the APACHE$COMMON:[CONF]HTTPD.CONF
file supplied by
the installation (or add the uncommented line to your existing
configuration
file):
#LoadModule
osuscript_module modules/mod_osuscript.exe
9. To test, execute the simple OSU script CLI_ENV_RM.COM. To do this, replace myhostname in the following URL
with your server's domain name:
http://myhostname/htbin/CLI_ENV_RM.COM
MOD_OSUSCRIPT does the
following:
1.
Opens a DECnet connection using task 0
for the APACHE$WWW username entered in the proxy command.
2.
Executes WWWEXEC.COM using the default HTTPD.CONF directives.
3.
Searches the WWW_ROOT:[BIN] directory for
the script name entered in the URL.
MOD_OSUSCRIPT supports
all of the script server protocol commands, except the following:
·
<DNETREUSE> Reuse logical link for subsequent scripts.
·
<DNETINVCACHE> Invalidate internal cache (the SWS does not have a
cache).
·
<DNETMANAGE> Send management command, OSU server specific.
· <DNETFORCEKA> Put client link in keep-alive mode.
3.6 File
Formats
The SWS Version 2.2 kit
no longer requires
all served files to be in Stream_LF format. If you
still want your files in Stream_LF format, see
Converting files to Stream_LF for information about a
command procedure that automatically converts your files.
The EnableMMAP
directive must be set to OFF to lift the Stream_LF
restriction. In Version 2.2, EnableMMAP is set to OFF by default. (In Version 2.0, the default for
EnableMMAP was ON.)
Note
In the SWS Version 2.2, the Web browser status bar shows page
loading progress, which requires an accurate byte count. To obtain an
accurate byte count for Variable and VFC format files, the SWS reads each file
twice. You can get better efficiency
from a Stream_LF format file because the SWS reads it
only once.
3.7 Managing
File and Directory Access Controls
The OpenVMS operating
system controls read/write/execute/delete access to files and directories at two
levels. (See the
OpenVMS Guide to System Security for more details on the OpenVMS security model.)
These two levels are as follows:
·
System:Owner:Group:World (SOGW) protection
through user/group identifier codes (UIC) based on file ownership.
This is
conceptually similar to standard UNIX file protection.
·
User-id/access pairs stored as Access Control Entries (ACE) within
a file's (or directory's) Access Control List
(ACL). ACLs can be used to provide fine-grained access control to files and directories that are not owned by the
user who is attempting access.
When the SWS is
installed, all files and directories under the APACHE$ROOT:[*...] directory tree are owned by the SWS UIC
[AP_HTTPD,APACHE$WWW]. Most of these files and directories are given the SOGW
protection of (S:RWED,O:RWED,G,W), which allows read+write+execute+delete
access to system and owner UICs ([SYSTEM] and
[AP_HTTPD,APACHE$WWW]). This allows the SWS processes to access their own files
and directories.
There are instances when
you will need to modify file and directory protections. In most cases, you
should use ACLs to grant or deny access, because
ACLs provide you better control and security. In general,
you should not modify file and directory UICs unless
there is good reason to do so.
The following sections
explain situations when you need to modify file and directory protections.
3.7.1 Outbound Access to Non-CSWS Files
and Directories
If, for example, you
allow users to host document files from their home directories (see the
UserDir directive
for more information), and you have the following directive defined in your
HTTPD.CONF file:
UserDir
public_html
In this case, a user is
allowed to define a subdirectory called
public_html under their default
login directory (for example, [JOE.PUBLIC_HTML]). For SWS to serve those
documents from that directory, it needs access to that directory and its
contents, as well as all upper-level directories leading to it.
The correct way to
accomplish this for user "Joe" is as follows:
$ SET SECURITY/ACL=(IDENT=APACHE$WWW,ACCESS=READ)
-
_$ dev:[000000]JOE.DIR
$ SET
SECURITY/ACL=(IDENT=APACHE$WWW,ACCESS=READ+EXECUTE) -
_$ dev:[JOE]PUBLIC_HTML.DIR
$ SET
SECURITY/ACL=(IDENT=APACHE$WWW,ACCESS=READ+EXECUTE) -
_$ dev:[JOE.PUBLIC_HTML]*.*
When accessing SWS files
and directories from another user account (UIC), make sure the ACL for the
target directory and file allows access by that UIC.
For example, if you are
performing a File Transfer Process (FTP) operation to transfer new files to a
CSWS directory, protect the files as follows:
$ SET SECURITY/ACL=(IDENTIFIER=yourFTPname,ACCESS=READ+WRITE) -
_$ [directory]
$ SET
SECURITY/ACL=(IDENTIFIER=yourFTPname,ACCESS=READ+WRITE) -
_$
[directory]*.*
3.8 Logical
Names
The SWS for OpenVMS
creates the following logical names.
|
Logical Name
|
Description
|
|
APACHE$APU_SHR |
System executive mode
logical name that points to the Apache Runtime Utility shared image that
provides common utility routines needed by the SWS.
If no logical is
specified, the default is APACHE$COMMON:[000000]APACHE$APU_SHR.EXE.
|
|
APACHE$APR_SHR |
System executive mode logical name that points to the Apache Runtime Utility shared image that provides common routines needed by the SWS.
If no logical is
specified, the default is APACHE$COMMON:[000000]APACHE$APR_SHR.EXE.
|
|
APACHE$APR_SHRP |
System executive mode
logical name that points to the Apache Runtime protected shared image which
provides privileged access routines needed by the SWS.
If no logical is
specified, the default is APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE.
|
|
APACHE$COMMON
|
Concealed logical name
that defines clusterwide files in APACHE$ROOT (device:[APACHE]).
|
|
APACHE$HTTPD_SHR |
System executive mode logical name that points to the Apache HTTPD shared image that provides server routines needed by the SWS.
If this logical is not
set, the default is APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE.
|
|
Logical Name
|
Description
|
|
APACHE$ROOT
|
System executive mode
logical name defined during startup that points to the top-level directory.
(device:[APACHE], device:[APACHE.SPECIFIC.node-name]).
|
|
APACHE$SERVER_PID |
Created by the
APACHE$CONFIG.COM READ function to identify the running server process that
corresponds to a particular configuration file. This logical name is
equivalent to the process ID of the running server, or a blank space (" ")
if there is no running server for the specified configuration file.
|
|
APACHE$SERVER_TAG
(Obsolete in Version 2.x) |
Defines the currently
running server's tag and is intended for reference only. This logical
contains the 1-4 character server tag defined via the VmsServerTag
directive. If no logical is
specified, the default is SWS.
|
|
APACHE$SPECIFIC
|
Concealed logical name
that defines system-specific files in APACHE$ROOT
(device:[APACHE.SPECIFIC.node-name]).
|
Note
The APACHE$COMMON,
APACHE$SPECIFIC, and APACHE$ROOT logical names are no longer defined
systemwide. They are process logical names defined for each server
process and its child processes.
Because the SWS supports
multiple server processes on the same system, each server process can have its
own definitions for these logical names. Therefore, these logical names cannot
be made systemwide.
The process logical names
are made by APACHE$CONFIG.COM, APACHE$STARTUP.COM, and APACHE$SHUTDOWN.COM. You
can edit a clusterwide
version of HTTPD.CONF by entering the following command:
$
EDIT APACHE$COMMON:[CONF]HTTPD.CONF
If you attempt to use the
preceding command on a process that has not run APACHE$CONFIG.COM,
APACHE$STARTUP.COM, or APACHE$SHUTDOWN.COM, the command will fail because the
logical name APACHE$COMMON is not defined for that process.
|
Logical Name
|
Description
|
||||||||
|
APACHE$BG_PIPE_BUFFER_SIZE
|
System logical name that
is used to set the socket pipe buffer size for exec functions.
If this logical is not
set, the default is 32767.
|
||||||||
|
APACHE$CGI_BYPASS_OWNER_
CHECK |
If defined to any value,
this logical name causes the SWS to bypass the file owner check of the CGI
script file. The default is to enforce the owner check on CGI script files
for security purposes.
|
||||||||
|
APACHE$CGI_MODE
|
System logical name that
controls how CGI environment variables are defined in the executing CGI
process. There are three different options. Note that only one option is
available at a time.
|
||||||||
|
|
|
||||||||
|
APACHE$CREATE_SYMBOLS_
GLOBAL
|
If defined, this system
logical name causes CGI environment symbols to be defined globally. They are
defined locally by default.
|
||||||||
|
APACHE$DAV_DBM_TYPE |
Used to define the
desired DBM organization to use for MOD_DAV. The valid options for this
logical are: GDBM, SDBM, VDBM.
If this logical is not
set, the default is VDBM.
|
||||||||
|
APACHE$DEBUG_DCL_CGI
|
If defined, this system
logical name enables APACHE$VERIFY_DCL_CGI and APACHE$SHOW_CGI_SYMBOL.
|
||||||||
|
APACHE$DL_CASE |
System logical name that
controls how Apache will locate shareable entry points. There are four
different options. Note that only one option is available at a time.
|
||||||||
|
|
|
||||||||
|
APACHE$DL_FORCE_UPPERCASE
|
If defined to be true
(1, T, or Y), this system logical name forces case-sensitive dynamic image
activation symbol lookups. By default, symbol lookups are first done in a
case-sensitive manner and then, if failed, a second attempt is made using
case-insensitive symbol lookups. This fallback behavior can be disabled with
APACHE$DL_NO_UPPERCASE_FALLBACK.
|
||||||||
|
APACHE$DL_NO_UPPERCASE_
FALLBACK |
If defined to be true
(1, T, or Y), this system logical name disables case-insensitive symbol name
lookups whenever case-sensitive lookups fail. See APACHE$DL_FORCE_UPPERCASE.
|
||||||||
|
APACHE$FIXBG |
System executive mode logical name pointing to installed, shareable images. Not intended to be modified by the user. Replaced by APACHE$SET_CCL.EXE. |
||||||||
|
APACHE$FLIP_CCL |
Used by APACHE$SET_CCL.EXE, which replaces APACHE$FIXBG.EXE. |
||||||||
|
APACHE$INPUT
|
Used by CGI programs for
PUT/POST methods of reading the input stream.
|
||||||||
|
APACHE$MB_PIPE_BUFFER_SIZE
|
Used to set the mailbox
pipe buffer size for exec functions.
If this logical is not
set, the default is 4096.
|
||||||||
|
APACHE$PLV_ENABLE_<username>
|
System executive mode
logical name defined during startup and used to control access to the
services provided by the APACHE$PRIVILEGED image. Not intended to be
modified by the user.
|
||||||||
|
APACHE$PLV_LOGICAL |
System executive mode
logical name defined during startup and used to control access to the
services provided by the APACHE$PRIVILEGED image. Not intended to be
modified by the user.
|
||||||||
|
APACHE$PREFIX_DCL_CGI_
SYMBOLS_WWW
|
If defined, this system
logical name prefixes all CGI environment variable symbols with "WWW_". By
default, no prefix is used.
|
||||||||
|
APACHE$PRIVILEGED |
System executive mode
logical name pointing to installed, shareable images. Not intended to be
modified by the user.
|
||||||||
|
APACHE$READDIR_NO_DOT_FILES
|
Used to disable the
simulating of dot files when processing directories. There is no default
value.
|
||||||||
|
APACHE$READDIR_NO_NULL_TYPE
|
Used to disable the
elimination of the null type which contains a single dot when processing
directories. There is no default value.
|
||||||||
|
APACHE$READDIR_NO_UNIX_OPEN
|
Used to disable the
processing of unix files when processing directories. There is no default
value.
|
||||||||
|
APACHE$SET_CCL |
Used by APACHE$SET_CCL.EXE, which replaces APACHE$FIXBG.EXE. |
||||||||
|
APACHE$SHOW_CGI_SYMBOL
|
If defined, this system
logical name provides information for troubleshooting the CGI environment by
dumping all of the symbols and logicals (job/process) for a given CGI. Use
with APACHE$DEBUG_DCL_CGI.
|
||||||||
|
APACHE$SSL_DBM_TYPE |
Used to define the
desired DBM organization to use for MOD_SSL. The valid options for this
logical are: GDBM, SDBM, VDBM.
If this logical is not
set, the default is VDBM.
|
||||||||
|
APACHE$SPL_DISABLED |
Used to determine
whether Shared Process Logging is to be disabled. There is no default value.
|
||||||||
|
APACHE$SPL_MAX_BUFFERS
|
Used to determine the
maximum buffer quota for each Shared Process Logging mailbox.
If this logical is not
set, the default is 10.
|
||||||||
|
APACHE$SPL_MAX_MESSAGE
|
Used to determine the
maximum message size for each Shared Process Logging mailbox.
If this logical is not
set, the default is 1024.
|
||||||||
|
APACHE$SPL_FLUSH_INTERVAL
|
Used to determine the maximum message count per Shared Process Logging file before data is flushed to disk.
If this logical is not
set, the default is 256.
|
||||||||
|
APACHE$USE_CUSTOM_STAT
|
System logical name that
is used to indicate that the custom apache stat function should be used
rather than the run-time stat function.
|
||||||||
|
APACHE$USER_HOME_PATH_
UPPERCASE |
If defined to be true
(1, T, or Y), this system logical name uppercases device and directory
components for user home directories when matching pathnames in <DIRECTORY>
containers. This provides backward compatibility for sites that specify
these components in uppercase within <DIRECTORY> containers. See the UserDir
directive in
Modules and Directives
section for more information.
|
||||||||
|
APACHE$VERIFY_DCL_CGI
|
If defined, this system
logical name provides information for troubleshooting DCL command procedure
CGIs by forcing a SET VERIFY before executing any DCL CGI. Use with
APACHE$DEBUG_DCL_CGI.
|
||||||||
3.9 OpenVMS Cluster Considerations
Note
The SWS runs and has been
tested in Alpha-only, Integrity server only, and mixed-architecture (Alpha and
VAX) clusters. (The SWS does not run
on VAX systems but runs on Alpha systems in an Alpha and VAX cluster.)
Although HP expects that
SWS will also run in a mixed-architecture (Alpha and Integrity server) cluster,
the Version 2.2 kit has not been tested in that configuration.
The configuration
procedure lets you specify where you want to store the server software, the
server system files (configuration, startup, and shutdown files), and your HTML
files (content). By default, everything will go in SYS$COMMON or the device and
directory you specified with the PRODUCT INSTALL command.
Where you put each server
component depends on your OpenVMS cluster environment and how much you want to
integrate or segregate the SWS and its activities. You can install the server
once on a disk that is visible to multiple systems in the cluster. You have the
option of:
·
Using one configuration for all systems, or
·
Configuring individual systems, provided
they all share a common system disk.
In the latter case, a
common system disk is needed so that all the systems have access to the server
system files on the system disk. If a system has access to a clusterwide directory where the SWS is installed, but does not share a
system disk with the other systems, you might need an additional installation.
If you have more than one
installation, you must make sure that the APACHE$WWW account has the same UIC
across the entire cluster. The installation procedure automatically assigns the
APACHE$WWW UIC to all the files under [APACHE], regardless of their actual
physical locations. One UIC definition for APACHE$WWW for all installations
ensures that all files are visible at all times.
·
APACHE$READ
· APACHE$EXECUTE
· APACHE$SUEXEC_SRVR
·
APACHE$SUEXEC_USER
These identifiers are used in ACLs and are attached to disk files that might be shared in
a cluster.
3.9.1 Individual System vs.
Clusterwide Definition
To define
clusterwide vs. individual configuration files, APACHE$ROOT
uses the following concealed logical names:
·
APACHE$COMMON defines
clusterwide
files.
·
APACHE$SPECIFIC defines system-specific
files.
When reading a file, the
server first looks for a system-specific version of the file in APACHE$SPECIFIC:[directory]. If it does not find one, it looks for a
clusterwide file in APACHE$COMMON:[directory].
To avoid confusion,
always use the appropriate concealed logical name to specify the file you want
to edit. For example, to edit a clusterwide version of
HTTPD.CONF, refer to:
$
EDIT APACHE$COMMON:[CONF]HTTPD.CONF
If you referred to:
$
EDIT APACHE$ROOT:[CONF]HTTPD.CONF
the server would open the
clusterwide file but save it as a system-specific version.
The latest version of HTTPD.CONF would then be visible only to the individual
node it was saved on.
Within HTTPD.CONF itself,
you should make this distinction whenever you refer to a path or file location.
This improves performance and ensures the server will return a complete
directory listing. For example, you should specify APACHE$COMMON or
APACHE$SPECIFIC (instead of APACHE$ROOT) with Directory directives.
The following extract,
from the HTTPD.CONF file distributed with the OpenVMS kit, refers to
APACHE$COMMON because the content for the default web page is in the
clusterwide directories.
DocumentRoot "/apache$common/htdocs"
. . .
<Directory "/apache$common/htdocs">
Options Indexes
FollowSymLinks Multiviews
AllowOverride
None
Order
allow,deny
Allow from
all
</Directory>
3.9.2 Mixed-Architecture (Alpha and VAX)
Cluster
In a mixed-architecture
cluster of Alpha and VAX systems, do not use a cluster alias IP address with the
SWS. Because the VAX systems will not have the SWS running, they will not be
able to service HTTP requests.
3.10 Common Gateway Interface (CGI)
Common Gateway Interface
(CGI) programs execute within the DCL shell on the SWS for OpenVMS. Please note
the following OpenVMS specific information.
3.10.1 CGI Environment Variables
By default, an
environment variable symbol takes the form designated by the name of the
environment variable. You can determine how environment variables are set when
the server executes a CGI program.
You can define the
APACHE$PREFIX_DCL_CGI_SYMBOLS_WWW logical name to prefix all environment
variable symbols with "WWW_". By default, no prefix is used.
The APACHE$CGI_MODE
logical name controls how CGI environment variables are defined in the executing
CGI program, as follows:
APACHE$CGI_MODE option
where
option can have
one of the following values
at a time:
|
0
|
Default. Environment
variables are defined as local symbols and are truncated at 970 (limitable
with DEC C).
|
|
1
|
Environment variables
are defined as local symbols unless they are greater than 970 characters. If
the environment value is greater than 970 characters, it is defined as a
multi-item logical.
|
|
2
|
Environment variables
are defined as logicals. If the environment value is greater than 255
characters, it is defined as a multi-item logical.
|
APACHE$DCL_ENV is a
foreign symbol that lets you define CGI environment variables as follows:
APACHE$DCL_ENV [-c] [-d] [-e
env-file] [-l]
where:
|
-c
|
Default. Indicates
create environment variables.
|
|
-d
|
Indicates delete
environment variables.
|
|
-e env-file
|
Specifies an alternate
environment file. The environment file does not need to be specified by the
caller because the parent derives it (it is easily be determined by
default).
|
|
-l
|
Allows you to list the
contents of the environment file. This option is used to display the
enviroment variables when you specify the APACHE$DEBUG_DCL_CGI and the
APACHE$SHOW_CGI_SYMBOLS logical names.
|
An example of the output
of an environment file is as follows:
(CGI Environment
Variables)
"DOCUMENT_ROOT" = "/apache$common/htdocs"
"HTTP_ACCEPT" = "image/gif, image/x-xbitmap,
image/jpeg, image/pjpeg, */*"
"HTTP_ACCEPT_LANGUAGE" = "en-us"
"HTTP_CONNECTION" = "Keep-Alive"
"HTTP_HOST" = "husky2.zko.dec.com"
The following example
deletes the environment and then recreates it:
Example:
diff_mode_cgi.com
$ APACHE$DCL_ENV -d
$ Define
APACHE$PREFIX_DCL_CGI_SYMBOLS_WWW 1
$ APACHE$DCL_ENV –c
CGI scripts that
reference input to the SWS must refer to APACHE$INPUT.
3.10.3 Executing CGI
On OpenVMS, CGI images
execute within a DCL process. You cannot execute CGI images directly.
3.10.4 Logicals
for Debugging CGI Scripts
Use the following logical
to debug CGI scripts.
|
Logical Name
|
Description
|
|
APACHE$DEBUG_DCL_CGI
|
If defined, this system
logical name enables APACHE$VERIFY_DCL_CGI and APACHE$SHOW_CGI_SYMBOL.
|
|
APACHE$VERIFY_DCL_CGI
|
If defined, this system
logical name provides information for troubleshooting DCL command procedure
CGIs by forcing a SET VERIFY before executing any DCL CGI. Enabled by
APACHE$DEBUG_DCL_CGI.
|
|
APACHE$SHOW_CGI_SYMBOL
|
If defined, this system
logical name provides information for troubleshooting the CGI environment by
dumping all of the symbols and logicals (job/process) for a given CGI.
Enabled by APACHE$DEBUG_DCL_CGI.
|
3.10.5 Displaying Graphics with CGI Command Procedures
To display a graphics
file with a CGI command procedure, use the APACHE$DCL_BIN foreign symbol in the
following format:
APACHE$DCL_BIN [-s bin-size] bin-file
where
|
-s bin-size
|
Specifies the actual or
approximate file size in bytes. Bin-size is automatically determined if the
image file is larger than 32768K (default value). If the image file is
smaller than 32768K, you can provide an approximate (or actual) size (this
will boost performance).
|
|
bin-file
|
Specifies the file to be
displayed.
|
For example:
$ APACHE$FLIP_CCL
$ WRITE SYS$OUTPUT
F$FAO("!as!/!/","CONTENT-TYPE: IMAGE/GIF")
$ APACHE$DCL_BIN
APACHE$ROOT:[ICONS]APACHE_PB.GIF
$ EXIT
Chapter 4
Security Information
The SWS for OpenVMS is a
non-privileged, user-mode, socket-based network application. TMPMBX and NETMBX
are the only privilege requirements. The server runs under its own unique UIC
and user account (APACHE$WWW).
4.1 Process Model
The SWS runs as a single
job which consists of:
·
A master process (APACHE$ssss)
·
Several detached processes
Note
Although the Apache 2.0
stream contains support for running the server in a hybrid multiprocess, multithreaded mode, the SWS Version 2.2 kit is built on a
process-based model. A threads-based version of the
SWS is under investigation and may be included in a subsequent
release.
Server processes have a
process name of the form APACHE$ssss, where
ssss is up to four
alphanumeric characters defined in the VmsServerTag
directive. The default is APACHE$SWS.
Similarly, child
processes have a process name of the form APACHE$ssssnnnn,
where
APACHE$ssss is the server name and
nnnn is the child server process number
represented as a hex value. For example:
Parent
APACHE$SWS
Child 1
APACHE$SWS0000
Child 2
APACHE$SWS0001
Child 3
APACHE$SWS0002
The CSWS_JAVA Java
servlet engine creates a process (APACHE$TOMCAT) to execute
Java programs. CSWS_PERL does not create any processes.
The OpenVMS security
profile for each process is identical and no enhanced mechanism is required for
these processes to communicate with one another. Resource utilization is
controlled by a single user account (APACHE$WWW) where pooled quotas are
defined.
4.2 Privileges Required
to Start and Stop the Server
The SWS runs under the
APACHE$WWW username and UIC and is started as a detached, network process.
During startup, protected images are installed and logical names are placed in
the system logical name table. Shutdown is accomplished by sending a KILL signal
to the master process and its subprocess.
These actions require
enhanced privileges (DETACH, SYSNAM, WORLD, etc.) and are usually performed from
a suitably privileged account.
4.3 File Ownership and Protection
All of the server's files
reside under its root directories pointed to by the APACHE$ROOT logical name.
During installation, file protection is set to (S:RWED,
O:RWED, G, W). During configuration, all files are set to be owned by
APACHE$WWW.
4.4 Authentication Using OpenVMS
Usernames and Passwords
(MOD_AUTH_OPENVMS)
The MOD_AUTH_OPENVMS
module supports authentication using the usernames and passwords contained in
the system authorization file (SYS$SYSTEM:SYSUAF.DAT).
You can optionally load the new module at startup. The module is located in:
APACHE$COMMON:[MODULES]MOD_AUTH_OPENVMS.EXE
Note
The HTTP password authentication protocol transmits username and password information in plain text. When you enable mod_auth_openvms, you are potentially exposing your user's passwords to password sniffing attacks. If your application is intended to be used over external network connections, consider placing your password-protected pages within an SSL-protected directory so usernames and passwords are encrypted before they are transmitted.
To enable
mod_auth_openvms, edit the HTTPD.CONF file to include the following
directive:
LoadModule
auth_openvms_module
/apache$common/modules/mod_auth_openvms.exe
This module supports the
following directives:
·
AuthOpenVMSUser {On,Off}
This directive controls whether user authentication and authorization using
MOD_AUTH_OPENVMS are enabled or disabled (On or Off, respectively). By default,
AuthOpenVMSUser is set to On if the MOD_AUTH_OPENVMS
module is loaded.
The syntax is similar to the
AuthUserFile directive
provided by MOD_AUTH and the AuthDBUserFile directive
provided by MOD_AUTH_DB.
Note
Versions of the SWS prior to Version 1.3 defined the AuthUserOpenVMS directive, which is equivalent to AuthOpenVMSUser. The AuthUserOpenVMS directive is still supported; however, HP recommends that you use the new syntax. By default, the module is enabled once it is loaded.
·
AuthOpenVMSGroup {On,Off}
This directive controls whether group authorization using MOD_AUTH_OPENVMS is enabled or disabled (On or Off,
respectively). By default, AuthOpenVMSGroup is set to On if the MOD_AUTH_OPENVMS module is loaded. (If
AuthOpenVMSUser is disabled, then AuthOpenVMSGroup is also disabled, even if AuthOpenVMSGroup On is
specified.)
The syntax is similar to the AuthGroupFile directive provided by MOD_AUTH and the AuthDBGroupFile directive
provided by MOD_AUTH_DB.
For example, if a
directory is protected using an .HTACCESS file, the contents of that file might
contain:
AuthType Basic
AuthName
"OpenVMS authentication"
AuthOpenVMSUser
On
require valid-user
When a user seeks to open
a file in that directory, the user will be prompted for a username and password.
That username and password must match entries in the SYSUAF.DAT file.
Furthermore, the SYSUAF.DAT entry must allow a network login for that username
at the time of the request. If an invalid authentication request occurs, an
intrusion record is written.
An authentication request
can be rejected for the following reasons:
·
Username is blank or invalid.
·
Password is blank or invalid. (Note: The SWS does not allow blank
or null passwords, even though blank or null
passwords are allowed by OpenVMS.)
·
Password is valid, but target account is flagged as an intruder.
(Account is flagged after 5 consecutive failures in a
given time period; see the DCL commands SHOW INTRUSION and DELETE INTRUSION.)
·
Target account has a secondary password defined. (HTTP password
protocol does not support secondary
passwords.)
· Account is marked for external authentication (see AUTHORIZE /FLAGS=EXTAUTH qualifier).
· Password has expired (see AUTHORIZE /FLAGS=PWD_EXPIRED qualifier).
· Account has expired (see AUTHORIZE /EXPIRATION qualifier).
· Account is disabled (see AUTHORIZE /FLAGS=DISUSER qualifier).
· Access restrictions prevent a network access for this time of day (see AUTHORIZE /ACCESS and /PRIMEDAYS
qualifiers).
When you use
MOD_AUTH_OPENVMS for authentication, the software accepts one or more require
group directives. Each require group directive can contain one or more group
names or identifiers. (Note that the software treats the values specified in the
require group directives in a case-insensitive manner.)
After a user has been
authenticated using the specified password, MOD_AUTH_OPENVMS compares the UIC of
the user to determine if the account is a member of a group that was included in
the list of require group directives. If so, the user is allowed access. If not,
the module looks to see if the SYSUAF account has been granted any of the
specified identifiers.
4.4.2 The require user Directive
For simplicity and for
consistency with the require group directive, MOD_AUTH_OPENVMS uses a
case-insensitive comparison when processing values specified by the require user
directive.
System administrators can
specify the accounts that MOD_AUTH_OPENVMS will use for authentication and
authorization. In particular, system administrators may want to prevent users
from attempting to authenticate using certain accounts.
By default, any account
in the SYSUAF file can be used by the MOD_AUTH_OPENVMS module. However, if the
system administrator uses the AUTHORIZE utility to create an identifier called
APACHE$MOD_AUTH_OPENVMS_ENABLE, then MOD_AUTH_OPENVMS only utilizes accounts
that have APACHE$MOD_AUTH_OPENVMS_ENABLE granted to them. Any account that does
not have that identifier granted to it is effectively hidden.
If the
APACHE$MOD_AUTH_OPENVMS_ENABLE identifier has not been defined, then the system
administrator can define an identifier called APACHE$MOD_AUTH_OPENVMS_DISABLE.
If that identifier exists, then any account in the SYSUAF file can be used by
MOD_AUTH_OPENVMS provided that account does not hold the
APACHE$MOD_AUTH_OPENVMS_DISABLE identifier. Any account that has
APACHE$MOD_AUTH_OPENVMS_DISABLE granted to it is hidden. This identifier might
be used in cases where the system administrator wants to use MOD_AUTH_OPENVMS
for all accounts except certain specific ones.
APACHE$MOD_AUTH_OPENVMS_DISABLE is ignored. For example, if the system
administrator has been using the APACHE$MOD_AUTH_OPENVMS_ENABLE identifier to
specify individual accounts that can be used by MOD_AUTH_OPENVMS, then the
administrator will have to remove that identifier from all accounts and remove
the definition of that identifier before the administrator can define the
APACHE$MOD_AUTH_OPENVMS_DISABLE identifier. Otherwise the software will see the
definition of APACHE$MOD_AUTH_OPENVMS_ENABLE and will require that that
identifier be granted for any account that can be used by MOD_AUTH_OPENVMS.
An account that is hidden
is treated by MOD_AUTH_OPENVMS as if the account does not exist. If
AuthOpenVMSAuthoritative is on, a security request for a
hidden account is rejected. If AuthOpenVMSAuthoritative
is off, the request is declined, and some other security facility can be used to
process the request.
Installing a privileged
shareable image library such as
APACHE$APR_SHRP adds some risk to
system security. In particular, with APACHE$APR_SHRP
installed, certain users will be able to tell which accounts
are valid and will be able to check to see if certain accounts hold certain
identifiers. However, only user accounts that are granted the appropriate
APACHE$APR_* rights identifiers are allowed to run these routines. Frequently, this means that only the SWS
server process account (APACHE$WWW) is allowed to call these
privileged functions.
Furthermore, the system
administrator can use the APACHE$MOD_AUTH_OPENVMS_ENABLE or
APACHE$MOD_AUTH_OPENVMS_DISABLE identifier to hide some accounts, particularly
privileged accounts, from the SWS software.
The following directives
demonstrate MOD_AUTH_OPENVMS authentication and authorization.
In the following portion
of an HTTPD.CONF file, MOD_AUTH_OPENVMS is used for authentication and
authorization:
AuthType Basic
require user
j_smith m_jones
require group
db_read_ident db_write_ident
require group
db_maint db_systems
db_admin
require group
testing customer_support
require group
accounting travel
</Location>
Some of the specified
user names and groups names may not be defined in the
SYSUAF file. Instead, the user may be in the PASSWD.DAT file. If so, authentication will be performed by MOD_AUTH using the groups
defined in the GROUPS.DAT file.
AuthType Basic
AuthUserFile /private/passwd.dat
AuthGroupFile
/private/groups.dat
AuthOpenVMSGroup
Off
require user
j_smith m_jones
require group
db_maint db_systems
db_admin
require group
testing customer_support
require group
accounting travel
</Location>
Server extensions, such
as CGI scripts, PHP scripts, and Perl modules, run within the context of the
SWS's process or its subprocesses. These extensions
have complete control over the server environment. You can configure the server
to allow execution of arbitrary user scripts, but standard practice is to limit
such activity to scripts written by completely trusted users.
The SWS includes
directives that allow a web administrator to control script execution and client
access. The use of these directives is described in numerous books and is not
duplicated here.
4.6 suEXEC in
the Secure Web Server
The following sections
discuss the implementation of suEXEC in the SWS.
suEXEC in the SWS uses rights identifiers to indicate
authorized users to run suEXEC
as well as users to be run via suEXEC.
The SWS does not use
UID/GID minimums to determine the validity of the calling user. The use of the
SETUID/SETGID restrictions on the invoked CGI or SSI program is currently not
implemented.
suEXEC in the SWS supports the use of the User and
UserDir directives within virtual hosts, and also supports the EXEC CGI
mod_include directive.
There are no restrictions
on OpenVMS account privileges or MAXSYSGROUP for suEXEC programs.
You can configure
suEXEC using the configuration utility provided with the
installation (APACHE$COMMON:[000000]APACHE$MENU.COM). This
utility allows you to enable or disable the suEXEC
feature for a given server.
Note
Before you enable
suEXEC, be sure that the user accounts that are to be run
via suEXEC have been created.
To enable
suEXEC, run SYS$MANAGER:APACHE$CONFIG.COM and
answer Yes to the question about enabling the suEXEC
feature.
The suEXEC
image is installed with privileges.
When you enable
suEXEC, the following occur:
·
The APACHE$SUEXEC_SRVR and APACHE$SUEXEC_USER rights identifiers
are created in the rights
database, if they do not already exist.
· The APACHE$SUEXEC_SRVR rights identifier is granted to the server account, and the user is prompted to enter
user accounts that are to be run via suEXEC. These user accounts are granted the APACHE$SUEXEC_USER
rights identifier.
· An suEXEC directory is created within the htdoc root (APACHE$COMMON:[HTDOCS.SUEXEC]) and set with the
appropriate default ACEs that allow the
Apache server read access to the suEXEC CGI/SSI
programs.
After you have enabled
suEXEC, manually perform the following steps:
·
For each user account to be run via suEXEC,
create a directory owned by that user under the suEXEC
directory.
For example, if you create a directory named user, it will be located in APACHE$COMMON:
[HTDOCS.SUEXEC.user].
· Within each virtual host configuration, use the Alias or ScriptAlias directive to define a location for the suEXEC
CGI/SSI programs to be used.
To disable
suEXEC, run SYS$MANAGER:APACHE$CONFIG.COM
and answer No to the question about enabling the suEXEC
feature.
Execute the command below to assign the APACHE$WWW user with read and execute access privileges for each directory in the entire directory tree where individual user directories reside:
$ Set security/acl=(IDENTIFIER=[AP_HTTPD,APACHE$WWW],ACCESS=READ+EXECUTE) <directory name>
Note
You
must perform this step for all directories above the respective user
directories.
Ensure that all users have ownership for their respective user directories.
Assign the APACHE$WWW user with read and execute access privileges to the user directory.
Assign respective suEXEC users with read access privilege to all container directories.
Configure either the
device name
or the
logical name.
Note
suEXEC receives the user’s home
directory details from UAF.
The example below shows a directory
structure with user directories as well as the privileges required for each
directory.
|
xyz$dka0
|
A
|
B
________|________
|
|
User1
User2
|
|
public_html
public_html
·
APACHE$WWW user should have read and execute access
privileges to A, B, User1, User2, and 2 public_html directories.
·
User1 and User2 should have read access privileges to A and
B directories.
·
User1 should own the User1 directory. · User2 should own the User2 directory. |
4.6.2.1 Using Paths with Logicals in
UserDir Directive
When you disable suEXEC,
the following occur:
· The APACHE$SUEXEC_SRVR rights identifier is revoked from the server account (APACHE$WWW) and the user
is prompted about whether to disable all suEXEC servers.
·
The user is prompted about whether to disable all suEXEC users.
· If no server accounts remain enabled, the APACHE$SUEXEC_SRVR rights identifier is removed from the rights
database.
· If no user accounts remain enabled, the APACHE$SUEXEC_USER rights identifier is removed from the rights
database.
The SWS's certificate
keys must be protected against disclosure. The keys, by default, are owned by
APACHE$WWW, and protected as (S:RWED, O:RWED, G, W). As an additional measure of
security, the keys can be encrypted. When using encrypted keys, a password must
be entered during startup to decrypt the keys.
A second threat for key
disclosure exists during script execution because scripts run in the context of
the server and have complete access to key files no matter where they exist (as
long as they exist in a directory accessible to APACHE$WWW). Therefore, it is
not advisable to allow the execution of arbitrary user scripts when using SSL.
Chapter 5
Building and Debugging Loadable Apache Modules for the SWS
Note
The instructions in this chapter have not been tested by HP on the SWS Version 2.2.
The SWS for OpenVMS is ported from the Apache Web Server and includes
all of the standard Apache modules as well as several optional modules. The
Apache Web Server design architecture allows new modules to be added to the
server at the following times:
· Dynamically at run-time using the Apache Dynamic Shared Object
(DSO) feature
5.1 The Apache API, Run-Time Library, and
HTTP Request Processing
A module must conform to
the Apache API, which dictates how the server and module communicate with one
another and how HTTP requests are represented and processed. The Apache module
data structure is an important component of this communication because it
provides information to the server about the module and its capabilities.
5.2 Building a Module
The natural language for
building Apache modules is C. This is the only language for which Apache
provides data structure definitions and function prototypes. You can write an
Apache module in any language you choose, but you will need to provide your own
language-specific header files or C-wrappers. In the rest of this section, we
use C as the implementation language.
Your module must include
the Apache module data structure pointed to by a universal symbol of your
choice. During startup, the server dynamically activates your module by calling
LIB$FIND_IMAGE_SYMBOL with the name of your module's Apache Module Data
Structure (obtained from the LoadModule directive in
your httpd.conf file).
The following compiler
switch is used to build the server:
Note
Beginning with the SWS Version 2.0, the EAPI macro /DEFINE=(EAPI) is no longer required. SSL is built into the Apache base code by default and is no longer patched.
5.2.3 Linking a Module
A loadable module is
implemented as an OpenVMS shareable image. Link your module with the /SHARE
qualifier.
Note
Your shareable image must
not contain any linker warnings or errors in order to be properly loaded at
run-time by LIB$FIND_IMAGE_SYMBOL.
For guidelines on how to
design and write a shareable image, see the
OpenVMS Linker Utility Manual and
Guide to Creating OpenVMS Modular
Procedures.
mod_rewrite provides powerful URL-rewriting capabilities.
(See http://httpd.apache.org/docs/mod/mod_rewrite.html for a description of
mod_rewrite capabilities). You can include
mod_rewrite with SWS by building it as a DSO module from
sources.
$!
$! Copy the following files from the CSWS source kit to your default directory:
$!$!
$!
mod_rewrite.h
$!
$! Copy rewriteguide.html from the CSWS source kit to
$!
apache$common:[htdocs.manual.misc].
$!
$! Once mod_rewrite.exe is built, copy it to
apache$common:[modules]
and
$! add the following line to your
httpd.conf file:
$!
$!
LoadModule rewrite_module
/apache$common/modules/mod_rewrite.exe
$!
$! Restart the server.
$!
$ cc/lis/define=eapi/prefix=all -
/include=(apache$common:[src.include],apache$common:[src.os.openvms]) -
mod_rewrite
$!
$ link/share/map
mod_rewrite,sys$input:/option
!
! Linker options
!
GSMATCH=LEQUAL,1,0
SYMBOL_VECTOR=(REWRITE_MODULE=DATA)
! Run SYS$STARTUP:APACHE$CONFIG to setup the following logical name.
!
APACHE$HTTPD_SHR/SHARE
$!
$ exit
This section describes
two methods for debugging a user-built Apache DSO module using the standard
server provided with the SWS. The instructions assume the SWS Version 1.1 or
later, but the same techniques can be used with earlier versions with slight
modifications.
There are two methods of
running the server for debugging purposes:
·
Running the server image in a detached process (normal)
·
Running the server image directly
The first method requires
a separate terminal device to send and receive debugger input/output. A
DECterm device is used in this example. If
DECwindows is not available, any terminal device that allows
read/write access to APACHE$WWW can be used (such as a logged-in TELNET
terminal), but APACHE$WWW will need SHARE privilege to access the device if it
is already assigned to another process.
The second method does
not require a separate terminal device. This technique can only be used to debug
the main process, so you must run the server with the "-X" option. If this
context is not appropriate for the problem you are debugging, the other method
of debugging can be used (a separate terminal window will be required for each
child process).
Before you begin
debugging your module, perform the following steps:
1. Insert the following code sequence as the
first lines of your module's initialization routine to activate the OpenVMS
debugger at run-time:
#include <ssdef.h>
#endif
lib$signal
(SS$_DEBUG);
2. Build a debug version of your module.
Compile with /DEBUG=(TRACEBACK,SYMBOLS) and link with /DEBUG,
then copy the
image to an appropriate directory. For example:
apache$common:[modules]mod_rewrite.exe_debug
You may also want to copy
the source code files here so that the debugger can find them (DBG> set
source/latest t apache$common:[modules]).
3. In httpd.conf,
load the debug version of the module. For example:
LoadModule
rewrite_module /apache$common/modules/mod_rewrite.exe_debug
4. Allow interactive logins to APACHE$WWW:
UAF> mod
apache$www/inter/pass=<password>/nopwdexpir
5.2.5.2
Debugging your module
Choose one of the
following two methods to debug your module, depending on how you run the Apache
server. These two methods are as follows:
context)
· Method B: Direct execution of server image (runs the Apache server
image in your
current
process)
This method allows the
Apache server to run in its normal, detached context. The only difference from
the standard configuration is that the APACHE$WWW process possesses GRPNAM
privilege (in order to define DBG$INPUT and DBG$OUTPUT logical names in the
LNM$GROUP table). In this example, the "-X" option is used so that no child
processes are created.
To debug a normal
detached server process, perform the following steps:
UAF> mod
apache$www/priv=grpnam/inter
2. From the APACHE$WWW account, run:
$ set proc/priv=grpnam
$ set
display/create/node=<domain-name-of-debug-window-client>/trans=tcpip
$ create/term/noprocess/define=(table=lnm$group,dbg$input,dbg$output)
$ @sys$startup:apache$config ! (specify "-X" for server options)
$ @sys$startup:apache$startup
Note
If the problem you are
debugging requires child processes, you will need a separate terminal device for
each process with process-specific dbg$input and
dbg$output logical names defined for each child process. One
way to do this is to create one DECterm window for
each child process (in this example, MaxSpareServers
is set to 1):
$ create/term/noprocess/define=(table=lnm$group,apache$00000_dbg)
$ create/term/noprocess/define=(table=lnm$group,apache$00001_dbg)
$ define/job
dbg$input
'f$process()'_dbg
$ define/job
dbg$output
'f$process()'_dbg
Method B - Direct Execution of Server Image
This method runs the
Apache server image in your current process. One advantage of this method is
that GRPNAM is not required nor is a separate debugger window needed.
To debug for direct
execution of a server image, perform the following steps:
1. From the SYSTEM (or suitably privileged)
account:
$ @sys$startup:apache$config ! (specify
system-wide logicals)
2. From the APACHE$WWW account, run:
$
mcr apache$root:[000000]apache_httpd.exe "-X"
Beginning in the SWS Version 2.0, a parameter to
the SYS$STARTUP:APACHE$STARTUP command procedure is
provided to execute the server in a single process.
@SYS$STARTUP:APACHE$STARTUP RUN ! (execute SWS in a
single process)
This allows the user to debug the new module as
all requests will be directed to the one server process.
This can be shown as an
alternative to the step 2 in starting the server.
Debugger Session
DBG> set image
mod_rewrite
DBG> set module/all
DBG> set source/latest apache$root:[modules]mod_rewrite.c
This chapter provides open
source license acknowledgements and license references.
This product includes
software developed by the
Apache Software Foundation.
This product includes
software developed by the
This product includes software developed by Ralf S. Engelschall <rse@engelschall.com> for use in the Mod_SSL Project.
This product includes
software developed by the
OpenSSL
Project.
This product includes cryptographic software written by Eric Young.
This product includes
software developed by the
Apache/Perl Integration Project.
This product includes
software developed by the
Perl Project.
This product includes software developed by the PHP Group.
» Return to the Secure Web Server for OpenVMS home page
 |
|||||||||||||||
|
|||||||||||||||