[PATCH] new readme and install pages for TPF

[David McCreedy]

Attached are the updated install-tpf.html and readme-tpf.html pages.
Due to the number of updates, and since they're just documents, I've
included the entire files for a replacement versus a patch.
(But I will produce a diff file if needed.)

It would be nice to have these updated in 1.3.21's apache/htdocs/manual
directory as well as at http://httpd.apache.org/docs/ once 1.3.21 goes out.

Thank you,

David McCreedy

(See attached file: readme-tpf.html)(See attached file: install-tpf.html)

Title: The Apache TPF Port






Overview of the Apache TPF Port



[ Configuration
Files  | What's
Available    | CGI Scripts 
 | Options 
 | Porting Notes 
]


This version of Apache includes changes allowing it to run on
IBM's EBCDIC-based TPF
(Transaction Processing Facility) operating system.
Unless otherwise noted TPF version 4.1 PUT09 is required. 

Refer to install-tpf.html for step-by-step installation
instructions. 

This port builds upon the EBCDIC changes
previously made to Apache. 



Apache Configuration Files


The distributed configuration files (httpd.conf-dist and
mime.types, both located in the conf subdirectory) work on TPF.
Performance considerations may dictate setting KeepAlive to "Off"
(the default is "On") or lowering the Timeout value from the
default 300 seconds (5 minutes) in order to reduce the number of
active ECBs on your system.
 


What's Available in this Version


The Apache organization provides online documentation describing
the various modules and components of the server. 

Components/modules tested on TPF:


alloc.c 

ap_base64.c 

ap_checkpass.c 

ap_cpystrn.c 

ap_ebcdic.c 

ap_fnmatch.c 

ap_md5c.c 

ap_sha1.c 

ap_signal.c 

ap_slack.c 

ap_snprintf.c 

buff.c 

buildmark.c 

gen_test.char.c 

gen_uri_delims.c 

htpasswd.c (requires PUT10) 

http_config.c 

http_core.c 

http_log.c 

http_main.c 

http_protocol.c 

http_request.c 

http_vhost.c 

logresolve.c (requires PUT10) 

mod_access.c (Use of mod_access directives
"allow from" &
"deny from" with host
names (verses ip addresses)
requires PUT10) 

mod_actions.c 

mod_alias.c 

mod_asis.c 

mod_auth.c 

mod_auth_anon.c 

mod_autoindex.c 

mod_cern_meta.c 

mod_cgi.c (requires
PUT10) 

mod_digest.c 

mod_dir.c 

mod_env.c 

mod_example.c 

mod_expires.c 

mod_headers.c 

mod_imap.c 

mod_include.c (CGI execution
requires TPF version 4.1 PUT10) 

mod_info.c 

mod_log_agent.c 

mod_log_config.c 

mod_log_referer.c 

mod_mime.c 

mod_mime_magic.c 

mod_negotiation.c 


mod_put.c (third party
module) 

mod_proxy.c 

mod_setenvif.c 

mod_speling.c 

mod_status.c 

mod_tpf_shm_static.c (third party module,
requires PUT10) 

mod_unique_id.c (requires
PUT10) 

mod_userdir.c 

mod_usertrack.c 

os.c 

os-inline.c 

proxy_cache.c 

proxy_connect.c 

proxy_ftp.c 

proxy_http.c 

proxy_util.c 

regular expression parser 

regular expression test tool (requires
PUT10) 

rfc1413.c 

rotatelogs.c (requires
PUT10) 

util.c 

util_date.c 

util_md5.c 

util_script.c 

util_uri.c 


Components/modules not yet supported on TPF:


htdigest.c 

lib/expat-lite 

mod_auth_digest.c 

mod_rewrite.c 

mod_vhost_alias.c 


Components/modules that don't apply or that probably won't ever
be available on TPF:


ab.c 

ap_getpass.c 

mod_auth_db.c 

mod_auth_dbm.c 

mod_auth_db.module 

mod_mmap_static.c 

mod_so.c 

suexec.c 




How to Use CGI Scripts


The following is a very simple example of a CGI script ("Hello World")
and the necessary steps to run it.
Refer to the 
mod_cgi module for additional information.
   
Add necessary directives to httpd.conf:

Example:
 
ScriptLog logs/script_log
ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/

A request for http://myserver/cgi-bin/filename.cgi would cause
the server to run the script /usr/local/apache/cgi-bin/filename.cgi


Create the CGI script:

For this example QZZ1 is the name of the TPF program that will
be executed by the CGI script.
The directory path must match what is in the httpd.conf file for
ScriptAlias directive.

zfile echo "#!QZZ1" > /usr/local/apache/cgi-bin/filename.cgi
zfile cat /usr/local/apache/cgi-bin/filename.cgi    
(this should display #!QZZ1)



Mark the script as executable:

zfile chmod 755 /usr/local/apache/cgi-bin/filename.cgi


Create, load, and activate a loadset containing the CGI program (QZZ1xx):
 

        /**     QZZ1-- simple "Hello world" program to demonstrate basic CGI output  **/
        #include <stdio.h>
        void main() {
        
             /**   Print the CGI response header, required for all HTML output.    **/
             /**   Note the extra \n, to send the blank line.                      **/

             printf("Content-type: text/html\n\n");

             /** Print the HTML response page to stdout. **/
             printf("<html>\n");
             printf("<head><title> CGI Output </title></head>\n");
             printf("<body>\n");
             printf("<h1> Hello world </h1> \n");
             printf("</body>\n");
             printf("</html>\n");
        
        }



Request the CGI script from a browser:
         
http://myserver/cgi-bin/filename.cgi




How to Use Apache Command Line Options


You cannot run Apache from the command line on TPF.
However you can use those Apache command line options which don't actually
start the server. This requires PJ27277 which shipped on PUT13.

Supported Apache options:


-d directory
Specify an alternate initial ServerRoot directory.
Default is /usr/local/apache.

-f file
Specify an alternate server configuration file.
Default is conf/httpd.conf.

-h
List a short summary of available command line options.
(Note that this outputs all options, not just those supported on TPF.)

-l
List modules compiled into the server.

-L
List available configuration directives.
(Note that this outputs all configuration directives, not just those supported on TPF.)

-S
Show the settings as parsed from the configuration file.
Currently only shows the virtualhost settings.

-t
Run syntax tests for configuration  files (with document root checks)

-T
Run syntax tests for configuration  files (without document root checks)

-v
Show the version number.

-V
Show the version number and various compile settings.


See 
http://httpd.apache.org/docs/programs/httpd.html for more information
about these command line options.

Note:  On TPF Apache arguments are supported only on the command line,
not through the ZINET XPARM field.


Setup

Ensure Apache (CHTA) is loaded

Create the httpd script:
   
   zfile echo "#!CHTA" > /bin/httpd
       zfile cat /bin/httpd  (this should display #!CHTA)
   

Mark the script as executable:
   zfile chmod 755 /bin/httpd

(See "ZFILE-Activate a TPF Segment or Script"
in the Operations guide for more information:
http://www.ibm.com/tpf/pubs/tpfpubs.htm.)



Example 1

zfile httpd -v

FILE0001I 11.43.09 START OF DISPLAY FROM httpd -v
Server version: Apache/1.3.20 (TPF)
Server built:   May 23 2001 09:39:22         
END OF DISPLAY         



Example 2

zfile httpd -t -f /usr/local/apache/conf/httpd.conf.new

FILE0002I 11.47.26 START OF ERROR DISPLAY FROM httpd -t ...
Syntax OK
END OF DISPLAY         






Porting Notes


Changes made due to differences between UNIX and TPF's process
models:


Signals: On TPF a signal that is sent to a process
remains unhandled until the process explicitly requests that
signals be handled using the tpf_process_signals()
function. Additionally, the default action for an alarm on TPF is
to take an OPR-7777 dump and exit. (On UNIX the default is the
equivalent of exit() with no dump taken.) These
differences necessitated a few modifications: 


  


bypass the use of ap_block_alarms() & 
ap_unblock_alarms() 

add tpf_process_signals() calls 

add select() calls to prevent blocking. 




Find that function...

Some simple functions & definitions initially needed to be
added on TPF, such as FD_SET(). We've put these in
src/os/tpf/os.h for now. 

EBCDIC changes:

TPF-specific conversion tables between US-ASCII and EBCDIC
(character set IBM-1047 to be exact) were created. 

Miscellaneous, minor changes:

Various minor changes (such as casting) were made due to
differences in how some functions are implemented on TPF. 

[ top 
 | Configuration Files 
 | What's Available 
 | CGI Scripts 
 | Options 
 | Porting Notes ]

Title: 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:


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. 
 

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 



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.
 


Decompress the tarball on OS/390 UNIX: 
gunzip os390_unix_filename.tar.Z 

Note that the .tar.Z file will be replaced by the decompressed
.tar archive file. 
 

Extract the archived files necessary for compiling Apache: 
pax -rvkf os390_unix_filename.tar -o from=ISO8859-1,to=IBM-1047 "*/src"
 

Remove unnecessary subdirectories:
   
   cd apache_1.3.xx/src/os
   rm -r bs2000 cygwin mpeix netware os2 os390 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 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 source code subdirectory: 
cd apache_1.3.xx/src 


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

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



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. 



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.



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.




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. 
 

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, 
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!)



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. 

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



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. 
 


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. 


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

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")


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. 
 


On TPF activate ZCLAW
Refer to the TCP/IP Offload Support section of the TPF TCP/IP
publication for more information:

http://www.ibm.com/tpf/pubs/tpfpubs.htm.

Note: Apache does not currently work with Native Stack.


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 functional
entry.
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.

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.


Start the server using the ZINET START S-APACHE
command.

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 ]