APACHE_1_3_42/src/os/mpeix/README

                        Using Apache With HP MPE/iX

This document explains how to compile, install, configure and run Apache
1.3 under HP MPE/iX.

The bug reporting page and new-httpd mailing list are NOT provided to
answer questions about configuration or running Apache. Before you submit a
bug report or request, first consult this document, the Frequently Asked
Questions page and the other relevant documentation topics. If you still
have a question or problem, post it to the comp.sys.hp.mpe newsgroup or the
associated HP3000-L mailing list, where many Apache users and several
contributors are more than willing to answer new and obscure questions
about using Apache on MPE/iX.

deja.com's newsgroup archives offer easy browsing of previous questions.
Searching the newsgroup archives, you will usually find your question was
already asked and answered by other users!

---------------------------------------------------------------------------

   * Requirements
   * Implementation Considerations
   * Binary Distributions
   * Create the Accounting Structure
   * Downloading Apache
   * Compiling Apache
   * Installing Apache
   * Configuring Apache
   * Running Apache
   * Controlling Apache

---------------------------------------------------------------------------

Requirements

Apache 1.3 requires MPE/iX 6.0 or greater.  It will NOT run on earlier
releases of MPE/iX.  The following MPE/iX patches (or their superseding
descendants) are relevant to Apache:

   * MPE/iX 6.0:
        o MPEKXT3B - fixes an MPE bug that results in transient "permission
          denied" errors being returned by the server to the browser.
        o MPELX36A - enhances the kill() function so that MPE users with SM
          capability can send signals to Apache for shutdown, restart, etc.
        o MPELX44C - fixes an MPE bug that prevents DSO modules from being
          dynamically loaded.
        o MPELX51C - enhances the kill() function so that Apache can use it
          when the Apache parent UID is different from the Apache children
          UID (strongly recommended).
        o NSTxxxxx - the latest network transport patch should always be
          installed when using TCP/IP applications such as Apache.
   * MPE/iX 6.5:
        o MPELX44D - fixes an MPE bug that prevents DSO modules from being
          dynamically loaded.
        o MPELX51D - enhances the kill() function so that Apache can use it
          when the Apache parent UID is different from the Apache children
          UID (strongly recommended).
        o NSTxxxxx - the latest network transport patch should always be
          installed when using TCP/IP applications such as Apache.

---------------------------------------------------------------------------

Implementation Considerations

While MPE has a very good POSIX implementation that enables fairly simple
porting of Unix applications such as Apache, there are some Unix concepts
which just don't exist or aren't fully implemented in MPE, and so this may
force some functionality changes in the package being ported.

Significant MPE vs. Unix OS differences

   * MPE lacks the concept of a Unix UID=0 root user with special
     privileges.  Where Unix functions require a user to be executing as
     root, MPE requires the user to be executing in priv mode, so the
     program file must be linked with PM (Priv Mode) capability, and the
     Unix function calls must be bracketed by GETPRIVMODE() and
     GETUSERMODE() calls.  The following Unix functions used by Apache are
     affected:
        o bind() for ports less than 1024
        o setgid()
        o setuid()
   * MPE's support for UIDs and GIDs is more limited than Unix.  Every MPE
     account maps to a unique GID.  Each MPE account can contain multiple
     MPE users, and every MPE user maps to a unique UID (UID 0 is not
     supported).  The current UID for a process must correspond to an MPE
     user within the MPE account that corresponds to the current GID of the
     process.
   * MPE child processes cannot survive the death of their parent.  When
     the parent terminates, any remaining children will be killed.
   * MPE doesn't initialize the envp parameter when invoking the main() of
     a new process.  Use the global variable environ instead of envp.
   * MPE link() exists, but always returns EIMPL.  Use rename() or symlinks
     instead of hard links.
   * MPE doesn't allow the @ character in filenames.
   * MPE lacks support for TCP_NODELAY, but that's the default anyway.
   * MPE lacks support for SO_KEEPALIVE.
   * MPE lacks support for process groups.
   * MPE inetd only passes stdin (and NOT stdout) to the invoked service.
     But you can write to stdin just fine.

Major Apache functionality issues

   * Beginning with HP-supported Apache 1.3.9 and HP WebWise MPE/iX Secure
     Web Server A.01.00 (based on Apache 1.3.9), the User and Group
     directives in httpd.conf are now unconditionally executed as
     corresponding setuid()/setgid() calls.  Previously this was only done
     if HTTPD was being run as MANAGER.SYS.  This functionality change was
     submitted back to the 1.3.13-dev source tree at www.apache.org.  The
     Apache for Unix behavior is to only honor User and Group if running as
     root.
   * Beginning with HP-supported Apache 1.3.9 and HP WebWise MPE/iX Secure
     Web Server A.01.00 (based on Apache 1.3.9), the SVIPC shared memory
     macros SHM_R and SHM_W have been modified from their traditional
     owner-only-read and owner-only-write values to be owner-and-group-read
     and owner-and-group-write on MPE/iX in order to allow increased
     parent/child flexibility in spite of MPE's limited POSIX UID/GID
     support.  This functionality change was submitted back to the
     1.3.13-dev source tree at www.apache.org.  The Apache for Unix
     behavior uses the traditional owner-only values of SHM_R and SHM_W.

Minor Apache functionality issues

   * Apache for Unix must be run as root to bind to TCP ports 1-1023.
     Apache for MPE must call GETPRIVMODE() to bind to TCP ports 1-1023; PM
     is not used for ports greater than 1023. The standard web server HTTP
     port is 80.
   * Apache for Unix in standalone mode will detach itself and run in the
     background as a system-type process. Apache for MPE in standalone mode
     cannot detach itself and run in the background because MPE POSIX
     doesn't allow this (the detached child would be killed when the parent
     terminated).  Therefore you must use an MPE batch job to run Apache in
     standalone mode.
   * Apache for Unix uses process groups to manage child processes. Apache
     for MPE cannot use process groups because MPE POSIX doesn't support
     this. The implications of this are unknown.
   * Apache for Unix uses the setsockopt() option TCP_NODELAY. Apache for
     MPE does not, because MPE doesn't support it. But TCP_NODELAY is the
     default MPE behavior anyway.
   * Apache for Unix uses the setsockopt() option SO_KEEPALIVE.  Apache for
     MPE does not, because MPE doesn't support it.
   * Apache for Unix under inetd reads from the socket via stdin and writes
     via stdout. Apache for MPE under inetd reads *AND* writes the socket
     via stdin. I consider MPE 5.5 inetd to be broken and poorly
     documented, so I submitted SR 5003355016 to address this. If HP ever
     alters the MPE inetd to pass the socket the way HPUX inetd does (not
     likely in the grand scheme of things), the existing Apache for MPE
     code will break.
   * Apache for Unix will use the @ character in proxy cache filenames, but
     since @ is illegal in MPE filenames, Apache for MPE uses the %
     character instead.

---------------------------------------------------------------------------

Binary Distributions

HP ships a fully supported Apache binary distribution with the Fundamental
Operating System (FOS) in MPE/iX 6.5 and later.  This distribution can be
found in the APACHE account.

HP supplies fully supported Apache binary distributions for MPE/iX 6.0 or
later available for downloading from
http://jazz.external.hp.com/src/apache/.

Mark Bixby supplies Apache binary distributions for MPE/iX available for
downloading from http://www.bixby.org/mark/apacheix.html.  Binaries from
bixby.org are NOT supported by HP.  HP only supports binaries distributed
by HP.

All of the binary distributions mentioned above may possibly include
functionality that hasn't yet been submitted back to the Apache Software
Foundation (though submitting back is the intended goal).  Please read the
documentation that comes with these binaries in order to determine
functionality differences (if any) compared to the latest sources available
from the ASF.

If you will be using one of these binary distributions, please stop reading
this document and start reading the specific distribution documentation for
installation details.

---------------------------------------------------------------------------

Create the Accounting Structure

Apache can be installed under the account of your choice.  For the purposes
of this document, the APACHE account will be used:

  1. :HELLO MANAGER.SYS
  2. :NEWACCT APACHE,MGR
  3. :ALTACCT APACHE;PASS=xxxxxxxx;CAP=AM,AL,ND,SF,BA,IA,PM,PH
  4. :ALTGROUP PUB.APACHE;CAP=BA,IA,PM,PH;ACCESS=(R,L,X:AC;W,A,S:AL)
  5. :ALTUSER MGR.APACHE;CAP=AM,AL,ND,SF,BA,IA,PM,PH;HOME=PUB
  6. :NEWUSER SERVER.APACHE
  7. :ALTUSER SERVER.APACHE;CAP=ND,SF,BA,IA,PH;HOME=PUB

Downloading Apache

Use your web browser to download the Apache source tarball from
http://www.apache.org/dist/.  Then ftp upload the tarball to your e3000 as
show below:

C:\Temp>ftp 3000.host.name
Connected to 3000.host.name.
220 HP ARPA FTP Server [A0009H09] (C) Hewlett-Packard Co. 1990
User (3000.host.name:(none)): MGR.APACHE
331 Password required for MGR.APACHE.  Syntax: acctpass
Password:xxxxxxxx
230 User logged on
ftp> quote type L 8
200 Type set to L (byte size 8).
ftp> put apache_v.u.ff.tar.Z /tmp/apache.tar.Z
200 PORT command ok.
150 File: /tmp/apache.tar.Z opened; data connection will be opened
226 Transfer complete.
ftp: 2685572 bytes sent in 2.75Seconds 976.57Kbytes/sec.
ftp> quit
221 Server is closing command connection

Unpack the tarball:

  1. :HELLO MGR.APACHE
  2. :XEQ SH.HPBIN.SYS -L
  3. $ mkdir src
  4. $ chmod 700 src
  5. $ cd src
  6. $ tar xvfopz /tmp/apache.tar.Z

Compiling Apache

It is STRONGLY recommended to use gcc instead of the HP C/iX compiler.  You
can obtain gcc from http://jazz.external.hp.com/src/gnu/gnuframe.html.

  1. $ cd apache_v.uu.ff
  2. $ ./configure --prefix=/APACHE/PUB --enable-module=xxx
     --enable-module=yyy ...etc...
  3. $ make

Installing Apache

  1. $ make install
  2. $ cd /APACHE/PUB
  3. $ mv bin/httpd HTTPD
  4. $ ln -s HTTPD bin/httpd
  5. $ callci "xeq linkedit.pub.sys 'altprog HTTPD;cap=ia,ba,ph,pm'"

Configuring Apache

Edit /APACHE/PUB/conf/httpd.conf and customize as needed for your
environment.  Be sure to make the following mandatory changes:

   * User SERVER.APACHE
   * Group APACHE

Running Apache

Simply create and :STREAM the following standalone server job in order to
start Apache:

!JOB JHTTPD,MGR.APACHE;OUTCLASS=,2
!XEQ SH.HPBIN.SYS "-c 'umask 007; ./HTTPD -f /APACHE/PUB/conf/httpd.conf'"
!eoj

Controlling Apache

Log on as MGR.APACHE (or MANAGER.SYS or any other SM user if you've
installed MPELX36A on 6.0) in order to shutdown or restart Apache via the
use of signals.

To shut down Apache from the POSIX shell:

$ kill `cat /APACHE/PUB/logs/httpd.pid`

To shut down Apache from the CI:

:XEQ SH.HPBIN.SYS '-c "kill `cat /APACHE/PUB/logs/httpd.pid`"'