D
Apache Server Installation/Configuration

This appendix lists the procedure and steps to install and configure Apache Server for HP OpenVMS Alpha. The following topics are included:

Post-Installation Checklist

After you configure the Oracle HTTP Server, perform the following tasks to ensure a successful startup:

Each of these tasks is explained below. Once you have completed them, you can test the installation by starting the Oracle HTTP Server.

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. On the Oracle HTTP Server for OpenVMS, AUTOGEN will probably increase the page file size and the number of swap file pages.

Check Disk Quota

If the disk quota is too low, the Oracle HTTP Server will not start. Either raise the disk quota for the user account ORACLE, 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 PROCESS/PRIVILEGES=EXQUOTA node-name::ORACLE

Check for SET TERMINAL/INQUIRE

When the Oracle HTTP Server for OpenVMS is started, the following login files are executed:

SYLOGIN.COM (system login file)
LOGIN.COM (login file for ORACLE)

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.

Test the Installation

Now you will manually start the Oracle HTTP Server to verify the installation and configuration of the server. Enter the following command:

$APACHECTL START

Browser Test

You can test the installation using your web browser. Replace host.domain in the following URL with the information for the Oracle HTTP Server you just installed:

HTTP://host.domain:<port>

If this is a new installation, the browser should display the standard introductory page with the following bold text at the top:

"If you see this, it means that the installation of the Apache web server 
software on this system successful."

The Apache logo is displayed at the bottom.

TELNET Test

You can also use TELNET on the local host to test the installation. Use the following procedure:

Enter the following command:

$ TELNET 0 80

The following text is displayed:

%TELNET-I-TRYING, Trying ... 127.0.0.1
%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: Tue, 23 May 2000 17:05:05 GMT
Server: Apache/1.3.12 (OpenVMS)
Last-Modified: Mon, 22 May 2000 15:33:27 GMT
ETag: "33dfec-681-39295347"
Accept-Ranges: bytes
Content-Length: 1665
Connection: close
Content-Type: text/html
%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80

Troubleshooting

If you do not receive a response from the Oracle HTTP Server, check the following:

Look in your SYLOGIN.COM file and make sure there is no SET TERMINAL/INQUIRE statement for NETWORK processes.

Look for the following files:

APACHE$ROOT:[000000]APACHE$SERVER.LOG
APACHE$ROOT:[LOGS]ERROR_LOG

Running the Oracle HTTP Server on OpenVMS

Starting and Stopping the Server

To startup the Oracle HTTP Server, enter the following command:

$ APACHECTL startup

To stop the Oracle HTTP Server, enter the following command:

$ APACHECTL stop

Server Log File

The server log file for APACHE$WWW is written to:

APACHE$SPECIFIC:[000000]APACHE$SERVER.LOG

Performance Considerations

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 at the following URL:

http://www.openvms.compaq.com:8000/73final/6491/6491pro.html

Recommendations for improving performance on a Oracle HTTP Server are provided below and in the Release Notes:

Limits and Quotas

The following table shows sample values for the ORACLE Account from a working and exercised Oracle HTTP Server 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.

Table D-1 Sample Values for the ORACLE Account

Parameter	Default	On Hewlett-Packard Web Server
ASTLM (NonPooled) Total number of asynchronous system trap (AST) operations and scheduled wake-up requests the user can have queued at one time	250	610 Or BIOLM + DIOLM + 10
BIOLM (NonPooled) Number of outstanding buffered I/O operations permitted for a user's process	150	300 You might also need to increase the SYSGEN parameter CHANNELCNT because it limits BIOLM,DIOLM, and FILLM.
BYTLM (Pooled) Amount of buffer space a user's process can use	64000	200000 Increase this value for a heavy load.
CHANNELCNT	256	FILLM and CHANNELCNT should be increased to match each other.
DIOLM (NonPooled) Number of outstanding direct I/O operations permitted to a user's process	150	300 You might also need to increase the SYSGEN parameter CHANNELCNT because it limits BIOLM,DIOLM, and FILLM.
ENGLM (Pooled) Specifies the lock queue limit	2000	2000
FILLM (Pooled) Number of files a user's process can have opened at one time. Includes the number of network logical links that can be active at the same time	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) Byte quota for the job-wide logical name table	4096	8192
PGFLQUO (Pooled) Number of pages the user's process can use in the system page file	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.
PRNumber of subprocesses a user's process can createCLM (Pooled)	8	20 You should increase this value for a heavy load.
TQELM (Pooled) Number of entries a user's process can have in the timer queue or the number of temporary common event flag clusters a user's process can have	10	610 Or BIOLM + DIOLM + 10

To change the quotas for the Oracle Account SYSUAF, use the system manager account and run the AUTHORIZE utility. For example:

$ SET DEFAULT SYS$SYSTEM
$ RUN AUTHORIZE
UAF> SHOW ORACLE
Username: ORACLE Owner: APACHE WEBSERVER
...
Maxjobs: 0 Fillm: 100 Bytlm: 64000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Prclm: 8 DIOlm: 150 WSdef: 2000
...
UAF> MODIFY ORACLE/FILLM=300/PRCLM=20
%UAF-I-MDFYMSG, user record(s) updated
UAF> EXIT
$

Server Experiencing Medium to High Usage

After you install the server and have been running it, look in the 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 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.

Global Pages and Global Sections

If a browser installation stalls, then 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 that you need. Some browsers might need more.

Excessive File Build Up

A large number of .LOG and .PID files can amass over time in the directories APACHE$ROOT:[0000000] 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.

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 Oracle HTTP Server 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:

MOD_OSUSCRIPT has been added to enable CGI scripts that were originally written for the OSU server.
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.
In an OpenVMS Cluster, you can specify either clusterwide or system-specific files.

How to Configure Apache

Perform the following steps to configure Apache to run while using an account other than the 'oracle' account:

Modify the configuration file HTTPD.CONF to include the following line:
```
User <username>
```
Modify APACHEUSER.COM to define logical APACHE_USERNAME to the required username. Make sure that the username is exactly the same as the entry in the httpd.conf file.
Restart the Apache Server if it is already running.

Modules and Directives

Following is a list of the modules included in the Oracle HTTP Server for OpenVMS distribution kit. The list shows the directives supported in each module. All supported modules and directives function as documented by the Apache Software Foundation at the following web site:

http://www.apache.org/docs

HTTP_CORE.C

AccessConfig

AccessFileName

AllowOverride

AuthName

AuthType

BindAddress

CoreDumpDirectory

DefaultType

DocumentRoot

ErrorDocument

ErrorLog

<Files>

HostnameLookups

IdentityCheck

Include

KeepAlive

KeepAliveTimeout

<Limit>

LimitRequestBody

LimitRequestFields

LimitRequestLine

Listen

ListenBacklog

LogLevel

MaxClients

MaxKeepAliveRequests

MaxRequestPerChild

MaxSpareServers

MinSpareServers

NameVirtualHost

Options

PidFile

Port

Require

ResourceConfig

RLimitCPU

RLimitMEM

RLimitNPROC

Satisfy

SendBufferSize

ServerAdmin

ServerAlias

ServerName

ServerPath

ServerRoot

ServerSignature

ServerTokens

ServerType

StartServers

TimeOut

UseCanonicalName

User

VirtualHost

MOD_ACCESS.C

allow

deny

order

MOD_ACTIONS.C

Action

Script

MOD_ALIAS.C

Alias

AliasMatch

Redirect

RedirectMatch

RedirectTemp

RedirectPermanent

ScriptAlias

ScriptAliasMatch

MOD_ASIS.C

MOD_AUTH.C

AuthGroupFile

AuthUserFile

MOD_AUTOINDEX.C

AddAlt

AddAltByEncoding

AddAltyByType

AddDescription

AddIcon

AddIconByEncoding

AddIconByType

DefaultIcon

FancyIndexing

HeaderName

IndexIgnore

IndexOptions

IndexOrderDefault

ReadmeName

MOD_CGI.C

ScriptLog

ScriptLogBuffer

ScriptLogLength

MOD_DIR.C

DirectoryIndex

MOD_ENV.C

SetEnv

UnsetEnv

MOD_IMAP.C

ImapBase

ImapDefault

ImapMenu

MOD_INCLUDE.C

MOD_INFO.C

AddModuleInfo

MOD_LOG_CONFIG.C

CustomLog

LogFormat

TransferLog

MOD_MIME.C

AddCharset

AddEncoding

AddHandler

AddLanguage

AddType

DefaultLanguage

ForceType

RemoveHandler

SetHandler

TypesConfig

MOD_NEGOTIATION.C

CacheNegotiatedDocs

LanguagePriority

MOD_SETENVIF.C

BrowserMatch

BrowserMatchNoCase

SetEnvIf

SetEnvIfNoCase

MOD_SO.C

LoadModule

MOD_STATUS.C

ExtendedStatus

MOD_UNIQUE_ID.C

MOD_USERDIR.C

UserDir

Supported and Unsupported Features

The server documentation from the Apache Software Foundation at the following web site:

http://www.apache.org/docs/

provides most of the information needed to run your Oracle HTTP Server for OpenVMS. Information specific to the OpenVMS operating system is provided below.

Modules Not Included

The following modules are not included in this version of the Oracle HTTP Server for OpenVMS kit:

MOD_AUTH_ANON

MOD_AUTH_DB

MOD_AUTH_DBM

MOD_AUTH_DIGEST

MOD_CERN_META

MOD_DIGEST

MOD_EXAMPLE

MOD_EXPIRES

MOD_HEADERS

MOD_ISAPI

MOD_JSERVE

MOD_LOG_AGENT

MOD_LOG_REFERER

MOD_MIME_MAGIC

MOD_MMAP_STATIC

MOD_PEARL

MOD_PROXY

MOD_REWRITE

MOD_SPELING

MOD_SSL

MOD_USERTRACK

MOD_VHOST_ALIAS

Unsupported Directives

The following directives are not supported:

AgentLog

AllowCONNECT

Anonymous

Anonymous_Authoritative

Anonymous_LogEmail

Anonymous_MustGiveEmail

Anonymous_NoUserID

Anonymous_VerifyEmail

AuthDBAuthoritative

AuthDBGroupFile

AuthDBMAuthoritative

AuthDBMGroupFile

AuthDBUserFile

AuthDBMUserFile

AuthDigestFile

CacheDefaultExpire

CacheDirLength

CachedirLevels

CacheForceCompletion

CacheGcInterval

CacheLastModifiedFactor

CacheMaxExpire

CacheRoot

CacheSize

CheckSpelling

CookieExpires

CookieTracking

Example

ExpiresActive

ExpiresByType

ExpiresDefault

Header

Metadir

MetaFiles

MetaSuffix

MimeMagicFile

MMapFile

NoCache

ProxyBlock

ProxyDomain

ProxyPass

ProxyPassReverse

ProxyReceiveBufferSize

ProxyRemote

ProxyRequests

ProxyVia

RefererIgnore

RefererLog

RewriteBase

RewriteCond

RewriteEngine

RewriteLock

RewriteLog

RewriteLogLevel

RewriteMap

RewriteOptions

RewriteRule

ScriptInterpreterSource

VirtualDocumentRoot

VirtualDocumentRootIP

VirtualScriptAlias

VirtualScriptAliasIP

Command Line Options

This section describes the HTTPD command line options supported on the Oracle HTTP Server. Before you can use them you must first define HTTPD as a symbol, as follows:

$ HTTPD :== $APACHE$ROOT:[000000]APACHE_HTTPD.EXE_ALPHA

Then you can use the following format to enter a command line option:

$ HTTPD -option

where -option is one of the following command line options:

-v: Displays the HTTPD version and its build date.

-"V": Displays the HTTPD base version, its build date, and a list of compile settings that influence the behavior and performance of the server.

-h: Displays a list of the HTTPD options.

-l: Displays a list of all modules compiled into the server.

"L": Displays a list of directives with expected arguments and places where the directive is valid.

The following example shows how to enter the L option to list the available configuration directives:

$ HTTPD -"L"

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 Oracle HTTP Server for OpenVMS.

Note:

On OpenVMS, the security profile of the running server is the same on all virtual hosts.

For more information, see the Apache Software Foundation documentation at the following web site:

http://www.apache.org/docs/vhosts/index.html

Dynamic Shared Object Support

Dynamic shared object support provides a method 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 the Apache Software Foundation documentation at the following web site:

http://www.apache.org/docs/dso.html

File Handlers

The Oracle HTTP Server for OpenVMS supports the ability to use file handlers explicitly. For more information, see the Apache Software Foundation documentation at the following web site:

http://www.apache.org/docs/handler.html

Content Negotiation

The MOD_NEGOTIATION module provides content negotiation. This module lets you specify language variants of HTML files. To specify language variants on OpenVMS, use an underscore instead of a period before the language extension.

For example:

On UNIX, filename.html.fr is the French variant of filename.html.
On OpenVMS, filename.html_fr is the French variant of filename.html.

For more information, see the Apache Software Foundation documentation at the following web site:

http://www.apache.org/docs/content-negotiation.html

Apache API

You can use the standard Apache API to write your own modules that will run on the Oracle HTTP Server for OpenVMS. For more information, see the Apache Software Foundation documentation at the following web site:

http://www.apache.org/docs/misc/API.html

suEXEC Support

The suEXEC feature provides the ability to run CGI programs under user IDs different from the user ID of the calling web server. This is not supported by the Oracle HTTP Server for OpenVMS.

File Formats

All file formats are supported. However, the Web browser status bar will not show page loading progress for logical or VFC format files larger than 8 K.

Page loading progress relies on an accurate byte count. Accurate byte count is not readily available for files in logical or VFC format. For files in these formats, the Oracle HTTP Server must count the bytes as the files load. The counting process can slow performance, so it has been turned off in this situation.

File Naming Conventions

In general, users who are running the Oracle HTTP Server for OpenVMS can specify either UNIX-style file names or OpenVMS-style file names. The Oracle HTTP Server usually displays UNIX-style file names.

The ODS-5 volume structure, introduced in HP OpenVMS Alpha Version 7.2-1, supports long file names, allows the use of a wider range of characters within file names, and preserves case within file names. However, the DEC C RTL that is shipped with HP OpenVMS Alpha Version 7.2-1 does not provide full support for extended file names on ODS-5 devices. This lack of full support imposes certain restrictions on users running the Oracle HTTP Server for HP OpenVMS Alpha.

Because mixed UNIX-style and OpenVMS-style extended file names are not yet supported by the DEC C RTL, you might be required to use UNIX-style syntax when interacting with the Oracle HTTP Server. An example would be appending additional directories or a file name to a root.

The following examples illustrate mixed UNIX-style and OpenVMS-style file names that are not supported in HP OpenVMS Alpha Version 7.2-1:

doc/foo.bar.bar
./tmp/foo.bar.b^_ar
~foo^.bar

You can, however, modify the last example so that it will work as an OpenVMS extended file name that has a tilde (~) as the first character. Precede the leading tilde (~) with the Extended File Specifications escape character (^). For example:

^~foo^.bar

For more information about using the tilde (~) in OpenVMS extended file names, see the OpenVMS Guide to Extended File Specifications at the following web site:

http://caedmon.zko.dec.com/72final/6536/6536pro.html

Mixed UNIX-style and OpenVMS-style file names will be supported in a future release of the DEC C RTL for HP OpenVMS Alpha.

File Transfer Process and Access Control List

When performing a File Transfer Process (FTP) operation, ensure that the Access Control List (ACL) for the target directory on the Oracle HTTP Server allows FTP access, as follows:

When transferring new files:

$ SET SECURITY/ACL=(IDENTIFIER=yourFTPname,ACCESS=READ+WRITE) [directory]

When replacing existing files:

$ SET SECURITY/ACL=(IDENTIFIER=yourFTPname,ACCESS=READ+WRITE) [directory]*.*

Logical Names

The Oracle HTTP Server for OpenVMS creates the following logical names, which are listed with their descriptions in table Table D-2.

Table D-2 Oracle HTTP Server Logical Names and Their Descriptions

Logical Name	Description
APACHE$COMMON	Concealed logical name that defines clusterwide files in APACHE$ROOT (device:[APACHE])
APACHE$FIXBG	System executive mode logical name pointing to installed, shareable images. Not intended to be modified by the user.
APACHE$HTTPD_SHR	System executive mode logical name pointing to installed, shareable images. Not intended to be modified by the user.
APACHE$INPUT	Used by CGI programs for PUT/POST methods of reading the input stream.
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$PRIVILEGED	System executive mode logical name pointing to installed, shareable images. Not intended to be modified by the user.
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$SPECIFIC	Concealed logical name that defines system-specific files in APACHE$ROOT (device:[APACHE.SPECIFIC.node-name])
APACHE$CGI_MODE	System logical name that controls how CGI environment logicals are defined in the executing CGI process. There are three different options. Note that only one option is available at a time. `0` Default. Environment logicals are defined as local symbols and are truncated at 970 (limitable with DEC C). `1` Environment logicals 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 logicals are defined as logicals. If the environment value is greater than 512 characters, it is defined as a multi-item logical.
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. Use with 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. Use with APACHE$DEBUG_DCL_CGI.
APACHE$PREFIX_DCL_CGI_SYMBOLS_WWW	If defined, this system logical name prefixes all CGI environment logical symbols with "WWW_". By default no prefix is used.
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$CGI_USE_DCLCOM_FOR_IMAGES	If defined, this system logical name forces CGI images to execute within a DCL process. The default is to execute CGI images directly. (Note: Direct execution of CGI images in not currently supported.)
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$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.

OpenVMS Cluster Considerations

An OpenVMS Cluster is a group of OpenVMS systems that work together as one virtual system. The Oracle HTTP Server runs in an OpenVMS Cluster so you can take advantage of the resource sharing that increases the availability of services and data. Keep the following points in mind:

The Oracle HTTP Server is supported on OpenVMS Alpha Version 7.1-2 or higher.
The Oracle HTTP Server runs in an Alpha or a mixed-architecture cluster.

Individual System versus Clusterwide Definition

To define clusterwide versus 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, then it looks for a clusterwide file in APACHE$COMMON:[directory].

To avoid confusion, always use the appropriate concealed logical name to specify the file that 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

then 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 on which it was saved.

Within HTTPD.CONF itself, you should make this distinction whenever you refer to a path or to a file location. This improves performance and ensures that 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, 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>

If there were content for one specific node in a cluster, the APACHE$SPECIFIC logical name would be used.

Mixed-Architecture Cluster

In a mixed-architecture cluster, do not use a cluster alias IP address with the Oracle HTTP Server. Because the VAX systems will not have the Oracle HTTP Server running, they will not be able to service HTTP requests.

Common Gateway Interface (CGI)

Common Gateway Interface (CGI) programs execute within the DCL shell on the Oracle HTTP Server for OpenVMS. Please note the following OpenVMS specific information.

CGI Environment Logical

By default, an environment logical symbol takes the form that is designated by the name of the environment logical. You can determine how environment logicals are set when the server executes a CGI program.

You can define the APACHE$PREFIX_DCL_CGI_SYMOBLS_WWW logical name to prefix all environment logical symbols with "WWW_". By default, no prefix is used.

The APACHE$CGI_MODE logical name controls how CGI environment logicals 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 logicals are defined as local symbols and are truncated at 970 (limitable with DEC C).

1 Environment logicals 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 logicals are defined as logicals. If the environment value is greater than 512 characters, it is defined as a multi--item logical.

APACHE$DCL_ENV is a foreign symbol that lets you define CGI environment logical, as follows:

APACHE$DCL_ENV [-c] [-d] [-e env-file]

where:

-c Default. Indicates create environment logicals.

-d Indicates delete environment logicals.

-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 can be easily determined by default).

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

Referencing Input

CGI scripts that reference input to the Oracle HTTP Server must refer to APACHE$INPUT.

Executing CGI

On OpenVMS, CGI images execute within a DCL process. You cannot execute CGI images directly.

Logicals for Debugging CGI Scripts

Use the following logicals 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.

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 32768 K (default value). If the image file is smaller than 32768 K, then you can provide an approximate (or actual) size. This will boost performance.

bin-file: Specifies the file to be displayed.

For example:

$ SAY := WRITE SYS$OUTPUT
$ SAY "Content-type: image/gif"
$ SAY ""
$ APACHE$DCL_BIN APACHE$ROOT:[ICONS]APACHE_PB.GIF
$ EXIT

Running the Oracle HTTP Server on OpenVMS 3ñ19

Security Information

The Oracle HTTP Server 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 (ORACLE).

Process Model

The Oracle HTTP Server runs as a single job which consists of:

A master process (ORACLE)

and
Several subprocesses

Subprocesses are created to service incoming HTTP requests and to execute CGI scripts.

Because the server runs as a single job, 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 (ORACLE) where pooled quotas are defined.

Privileged Images

The Oracle HTTP Server performs three operations that require additional privilege:

Binding to a port below 1024 (privileged ports).

By default, the server binds to port 8080 (HTTP).
Fetching path information for other users.

The server provides a replacement for the getpwnam C RTL routine to allow the server to fetch default path information for other users (required by MOD_UTIL and MOD_USERDIR).
Changing the "carriage-control" attribute on socket (BG) devices. The server also enables or disables (or both) the carriage-control attribute on BG (socket) devices for certain stream operations.

Two protected, shareable images are installed at startup to allow the server to perform these functions:

APACHE$PRIVILEGED.EXE (exec-mode services)
APACHE$FIXBG.EXE (kernel-mode services)

The APACHE$PRIVILEGED.EXE image provides exec-mode services for binding to privileged sockets and fetching user default path information. Access to these services is limited to processes running under the ORACLE username and is controlled by the APACHE$PLV_ENABLE_APACHE$WWW logical name. This logical name is defined as:

"APACHE$PLV_ENABLE_APACHE$WWW" = "3,80,1023"

The "3,80,1023" string represents three parameters where:

The first parameter (3) is a bit-mask which enables or disables the two services:
- Bit 0 controls binding to privileged ports.
- Bit 1 controls fetching user default path information.
The second and third parameters are the minimum and maximum port that is allowed to be bound.

When a call to either service is made, the service code:

Temporarily enables the privileges SYSPRV, OPER, SYSNAM, and NETMBX.
Performs the function.
Restores the process original privileges.

The APACHE$FIXBG.EXE_ALPHA image provides a kernel-mode service for manipulating the carriage-control attribute for BG devices that are owned by the calling process. No special access control exists on this service. This function can also be performed using a setsocketopt C RTL run-time call, but it is not supported by all TCP/IP stack vendors, which is the reason this service exists. This service does not enable privileges, but executes in kernel mode.

Privileges Required to Start and Stop the Server

The Oracle HTTP Server runs under the ORACLE 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, and so forth) and are usually performed from a suitably privileged account.

File Ownership and Protection

All of the server files reside under its root directories that are 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 ORACLE.

Server Extensions (CGI Scripts)

Server extensions, such as CGI scripts run within the context of the Oracle HTTP Server 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 that are written by completely trusted users. The Oracle HTTP Server 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.

suEXEC Not Available for Protecting Script Execution

The Oracle HTTP Server for OpenVMS does not currently support the suEXEC method of executing scripts under the username that owns the script. Many sites use this feature to allow execution of arbitrary, user-written scripts without the fear of compromising the server environment.

Open Source Licenses

This section provides open source license acknowledgments and license references.

Apache

This product includes software developed by the Apache Software Foundation (http://www.apache.org/). You can view the license at the following web site:

http://www.openvms.compaq.com/openvms/products/ips/apache/apache_license.txt

This product also includes software that is developed by Hewlett-Packard.

D Apache Server Installation/Configuration