HPlogo Communicator HP e3000 MPE/iX Express 2 Based on Release 6.5 > Chapter 3 Technical Articles

Apache 1.3.9 for MPE/iX

MPE documents

Complete PDF
Table of Contents
Index

By Barbara Dubbert
Commercial Systems Division

Apache 1.3.9 for MPE/iX is based on Apache 1.3.9 from the Apache Software Foundation. It is an upgrade to Apache 1.3.4 for MPE/iX with added enhancements such as DSO capability, an extended API (EAPI), and additional compiled-in modules.

Release Information

Apache 1.3.9 for MPE/iX is available as an individual patch for 6.0 or 6.5 from the HP Response Center. It is not part of the Express 2 release.

System Requirements and Patches

Apache 1.3.9 for MPE/iX requires the following:

  • MPE/iX 6.0 or 6.5

  • General Release Patch MPEKXU3F or supersedes (Release 6.0 only)

It is highly recommended that you also install the latest Network Services Transport patch (NSTxxxxx). The following patches fix a corruption problem when displaying large CGI output over a slow connection:

  • NSTFDR1A or supersedes (Release 6.0)

  • NSTFDR2A or supersedes (Release 6.5)

The following patches are optional. You may want to install one or more of these:

  • MPELX36 - This fix makes it possible to shut down or restart Apache using the kill command as MANAGER.SYS. The kill command can be used without this fix if the user is logged on as WWW.APACHE (Release 6.0 only).

  • MPELX37 - This fix addresses several problems in the TAR utility. Without this fix, files restored from the TAR tape will not have their permissions restored for an existing file on the target system. This could cause problems when updating from Apache versions earlier than 1.3.4 or where the file permissions or file ownership have been changed. (Release 6.0 and 6.5).

  • MPELX44 - This fix provides the capability to use Dynamic Shared Objects (DSOs). It is necessary for running Java Servlets for MPE/iX or any user-designed DSOs (Release 6.0 and 6.5).

  • MPELX51 - This fix makes it possible to shut down or restart Apache using the kill command as MGR.APACHE. The kill command can be used without this fix if the user is logged on as WWW.APACHE (Release 6.0 and 6.5).

  • MPELXC6 - This fix needs to be installed if the following error message occurs and MPELX44 is already installed on your system . "An invalid pointer was detected by VIRTUAL SPACE MANAGEMENT." This situation occurs when trying to load DSOs with Procedure Exits enabled.

  • PX1LXC8 - This patch changes the way getenv() operates. Currently getenv() returns the address of the value of an environment variable. This patch causes the value itself to be returned instead of the address. This change is needed for many customer applications.(Release 6.0 and 6.5).

Support

Apache 1.3.9 for MPE/iX is supported through the HP Response Center as part of MPE FOS support.

Product Description

Apache 1.3.9 for MPE/iX is an upgrade to base version Apache 1.3.9 and also includes major new features and functionality. These new features include:

  • Dynamic Shared Object (DSO) capability

  • Extended API (EAPI)

  • Additional compiled-in modules

  • General bug fixes and upgrades provided by the Apache Software Foundation as part of the Apache 1.3.9 base.

  • File Creation Mask

Dynamic Shared Objects (DSOs)

DSOs are add-on modules that extend the functionality of Apache. These module are loaded at Apache startup (and at restart, i.e. kill -HUP) into Apache process space. These modules exist separately from the Apache binary and allow a user to add new functionality as they desire. This DSO feature keeps Apache memory usage low while still making new features available. It also gives flexibility in Apache installations. No recompilation of Apache is necessary to use DSOs. However, DSOs require a DSO-enabled Apache, such as Apache1.3.9.

HP currently provides a DSO for Java Servlets. This DSO can be installed to run with Apache 1.3.9 or HP Webwise Secure Web Server.

Users can also create their own DSOs. A DSO is an Apache module, similar to the modules that are compiled into the Apache binary. DSOs can be written in C or perl. To write a DSO in C, /APACHE/PUB/libexec/mod_example.c file is a useful template. Mod_example.c compiles into a working DSO by compiling it as a shared library, mod_example.so.

DSOs can also be created by using the bin/apxs utility ("Apache eXtenSion" tool). If creating a DSO using bin/apxs, the -g and -n options will create a module skeleton and corresponding Makefile. This is useful as the Makefile will contain all the necessary MPE compile options. Details on using bin/apxs are found on the apxs manual page on your server in /APACHE/PUB/manual/dso.html. Please note that apxs is a perl script and perl is not distributed with FOS. It is available as downloadable software from http://jazz.external.hp.com but is not supported by HP.

DSOs are configured in conf/httpd.conf by specifying the AddModule and LoadModule directives: 
AddModule mod_example.c
LoadModule example_module libexec/mod_example.so
The LoadModule directive takes two arguments. The first is the name of the module to load. This is the module's structure name from the source file (e.g. mod_example.c). The second argument is the path to the shared object file to load. The path can be relative to the server root (/APACHE/PUB) as shown here, or it can be an absolute path.

EAPI

Apache 1.3.9 is built with an extended set of Apache APIs. This means that Apache also expects these EAPIs to be built into any module it calls, including DSOs. This EAPI feature was included in Apache 1.3.9 so that the same DSOs could be used by both Apache and WebWise without the need to recompile.

When creating DSOs, you must compile with the -DEAPI option. This will include the necessary EAPI header files. These header files are part of the Apache 1.3.9 distribution and reside in /APACHE/PUB/include. The /APACHE/PUB/include directory also contains the README.EAPI file. The README.EAPI file describes the functionality that is available with EAPI such as more features in the mod_rewrite, mod_status, and mod_proxy modules.

DSOs created with the -g -n options of bin/apxs will have a Makefile generated with the -DEAPI option automatically included.

Additional Modules

The Apache 1.3.9 for MPE/iX contains all the modules in Apache 1.3.4 for MPE/iX as well as five additional modules. To view the complete set of modules, execute the Apache binary with the "-l" option:

shell/iX>/APACHE/PUB/HTTPD -l

The modules that are new to Apache 1.3.9 are:

  • mod_proxy, for using the HP e3000 as a proxy server

  • mod_rewrite, for large-scale translation of URLs to a new address

  • mod_digest, a new browser authentication scheme (future browser feature)

  • mod_vhost_alias, for easy use of large numbers of virtual hosts with similar configurations

  • mod_so, makes DSOs loadable

mod_proxy - With this module, Apache can act as a proxy server, or intermediary, when clients make web server requests. Instead of a client making a direct request to a web server, the client makes a request to the proxy server. The proxy server then makes the actual request to the web server. The web server responds to the proxy server who then forwards the response back to the original client.

The proxy server can also cache documents and resources that pass through the proxy interface. If the proxy server has a copy of a requested document, it can return the copy immediately without contacting the web server.

mod_rewrite - Mod_rewrite is a very powerful module for translating requested URLs to new addreses on the fly. The URL manipulations can depend on various tests, for example server variables, environment variables, HTTP headers and time stamps. New translation rules can be added to existing ones. Because of this module's functionality and flexibility, it is complex to use. Extensive documentation on mod_rewrite is available from the official Apache web site, http://www.apache.org.

mod_digest - This module provides a method of authentication, called Digest Authentication. Although Digest Authentication is not currently used by web browsers on the market, it is available to use whenever web browsers adopt this type of authentication. Web browsers currently use Basic Authentication.

mod_vhost_alias - Mod_vhost_alias simplifies the use of large numbers of virtual hosts by replacing static virtual host configurations (<VirtualHost>) with dynamic configuration. With this feature, adding more virtual hosts does not require reconfiguring or restarting Apache. This feature can make Apache startup faster. It also uses less memory because the httpd.conf file is smaller.

mod_so - This module implements the Dynamic Shared Object (DSO) mechanism for loading executable code and modules into Apache at start-up or restart.

Apache 1.3.9 Base Features

An overview of the new Apache 1.3.9 base features is described in the online Apache newsletter, Apacheweek, at http://www.apacheweek.com/issues/99-08-20. These new features include the ability to better handle many virtual hosts, conformance to the latest draft for Digest Authentication, and the abiltiy to customize the name of a cookie.

File Creation Mask

A file creation mask, umask007, was added to the startup stream job, JHTTPD, for increased security. With this change, files created by Apache will prohibit access by anyone outside of the Apache account. Files in this category are log files, files created in the proxy directiory (when Apache is used as a proxy server) and any files created by CGI scripts.

Version Identification

This version of Apache has the product number A.01.00 which is viewable by running the Apache binary with the "-v" option 

  shell/iX> /Apache/PUB/HTTPD -v
  Server version: Apache/1.3.9 (HP MPE/iX A.01.00)
  Server built: Oct 23 2000 13:41:28

Product Installation

Apache 1.3.9 for MPE/iX is installed by following the installation instructions that come with the patch. The product will be installed in /APACHE/PUB and will overlay any previous versions of Apache installed in that location.

Product Configuration

The /APACHE/PUB/conf directory contains the Apache configuration files. After installation, you need to create your own copies of these. The httpd.conf.sample file was derived from the httpd.conf.default file with modifications for Apache on MPE/iX.

Make sure you are logged on as MGR.APACHE before beginning configuration, 

  :HELLO MGR.APACHE
  :xeq sh.hpbin.sys -L
  shell/iX>cd /APACHE/PUB/conf
  shell/iX>cp httpd.conf.sample httpd.conf
  shell/iX>cp mime.types.default mime.types
  shell/iX>cp magic.default magic
The access.conf.default file and the srm.conf.default file need not be copied. These files were used in earlier versions of Apache but their content is now included in the httpd.conf file. However, if these files exist, Apache will read and process them after processing the conf/httpd.conf file.

httpd.conf

Edit the httpd.conf file for your own server. You may also wish to change default values. For information about configuration directives, visit the online Apache documentation at http://www.apache.org/docs. Httpd.conf is a bytestream file. If you have Samba installed, you can edit httpd.conf on your PC.Modify the following httpd.conf directives by replacing "yourserver.com" with your own server name:

  • ServerAdmin MGR.APACHE@yourserver.com

  • ServerName yourserver.com

JHTTPD Job Stream File

The startup job stream file, JHTTPD, is provided as a sample file to prevent overwriting JHTTPD on an existing installation. For new installations, copy the sample file then change the timezone variable, TZ, to your own timezone. Note that the file mask is now set in this file. JHTTPD is an MPE, fixed-record filetype which can be edited with any MPE text editor. 

  shell/iX>cd /APACHE/PUB
  shell/iX>cp JHTTPD.sample JHTTPD
  shell/iX>cat JHTTPD

  !job jhttpd,www.apache,pub;outclass=,2
  !setvar TZ 'PST8PDT'
  !xeq sh.hpbin.sys \
    "-c 'umask 007;./HTTPD -f /APACHE/PUB/conf/httpd.conf'"
  !eoj

Updating from Earlier Versions

If you are updating from earlier versions of Apache, rename or remove the existing log files after stopping Apache. This way, Apache can create fresh log files with the correct ownership and permissions. Startup errors will also be easier to detect. Make sure to stop Apache before renaming or trying to remove these files. Apache will continue to hold log files open and write to them while it is running. 

  shell/iX>kill `cat /APACHE/PUB/logs/httpd.pid
  shell/iX>cd /APACHE/PUB/logs
  shell/iX>mv error_log error_log134
  shell/iX>mv access_log access_log134
Apache 1.3.9 runs as WWW.APACHE. If your previous version of Apache was running as a different user, you must change your documents (.html, .txt, etc.) to be readable by WWW.APACHE, your log files must be writeable by WWW.APACHE, and your CGI must be executable by WWW.APACHE. The Apache Troubleshooting Guide, http://jazz.external.hp.com/src/apache/troubleshoot.txt, has examples on how to set these permissions. File permissions will not be updated by the Apache 1.3.9 installation unless patch MPELX37 is installed.

If your current version of Apache is running successfully as WWW.APACHE, such as Apache 1.3.4, update to Apache 1.3.9 by following the installation and configuration instructions as given. File permissions should not be a problem.

Running Apache

Startup

Apache can be started from either the CI or the POSIX shell. 

  :stream jhttpd.pub.apache
  or
  shell/iX>callci stream JHTTPD.PUB.APACHE

Verifying Startup

Successful installation and startup of Apache 1.3.9 can be verified by

  • Doing a :SHOWJOB to see if JHTTPD,WWW.APACHE is running

  • Checking JHTTPD's output spoolfile

  • Looking at the content of the error_log

  • Accessing web pages

To check the content of the error_log, 

  shell/iX>cd /APACHE/PUB/logs
  shell/iX>tail error_log
If the JHTTPD job is running, try accessing Apache's home page, http://yourserver.com

If Apache does not start, try consulting the Apache Troubleshooting Guide for tips on debugging the problem.

Shutdown

Apache can be shut down by issuing an :ABORTJOB or kill. Using kill (which defaults to kill -TERM) is the preferred method since it uses Apache's internal routines to clean up open resources and shut down gracefully.

Apache can be restarted by issuing a kill -HUP. A restart will cause Apache to reread its configuration files without having to stop and restream the Apache job stream file. Restart is useful for making configuration changes without disrupting web users. After a restart, Apache continues running with the new configuration settings.

To use kill requires the use of one of the following:

  • Log on as WWW.APACHE

  • Log on as MANAGER.SYS with MPELX36 installed (patch needed for Release 6.0 only)

  • Log on as MGR.APACHE with MPELX51 installed (patch needed for Release 6.0 and 6.5)

To shut down Apache:

:ABORTJOB JHTTPD,WWW.APACHE

or

shell/iX>kill `cat /APACHE/PUB/logs/httpd.pid`

or

:xeq sh.hpbin.sys "-c 'kill `cat /APACHE/PUB/logs/httpd.pid`'"

To restart Apache:

shell/iX>kill -HUP `cat /APACHE/PUB/logs/httpd.pid`

or

:xeq sh.hpbin.sys "-c 'kill -HUP `cat /APACHE/PUB/logs/httpd.pid`'"

Additional Resources

For general Apache information, the official Apache web site, http://www.apache.org, contains documentation on configuration and functionality, FAQs, a list of books, and much more.

Apacheweek, http://www.apacheweek.com, is a weekly digest of Apache activities, book reviews, and in-depth articles on Apache features. After installing Apache, your manual directory contains a User's Guide, Reference Manual, and other information which pertains to the installed version of Apache: http://yourserver.com/manual. For writing DSOs, a good reference is Writing Apache Modules with Perl and C, by Lincoln Stein and Doug MacEachern, published by O'Reilly & Associates, ISBN 1-56592-567-X. For MPE-specific information on Apache, the following documents are available on HP's online document site, http://docs.hp.com

  • Configuring and Managing MPE/iX Internet Services for Release 6.5, Chapter 9

  • Communicator 3000 MPE/iX Release 6.5



Using the AS Clause in ALLBASE/SQL

Java Servlets for MPE/iX