diff options
Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/install-tpf.html')
| -rw-r--r-- | usr.sbin/httpd/htdocs/manual/install-tpf.html | 249 |
1 files changed, 153 insertions, 96 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/install-tpf.html b/usr.sbin/httpd/htdocs/manual/install-tpf.html index 6a357452aeb..661edba8850 100644 --- a/usr.sbin/httpd/htdocs/manual/install-tpf.html +++ b/usr.sbin/httpd/htdocs/manual/install-tpf.html @@ -9,7 +9,7 @@ <A NAME="top">Installing the Apache 1.3 HTTP Server on TPF</A> </H1> <HR> -<CENTER>[ <A HREF="#setup">Setup</A> +<CENTER>[ <A HREF="#download">Download</A> | <A HREF="#compilation">Compilation</A> | <A HREF="#installation">Installation</A> | <A HREF="#visualage">VisualAge</A> ] @@ -26,53 +26,65 @@ htdocs/manual/<A HREF="readme-tpf.html">readme-tpf.html</A> for basic information on the port of Apache to TPF including required PUT level and supported functions & modules. </P> - -<H2 align=center><A NAME="setup">Setup</A></H2> -<P> -Due to the use of EBCDIC on MVS OS/390 Open Edition -(later referred to simply as -"Open Edition"), we've found that the most reliable -method for loading Apache onto your system is to unzip and tar the distribution -file on your PC, and then copy the extracted files to Open Edition -via an NFS client -capable of transferring the data in EBCDIC format. -</P> -<P> -Before moving the distribution to an -Open Edition environment, verify that the NFS drive will transfer the -filenames with upper/lower case preserved. -</P> -<P> -Since Open Edition is not the ultimate destination of the files, -the only required files and subdirectories that need to be moved to -Open Edition -are in /src. -</P> -<P> -<FONT COLOR=red><STRONG>WARNING</STRONG></FONT>: -If you are using a product such as WinZip on your PC, verify that -the <EM>"TAR File Smart CR/LF Conversion"</EM> option is NOT checked. -You can find this in WinZip under Options, Configuration. -This will save you lots of headaches later on. -</P> -<P> -<FONT COLOR=red><STRONG>WARNING</STRONG></FONT>: -Editing files on a PC before moving them to Open Edition 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, edit them -in a UNIX editor such as vi or emacs. -</P> - +<H2 align=center><A NAME="download">Download</A></H2> +Releases of the Apache server are compressed into a "tarball" file and stored on the Apache web site. +You will need to choose a version and download the corresponding tarball to your PC. +Additionally the source code from the tarball will need to be copied onto an MVS OS/390 Open Edition machine +(later referred to simply as "Open Edition") for compiling. +So here are all the details on how to get Apache and how to get it where it needs to be: +<ol> + <li><A HREF="http://www.apache.org/dist/">Download</A> + the gzipped Apache files (the "tarball") to your PC. + The file name on the web site will be something like <i>apache_1.3.x.tar.gz</i>. + <br><font color=red size=4>TIP: </font>Be sure to keep the <i>.tar.gz</i> extension + when choosing the name of the PC file. + <br><br> + <li>Decompress the tarball on your PC using WinZip or some other PC decompression tool. + <br><font color=red size=4>TIP: </font>If you are using WinZip verify that the + <EM>"TAR File Smart CR/LF Conversion"</EM> option (under Options, Configuration) is NOT checked.<br> + This is what you can expect if you use WinZip: + <ul> + <li>open the tarball with WinZip (this can usually be done simply by double-clicking + on the downloaded tarball) + <li>you will be told that the archive contains one file (such as <i>apache_1.3.x.tar</i>) - + allow WinZip to decompress it to a temporary folder + <li>extract the archived files onto your PC - + you'll be using files from the <tt>conf, htdocs,</tt> and <tt>icons</tt> directories later in the install phase + </ul> + <br> + <li>FTP the tarball to your Open Edition machine using binary mode: + <ul> + <li>activate FTP in an MSDOS window: <tt><b>ftp <i>your.open.edition.machine.com</i></b></tt> + <li>sign in + <li>set mode to binary: <tt><b>binary</b></tt> + <li>send the file to Open Edition:<br> + <tt><b> send <i>c:\downloaded_filename.tar.gz open_edition_filename.tar.gz</i></b></tt> + <li>exit FTP: <tt><b>bye</b></tt> + </ul> + <br><font color=red size=4>TIP: </font> + 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.<br> + <br> + <li>Decompress the gzipped file on Open Edition: <tt><b>gunzip <i>open_edition_filename.tar.gz</i></b></tt> + <br>Note that the <i>.tar.gz</i> file will be replaced by the gunzipped <i>.tar</i> archive file. + <br><br> + <li>Extract the archived files necessary for compiling Apache: + <ul> + <li><tt><b>pax -rvkf <i>open_edition_filename.tar</i> -o from=ISO8859-1,to=IBM-1047 "*/src"</b></tt> + <li>switch to the source code subdirectory of the newly extracted apache directory: <tt><b>cd <i>apache-1.3</i>/src</b></tt> + <li>remove unnecessary subdirectories: + <tt><b>rm -r os/bs2000 os/mpeix os/netware os/os2 os/os390 os/win32</b></tt> + </ul> +</ol> +<br> <H2 align=center><A NAME="compilation">Compilation</A></H2> <P> 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 -make and Configure utility, "modules.c" will be created for you. +code (modules.c) which simply has a list of them. If you are using the <tt>Configure</tt> utility +and <tt>make</tt>, modules.c and other necessary files will be created for you automatically. </P> <P> The provided scripts assume a c89 compiler and have only been tested on an @@ -80,8 +92,15 @@ 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. </P> +<font color=red size=4>TIP: </font> +Editing files on your PC prior to moving them to Open Edition 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 Open Edition, +edit them in a UNIX editor such as vi or emacs.<br> <P> -Note that UNIX/Open Edition commands in this section are shown in +Note that Open Edition commands in this section are shown in <TT><STRONG>bold</STRONG></TT>, are case sensitive, and must be made from the "src" directory. </P> @@ -93,15 +112,12 @@ are case sensitive, and must be made from the "src" directory. of various "Rules" and an additional section at the bottom that determines which modules to compile: <BR><BR> - <OL type=a> + <UL> <LI>Adjust the Rules and <TT>EXTRA_CFLAGS|LIBS|LDFLAGS|INCLUDES</TT> if you feel so inclined. <BR><BR> <LI>Comment out (by preceding the line with a "#") lines corresponding to those modules you DO NOT wish to include. - At present the following modules MUST be commented out - as they are not yet supported on TPF: mod_actions, mod_auth, - mod_cgi, mod_env, mod_include, & mod_status. <BR><BR> <LI>Uncomment (by removing the initial "#", if present) lines corresponding to those optional modules you wish @@ -109,8 +125,16 @@ are case sensitive, and must be made from the "src" directory. you have written. The htdocs/manual/<A HREF="readme-tpf.html">readme-tpf.html</A> document lists the modules that have been tested on TPF. - </OL> - <BR> + </UL> + <br>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 + <A +HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/contrib/modules/</A>. + There are instructions on that page for linking these modules into the core Apache + code. + <BR><BR> <LI>Set the TPF environment variables: <TT><STRONG>. os/tpf/TPFExport</STRONG></TT> <BR> @@ -124,13 +148,10 @@ are case sensitive, and must be made from the "src" directory. DO NOT modify the <TT>TPF=YES</TT> export variable. If this is changed, the "Configure" script will not recognize TPF. <BR><BR> -<LI>Remove the src/lib/expat-lite directory: - <TT><STRONG>rm -r lib/expat-lite</STRONG></TT> - <BR><BR> <LI>Run the "Configure" script: <TT><STRONG>Configure</STRONG></TT> <BR> - The output will look something like this... + This generates modules.c, include/ap_config_auto.h, and necessary Makefiles: <PRE> Using config file: Configuration Creating Makefile @@ -139,17 +160,15 @@ are case sensitive, and must be made from the "src" directory. + 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 main - Creating Makefile in ap Creating Makefile in regex Creating Makefile in os/tpf + Creating Makefile in ap + Creating Makefile in main Creating Makefile in modules/standard - Creating Makefile in modules/example $ _ </PRE> - This generates modules.c and new versions of the Makefiles. - <BR><BR> If you want to maintain multiple configurations, you can say, <EM>e.g.</EM>, <BR> @@ -162,9 +181,8 @@ are case sensitive, and must be made from the "src" directory. + setting C compiler to <whatever> et cetera </PRE> - If you receive an error such as "<TT>Configure 146: FSUM7351 not found</TT>" - the most likely explanation is that one or more of the make related + the most likely explanation is that one or more of the <tt>make</tt> 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... @@ -178,19 +196,42 @@ are case sensitive, and must be made from the "src" directory. 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. - <BR><PRE> close the file: <STRONG>:q </STRONG>(or + <BR><PRE> close the file: <STRONG>:q </STRONG>(or <STRONG>:quit!</STRONG>)</PRE> + +<LI>Edit include/ap_config.h if you would like the scoreboard kept in shared + memory instead of file or system heap.<br> + The default behavior for Apache on all platforms <i>except</i> 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 <em>add</em> the directive + <tt><b>#define USE_SHMGET_SCOREBOARD</b></tt> + and comment out or <em>remove</em> the directive <tt><b>#define USE_TPF_SCOREBOARD</b></tt> + both of which are in the TPF section in ap_config.h. + This change will only take effect after Apache is (re)compiled. + <br><br> + If you prefer to use the file system instead of system heap or shared memory, ensure that both + <tt>USE_TPF_SCOREBOARD</tt> and <tt>USE_SHMGET_SCOREBOARD</tt> are commented out or removed. + This change will only take effect after Apache is (re)compiled. + +<A NAME="daemon"></A><br> <br> +<LI>Edit include/ap_config.h if you plan on using the ZINET DAEMON model instead of the NOLISTEN model.<br> + The default behavior is to let Apache check the server status (active/inactive) with ZINET + and shut itself down when appropriate. The default behavior also includes checking Apache's activation number. + Available with PUT11 (PJ25761) ZINET can perform these functions instead of Apache by using the DAEMON model. + 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 modify the default behavior of Apache by uncommenting or adding the directive + <tt><b>#define USE_TPF_DAEMON</b></tt> within the TPF section in ap_config.h. + This directive is also recommend when starting Apache from the command line (APAR PJ26515). + This change will only take effect after Apache is (re)compiled. + <br><br> + -<STRONG>:quit!</STRONG>)</PRE> <LI>Now compile the programs: <TT><STRONG>make</STRONG></TT><BR> - 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 - <A -HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/contrib/modules/</A>. - There are instructions on that page for linking these modules into the core Apache - code. - <BR><BR> + Besides compiling, <tt>make</tt> 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<BR><BR> If during compilation you get a warning about a missing 'regex.h', set <TT>WANTHSREGEX=yes</TT> in the src/Configuration file and start back at the <TT><STRONG>Configure</STRONG></TT> step. @@ -199,35 +240,48 @@ HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/co <A NAME="installation"> </A> <H2 align=center>Installation</H2> <OL> -<LI>After compilation, you will have all the object files required to build an - "httpd" loadset. The next step is to link the object files and create a loadset to be - stored in a PDS. Sample JCL for linking and loadsets has been included in - src/os/tpf/samples as "linkdll.jcl" and "loadset.jcl". You can submit these jobs - from CMS or directly from Open Edition if you have the proper authority. After - the jobs have completed, you can <TT>ZOLDR LOAD</TT> them to your TPF system. - <BR><BR> - NOTE: The <TT>mod_<EM>xxx</EM>.o</TT> files in the linkdll.jcl file must correspond to the - <TT>mod_<EM>xxx</EM>.o</TT> lines in the src/Configuration file. - <BR><BR> +<LI>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: + <ul> + <li>Change the IDs, data set names, and libraries for your particular site. + <li>Add/remove <TT>mod_<EM>xxx</EM>.o</TT> files so they correspond to the + <TT>mod_<EM>xxx</EM>.o</TT> lines in your src/Configuration file. + </ul> + <br><font color=red size=4>TIP: </font> + Do NOT include gen_test_char.o or gen_uri_delims.o in the link JCL since these files are only + used during the <tt>make</tt> step. + <br><br> +<LI>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. + <br><br> +<LI>Load (<tt>ZOLDR LOAD</tt>) and activate (<tt>ZOLDR ACT</tt>) the loadset on your test system. + <br><br> +<LI>Ensure that the program name you are using for Apache has <tt>RESTRICT</tt> and <tt>KEY0</tt> authorization. + <tt><b>zdpat <i>pppp</i> </b>(<b>c-c</b>)</tt> will display allocation information. + You can use <tt><b>zapat <i>pppp</i> restrict key0 </b>(<b>c-c</b>)</tt> 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 <tt>zdpat/zapat</tt> entries. + <br><br> <LI> 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. If your system is pre-PUT09 you - <font color=red><STRONG>must</STRONG></FONT> change <TT>ServerType</TT> from <TT>standalone</TT> - to <TT>inetd</TT>. + edit the /conf/httpd.conf copy with your site specific information. <BR><BR> General documentation for Apache is located at <A HREF="http://www.apache.org/docs/">http://www.apache.org/docs/</A> - and in the HTML pages included with this distribution under the + and in the HTML pages included with the distribution (tarball) under the /htdocs/manual directory. <BR><BR> <LI>On TPF activate ZCLAW and update INETD using ZINET entries, the common case: <BR><BR> <PRE> - ZINET ADD S-TFTP PGM-CTFT PORT-69 PROTOCOL-UDP MODEL-NOWAIT - ZINET ADD S-APACHE PGM-<EM>pppp</EM> PROTOCOL-TCP MODEL-NOWAIT PORT-80 (if inetd mode) - ZINET ADD S-APACHE PGM-<EM>pppp</EM> PROTOCOL-TCP MODEL-NOLISTEN (if standalone mode)</PRE> + ZINET ADD S-TFTP PGM-CTFT PORT-69 PROTOCOL-UDP MODEL-NOWAIT + + ZINET ADD S-APACHE PGM-<EM>pppp</EM> MODEL-NOLISTEN + or ZINET ADD S-APACHE PGM-<EM>pppp</EM> MODEL-DAEMON USER-root <A HREF="#daemon">(see notes above regarding the DAEMON model)</A></PRE> Please refer to <EM>IBM Transaction Processing Facility Transmission Control Protocol/Internet Protocol Version 4 Release 1</EM> for more information on ZCLAW, INETD, and TFTP. @@ -239,19 +293,23 @@ HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/co /usr/local/apache/logs /usr/local/apache/icons /usr/local/apache/htdocs</PRE> - The logs directory must exist in order to avoid an - <CODE>fopen</CODE> error while running Apache. TFTP an empty file into - the logs subdirectory to create it. All gif, jpg, and zip files should be - TFTP'd as binary; conf files and html pages should be TFTP'd as text. + All gif, jpg, and zip files should be TFTP'd as binary; conf files and html pages should be TFTP'd as text. + <br>The logs directory must exist in order to avoid an <CODE>fopen</CODE> error while running Apache. + If you're running a PUT10 or higher version of TPF make the directory using the + <tt><b>zfile mkdir /usr/local/apache/logs</b></tt> functional entry. + If you're running TPF version PUT09 TFTP an empty file into the logs subdirectory to create it. + <br><br> +<LI>Start the server using the <tt><b>ZINET START S-APACHE</b></tt> command. </OL> <A NAME="visualage"> </A> <H2 align=center>Compiling with VisualAge TPF</H2> <P> - It is not required that "make" be used to compile Apache for TPF: + It is not required that <tt>make</tt> 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. <BR><BR> The following VisualAge compile settings are required: +</P> <UL> <LI><EM>"DEFINE - Define preprocessor macro name(s)"</EM> must include <TT><STRONG>TPF, CHARSET_EBCDIC, _POSIX_SOURCE,</STRONG></TT> and @@ -264,10 +322,9 @@ HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/co <BR><BR> <LI><EM>"LONGNAME - Support long names"</EM> must be checked </UL> -</P> <HR> <CENTER>[ <A HREF="#top">top</A> - | <A HREF="#setup">Setup</A> + | <A HREF="#download">Download</A> | <A HREF="#compilation">Compilation</A> | <A HREF="#installation">Installation</A> | <A HREF="#visualage">VisualAge</A> ] |