Apache 2.0 on OS/390

Introduction and disclaimers

This is not part of the Apache 2.0 documentation. This is not a statement of Apache Software Foundation or Apache HTTP Server Project or even anybody really important.

Support

Who is closely tracking Apache 2.0 on OS/390 and can try to help you?

Jeff Trawick, trawick@apache.org
Greg Ames, gregames@apache.org

Don't even think about contacting me if you haven't read all of this document. I don't mind questions about items in these documents but I want to make sure that people take the ten-to-fifteen minutes required to go through them before they send e-mail to the first address they find.

Bug reports

Go to http://nagoya.apache.org/bugzilla and enter a bug report. Make sure to provide appropriate detail. Don't expect a response immediately. It is useful information to people who follow the reports, even if none of the handful of such people are able to do anything about it right away.

Mailing lists

If you suspect a problem or want to discuss a design issue with Apache 2.0 and you want more interaction than entering a bug report, feel free to subscribe to dev@httpd.apache.org by sending a blank message to dev-subscribe@httpd.apache.org, then post your question there. You'll likely get flamed, but whatever (just kidding). Please note that this is not a support forum for admin questions.

If you have a patch to resolve the problem in your e-mail, that is great.

Note that issues with code in srclib/apr and srclib/apr-util are discussed at dev@apr.apache.org. You can subscribe to that list by sending a blank message to dev-subscribe@apr.apache.org.

Information about all mailing lists can be found at http://www.apache.org/foundation/mailinglists.html. There are pointers from that page to archives for many of the lists.

Prereqs

compiler: IBM's C compiler (I've never tried gcc; it is very possible that tweaks would be needed to support gcc)
non-GNU libtool
Get this libtool: libtool.tar.Z
GNU autoconf and GNU m4
Get GNU autoconf and GNU m4 from http://www-1.ibm.com/servers/eserver/zseries/zos/unix/redbook/index.html . Whoops, links to autoconf on that page are hidden. try these:
```
ftp://ftp.software.ibm.com/s390/zos/tools/autoconf/autoconf.pax.Z.bin 
ftp://ftp.software.ibm.com/s390/zos/tools/autoconf/autoconf-2.54-ebcdic-bin.pax
```
shell script to unpack tarball on OS/390: xtar
apache source tarball httpd-2.0.XX.tar.Z from http://www.apache.org/dist/httpd/

Building and configuring...

Broken configurations

mod_proxy as a DSO

mod_proxy must be build statically. If it is built as a DSO (e.g."--enable-proxy=shared"), you'll get errors like this:

Building shared: mod_proxy.la mod_proxy_connect.la mod_proxy_ftp.la
mod_proxy_http.la
/bin/sh /u/trawick/apache/httpd-2.0/shlibtool --silent --mode=link cc -->
---DNO_DBM_REWRITEMAP  -U_NO_PROTO -->
---DPTHREAD_ATTR_SETDETACHSTATE_ARG2_ADDR -DPTHREAD_SETS_ERRNO -->
---DPTHREAD_DETACH_ARG1_ADDR -DSIGPROCMASK_SETS_THREAD_MASK -->
---DTCP_NODELAY=1  -I/u/trawick/apache/httpd-2.0/srclib/apr/include -->
---I/u/trawick/apache/httpd-2.0/srclib/apr-util/include -->
---I/u/trawick/apache/httpd-2.0/srclib/apr-util/xml/expat/lib -->
---I. -I/u/trawick/apache/httpd-2.0/os/unix -->
---I/u/trawick/apache/httpd-2.0/server/mpm/prefork -->
---I/u/trawick/apache/httpd-2.0/modules/http -->
---I/u/trawick/apache/httpd-2.0/modules/filters -->
---I/u/trawick/apache/httpd-2.0/modules/proxy -->
---I/u/trawick/apache/httpd-2.0/include -->
---I/u/trawick/openssl/include/openssl -I/u/trawick/openssl/include -->
---I/u/trawick/apache/httpd-2.0/modules/dav/main -export-dynamic -->
---L/u/trawick/apache/httpd-2.0/srclib/apr-util/xml/expat/lib -->
---L/u/trawick/openssl/lib -->
----core-dll=/u/trawick/apache/httpd-2.0/apachecore.dll   -o -->
--mod_proxy_connect.la -rpath /u/trawick/apacheinst/modules -module -->
---avoid-version  proxy_connect.lo
 IEW2456E 9207 SYMBOL proxy_hook_canon_handler UNRESOLVED.  MEMBER
 COULD NOT BE
          INCLUDED FROM THE DESIGNATED CALL LIBRARY.
 IEW2456E 9207 SYMBOL proxy_hook_scheme_handler UNRESOLVED.  MEMBER
 COULD NOT BE
          INCLUDED FROM THE DESIGNATED CALL LIBRARY.
 IEW2456E 9207 SYMBOL ap_proxy_connect_to_backend UNRESOLVED.  MEMBER
 COULD NOT
          BE INCLUDED FROM THE DESIGNATED CALL LIBRARY.
 IEW2456E 9207 SYMBOL ap_proxy_checkproxyblock UNRESOLVED.  MEMBER
 COULD NOT BE
          INCLUDED FROM THE DESIGNATED CALL LIBRARY.
 IEW2456E 9207 SYMBOL ap_proxyerror UNRESOLVED.  MEMBER COULD NOT BE
 INCLUDED
          FROM THE DESIGNATED CALL LIBRARY.
FSUM3065 The LINKEDIT step ended with return code 8.
libtoolexe: returning error code 3...
FSUM8226 make: Error code 3
FSUM8226 make: Error code 1
FSUM8226 make: Error code 1
FSUM8226 make: Error code 1
FSUM8226 make: Error code 1

mod_ssl as a DSO

mod_ssl must be built statically. Otherwise there are link-edit errors accessing openssl routines.

Goal for the configuration

An important module for EBCDIC machines is mod_charset_lite, which allows you to translate the character set of documents before they are sent to the client. Since mod_charset_lite is not included in the build by default, we'll add it explicitly by adding "--enable-charset-lite=shared" to the normal configure parameters. Build Apache with a few standard modules, including mod_so so that you can (hopefully) load your own module into the server. We'll add mod_ssl too.

We should use the worker MPM because that is the strategic multi-process, multi-threaded MPM for Unix, but this example uses the prefork MPM, which behaves like Apache 1.3.

Details of the build

Grab the source tarball. Uncompress the tarball with uncompress. Unpack the tarball using xtar. Change into the root source directory. Run buildconf and configure like this:

$ ./buildconf
$ ./configure --prefix=/u/trawick/apacheinst --with-mpm=prefork \
  --enable-charset_lite=shared --enable-proxy \
  --enable-ext-filter=shared

If you want mod_ssl, also add --enable-ssl --with-ssl=/path/to/openssl.

--prefix is used to override the default install path of /usr/local/apache2. --with-ssl is used to override the default locations of openssl.

This first step will take a long time while it detects what capabilities are available on your system. After this is done, run make and make install.

Other build notes

Use make distclean to clean things up back to the point of unpacking a tarball. If you are updating from CVS, use make extraclean followed by buildconf any time you update to get to the state of a fresh tarball.

Running it

Do it just like 1.3 except for the directory. Put /usr/local/apache2/bin in your PATH and use apachectl start.

Note that some environment variables are required on OS/390. Make sure you use apachectl to start it instead of invoking httpd directly. As of 2.0.37, apachectl can be used to pass in any httpd options, so no function is lost.

If you enable mod_ssl and initialization terminates with messages like these in error_log

[Fri Jun 14 13:19:15 2002] [warn] Init: PRNG still contains not sufficient entropy!
[Fri Jun 14 13:19:15 2002] [error] Init: Failed to generate temporary 512 bit RSA private key
Configuration Failed

you'll need to supply some entropy. (OS/390 doesn't support /dev/random.) One way is to copy some entropy from /dev/random to a file on Linux, then transfer that to a file on OS/390. If that file is $HOME/.rnd, then the openssl command will be happy with it too. You'll need something like this in httpd.conf, though:

SSLRandomSeed startup /home/trawick/.rnd
SSLRandomSeed connect /home/trawick/.rnd

If the BPX.DAEMON facility class is defined on your system and you start Apache with UID(0), you'll need to take extra steps after installation. Otherwise, Apache will fail to initialize and you'll get messages like this in error_log:

[Fri Jun 14 13:29:29 2002] [alert] (157)EDC5157I An internal error has
occurred. (errno2=0x0B8802AF) : setuid: unable to change to uid: 7008
[Fri Jun 14 13:29:30 2002] [alert] Child 16777630 returned a Fatal error...
Apache is exiting!

Here is how to fix this:

cd /where/you/installed/apache
extattr +ap bin/httpd lib/apachecore.dll modules/*.so

After starting Apache, try to read the start page from a browser. If it is gibberish, you forgot to configure mod_charset_lite. A simple config to start with is to add

   CharsetSourceEnc IBM-1047
   CharsetDefault   ISO8859-1

inside the container for directory /, as in

<Directory />
    Options FollowSymLinks
    AllowOverride None
   CharsetSourceEnc IBM-1047
   CharsetDefault   ISO8859-1
<Directory>

This should be sufficient for loading the default pages supplied with Apache (including the manual). For your own pages, particularly if some are stored in character sets other than IBM-1047, please see the mod_charset_lite documentation in the Apache manual.

If you want to enable mod_status, find this section:

#<Location /server-status>
#    SetHandler server-status
#    Order deny,allow
#    Deny from all
#    Allow from .your_domain.com
#</Location>

and uncomment all but the Order, Deny, and Allow lines. Also, find #ExtendedStatus On and uncomment that too. The server-status page with 2.0 still isn't completely accurate but it is nice to have anyway.

Important: See the documentation for mod_access for what to do with the Order, Deny, and Allow lines in case you want to restrict who can see your server-status page.