Installing Apache on TPF

## Installing the Apache 1.3 HTTP Server on TPF

[ Download | Compilation | Installation | VisualAge ]

This document outlines the steps needed to install Apache onto a TPF system.

You should first read readme-tpf.html for basic information on the port of Apache to TPF including required PUT level and supported modules.

## Download

Releases of the Apache server are compressed into a "tarball" file which must be downloaded to your PC. Additionally the source code from the tarball will need to be copied onto an OS/390 UNIX System Services machine (later referred to simply as "OS/390 UNIX") for compiling. Here are all the details on how to get Apache and how to get it where it needs to be:

1. Download the compressed Apache files (the "tarball") to your PC. The file name on the web site will be something like `apache_1.3.xx.tar.Z`.
   TIP: Be sure to keep the `.tar.Z` extension when choosing the name of the PC file.
2. Decompress the tarball on your PC using WinZip or some other PC decompression tool.
   TIP: If you are using WinZip verify that the "TAR File Smart CR/LF Conversion" option (under Options, Configuration) is NOT checked.
   This is what you can expect if you use WinZip:
   - open the tarball with WinZip (this can usually be done simply by double-clicking on the downloaded tarball)
   - you will be told that the archive contains one file (such as apache_1.3.xx.tar) - allow WinZip to decompress it to a temporary folder
   - extract the archived files onto your PC - you'll be using files from the `conf, htdocs,` and `icons` directories later in the install phase
3. FTP the tarball to your OS/390 UNIX machine using binary mode:
   - activate FTP in an MSDOS window: `ftp your.os390.unix.machine.com`
   - sign in
   - set mode to binary: `binary`
   - send the file to OS/390 UNIX:
     `send c:\downloaded_filename.tar.Z os390_unix_filename.tar.Z`
   - exit FTP: `bye`

   TIP: UNIX file names are case sensitive. If you use an NFS client to transfer files from your PC to OS/390 UNIX (instead of using FTP as described above) verify that the NFS drive will transfer the file names with upper/lower case preserved.

4. Decompress and extract the archived files necessary for compiling Apache:
   `pax -rvzkf os390_unix_filename.tar.Z -o from=ISO8859-1,to=IBM-1047 "*/src"`
5. Remove unnecessary subdirectories:
   - `cd apache_1.3.xx/src/lib`
   - `rm -r expat-lite sdbm`
   - `cd ../os`
   - `rm -r bs2000 cygwin mpeix netware os2 os390 win32`
   - `cd ..`

## Compilation

Apache supports the notion of "optional modules". However, the server has to know which modules are compiled into it. In order for those modules to be effective, it is necessary to generate a short bit of code (modules.c) which simply has a list of them. If you are using the `Configure` utility and `make`, modules.c and other necessary files will be created for you automatically.

The provided instructions assume a c89 compiler and have been tested on an OS/390 UNIX machine running at version 2.6 that contained both OS/390 UNIX and TPF C header files. If you are using a platform other that OS/390 UNIX you may need to modify src/os/tpf/TPFExport and src/Configure to match your environment.
TIP: Editing files on your PC prior to moving them to OS/390 UNIX may result in the loss/addition of unprintable characters. Files of concern include shell scripts and src/Configuration. The most common problems are with tab characters and CR/LF characters. Most editors will handle the CR/LF problem correctly but none seem to handle tab characters. If you need to edit files prior to moving them to OS/390 UNIX, edit them in a UNIX editor such as vi or emacs.

Note that OS/390 UNIX commands in this section are shown in `bold`, are case sensitive, and must be made from the "src" directory.

1. Switch to the source code subdirectory: `cd apache_1.3.xx/src`
2. Overlay src/Configuration with src/Configuration.tmpl: `cp Configuration.tmpl Configuration`
3. Edit src/Configuration. It contains the list and settings of various "Rules" and an additional section at the bottom that determines which modules to compile:
   - comment out (by preceding the line with a "#") lines corresponding to those modules you DO NOT wish to include
   - uncomment (by removing the initial "#", if present) lines corresponding to those modules you wish to include or add new lines corresponding to any custom modules you have written (the readme-tpf.html document lists the modules that have been tested on TPF)
   - if you did not delete the src/lib/expat-lite directory as noted in the download instructions, add "`Rule EXPAT=no`" to the src/Configuration file
   - adjust the other rules, `EXTRA_CFLAGS`, `EXTRA_LIBS`, `EXTRA_LDFLAGS`, and `EXTRA_INCLUDES` settings if you feel so inclined

   The modules placed in the Apache distribution are the ones that have been tested and are used regularly by various members of the Apache development group. Additional modules contributed by members or third parties with specific needs or functions are available at http://modules.apache.org/. There are instructions on that page for linking these modules into the core Apache code.

4. Indicate whether the `non_socket_select` function is implemented on your system.

   If you are on a PUT12 or higher system, or have PJ26895 installed, then you probably support `non_socket_select`.
   You can verify this by looking for the `non_socket_select` prototype in your system header files (specifically `i$pwbl.h`).

   If your TPF system supports `non_socket_select` do one of the following:

   - add "`#define TPF_HAVE_NONSOCKET_SELECT`" to `src/os/tpf/os.h` or
   - add "`-DTPF_HAVE_NONSOCKET_SELECT`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport

   Otherwise:

   - add "`#define TPF_NO_NONSOCKET_SELECT`" to `src/os/tpf/os.h` or
   - add "`-DTPF_NO_NONSOCKET_SELECT`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport

   Without `non_socket_select` CGI output is buffered and only sent to the browser when the CGI program finishes.

5. Indicate whether the `tpf_sawnc` function is implemented on your system.

   If you are on a PUT10 or higher system, or have PJ27387/PJ26188 installed, then you probably support `tpf_sawnc`.
   You can verify this by looking for the `tpf_sawnc` prototype in your system header files (either `tpfapi.h` or `i$fsdd.h`).

   If your TPF system supports `tpf_sawnc` do one of the following:

   - add "`#define TPF_HAVE_SAWNC`" to `src/os/tpf/os.h` or
   - add "`-DTPF_HAVE_SAWNC`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport

   Otherwise:

   - add "`#define TPF_NO_SAWNC`" to `src/os/tpf/os.h` or
   - add "`-DTPF_NO_SAWNC`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport

   The use of `tpf_sawnc` allows for a cleaner shutdown of Apache.

6. Indicate if you would like to use the TCP/IP network services database. (This only applies if you are using TCP/IP native stack.)

   If you are on a PUT16 or higher system, or have PJ28195 installed, you can use the TCP/IP network services database. To do so, you must do one of the following:

   - add "`#define TPF_HAVE_NSD`" to `src/os/tpf/os.h` or
   - add "`-DTPF_HAVE_NSD`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport

   See TPF Transmission Control Protocol/Internet Protocol for more information about the TCP/IP network services database: http://www.ibm.com/tpf/pubs/tpfpubs.htm.

7. Set the TPF environment variables: `. os/tpf/TPFExport`
   TIP: The initial period and blank on the command are required to ensure the environment variables exist beyond the scope of the shell script.
   This script will set the environment variables required to compile the programs for TPF. Verify that the export variables are valid for your installation, in particular, the system include file directories. The system include files must reside on your OS/390 UNIX system in the appropriate file structure similar to /usr/include and /usr/include/sys. DO NOT modify the `TPF=YES` export variable. If this is changed, the "Configure" script will not recognize TPF.
8. Run the "Configure" script: `Configure`

   This generates modules.c, include/ap_config_auto.h, and necessary Makefiles:

             Using config file: Configuration
             Creating Makefile
              + configured for TPF platform
              + setting C compiler to c89
              + setting C pre-processor to c89 -E
              + checking for system header files
              + adding selected modules
              + checking sizeof various data types
             Creating Makefile in support
             Creating Makefile in regex
             Creating Makefile in os/tpf
             Creating Makefile in ap
             Creating Makefile in main
             Creating Makefile in modules/standard
             $ _

   If you want to maintain multiple configurations, you can say, for example,
   `Configure -file Configuration.2nd`

             Using config file: Configuration.2nd
             Creating Makefile
              + configured for <whatever> platform
              + setting C compiler to <whatever>
             et cetera

   If you receive an error such as "`Configure 146: FSUM7351 not found`" the most likely explanation is that one or more of the `make` related files were edited on a non-UNIX platform, corrupting the end-of-line marks. Verify that lines ending with "\" in the flagged file do not have trailing spaces. Using the vi editor and the sample error above as an example...

            pull up the flagged file:       vi Configure
            turn on punctuation:            :set list
            go to the line in question:     146G
               or find a line with a "\":   /\\

   The end of line should display as "`\$`". If it is displayed as "`\ $`" (with a blank between \ and $) then you should revert to the distributed version of the file and make the site-specific changes again using a UNIX compatible editor such as vi or emacs. Then try the Configure command again.

            close the file:                 :q  (or :quit!)

9. Edit include/ap_config.h if you do not want the scoreboard kept in shared memory.

   The default behavior for Apache on all platforms except TPF is to use the file system for maintaining the scoreboard (which holds current Apache children status). The default behavior for Apache on TPF is to use shared memory. This reduces file activity for the parent Apache ECB and improves performance. If you are on a pre-PUT10 system you must change ap_config.h to use either system heap or the file system.

   To use system heap for the scoreboard replace `#define USE_SHMGET_SCOREBOARD` with `#define USE_TPF_SCOREBOARD` in the TPF section of ap_config.h.
   If you prefer instead to use the file system, remove both `#define USE_SHMGET_SCOREBOARD` and `#define USE_TPF_SCOREBOARD` from the TPF section of ap_config.h
   The change will only take effect after Apache is (re)compiled.
10. Now compile the programs: `make`

    Besides compiling, `make` also runs src/main/gen_test_char.c and src/main/gen_uri_delims.c in order to create src/main/test_char.h and src/main/uri_delims.h respectively

    - The following compilation warning is expected and can be ignored:
      util_uri.c: `Function argument assignment between types "unsigned char*" and "const unsigned char*" is not allowed.`
    - If during compilation you get a warning about a missing 'regex.h', set `WANTHSREGEX=yes` in the src/Configuration file and start back at the `Configure` step.
    - If you get a '`Duplicate type specifier "long" ignored`' error, add "`-W 0,langlvl(extended)`" to the `_C89_OPTIONS` export in src/os/tpf/TPFExport and start back at the `export` step

## Installation

1. Link the compiled object files into a DLL. Sample link JCL has been included as src/os/tpf/samples/linkhttp.jcl. You will need to modify this JCL:
   - Change the IDs, data set names, and libraries for your particular site.
   - Add/remove `mod_xxx.o` files so they correspond to the `mod_xxx.o` lines in your src/Configuration file.
   TIP: Do NOT include gen_test_char.o or gen_uri_delims.o in the link JCL since these files are only used during the `make` step.
   If you receive an "Unresolved references" error for "`XML_ErrorString`" you probably need to remove the expat-lite directory and start back at the "Run the Configure script" step
   If you receive an "unable to open" error for `lib/expat-lite/hashtable.o`" you probably need to remove all of the expat-lite .o's from your link JCL
2. Create a loadset. Sample loadset JCL has been included as src/os/tpf/samples/loadset.jcl. You will need to modify this JCL for your particular site.
   A JCL condition code of 4 is expected since the C load module will contain no link map data.
3. Load (`ZOLDR LOAD`) and activate (`ZOLDR ACT`) the loadset on your test system.
4. Ensure that the program name you are using for Apache has `RESTRICT` and `KEY0` authorization. `zdpat chta` (c-c) will display allocation information. You can use `zapat chta restrict key0` `(c-c)` to alter the authorization. Note that if the program name is unallocated, you must have the loadset for it activated or you will receive `INVALID PROGRAM NAME` from the `zdpat/zapat` entries.
5. Create the Apache run-time configuration file. The server requires a configuration file to initialize itself during activation. (Previously three configuration files were used.) Copy the distribution version, /conf/httpd.conf-dist, to /conf/httpd.conf and then edit the /conf/httpd.conf copy with your site specific information.

   At a minimum you must change every occurrence of "`@@ServerRoot@@`" to your document server root (for example "`/usr/local/apache`")

6. General documentation for Apache is located at http://httpd.apache.org/docs/ and in the HTML pages included with the distribution (tarball) under the `/htdocs/manual` directory.

7. On TPF activate your TCP/IP Offload (ZCLAW) or Native Stack communications device.

   Refer to the TPF TCP/IP publication for more information: http://www.ibm.com/tpf/pubs/tpfpubs.htm.

8. Using either TFTP or FTP, transfer the configuration file, icons, and web pages to your TPF system. A typical directory structure for Apache is as follows:

        /usr/local/apache/conf
            /usr/local/apache/logs
            /usr/local/apache/icons
            /usr/local/apache/htdocs

   All gif, jpg, and zip files should be transferred as binary; the configuration file and html pages should be transferred as text.
   The logs directory must exist in order to avoid an `fopen` error while running Apache:
   If you're running a PUT10 or higher version of TPF make the directory using the `zfile mkdir /usr/local/apache/logs` command.
   If you're running TPF version PUT09 TFTP an empty file into the logs subdirectory to create it.
   Make sure Apache can write into the logs subdirectory by doing a `zfile chmod` on it with the appropriate permission settings.

   Refer to the TFTP and FTP sections of the TPF TCP/IP publication for more information: http://www.ibm.com/tpf/pubs/tpfpubs.htm.

9. On TPF add Apache to the Internet Daemon's tables using ZINET entries, the common case:
   - For PUT11 and later use the DAEMON model for Apache: `ZINET ADD S-APACHE PGM-chta MODEL-DAEMON USER-root`
   - On pre-PUT11 systems use the NOLISTEN model instead: `ZINET ADD S-APACHE PGM-chta MODEL-NOLISTEN`
   TIP: Logic changes implemented with PUT11 cause ZINET to not restart NOLISTEN servers after `ZOLDR ACT` and `ZOLDR DEACT` entries. This means that Apache running as NOLISTEN on a PUT11 or later system will exit whenever any `ZOLDR ACT` or `ZOLDR DEACT` entry is made. Therefore at PUT11 you should switch to the DAEMON model and ensure that you have APARs PJ25761 and PJ27363 applied.
   Refer to the Internet Daemon section of the TPF TCP/IP publication for more information: http://www.ibm.com/tpf/pubs/tpfpubs.htm.
10. Start the server using the `ZINET START S-APACHE` command.
11. Request a page from your browser: `http://xx.xx.xx.xx` (where xx.xx.xx.xx is your IP address)

## Compiling with VisualAge TPF

It is not required that `make` be used to compile Apache for TPF: Individual programs may be compiled using IBM's VisualAge TPF product. This is particularly useful when compiling selected programs for the Debug Tool.

The following VisualAge compile settings are required:

- "DEFINE - Define preprocessor macro name(s)" must include `TPF, CHARSET_EBCDIC, _POSIX_SOURCE,` and `USE_HSREGEX`
- "LSEARCH - Path for user include files" must include `../src/include` and `../src/os/tpf`
- "DLL - Generate DLL code" must be checked
- "LONGNAME - Support long names" must be checked

[ top | Download | Compilation | Installation | VisualAge ]