Using Apache HTTP Server Version 2.2.9 Customized for z/TPF

This document gives a brief overview of the Apache 2.2.9 HTTP Server and details the steps needed to install it on an IBM z/TPF Enterprise Edition V1 R1 system (TPF). It assumes that you are familiar with the MakeTPF build solution and the TPF APAR process.

For contact assistance and problem reporting, follow the normal problem reporting process for TPF issues and questions or contact a TPF Customer Support Representative.

PUT05 or later is required for the Server to function on TPF.

top

Architecture

This is the Apache 2.2 HTTP Server architecture (with Apache CSO/program names shown in blue):

architecture diagram

The Apache Portable Runtime provides a platform-independent library of functions for things like file i/o, locking, memory, and threads. It shields the Server itself from operating system specifics and is built as three CSOs:

Apache supports Perl-compatible regular expression syntax. This does not require Perl nor is Perl supported on z/TPF. It is implemented in C language:

The Server itself has a core set of processing with an extensive set of optional modules. Which modules are available is determined at compile-time, although the use of the mod_so module allows some flexibility. A special type of module, called an MPM, manages incoming requests and controls the Server's children. The Server is built as two CSOs on TPF:

Additional servers can be built using names other than CA2S and CA2M. This README will use those names for the Server CSOs throughout the examples.

top

What's Available in this Version

The Apache organization provides online documentation for most Modules/MPMs and Supporting Programs.

Only the mod_ssl module has been tested on the z/TPF system. All other optional modules and MPMs are available to use at your own risk.

top

Acquire the Code

Download and extract the Apache 2 source files from the TPF Repository. This code completely replaces any previous copies of Apache 2.

  1. Download the apache2-2.2.9_20160121.tar.gz file to your root source directory.
    If you are using FTP - please ensure you use Binary transfer mode
    Issues with MS IE and WinZip:

    When downloading the apache2-2.2.9_20160121.tar.gz package with Microsoft IE for Windows, the name might be changed to apache2-2.2.9_20160121.tar.tar. WinZip will fail when trying to extract the package while it is named apache2-2.2.9_20160121.tar.tar.

    To correct this, rename the file back to apache2-2.2.9_20160121.tar.gz and WinZip will correctly extract the tarball.

    Make sure you have "Hide Extensions for Known Types" un-checked in your Internet Explorer options so you will actually get access to the file extension.

  2. If you have a previous copy of Apache 2 in the opensource/apache2 directory, move it to another directory before proceeding. If you've made changes to previous copies of Apache 2 MakeTPF .mak files or source files be sure to save them, if desired, so they can be applied to the newly downloaded files.

  3. Unarchive apache2-2.2.9_20160121.tar.gz to your source directory. This package contains the tarred source trees for the Apache 2.2.9 HTTP Server (http://httpd.apache.org/) with additional modifications for the TPF system.

    tar zxvfp apache2-2.2.9_20160121.tar.gz

    This will create the directory structure opensource/apache2 in your source directory.
top

MakeTPF Setup

  1. Copy the six sample Apache 2 maketpf.env_apache2xxx environment files to the same directory as your other environment files. Adjust any settings if necessary.

  2. The CA2x program names used for Apache 2 are already in the tpf_app_base.cntl control file. Adjust any settings if necessary by making copies in your local_mod version.

  3. Sample ca2x.mak files for Apache 2 are located in the opensource/apache2 directory. Verify that the maketpf_env assignment in ca2s.mak is correct for your build environment. If it is not, correct it in all of the provided ca2x.mak files.

  4. Create a configuration file named opensource/apache2/maketpf.cfg or set TPF_CFG to the name of your maketpf.cfg file prior to compiling.
    Ensure that the first assignment of TPF_ROOT in your maketpf.cfg file is the absolute path to the directory just above opensource/apache2.

  5. Later if you want to include Apache 2 in your full build add APACHEV2=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 APACHEV2 function switch enabled.

top

Build

  1. Switch to the opensource/apache2 directory.

  2. Enable the use of OpenLDAP if desired.

    Apache can use OpenLDAP if you have downloaded and installed it on your system.
    To enable OpenLDAP, you must update three files:

    • srclib/apr-util/include/apr_ldap.h

      Change #define APR_HAS_LDAP from 0 to 1.

    • ca2u.mak and ca2s.mak

      uncomment (by removing the initial "#") the following lines:

      # LIBS += CLLB
      # LIBS += CTOE
      # maketpf_env += ldap

  3. Build the Apache Portable Runtime and PCRE libraries:

    maketpf ca2x.mak -f
    maketpf ca2r.mak -f
    maketpf ca2u.mak -f
    maketpf ca2p.mak -f

  4. Pick which MPM module to use: Prefork (default) or Worker.

    MPMs are special modules that manage incoming requests and control the Server's children. Only one MPM can be compiled into the Server. TPF supports the Prefork MPM, which uses fork(), and the Worker MPM, which uses fork() and threads.

    The default MPM is Prefork and requires no customization. Use Prefork unless you have a compelling reason for the server itself to run threaded.

    If you want to use the Worker MPM you'll need to update two MakeTPF files:

    • Edit the ca2s.mak file:
      Comment out (by preceding the line with a "#") the C_SRC += server/mpm/prefork/... line.
      Uncomment (by removing the initial "#") the C_SRC += server/mpm/worker/... lines.
    • Edit the maketpf.env_apache2server file:
      Change all instances of prefork to worker

  5. Choose which modules to compile into the Server.

    On TPF the ca2s.mak file controls which optional modules are compiled into Apache. (Linux systems use the configure script.) Leave the file as-is if you want to use the default set of modules. Otherwise edit the ca2s.mak file to customize which modules are used:

    • Comment out C_SRC lines (by preceding the line with a "#") corresponding to those modules you do not wish to include.
    • Uncomment C_SRC lines (by removing the initial "#", if present) corresponding to those modules you wish to include.

      If you include mod_deflate, you must also uncomment the LIBS += CZCM line

      If you include mod_ssl, you must also uncomment the following lines

      • LIBS += CSSL
      • maketpf_env += openssl
    • Add C_SRC lines for any custom or third party modules you wish to include. (Do a find on "third party modules go here" to see where they go.) 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 elsewhere.

  6. Create modules.c.

    Use the tpfgenmodlist script to script the modules.c file. (Linux systems use the configure script.)

    sed -f tpfgenmodlist ca2s.mak | tr -d '\n' | awk -f build/build-modules-c.awk > modules.c

    TIP: Any time you change which MPM or modules are in ca2s.mak you must regenerate modules.c

  7. Build the Server:

    maketpf ca2s.mak -f
    maketpf ca2m.mak -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.

top

Install

This section will walk though the installation of the simplest of test servers using default settings and layouts.

General documentation for Apache is located at http://httpd.apache.org/docs/ and in the HTML pages included with the distribution (tarball) under the opensource/apache2/docs/manual directory. This is not meant to replace that documentation.

  1. Load and activate the Apache code on your test system. At a minimum this will be ca2m, ca2p, ca2r, ca2s, ca2u, and ca2x. If you are following examples later in this document it will include additional code.

  2. Ensure that the Server program names (ca2m and ca2s) have RESTRICT and KEY0 authorization:

    zdpat ca2m
    zdpat ca2s


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


    zapat ca2m restrict key0 c-c
    zapat ca2s restrict key0 c-c

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

  4. Review the Apache run-time configuration file.

    The server requires a configuration file to initialize itself during activation. A sample configuration file for use on your test system is included as opensource/apache2/os/tpf/samples/httpd.conf. It is based on httpd.conf.in with the following changes:

    • The User daemon directive was replaced with User tpfdfltu
    • The Group daemon directive was replaced with Group tpfdfltg
    • Two Charset directives were added to the htdocs and cgi-bin directory containers:
      CharsetSourceEnc IBM-1047
      CharsetDefault ISO-8859-1
    • Port 80 was used for @@Port@@
    • The ServerName 127.0.0.1:80 directive was added to prevent Apache from doing a host name lookup on the test system during server startup
    • @@LoadModule@@ was deleted
    • Default locations were used for all remaining tokens: @@ServerRoot@@, @exp_cgidir@, @exp_htdocsdir@, @rel_logfiledir@, @rel_runtimedir@, and @rel_sysconfdir@

  5. Transfer configuration files and content to your test system.

    Using either FTP or TFTP, transfer the configuration file, icons, and web pages to your TPF system. A typical directory structure for Apache 2.2 is as follows:

    /usr/local/apache2/conf
    /usr/local/apache2/logs
    /usr/local/apache2/icons
    /usr/local/apache2/htdocs

    At a minimum you will need these files on your TPF test system:

    /usr/local/apache2/conf/httpd.conf   (from opensource/apache2/os/tpf/samples)
    /usr/local/apache2/conf/mime.types   (from opensource/apache2/docs/conf)
    /usr/local/apache2/htdocs/index.html (from opensource/apache2/docs/docroot)

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

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

  6. Create the logs directory: The logs directory must exist and be accessible in order to avoid an fopen error while starting the server:

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

top

Test

  1. Add the server to the Internet Daemon's tables using ZINET entries:

    zinet add s-apache2 pgm-ca2m model-daemon user-root

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

  2. Start the server:

    zinet start s-apache2

  3. Verify the server successfully started:

    zfile tail -n7 /usr/local/apache2/logs/error_log

    FILE0001I 18.50.40 START OF DISPLAY FROM tail -n7 /usr/local/apache2/logs/er...
    [Thu Sep 18 18:50:24 2008] [notice] Apache/2.2.9 (TPF) configured -- resuming normal operations
    END OF DISPLAY

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

    zinet stop s-apache2

    correct the httpd.conf file and transfer it to TPF

    zfile rm /usr/local/apache2/logs/error_log
    zinet start s-apache2

    See "How to Use "Dash" Options" below for instructions on using the -t option to run syntax checks against configuration files without starting the server.

  4. Request the index page from a web browser as http://12.34.56.78/index.html (where 12.34.56.78 is your test system IP address). You should see "It works!".

    If you see garbage like "L^£”“nL,-,,¨nL^ñnÉ£..." instead of "It works!" you are probably missing the necessary Charset directives in your conf file:

    <Directory "/usr/local/apache2/htdocs">
    CharsetSourceEnc IBM-1047
    CharsetDefault ISO-8859-1
    ...
    </Directory>

    Correct the conf file, restart the server, and reload the page.

    You may need to clear the web browser's cache or "temporary Internet files" in order to get the new response depending on the browser and its settings.

top

Stopping and Restarting

Apache documentation details stopping and restarting Apache 2.2. While the concepts still apply, TPF does not support apachectl nor WINCH.

The Internet Daemon (ZINET/InetD) is used to initially start the server on TPF and only the ZINET DAEMON model is supported for Apache 2.2.

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

This is how Apache 2.2 interacts with TPF's Internet Daemon (with Apache CSO/program names shown in blue):

zinet diagram

CLTZ, shown in the diagram above, creates the Apache parent and monitors it. CLTZ will create a new parent if the original one exits.
CLTZ will send a SIGTERM signal to the Apache parent if a zinet stop entry is made or if there has been a change to the program activation number.
(You can minimize unnecessary recycling because of ZOLDR program activation number changes by updating the user exit UERA.)

The Apache parent will shut down and exit under various conditions:

There are various ways to manually restart the server using signals. All of these examples assume the default ServerRoot and PidFile:
top

ZOLDR Recycling

TPF's Internet Daemon (specifically CLTZ) will recycle Apache if the program activation number (ACN) changes for any reason. The "E-type loader recycle interface" was added with PJ37377 so you can tell the Internet Daemon which programs are relevant to a given server. It allows the Daemon to recycle only when server code, Daemon code, or standard libraries have changed. This minimizes unnecessary recycling because of E-type loader (ZOLDR) program activation number changes.

Apache has been modified to work with the recycle interface but you must update user exit UERA with the program names used for your server to take advantage of this feature.
Here's an example of what you would put at the bottom of UERA if you built the most basic server CA2M/CA2S using the instructions in this README: 

if(memcmp(local_entry_pgm, "CA2M", 4) == 0) {
   /* The list already has CA2M (the server entry program),
      CLTW, CLTY, CLTZ, UERA, and IELD_LAST_RECYCLE_PROGRAM.
      Add the other libraries that make up this server:
   */
   int i = (*daemon_server_pgm_list)->num_of_pgm_entries - 1;
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname, "CA2S", 4);
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname, "CA2P", 4);
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname, "CA2R", 4);
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname, "CA2U", 4);
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname, "CA2X", 4);
   /* If you have additional libraries, put them here. */
   memcpy((*daemon_server_pgm_list)->entry[i++].pgmname,
          IELD_LAST_RECYCLE_PROGRAM, ELD_PROGNAME_LEN);
   (*daemon_server_pgm_list)->num_of_pgm_entries = i;
} else {

Remember to add any additional libraries used by your server to UERA. For example, if you build CA2M/CA2S with mod_info using the mod_so example below, you need to add CA2I.

The standard libraries listed in the "E-type loader recycle interface" section of the IBM TPF Information Center and TPF's Internet Daemon do not need to be added to UERA.

CGI scripts do not need to be added to UERA.

top

How to Use "Dash" Options

Apache can be invoked with various "dash" options, such as -f which lets you override the default configuration file name.

Some of these options display information about the server or perform syntax checks but they don't actually start the server. These "information only" options are useful with TPF's ZFILE command line feature: -h, -L, -l, -M, -S, -t, -V, and -v.

Other options, -E, -e, and -X, are used when actually running the server. They are passed to Apache through the ZINET XPARM field since ZINET is the only way to start the server on TPF.

TIP: The -X debug option is supported with the Prefork MPM only. TPF does not support -X with the Worker MPM.

A third group of options apply to both the informational displays (ZFILE) and running the server (ZINET XPARM): -C, -c, -D, -d, and -f.

The rest of Apache's dash options are either not applicable or are not supported on TPF: -k, -n, -R, and -w.

ZFILE: -C -c -D -d     -f -h -L -l -M -S -t -V -v  
ZINET: -C -c -D -d -E -e -f                 -X 

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

See "Activate a z/TPF segment or script" in the IBM TPF Information Center for additional ZFILE information.

See "ZINET ADD" and "ZINET ALTER" in the IBM TPF Information Center for additional information about using the ZINET XPARM field.

top

TPF Uniqueness

This section covers items unique to TPF that are not addressed elsewhere in this README.

Notes organized by directive:

Notes organized by module:

General notes:

Apache 2.2 removes some TPF-unique features found in Apache 1.3:

top

mod_cgi Example

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 documentation for additional information.

  1. Create, load, and activate the CGI program (QZZ1) on your TPF test system:

    /* QZZ1-- simple "Hello world" program to demonstrate basic CGI output */

#include <stdio.h>
#include <stdlib.h>

int main() {

   /* Print the CGI response header, required for all HTML output. */
   /* Note the extra \n, to send the blank line.                   */
   /* Print the HTML response page to STDOUT.                      */
   printf("Content-type: text/html\n\n");

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

   exit(0);
}

  2. 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. The httpd.conf file should already have this directive: ScriptAlias /cgi-bin/ "/usr/local/apache2/cgi-bin/"
    If it does not, add it. The directive causes a request for http://12.34.56.78/cgi-bin/filename.cgi to run the script /usr/local/apache2/cgi-bin/filename.cgi

    # create the script:
    zfile mkdir /usr/local/apache2/cgi-bin
    zfile echo "#!QZZ1" > /usr/local/apache2/cgi-bin/filename.cgi
    # verify the script contents - expected output is #!QZZ1
    zfile cat /usr/local/apache2/cgi-bin/filename.cgi
    # mark the script as executable:
    zfile chmod 755 /usr/local/apache2/cgi-bin/filename.cgi

  3. Temporarily add the ScriptLog directive to httpd.conf and transfer it to your test system:

    ScriptLog logs/script_log

    The ScriptLog can be helpful in determining CGI errors but note that "... script logging is meant to be a debugging feature when writing CGI scripts, and is not meant to be activated continuously on running servers."

  4. Start or restart the server to pick up the new conf file.

  5. Request the CGI script from a web browser as http://12.34.56.78/cgi-bin/filename.cgi (where 12.34.56.78 is your test system IP address). You should see "Hello world.".

    If you see garbage like "L^£n±L^±,,nL£%£nÃÇ..." instead of "It works!" you are probably missing the necessary Charset directives in your conf file:

    <Directory "/usr/local/apache2/cgi-bin">
    CharsetSourceEnc IBM-1047
    CharsetDefault ISO-8859-1
    ...
    </Directory>

    Correct the conf file, restart the server, and reload the page.

    If you get different errors check the script_log (which may or may not exist) and the error_log:

    zfile tail -n7 /usr/local/apache2/logs/script_log
    zfile tail -n7 /usr/local/apache2/logs/error_log

    You may need to clear the web browser's cache or "temporary Internet files" in order to get the new response depending on the browser and its settings.

top

mod_so Example

The mod_so module allows specific modules to be loaded into the server at startup or restart time instead of during compilation. To do this, each target module is compiled separately and activated dynamically with a LoadModule directive.

For this example we will be using mod_info as the target module to be dynamically loaded:

  1. Build the server with mod_so but without mod_info. It can have whatever other modules you like. Check ca2s.mak. If it was already built with mod_so and without mod_info there's no need to rebuild it for this example.

  2. Build mod_info by itself (ca2i):

    maketpf ca2i.mak -f

    If we were building several modules to load dynamically, each would have its own .mak file.

  3. Stop the server if it is currently running on your test system

  4. Load and activate the Apache code, including CA2I, on your test system.

  5. Update the httpd.conf file and transfer it to your test system:

    # mod_so directive to load mod_info:
    LoadModule info_module modules/mod_info.so

    # associate the .../server-info URL with mod_info:
    <Location /server-info>
    SetHandler server-info
    </Location>

  6. Create the LoadModule file/script on your test system:

    # create the LoadModule script:
    zfile mkdir /usr/local/apache2/modules
    zfile echo "#!CA2I" > /usr/local/apache2/modules/mod_info.so

    # verify the script contents - expected output is #!CA2I
    zfile cat /usr/local/apache2/modules/mod_info.so

    # mark the script as executable:
    zfile chmod 755 /usr/local/apache2/modules/mod_info.so

  7. Start the server

    The mod_so module is probably missing from your server if you see this error message:
    Invalid command 'LoadModule', perhaps misspelled or defined by a module not included in the server configuration

    CA2I (the mod_info module) is probably missing from your system if you receive an OPR-I000004 dump with TRC-CA2R OBJ-cdlsym

  8. Request the server information page from a web browser as http://12.34.56.78/server-info (where 12.34.56.78 is your test system IP address). You should see the "Apache Server Information" page.

top

mod_ssl Example

NOTE: PJ45286 added support for the latest security standards in the z/TPF Apache HTTP Server Version 2.2.9. This support allows for TLS 1.1 and TLS 1.2 Apache sessions.

This is a simple example of testing mod_ssl with a self-signed certificate.

  1. Rebuild the server with mod_ssl using the build instructions above. Load the rebuilt server to your test system.

  2. Create a self-signed certificate called test.pem.

    One way to create a self-signed certificate is by using the OpenSSL command line tool on a Linux box. Our test.pem file will hold both the key and the certificate. Prompted input is shown below in italics:

    openssl req -x509 -nodes -newkey rsa:1024 -keyout test.pem -out test.pem

    Generating a 1024 bit RSA private key
    ......................................++++++
    .................++++++
    writing new private key to 'test.pem'
    -----
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [AU]: US
    State or Province Name (full name) [Some-State]: CO
    Locality Name (eg, city) []: Denver
    Organization Name (eg, company) [Internet Widgits Pty Ltd]: ACME
    Organizational Unit Name (eg, section) []: Mfg
    Common Name (eg, YOUR name) []: Joe
    Email Address []: joe@acme.com

    Transfer the file (as text) to your test system as /usr/local/apache2/test.pem.

  3. Add these directives to the httpd.conf file and transfer it to your test system. Port 443 is the default for HTTPS:

    Listen 443
    <VirtualHost _default_:443>
    SSLEngine on
    SSLCertificateFile "/usr/local/apache2/test.pem"
    SSLCertificateKeyFile "/usr/local/apache2/test.pem"
    </VirtualHost>
    SSLMutex yes
    <Directory /usr/local/apache2/htdocs>
    SSLRequireSSL
    </Directory>

  4. Start or restart the server to pick up the new conf file.

    The server is probably missing mod_ssl if you receive this error: Invalid command 'SSLEngine', perhaps misspelled or defined by a module not included in the server configuration

    The /usr/local/apache2/test.pem file is probably missing, transferred incorrectly, or inaccessible if you receive this error: SSLCertificateFile: file '/usr/local/apache2/test.pem' does not exist or is empty

  5. Request the index page from a web browser as https://12.34.56.78/index.html (where 12.34.56.78 is your test system IP address). You should see "It works! once the self-signed certificate is accepted".

    Because the test certificate is self-signed, your web browser will warn you that the site is not to be trusted. (For a production website you wouldn't use a self-signed certificate and would not see this warning.) How you accept the certificate depends on the browser you are using:

    • Microsoft Internet Explorer 6 will display a "Security Alert" and ask "Do you want to proceed?".
    • Firefox 3 will display "Secure Connection Failure ... The certificate is not trusted because it is self signed. The certificate is only valid for Joe". Click the "add an exception" link to get the certificate and add an exception.
    • Google Chrome will display "the site's security certificate is not trusted!". Click "Proceed anyway". It will show the "https" with a slash through it since it is a self-signed certificate.

    If you get an HTTP 403 Forbidden error (not authorized to view this page), verify that you requested https://... and not http://...

top

mod_suexec Example

The mod_suexec module, used along with Apache's suexec program, runs CGI scripts as a specific user/group. It stands for "Switch User for EXEC" and is sometimes used with multi-user virtual hosting. In this simple example we will be running CGI scripts as user tpfuser1 / group tpfuser.

  1. Follow the entire mod_cgi example. After you have successfully served up the CGI script filename.cgi, stop the server.

  2. Rebuild the server with the mod_suexec module added using the build instructions above.

  3. Build the suexec program as CA2E.

    When a CGI is called using mod_suexec, the Apache suexec program (CA2E) is first invoked as the mechanism for switching to the desired user.

    • Customize ca2e.mak:

      • Set AP_DOC_ROOT to the directory where your CGI scripts will reside. For this example that is /usr/local/apache2/cgi-bin:

        CFLAGS_CA2E += -D AP_DOC_ROOT=\"/usr/local/apache2/cgi-bin\"

      • Set AP_LOG_EXEC to the file name you would like to use for the suexec log. The default is /usr/local/apache2/logs/suexec_log:

        CFLAGS_CA2E += -D AP_LOG_EXEC=\"/usr/local/apache2/logs/suexec_log\"

      • Set AP_HTTPD_USER to the User directive value in your httpd.conf file (User tpfdfltu). For this example, change the AP_HTTPD_USER definition to tpfdfltu:

        CFLAGS_CA2E += -D AP_HTTPD_USER=\"tpfdfltu\"

      • Set AP_UID_MIN to the lowest numeric User ID (UID) you want to allow. For this example, change the AP_UID_MIN definition to 260 which is the numeric UID for tpfuser1:

        CFLAGS_CA2E += -D AP_UID_MIN=260

        You can determine the numeric UID by displaying the entire /etc/passwd file (zfile cat /etc/passwd) or just the line for tpfuser1 (zfile grep tpfuser1 /etc/passwd).

      • Set AP_GID_MIN to the lowest numeric Group ID (GID) you want to allow. For this example, change the AP_GID_MIN definition to 100 which is the numeric GID for tpfuser:

        CFLAGS_CA2E += -D AP_GID_MIN=100

        You can determine the numeric GID by displaying the entire /etc/group file (zfile cat /etc/group) or just the line for tpfuser (zfile grep tpfuser /etc/group).

    • Build CA2E:

      maketpf ca2e.mak -f

  4. Load and activate the rebuilt server code, QZZ1, and CA2E to your test system.

  5. Create the suexec script and verify its build settings:

    # create the script:
    zfile mkdir /usr/local/apache2/bin
    zfile echo "#!CA2E" > /usr/local/apache2/bin/suexec
    # verify the script contents - expected output is #!CA2E
    zfile cat /usr/local/apache2/bin/suexec
    # mark the script as executable:
    zfile chmod 4755 /usr/local/apache2/bin/suexec

    # verify suexec's build settings:
    zfile /usr/local/apache2/bin/suexec -V

    FILE0002I 14.23.40 START OF ERROR DISPLAY FROM /usr/local/apache2/bin/suexec -V
    -D AP_DOC_ROOT="/usr/local/apache2/cgi-bin"
    -D AP_GID_MIN=100
    -D AP_HTTPD_USER="tpfdfltu"
    -D AP_LOG_EXEC="/usr/local/apache2/logs/suexec_log"
    -D AP_SAFE_PATH="/usr/local/bin:/usr/bin:/bin"
    -D AP_UID_MIN=260
    -D AP_USERDIR_SUFFIX="public_html"
    END OF DISPLAY

  6. Add the SuexecUserGroup directive to httpd.conf and transfer it to your test system:

    SuexecUserGroup tpfuser1 tpfuser

  7. Set permissions and ownership for the CGI script.

    The directory containing the CGI script cannot be writable by others. That directory and the script must be owned by the user/group in the SuexecUserGroup directive:

    zfile chmod 755 /usr/local/apache2/cgi-bin
    zfile chown tpfuser1:tpfuser /usr/local/apache2/cgi-bin
    zfile chown tpfuser1:tpfuser /usr/local/apache2/cgi-bin/filename.cgi

  8. Start the server.

    zinet start s-apache2

    The mod_suexec module is probably missing from your server if you see this error message:
    Invalid command 'SuexecUserGroup', perhaps misspelled or defined by a module not included in the server configuration

    The /usr/local/apache2/bin/suexec script is probably missing or does not have the right permission settings if you see this error message:
    Warning: SuexecUserGroup directive requires SUEXEC wrapper.

  9. Verify the server successfully started with the "suEXEC mechanism enabled":

    zfile tail -n7 /usr/local/apache2/logs/error_log

    FILE0001I 16.01.00 START OF DISPLAY FROM tail -n7 /usr/local/apache2/logs/er...
    [Sat Oct 04 15:57:51 2008] [notice] suEXEC mechanism enabled (wrapper: /usr/local/apache2/bin/suexec)
    [Sat Oct 04 15:57:51 2008] [notice] Apache/2.2.9 (TPF) configured -- resuming normal operations
    END OF DISPLAY

  10. Request the CGI script from a web browser as http://12.34.56.78/cgi-bin/filename.cgi (where 12.34.56.78 is your test system IP address). You should see "Hello world.".

    Additionally, the suexec_log will note the transaction:

    zfile tail -n7 /usr/local/apache2/logs/suexec_log

    FILE0001I 19.47.14 START OF DISPLAY FROM tail -n7 /usr/local/apache2/logs/su...
    [2008-10-04 18:21:35]: uid: (260/tpfuser1) gid: (100/tpfuser) cmd: filename.cgi

    END OF DISPLAY

    If you receive HTTP 500 "Internal Server Error" use the suexec_log to help determine the cause of the error:

    • user mismatch (xxx instead of yyy)

      This error message indicates the server is running as user xxx but suexec (CA2E) was built with AP_HTTPD_USER defined as yyy. Verify the User directive in the httpd.conf file and the AP_HTTPD_USER setting in ca2e.mak. For this example make sure that both of these are tpfdfltu.

    • cannot run as forbidden uid (260/filename.cgi)

      This error message indicates the AP_UID_MIN definition that suexec (CA2E) was built with was larger than 260.

    • cannot run as forbidden gid (100/filename.cgi)

      This error message indicates the AP_GID_MIN definition that suexec (CA2E) was built with was larger than 100.

    • directory is writable by others: (/usr/local/apache2/cgi-bin)

      This error message indicates you need to change permission settings: zfile chmod 755 /usr/local/apache2/cgi-bin

    • target uid/gid (260/100) mismatch with directory (x/y) or program (x/y)

      This error message indicates you need to change ownership settings:
      zfile chown tpfuser1:tpfuser /usr/local/apache2/cgi-bin
      zfile chown tpfuser1:tpfuser /usr/local/apache2/cgi-bin/filename.cgi

top

Supporting Programs

The Apache 2 Server comes with various supporting programs that fall into two groups: functional entries and executables called by the server itself. With the exception of checkgid all of these programs are documented in the Supporting Programs area of the Apache website.

  1. Function entries

    All supporting programs in this group are built and activated as follows (with actual values substituted for ca2x, #!CA2X, command, and arguments):

    # build, load, and activate the code to your system
    maketpf ca2x.mak -f

    # create the script:
    zfile echo "#!CA2X" > /bin/command
    # verify the script contents - expected output is #!CA2X
    zfile cat /bin/command
    # mark the script as executable:
    zfile chmod 755 /bin/command

    # run the functional entry:
    zfile command arguments

    Using the values below for checkgid we get this example:

    # build, load, and activate the code to your system
    maketpf ca2g.mak -f

    # create the script:
    zfile echo "#!CA2G" > /bin/checkgid
    # verify the script contents - expected output is #!CA2G
    zfile cat /bin/checkgid
    # mark the script as executable:
    zfile chmod 755 /bin/checkgid

    # run the functional entry:
    zfile checkgid foo bar
    FILE0002I 18.12.35 START OF ERROR DISPLAY FROM checkgid foobar
    /bin/checkgid: group 'foo' not found
    /bin/checkgid: group 'bar' not found
    END OF DISPLAY

    zfile checkgid tpfdfltg
    CSMP0097I 18.10.59 CPU-B SS-BSS SSU-HPN IS-01
    FILE0003I 18.10.59 checkgid tp... COMPLETED SUCCESSFULLY. NO OUTPUT TO DISPLAY

    These are the commands:

    • checkgid (use ca2g.mak and #!CA2G)

      This command is not documented but its syntax is checkgid gid [...].

    • htcacheclean (use ca2k.mak and #!CA2K)

    • htdbm (use ca2b.mak and #!CA2B)

      The -b (batch) option is required on TPF.

    • htdigest (use ca2d.mak and #!CA2D)

      The -b (batch) option is required on TPF.
      This option is not shown in the online documentation but is present in the downloaded files (opensource/apache2/docs/manual/programs/htdigest.html.en and opensource/apache2/docs/man/htdigest.1).
      It uses this syntax: htdigest [-c] -b passwdfile realm username password

    • htpasswd (use ca2w.mak and #!CA2W)

      The -b (batch) option is required on TPF.

      The -d (crypt) option is not supported on TPF and MD5 encryption will be used instead.

    • httxt2dbm (use ca2h.mak and #!CA2H)

    • logresolve (use ca2l.mak and #!CA2L)

    With the exception of checkgid and logresolve, zfile command with no arguments will give you an error message and a usage display for the command.

  2. Server executables

    • rotatelogs (use ca2o.mak and #!CA2O)

      Build and create the script for rotatelogs like you would a functional entry above.

      Instead of invoking it with a zfile functional entry, add directives to your httpd.conf file. For example, to rotate a log hourly:

      LogFormat "%h %l %u %t \"%r\" %>s %b" common
      CustomLog "|/bin/rotatelogs /usr/local/apache2/logs/custom_log 3600" common

    • suexec

      See the mod_suexec example for instructions on building suexec.

top

Syslog Daemon

The syslog daemon is a server process that provides a message logging facility for application and system processes. It can be used to write messages to log files or to tapes. See "Operating the Syslog Daemon" in the IBM TPF Information Center. And see the Apache ErrorLog directive documentation for details on how to use syslog with Apache.

Here are some tips on using syslog with Apache. They are not meant to replace the syslog documentation in the TPF TCP/IP publication.

top

Upgrading / Migration from Apache 1.3 to Apache 2.2

Apache 1.3 and 2.2 servers can run concurrently, either during migration or permanently. If they service traffic from the same port, (for example, port 80), you must add an IP address to the Listen directives in both their httpd.conf files or the second server started will fail. (They can't both bind to the same port and IP address.)

Apache 2 changes the default server root from /usr/local/apache to /usr/local/apache2. You can override this with the -d option. (See the "How to use dash options" section.) If you run multiple servers with the same server root use the ErrorLog and PidFile directives to ensure they don't overwrite each others' logs.

You can use the DocumentRoot /usr/local/apache/htdocs directive to serve your Apache 1.3 content without moving it to /usr/local/apache2/htdocs if you like.

There are major httpd.conf differences between Apache 1.3 and 2.2 that will require manual adjustments. This includes the addition of two Charset directives of special interest for EBCDIC platforms:

Any third-party Apache 1.3 modules, like mod_tpf_soap, will need to be upgraded to accommodate the new Apache 2 module API.

top

Known Issues

top

Change History

apache2-2.2.9_20180522.tar.gz

apache2-2.2.9_20160121.tar.gz

httpd-2.2.9_20121018.tar.gz

httpd-2.2.9_20121004.tar.gz

httpd-2.2.9_20120622.tar.gz

httpd-2.2.9_20110407.tar.gz

httpd-2.2.9_20110127.tar.gz

httpd-2.2.9_20100924.tar.gz

httpd-2.2.9_20100805.tar.gz

httpd-2.2.9_20100430.tar.gz

httpd-2.2.9_20090323.tar.gz

httpd-2.2.9_20081007.tar.gz (First download containing TPF and EBCDIC changes.)

top

last updated 2016-01-21