This document outlines the steps needed to install Apache onto an IBM TPF4.1 system. (There are separate installation instructions for z/TPF.)
You should first review readme-tpf.html for basic information on the port of Apache to TPF including a list of supported modules and required PUT levels.
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 apache/src is used
for the Apache source code directory. You can use different
directories than apache if you wish.
If you change the program or directory names be sure to change the entries shown in these instructions.
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:
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.
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:
FTP the tarball to your OS/390 UNIX machine using binary mode:
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.
On your OS/390 UNIX machine, decompress and extract the archived files necessary for compiling Apache:
pax -rvzkf apache_1.3.vv.tar.Z -o from=ISO8859-1,to=IBM-1047 "*/src"
Remove unnecessary subdirectories:
cd apache_1.3.vv/src/lib
rm -r expat-lite sdbm
cd ../os
rm -fr bs2000 cygwin mpeix netware os2 os390 unix win32
cd ..
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.
Switch to the Apache source code subdirectory:
cd apache_1.3.vv/src
Overlay src/Configuration with src/Configuration.tmpl:
cp Configuration.tmpl Configuration
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:
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:
Otherwise:
Without non_socket_select CGI output is buffered and only sent to the browser when the CGI program finishes.
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:
Otherwise:
The use of tpf_sawnc allows for a cleaner shutdown of Apache.
Indicate if you have the Syslog Daemon message logging facility.
If you are on a PUT13 or higher system, or have PJ27214 installed,
you can use syslog for Apache's ErrorLog.
To have the option of using syslog you must do one of the
following:
You also need to add "INCLUDE OBJLIB(CSYLOG40)" to your link JCL.
See the syslog section of readme-tpf.html for more information.
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:
See "Network Services Database Support" in the IBM TPF Product Information Center for details.
Set the TPF environment variables:
. os/tpf/TPFExport
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.
Run the "Configure" script to generate modules.c, include/ap_config_auto.h, and necessary Makefiles:
./Configure
Using config file: Configuration Creating Makefile + configured for TPF platform + setting C compiler to c89 + setting C pre-processor to c89 -E + 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 regex Creating Makefile in os/tpf Creating Makefile in ap Creating Makefile in main Creating Makefile in modules/standard $ |
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 |
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!) |
Edit src/os/tpf/os.h if you want to use the sigaction() function.
The sigaction() function supersedes the signal() interface and should be used in preference. This function was implemented with APAR PJ26188 which shipped with PUT10.
To use sigaction() remove #define NO_USE_SIGACTION in os.h.
The change will only take effect after Apache is (re)compiled.
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 you are on a pre-PUT10 system, or for some reason you do not want to use shared memory for the scoreboard, you must remove "#define USE_SHMGET_SCOREBOARD" from os.h
The change will only take effect after Apache is (re)compiled.
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 may or may not occur. It should be ignored:
main/http_main.c: Infinite loop detected in function child_main. Program may not stop.
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
The allocated CHTA program name is used throughout these instructions to refer to Apache. You can use a different program name if you wish.
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:
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
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.
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.
If you require a link map refer to the instructions below.
Load (zoldr load) and activate (zoldr act) the loadset on your test system.
Ensure that the program name you are using for Apache has RESTRICT and KEY0 authorization:
zdpat chta (c-c)
If necessary you can use the zapat entry to alter the authorization:
zapat chta restrict key0 (c-c)
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.
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.
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
On TPF activate your TCP/IP Offload (ZCLAW) or Native Stack
communications device.
Refer to the
IBM TPF Product Information Center
for details.
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.
The logs directory must exist and be accessible 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 a zfile commands:
zfile mkdir /usr/local/apache/logs
zfile chmod 777 /usr/local/apache/logs
If you're running TPF version PUT09 TFTP an empty file into the
logs subdirectory to create it.
Then make sure Apache can write into the logs subdirectory:
zfile chmod 777 /usr/local/apache/logs
Add Apache to the Internet Daemon's tables using zinet entries
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 IBM TPF Product Information Center for details on the Internet Daemon and zinet commands.
Start the server:
zinet start s-apache
Verify Apache was successfully started:
zfile cat /usr/local/apache/logs/error_log
[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
Request a page from your browser:
http://xx.xx.xx.xx (where xx.xx.xx.xx is your test system IP address)
Three different tools can be used to generate a link map for Apache: TPF Build Tools, TPF Toolkit, and VisualAge TPF.
src directory:
ld -M --dlm -O'<your-dsd-dsn>(CHTA<vv>)' \ CSTRTD40 \ CINET640 \ buildmark.o \ modules.o \ ap/ap_base64.o \ . . . regex/regexec.o \ regex/regfree.o |
chmod command.