This document outlines the steps needed to install Apache onto an IBM z/TPF Enterprise Edition V1 R1 system. (There are separate installation instructions for TPF4.1.)

You should first review readme-tpf.html for basic information on the port of Apache to TPF including a list of supported modules.

The allocated CHTA program name is used throughout these instructions to refer to Apache. You can use a different program name if you wish.
Likewise the directory structure opensource/apache/src is used for the Apache source code directory. You can use different directories than opensource/apache if you wish.

If you change the program or directory names be sure to change the entries shown in these instructions, all MakeTPF-related files, and the sample files accordingly.

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 your Linux build system 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 1.3 files (the "tarball") from http://httpd.apache.org/download.cgi to your PC. The file name on the web site will be apache_1.3.vv.tar.Z, where "vv" is the version number. Replaced "vv" throughout these instructions with the actual version number.

   TIP: Be sure to keep the .tar.Z extension when saving the 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 (apache_1.3.vv.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 Linux build machine using binary mode:

   • activate FTP in an MSDOS window:
        ftp your.linux.build.machine.com 
   • sign in 
   • set mode to binary:  binary 
   • send the file to your Linux build machine:
        send "c:/path/apache_1.3.vv.tar.Z" apache_1.3.vv.tar.Z
   • exit FTP:  bye

   TIP: Linux file names are case sensitive.

4. On your Linux build machine, decompress and extract the archived files necessary for compiling Apache:

   tar -xzkf apache_1.3.vv.tar.Z "*/src"

   Note that the following "src" subdirectories are not used for Apache on z/TPF and may be removed if desired:

   lib/expat-lite, lib/sdbm, regex, and all os subdirectories except for os/tpf.

5. Create header files that are automatically generated for other platforms but are not for z/TPF:

   cp apache_1.3.vv/src/os/tpf/samples/test_char.txt  apache_1.3.vv/src/main/test_char.h
   cp apache_1.3.vv/src/os/tpf/samples/uri_delims.txt apache_1.3.vv/src/main/uri_delims.h

1. Move the source code into your desired directory structure for MakeTPF with the following entries.
   Replace "foobar" below with your actual directory name:

   export AROOT="foobar/opensource/apache"
   mkdir -p $AROOT
   mv apache_1.3.vv/* $AROOT
   

2. CHTA is already in the tpf_app_base.cntl control file. Adjust any settings if necessary.

3. Create an environment file for Apache named maketpf.env_apache using $AROOT/src/os/tpf/samples/sample_env.txt as a guide.
   Place maketpf.env_apache in the same directory as your other environment files.

4. Create a .mak file for Apache named $AROOT/src/chta.mak using $AROOT/src/os/tpf/samples/sample_mak.txt as a guide
   Verify that the maketpf_env assignments in chta.mak are correct for your build environment.

5. Create a configuration file named $AROOT/src/maketpf.cfg.
   Ensure that the first assignment of TPF_ROOT in maketpf.cfg is the absolute path to your "foobar" directory.

6. Later if you want to include Apache in your full build add APACHE=YES to the CONFIG macro in your Stage 1 deck.
   Then reassemble the SIP deck (sip.asm) to update the SIP generated build files with the APACHE function switch enabled.

1. Switch to the Apache source code subdirectory:

   cd $AROOT/src

2. Overlay src/Configuration with src/Configuration.tmpl:

   cp Configuration.tmpl Configuration

3. The src/Configuration file controls which optional modules are compiled into Apache.
   Leave the file as-is if you want to use the default set of modules.
   Otherwise edit the src/Configuration file to customize which modules are used:

   • 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.
     (The readme-tpf.html document lists the modules that have been tested on TPF).
   • Add lines for any custom or third party modules you wish to include.
     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. If you would like to use the TCP/IP network services database add "CFLAGS_CHTA += -DTPF_HAVE_NSD" to either src/chta.mak or src/maketpf.cfg. See "Network Services Database Support" in the IBM TPF Product Information Center for details.

5. Run the "Configure" script:

   export TPF=YES; export TPF64BIT=YES
   ./Configure

   Using config file: Configuration Creating Makefile + configured for TPF platform + setting C compiler to c89 + setting C pre-processor to /usr/bin/cpp + using "tr [a-z] [A-Z]" to uppercase + checking for system header files + adding selected modules + checking sizeof various data types Creating Makefile in support Creating Makefile in os/tpf Creating Makefile in ap Creating Makefile in main Creating Makefile in modules/standard $

   This generates modules.c and the apache.modules text file for use later by MakeTPF.
   (Other files created by Configure are not used on z/TPF such as include/ap_config_auto.h and the various Makefiles, so don't be concerned that the C compiler and pre-processor shown in the Configure output are incorrect.)

   Use the -file option if you want to maintain multiple configurations:

   ./Configure -file Configuration.2nd

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

    

6. Edit src/os/tpf/os.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 and improves performance.

   If for some reason you do not want to use shared memory for the scoreboard, you must remove "#define USE_SHMGET_SCOREBOARD" from the os.h. The change will only take effect after Apache is (re)compiled.

7. Compile and link Apache:

   maketpf chta -f

   TIP: Apache uses cinet6 from CLTY, which is part of the Internet Daemon (ZINET). Ensure that you link Apache with the proper version of CLTY for your system. If you apply changes to CLTY you should re-link Apache to prevent the inetd_getServer and/or inetd_getServerStatus functions from failing.

1. Load and activate Apache on your test system.

2. Ensure that the program name you are using for Apache has RESTRICT and KEY0 authorization:

   zdpat chta

   If necessary you can use the zapat entry to alter the authorization:

   zapat chta restrict key0

3. 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.

4. Create the Apache run-time configuration file. The server requires a configuration file to initialize itself during activation.
   Copy the distribution version, conf/httpd.conf-dist from the decompressed tarball on your PC, to conf/httpd.conf and then edit the conf/httpd.conf copy with your site specific information.

   You must change every occurrence of "@@ServerRoot@@" to your document server root (for example "/usr/local/apache")

   You should also add the following line to the httpd.conf file to prevent Apache from doing a host name lookup on your test system:

   ServerName 127.0.0.1

5. Be sure your Native Stack communications device is active on TPF.
   Refer to the IBM TPF Product Information Center for details.

6. 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
   

   At a minimum you will need these files on TPF:

   /usr/local/apache/conf/httpd.conf
   /usr/local/apache/conf/mime.types
   /usr/local/apache/htdocs/index.html.en
   /usr/local/apache/htdocs/apache_pb.gif
   

   All gif, jpg, and zip files should be transferred as binary; the configuration file and html pages should be transferred as text.

   Refer to the IBM TPF Product Information Center for details on TFTP and FTP.

7. The logs directory must exist and be accessible in order to avoid an fopen error while running Apache:

   zfile mkdir /usr/local/apache/logs
   zfile chmod 777 /usr/local/apache/logs
   

8. Add Apache to the Internet Daemon's tables using ZINET entries:

   zinet add s-apache pgm-chta model-daemon user-root

   Refer to the IBM TPF Product Information Center for details on the Internet Daemon and ZINET commands.

9. Start the server:

   zinet start s-apache

10. Verify Apache was successfully started:

    zfile cat /usr/local/apache/logs/error_log

    The output should be similar to this:

    [timestamp] [notice] Apache/1.3.vv (TPF) configured -- resuming normal operations [timestamp] [notice] Accept mutex: tpfcore (Default: tpfcore)

    If there are severe errors correct the conf file and restart the server:

    zinet stop s-apache
    correct the httpd.conf file and transfer it to TPF
    zfile rm /usr/local/apache/logs/error_log
    zinet start s-apache

1. Request a page from your browser:

   http://xx.xx.xx.xx   (where xx.xx.xx.xx is your test system IP address)