z/OS FAQ¶
Related Links¶
DGW Migration FAQ¶
Information related to DGW migration can be found in the DGW Migration FAQ.
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. In z/OS 2.2 and later, IHS 9.0 is available as part of the base operating system via SMPE.
What happens during an IHS SMPE upgrade?¶
No action is required of the user after an IHS PTF is applied. The following steps happen automatically.
The IHS binaries in /usr/lpp/ihsa_zos are replaced and marked program controlled as the PTF is applied.
The next time apachectl
is run from an IHS instance, the differences between the instances version.signature
and the copy in /usr/lpp/ihsa_zos is detected.
If the
apachectl
invocation was for a start/restart, postinstallation is performed for the instance prior to the start/restartNew symlinks are added for any files in the following /usr/lpp/ihsa_zos subdirectories:
bin conf modules modules/debug lib include icons build
The IHS postinaller program is run. It is responsible for substituting variables or otherwise making corrections to shipped text files.
If the
apachectl
invocation was for anything else, a brief message is issued that the installation has been updated since the last start.
Can I move an existing instance to an alternate install/read-only root?¶
8.5.5.13/9.0.0.0 and later include a script called "new_install_root" which allows an existing instance to be pointed at an additional read-only installation root. This allows IHS to be installed and configured on a "prep" system and also allows an existing instance to be pointed at an alternate service level of the binaries without changing all instances.
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
Where is the sample JCL?¶
SMPE installations include sample JCL that shows a PROC that can be used
to start IHS. The JCL is installed by default into HAP.SHAPJCL3(HAPCPROC)
. On
some systems, HAP
may be replaced by a custom high level qualifier.
Additionally, you may need to explicitly search your IPL volume serial (/D
IPLINFO).
The JCL provided contains a brief PROC and EXEC, but not a job that can be submitted directly. The sample
can be referenced by a new JOB by passing in the DIR= variable point to a location where bin/install_ihs
has been used to create a webserver instance. Alternatively, the sample can be copied to a local PROCLIB
and it can be prefixed with a JOB card.
Example of calling the proc:
//IHS JOB @@USEID,'IHS',CLASS=A,REGION=0M
//JCL1 JCLLIB ORDER=SYS1.SHAPJCL3
//A EXEC PROC=HAPCPROC,DIR='/etc/webserv1'
//
Integration with z/OS features¶
DVIPA issues¶
Dynamically created DVIPAs do not work with IBM HTTP Server, because when the DVIPA is moved it is deleted from the prior system, rendering the listening socket unusable. errno "3448" (EUNATTACH) is returned perpetually in an IHS instance whose dynamic DVIPA has been deleted.
SDBM LDAP¶
The LDAP server on z/OS can provide an LDAP view of the RACF database which allows portable applications to use RACF data as a directory service. While generally the IHS interface into RACF is via mod_authnz_saf and does not require LDAP, it is sometimes useful to use mod_ldap and mod_authnz_lpda to point to such an SDBM LDAP server on z/OS.
The first parameter of
AuthLDAPURL
(after the host and port) should be the "LDAP suffix" for the LDAP server instance appended toprofiletype=user,
e.g.profiletype=user,o=my-suffix
The second parameter of
AuthLDAPURl
in most cases will beracfid
instead of thecn
value you see in many examples.If using LDAP groups for authorization:
Specify the group name in this form:
Require ldap-group racfid=MYGROUP,profiletype=GROUP,o=MYSUFFIX
Add the following directive to the configuration stanza:
AuthLDAPGroupAttribute racfgroupuserids
If you are trying to avoid having a dedicated LDAP DN for the webserver, the following directives are helpful:
AuthLDAPInitialBindAsUser ON AuthLDAPDNFromBindAsUser ON AuthLDAPInitialBindPattern (.+) "racfid=$1,profiletype=user,o=my-suffix"
How can I force TLSv1.2 for outgoing LDAP connections¶
Append the following stanza to $IHSROOT/bin/envvars and do a full stop/start:
export GSK_PROTOCOL_TLSV1=OFF
export GSK_PROTOCOL_TLSV1_1=OFF
export GSK_PROTOCOL_TLSV1_2=ON
This will not have any effect on the TLS settings used for inbound or output https connections. For more information, consult the "Environment Variables" topic in the "Cryptographic Services System Secure Sockets Layer Programming" for your release of z/OS.
Translation questions¶
Why are line endings missing from my content served from datasets?¶
If you are missing line endings in text files, possibly with an unusual or empty Content-Type, see the following section of the mod_mvsds manual:
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.
If the content is identified by path prefix, append this to the bottom of httpd.conf:
<Directory /var/www/app1/static/> CharsetSourceEnc UTF-8 CharsetDefault UTF-8 </Directory >
If the content is mixed on-disk, but identified by some ascii extension, append this to httpd.conf:
<FilesMatch \.ascii$> CharsetSourceEnc UTF-8 CharsetDefault UTF-8 # Technically this is processed before Location and LocationMatch, and will be overridden # by <lLocation />, which is why NoImplicitAdd is required. CharsetOptions NoImplicitAdd </FilesMatch>
For on-disk content, a subset of which does not require translation:
<Directory /var/www/myapp/style/> <FilesMatch \.css$> CharsetSourceEnc UTF-8 CharsetDefault UTF-8 # Technically this is processed before Location and LocationMatch, and will be overridden # by <Location />, which is why NoImplicitAdd is required. CharsetOptions NoImplicitAdd </Directory>
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>
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 <Files> configuration section or in a <Directory> section.
This is resolved in PI62663.
Special considerations for multipart form uploads¶
When multipart form uploads are processed by IHS (such as CGI or PHP, but not forwarded to WebSphere) there are special translation considerations. Multipart form uploads might mix text data, which needs to be translated, with binary file uploads which must not be translated
IHS cannot partially translate the request body.
By default, the application will see the multipart metadata and any text data as EBCDIC. If a multipart upload has binary files attached, they will need to be translated back by the application.
If IHS is configured with the 'NoTranslateRequestBodies'
CharsetOption
, then the body is passed verbatim to the application
without translation. The application will need to be able to interpret
the ASCII-encoded text parts of the multipart upload, and the file bytes
will need to be used verbatim.
Note: PHP on z/OS appears to work with this method.
CGI questions¶
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 sureSAFRunAs
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%%
</Doirectory>
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>
Other CGI/REXX tips¶
See dgw_migration_faq.html#CGI for various CGI and REXX tips related to migrating between DGW and APache.
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.
SAF Questions¶
No username and password prompt with Chrome/Edge ¶
When SAF authentication is configured (AuthBasicProvider SAF
), some browsers get an immediate HTTP 401 response instead of
prompting for a username and password.
Policies implemented in Microsoft Windows domains can disable support for HTTP Basic Authentication in Edge and Chrome..
IBM HTTP Server only uses HTTP Basic Authentication when configured authenticate using zOS userids and passwords.
You can verify the allowed authentication methods from within MS Edge by:
Visit
edge://policy
in the browserFilter all of the policies by typing AuthSchemes in the find bar in the upper right of the page
Under
AuthSchemes
policy, if it does not include "basic" in the list then Basic Auth is disabled. It may, for example, only list ntlm and negotiate as the allowable auth schemes.
These links regarding the AuthScheme policy might be useful:
https://docs.microsoft.com/en-us/deployedge/microsoft-edge-policies#http-authentication
https://docs.microsoft.com/en-us/deployedge/microsoft-edge-policies#authscheme
IHS does not currently support any other authentication protocols, other than TLS client authentication using certificates.
SAFAPPLID and certificate authentication¶
Using SAFAPPLID
in conjunction with TLS client certificate
authentication (SAFRunAs %%CERTIF%%
or SAFRunAs %%CERTIF_REQ%%
)
requires z/OS APAR OA54407.
IHS/Apache and MFA¶
If z/OS is configured to use unique passwords for each authentication, such as those related to Multi Factor Authentication (MFA) or other one-time password schemes, then these passwords cannot be used in the usual way with IHS over HTTP Basic Authentication.
HTTP Basic Authentication is stateless, and each HTTP request is accompanied by the username and password. Most HTTP client software re-sends the same credentials perpetually once a successful authentication has occurred. This is fundamentally in conflict with a password policy where a password cannot be used twice (due to a mix-in from a secure token, for example)
If such an OS configuration is enabled, and IHS has been configured to check system users and passwords via "AuthBasicProvider SAF", this automatic credential exchange will not succeed because the password is not static. In an interactive browser, this would result on a new prompt for each HTTP request (may be multiple per page view).
If using IBM MFA, "mod_saf_mfa" can be used to establish a session that keeps the user authenticated via a cookie, which is used instead of the HTTP Basic Authentication credentials (which will be stale when implicitly retransmitted by the client). This module is provided with IBM MFA, not as part of IBM HTTP Server.
SAF Expired Password Information¶
Questions and information regarding expired SAF passwords can be found on the SAF Expired Password Information page.
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¶
"The Apache Modules Book: Application Development with Apache" (Nick Kew, ISBN-13: 978-0132409674) is the best paperback resource.
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:
Apache 2.2 / IBM HTTP Server 7.0-8.5.5 development notes: http://publib.boulder.ibm.com/httpserv/manual70/developer/index.html
Apache 2.4 development notes (expanded from 2.2) http://httpd.apache.org/docs/2.4/developer/
Doxygen for Apache HTTP Server trunk: http://ci.apache.org/projects/httpd/trunk/doxygen/
Example modules¶
z/OS whitepaper describing writing a WLM classification Apache module: http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101858
z/OS whitepaper describing writing an SMF logging Apache module: http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101225
Migration redpaper(chapter 11)
mod_headers from apache.org: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/modules/metadata/mod_headers.c?view=markup
mod_rewrite from apache.org: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/modules/mappers/mod_rewrite.c?view=markup