Installing the Apache 1.3 HTTP Server on TPF

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

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

Download

1. Download the gzipped Apache files (the "tarball") to your PC. The file name on the web site will be something like apache_1.3.x.tar.gz.
   TIP: Be sure to keep the .tar.gz 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.x.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 Open Edition machine using binary mode:
   • activate FTP in an MSDOS window: ftp your.open.edition.machine.com
   • sign in
   • set mode to binary: binary
   • send the file to Open Edition:
        send c:\downloaded_filename.tar.gz open_edition_filename.tar.gz
   • exit FTP: bye
   
   TIP: Open Edition and UNIX file names are case sensitive. If you use an NFS client to transfer files from your PC to Open Edition (instead of using FTP as described above) verify that the NFS drive will transfer the file names with upper/lower case preserved.
   
   
4. Decompress the gzipped file on Open Edition: gunzip open_edition_filename.tar.gz
   Note that the .tar.gz file will be replaced by the gunzipped .tar archive file.
   
   
5. Extract the archived files necessary for compiling Apache:
   • pax -rvkf open_edition_filename.tar -o from=ISO8859-1,to=IBM-1047 "*/src"
     (any errors extracting files outside of the "src" directory can be ignored)
   • switch to the source code subdirectory of the newly extracted apache directory: cd apache-1.3/src
   • remove unnecessary subdirectories: rm -r os/bs2000 os/mpeix os/netware os/os2 os/os390 os/win32

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 scripts assume a c89 compiler and have only been tested on an Open Edition environment. If you are using a platform other that Open Edition you may need to modify src/os/tpf/TPFExport and src/Configure to match your environment.

Note that Open Edition commands in this section are shown in bold, are case sensitive, and must be made from the "src" directory.

1. Overlay src/Configuration with src/Configuration.tmpl: cp Configuration.tmpl Configuration
   
   
2. 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:
   
   
   • Adjust the Rules and EXTRA_CFLAGS|LIBS|LDFLAGS|INCLUDES if you feel so inclined.
     
     
   • 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 optional modules you wish to include or add new lines corresponding to any custom modules you have written. The htdocs/manual/readme-tpf.html document lists the modules that have been tested on TPF.
   
   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://www.apache.org/dist/contrib/modules/. There are instructions on that page for linking these modules into the core Apache code.
   
   
3. 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 Open Edition system in the appropriate file structure similar to /usr/include and /usr/include/sys. If your system header files contain line numbers in columns 72-80, you must truncate them.
   
   Do not modify the TPF=YES export variable. If this is changed, the "Configure" script will not recognize TPF.
   
   
4. 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 lib/expat-lite
         Creating Makefile in modules/standard
         $ _
         

   If you want to maintain multiple configurations, you can say, e.g.,
   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!)

5. Edit include/ap_config.h if you would like the scoreboard kept in shared memory instead of file or system heap.
   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 system heap. Available with PUT10 is the use of shared memory for the scoreboard in place of the file system. This reduces file activity for the parent Apache ECB and improves performance. To activate shared memory, uncomment or add the directive #define USE_SHMGET_SCOREBOARD and comment out or remove the directive #define USE_TPF_SCOREBOARD both of which are in the TPF section in ap_config.h. This change will only take effect after Apache is (re)compiled.
   
   If you prefer to use the file system instead of system heap or shared memory, ensure that both USE_TPF_SCOREBOARD and USE_SHMGET_SCOREBOARD are commented out or removed. This change will only take effect after Apache is (re)compiled.
    
   
6. Determine if you will use the ZINET DAEMON model instead of the default NOLISTEN model.
   The default behavior is to let Apache check the server status (active/inactive) with ZINET and shut itself down when appropriate. This default behavior also includes checking the activation number. ZINET can now perform these functions instead of Apache by using the DAEMON model (PUT12 with APARs PJ25761 & PJ27363 required). This model offers increased reliability and is preferred over the NOLISTEN model. If Apache goes down while running under the NOLISTEN model, ZINET will not reactivate it nor alert the operator.
   
   To use the DAEMON model you must do the following:
   
   
   • Modify the default behavior of Apache by uncommenting or adding the directive #define USE_TPF_DAEMON within the TPF section of include/ap_config.h. This change will only take effect after Apache is (re)compiled.
     
     
   • Insert these four lines of code immediately prior to the #endif line in the os_check_server function in os/tpf/os.c (if they are not already there):
     
     
     #else
     if (getppid() == 1) {
     
     return 1;
     
     }
     
     
7. Now compile the programs: make
   Besides compiling, make also runs main/gen_test_char.c and main/gen_uri_delims.c in order to create main/test_char.h and main/uri_delims.h respectively
   
   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, append the following line to the os/tpf/TPFExport file and start back at the export step:
   
   
   export _C89_OPTIONS="-W 0,langlvl(extended)"
   
   The following compilation warnings are expected and can be ignored:
   
   
   • util_uri.c:   Function argument assignment between types "unsigned char*" and "const unsigned char*" is not allowed.
   • mod_put.c:   #include file "ap_vercompat.h" not found
   • mod_tpf_shm_static.c:   #include file <sys/mman.h> not found
   • mod_usertrack.c:   #include file <sys/time.h> not found

Installation

1. Link the compiled object files into a DLL. Sample link JCL has been included as src/os/tpf/samples/linkdll.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.
   
   
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 pppp (c-c) will display allocation information. You can use zapat pppp 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. Apache 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.
   
   General documentation for Apache is located at http://www.apache.org/docs/ and in the HTML pages included with the distribution (tarball) under the /htdocs/manual directory.
   
   
6. On TPF activate ZCLAW and update INETD using ZINET entries, the common case:
   
   

       ZINET ADD S-TFTP PGM-CTFT PORT-69 PROTOCOL-UDP MODEL-NOWAIT
   
       ZINET ADD S-APACHE PGM-pppp MODEL-NOLISTEN
       or ZINET ADD S-APACHE PGM-pppp MODEL-DAEMON USER-root (see notes above regarding the DAEMON model)

   Please refer to IBM Transaction Processing Facility Transmission Control Protocol/Internet Protocol Version 4 Release 1 for more information on ZCLAW, INETD, and TFTP.
   
   
7. Prior to sending a request to your Apache server from a browser, TFTP the configuration file, log, 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 TFTP'd as binary; conf files and html pages should be TFTP'd 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 functional entry.
   
   If you're running TPF version PUT09, TFTP an empty file into the logs subdirectory to create it.
   
   Regardless of your TPF version, make sure Apache can write into the logs subdirectory by doing a zfile chmod on it with the appropriate permission settings.
   
   
8. Start the server using the ZINET START S-APACHE command.

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