DGW Migration FAQ

Provide feedback on the IBM HTTP Server forum on IBM developerWorks.

Other sources of information

Install questions

Do I need to use IBM Installation Manager to install IHS powered by Apache on z/OS?

IBM Installation Manager is only used with the IBM HTTP Server bundled with WebSphere Application Server. IBM HTTP Server 8.5.5 included with z/OS Ported Tools installs uses SMPE just like V7R0 did.

Setup / System Config / prerequisites

ICSF issues

To use modern TLS ciphers, ICSF must be configured. See "RACF CSFSERV Resource Requirements" in the z/OS Cryptographic Services System SSL Programming for more information (including CSFRNG access).

IBM HTTP Server 9.0 uses /dev/random which also requires ICSF to be configured and accessible to the IHS userid.

In z/OS 2.2 and later, IHS'es use of CSFRNG can generate many audit events

URL mapping questions

Problems with double-slashes

Domino by default "simplifies" URL paths that contained double-slashes, such as http://www.example.com/icons//spacer.jpg. While these do not affect mapping of URL paths to the filesystem, they can affect other modules that work on the URI directly, such as the WAS WebServer Plug-in.

Here is a recipe to remove one double-slash from the URL path:

  1. Uncomment LoadModule for mod_rewrite near top of httod.conf
  2. Once at bottom of httpd.conf and once in each :
    RewriteEngine ON
    # Remove first double-slash from the path component of the URL
    RewriteRule ^(.*)//+(.*)$ $1/$2 [PT] 
    

Translation questions

How can I serve ASCII static content?

The default configuration translate static files from IBM1047 to ISO8859-1. You can add later rules to fine-tune or opt out of translation for specific resources. Any time CharsetSourceEnc and CharsetDefault have the same value, translation is disabled. The specific value is not important.

How does IHS treat request bodies?

IHS does the inverse translation on request bodies of POST and PUT requests as configured by mod_charset_lite. On individual locations, this can be suppressed.

<Location /app1/form>
   CharsetOptions NoTranslateRequestBodies
</location>

How can I serve a xml file that is in EBCDIC and requires translation?

Use the LocationMatch stanza to define the following options. This will translate an xml or xsl file coming from the files/xml folder.

# Note, be sure to places this after existing/default translation rules.
# Ideally, append it to httpd.conf.
<LocationMatch ^/~user1/xml/.*\.x[ms]l$>
   CharsetSourceEnc IBM-1047           
   CharsetDefault   ISO8859-1          
   CharsetOptions TranslateAllMimeTypes
</LocationMatch>

Are there any locale (LC_*) differences between DGW and IHS?

IHS doesn't call setlocale(LC_ALL, ""), so setting LC_* variables doesn't have any direct affect on locale-sensitive standard library calls.

Translation problems with "#include file=" in SSI

When file parsed by Server Side Includes (SSI) contains "#include file=" (but not virtual=), the default configuration will not translate the included file. This is due to the default translation being specified in a <Location> but directly including a file in this way does not associate it with any particular URL-path.

One simple workaround is to re-specify the default translation configuration in a &lt;Files *&gt; configuration section or in a <Directory> section.

This is resolved in PI62663.

CGI questions

Authtype basic AuthName foo AuthBasicProvider saf Require valid-user SafRunAs %%CLIENT%% Options +FollowSymlinks RewriteEngine ON RewriteCond %{REMOTE_USER} (.+) RewriteRule .* - [E=_BPX_USERID:%1]

Why isn't _BPX_USERID set for my CGI environment?

Domino unnecessarily set _BPX_USERID in a CGI's environment even though it already changed userids. Apache does not currently set this variable, but you can copy the "REMOTE_USER" variable to this variable to allow existing scripts to continue to function unchanged.


<Location /cgi-bin/test-cgi>
  # Example of SAF-authenticated resource.
  Authtype basic
  AuthName foo
  AuthBasicProvider saf
  Require valid-user
  SafRunAs  %%CLIENT%%
  
  # Copy REMOTE_USER to _BPX_USERID. Note that this only works when mod_rewrite
  # is configured in "directory" context. You cannot put this outside of 
  # Location/Directory, as it will run prior to authentication.
  Options +FollowSymlinks
  RewriteEngine ON
  RewriteCond %{REMOTE_USER} (.+)
  RewriteRule .* - [E=_BPX_USERID:%1]
</Location>

FSCP and NETCP environment variables

These variables are not set by Apache. If you depend on them being set as a global configuration for a CGI, set them with SetEnv.

Why doesn't 'PULL PARSE' work in a REXX CGI?

If the POST body is not newline-terminated, PULL PARSE won't read any data. There is no reason for a POST body to be newline terminated. DGW had a workaround to accomodate this by adding data to the users POST body. Apache doesn't modify the body in this way.

How can a CGI opt out of otherwise configured translation?

Set CharsetOptions DGWCompat and then issue a response header of Content-Encoding: binary. This will be filtered out and short-circuit translation in 8.5.5 and later.

Why does my CGI/REXX/PHP not run under the userid I expect?

There are a handful of subtle reasons that SAFRunAs might not apply to your request.

  • SAFRunAs must be specified in some context your script is running in!
  • If using the Action directive to pass scripts to an interpreter, make sure SAFRunAs applies to the location of the interpreter rather than the path to the scripts -- even though the initial request is for the script.

Examples

Normal CGI Example (any language)

# /usr/local/my-app-1.0/ has executables that might be native binaries, or text files
# that specify #!/usr/bin/perl, #!/usr/bin/php-cgi, #!/bin/sh, or any other interpeter.
Alias /my-app/ /usr/local/my-app-1.0/
<Directory /usr/local/my-app-1.0/>
  Options +ExecCGI
  SetHandler cgi-script

  Authname "LOGON REQUIRED"                                               
  AuthType Basic                                                          
  AuthBasicProvider saf                                                   
  Require valid-user                                                      
  SAFRunAs %%CLIENT%%    
</Directory>

Action Example (any language)

The Action directive allows you to pass your scripts to a custom interpreter instead of executing them directly. Because of the way requests to your script are translated into requests for the interpreter, the SAFRunAs config has to be associated with the path to the interpreter. You provide the interpreter, which is often a wrapper around something like php-cgi with custom environment variables.

# Give the wrapper a URL
ScriptAliasMatch /cgi-bin/my-php-wrapper.sh /usr/local/php/my-php-wrapper.sh

# Make up a new virtual mimetype to map requests to the wrapper
Action indirect-php-script /cgi-bin/my-php-wrapper.sh

# The wrapper itself must act like a CGI
<Location /cgi-bin/my-php-wrapper.sh>
  Options +ExecCGI
  SetHandler cgi-script

  # Since our application runs entirely beneath the wrapper, it's where
  # we must conigure things like SAFRunAs

  Authname "LOGON REQUIRED"                                               
  AuthType Basic                                                          
  AuthBasicProvider saf                                                   
  Require valid-user                                                      
  SAFRunAs %%CLIENT%%    

  # This is IHS 9.0 / Apache 2.4 syntax
  <IfModule authz_core_module>
      <RequireAll>
          Require valid-user
          # Prevent direct access to the wrapper
          Require env REDIRECT_STATUS
      </RequireAll>
  </IfModule>

  # This is IHS 8.5.5 / Apache 2.2 syntax:
  <IfModule !authz_core_module>
      Satisfy all
      Require valid-user
      Order allow,deny
      # Prevent direct access to the wrapper
      allow from env=REDIRECT_STATUS
  </IfModule>

</Location>

Alias /my-app/ /usr/local/my-app-1.0/
<Directory /usr/local/my-app-1.0/>
  # PHP files in this dir should be sent to our indirect-php-script action
  AddHandler indirect-php-script .php

  # Access control for non-script resources
  Authname "LOGON REQUIRED"                                               
  AuthType Basic                                                          
  AuthBasicProvider saf                                                   
  Require valid-user                                                      
  SAFRunAs %%CLIENT%%    
<Directory>

Authentication, authorization, and access control questions

What's the equivalent of the UserID directive?

While there is no direct equivalent, if UserID was being used to change to a different thread identity, mod_authnz_saf can do similar userid changes.

MVSDS (MVS Dataset support) questions

Problems with Content-Type

The core of Apache will assign content types based on dataset names from the conf/mime.types file. If there are no matches, mod_mvsds will try to infer if the file is XML or HTMl to set an appropriate content-type. The type can be overridden with LocationMatch and ForceType.

Corrupt binary files

IHS before 8.5.5.4 (PI21655) had problems serving binary files from MVS datasets.

GWAPI / Module development questions

How is the Apache API/ABI versioned?

Apache has a major release (1.3, 2.0, 2.2, 2.4) approximately very 6 years. Modules need to be re-compiled to be loaded under a subsequent release. Typically, a change in the minor version will require almost no source code changes. Fixpacks never change the ABI or change existing APIs.

What resources are available to learn about Apache module development?

Books

API documentation

The API is not comprehensively documented outside of the header files shipped in the include/ subdirectory. Some documentation specific to Apache 2.4 has been recently expanded:

Example modules