IBM HTTP Server Questions and Answers

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

Table of Contents

common questions about rotatelogs.

common questions about building/using modules not provided with IHS (PHP, etc).

common questions about supported configurations.

common questions about SSL.

common questions about caching.

common questions about using IHS with the WAS plugin.

common questions about IBM HTTP Server v8.0.

misc. questions that don't fit anywhere else.

Is IBM HTTP Server release supported on platform?

For this IBM HTTP Server

release... Check here...

1.3.26.2 WebSphere Application Server V5.0.2 software requirements

1.3.28.1 WebSphere Application Server V5.1.1 software requirements

2.0.42.2 WebSphere Application Server V5.0.2 software requirements

2.0.47.1 WebSphere Application Server V5.1.1 software requirements

6.0.2 WebSphere Application Server V6.0.2 - detailed system

requirements

6.1 List of supported software for WebSphere Application Server

V6.1

7.0 List of supported software for WebSphere Application Server

V7.0

Can IBM HTTP Server release x be used with WebSphere release y, or with

plugin from WebSphere release y?

There are two issues of compatibility:

1. The WebSphere plug-in used in the web server must be compatible with the release of

WebSphere. A table is provided in the Web server plug-in policy technote.

2. The WebSphere plug-in must be compatible with the release of IBM HTTP Server. The

best way to accomplish this is by using the plug-in from the same WebSphere release as

IBM HTTP Server.

Refer to this documentation:

Web server plug-in policy for WebSphere Application Server

IBM HTTP Server Version 2.0.42, 1.3.26/HTTP Plug-in V5.1 and Version 2.0.47,

1.3.28/HTTP Plug-in V5.0 are not supported

As an example, if you need to support versions 5.1, 6.0, and 6.1 of the application server, you

should use IBM HTTP Server 6.1 and the WebSphere 6.1 plugin. (According to the web server

plug-in policy, the 6.1 plugin is the only version which supports all three application server

versions.

Can more than one version of the WebSphere plugin be loaded into IBM HTTP

Server?

No; only one WebSphere plugin can be configured and loaded in a single web server

configuration.

Is IBM HTTP Server installed with WebSphere?

WebSphere 5.0: IBM HTTP Server 1.3.26 is installed by default during the application

server installation

WebSphere 5.1: IBM HTTP Server 1.3.28 is installed by default during the application

server installation

WebSphere 6.0 and later: IBM HTTP Server is installed separately

What are the product lifecycle dates for IBM HTTP Server?

http://www-1.ibm.com/support/docview.wss?rs=177&uid=swg21200212

What release of Apache is IBM HTTP Server based on?

IBM HTTP

Server release

corresponding Apache release

that it was based on

corresponding WebSphere

Application Server release

1.3.12.x 1.3.12 3.5.x

1.3.19.x 1.3.20 4.0.x

1.3.26.x 1.3.26 5.0.x

1.3.28.x 1.3.28 5.1.x

2.0.42 2.0.42 5.0

2.0.42.1 2.0.44 Fix pack 5.0.1

2.0.42.2 2.0.46 Fix pack 5.0.2

2.0.42.2-PQ85834

and later 2.0.47 N/A

2.0.47 and later 2.0.47 5.1

6.0 2.0.47 6.0

6.1 2.0.47 6.1

7.0 2.2.8 7.0

Note: Fixes from later levels of Apache are also included. The Apache releases above should be

referred to for the purposes of third-party module compatibility as well as determining the base

level of Apache fixes included, before additional fixes were incorporated to resolve specific

customer problems.

Is a specific Apache fix in my level of IBM HTTP Server?

First, check the previous table which lists the level of Apache on which your level of IBM HTTP

Server is based.

If the fix was included in the same or earlier level of Apache, your level of IBM HTTP

Server contains the fix.

If the fix was included in a later level of Apache, refer to the next table.

IBM HTTP

Server

release

How to check

6.0 and

above

Look in install_root/readme/CHANGES_HTTPD for the Apache CHANGES text.

Apache CHANGES entries are copied there when a fix from a later level of

Apache is integrated.

If the Apache CHANGES entry is in CHANGES_HTTPD, then your level of IBM

HTTP Server has the fix.

1.3, 2.0

Check the readme.txt associated with the last cumulative e-fix which was applied.

Those have one-line extracts of the Apache CHANGES entries, so the text won't

match exactly.

What is the sequence of cumulative fix packages for IBM HTTP Server 2.0.42.2

and 2.0.47.1?

Cumulative fix packages for these releases use an APAR number for the fix level instead of a

higher version number. Support documentation often lists the first fix package which resolves a

defect; e.g., PK07831 or later. The table below, which provides the order of the fix packages, can

be used to determine if the defect is already corrected in your level of IBM HTTP Server. If a

later fix package has already been applied, the defect is already resolved.

APAR

number

Date of

release Notes

PQ85834 Q2 2004

2.0.42.x users must install this or PQ87339 in order to apply later

maintenance.

2.0.47 users should install the latest cumulative fix instead of

this.

PQ87339 Q2 2004 This is needed only for Solaris users with certain levels of GSKit

installed.

PQ90698 Q3 2004

PQ94086 Q3 2004

PQ94389 Q4 2004

PK01070 Q1 2005

PK07831 Q3 2005

PK13230 Q4 2005

PK25355 Q2 2006

PK29827 August 21,

2006 This is the final cumulative fix package for 2.0.42.2.

PK53584 October 3,

2007 2.0.47 only

PK65782 May 23, 2008 2.0.47 only

When a defect needs to be resolved, always apply the current recommended update instead of the

first fix package that contained the fix.

Recommended Updates for IBM HTTP Server

What is the sequence of cumulative fix packages for IBM HTTP Server 1.3.26.2

and 1.3.28.1?

Cumulative fix packages for these releases use an APAR number for the fix level instead of a

higher version number. Support documentation often lists the first fix package which resolves a

defect; e.g., PK05084 or later. The table below, which provides the order of the fix packages, can

be used to determine if the defect is already corrected in your level of IBM HTTP Server. If a

later fix package has already been applied, the defect is already resolved.

1.3.28.1

APAR number Date of release

PQ90262 August 31, 2004

PQ98444 January 28, 2005

PK05084 May 9, 2005

PK16139 January 16, 2006

PK27875 August 10, 2006

PK55141 November 16, 2007

PK63273 April 2008

1.3.26.2

APAR number Date of release

PQ87084 May 13, 2004

PQ90262 August 31, 2004

PK05084 May 9, 2005

PK16139 January 16, 2006

PK27875 August 10, 2006

When a defect needs to be resolved, always apply the current recommended update instead of the

first fix package that contained the fix.

Recommended Updates for IBM HTTP Server

What is the difference between WebSphere keep-alive settings and IHS keep-

alive settings?

IHS keepalive settings affect connections between IHS and the web client. WebSphere settings

affect connections between the WebSphere plug-in (running in IHS) and WebSphere. The

connections are independent and the settings are independent.

When does KeepAliveTimeout period start, relative to sending the response to

the previous request to the client?

Does it start counting when IHS sent a response back to the client, or does the timeout period

start when client ACKed the response?

It could be at either point, depending on the situation. IHS will start measuring the

KeepAliveTimeout as soon as it successfully queues all of the previous HTTP response to the

TCP layer. The operating system TCP layer sits between IHS and the network (client). IHS isn't

aware of some network flows such as ACK flows, but it is affected by ACK flows.

Requests handled by WebSphere plug-in aren't authenticated. WebSphere plug-

in doesn't send user id to WebSphere. Why not?

When enabling authentication in IHS, be aware that some configuration mechanisms apply only

to static files served by IHS but not to requests handled by the WebSphere plug-in.

Example 1:

<Directory /usr/HTTPServer/htdocs/en_US>

AuthType Basic

AuthName WebAccess

AuthUserFile /usr/HTTPServer/userids

Require valid-user

</Directory>

This type of configuration only affects files served by IHS, because the Directory keyword is

used. It does not affect WebSphere requests.

Similarly, rules in a .htaccess file can only control access to files served by IHS. They do not

apply to proxy or WebSphere requests.

Example 2:

<Location />

AuthType Basic

AuthName WebAccess

AuthUserFile /usr/HTTPServer/userids

Require valid-user

</Location>

This type of configuration affects any request for that location served by IHS, including

WebSphere requests, because the Location keyword is used. The WebSphere plug-in would then

pass the user id on to WebSphere for possible use by the application.

How can I log my WebSphere-based authentication in the IHS access log?

If WebSphere is configured to use HTTP Basic Authentication, IHS can only log the userid and

password together in base64 encoded form. This is accomplished by adding

%{Authorization}i to your LogFormat directive.

If WebSphere is configured to use form-based authentication, IHS cannot log a username. As an

exception, if the application code itself sets a cookie or HTTP header based on the logged in

userid, this cookie or header can be logged by IHS.

Example LogFormat additions for logging of incoming cookies or response headers (full

information is available in the documentation for mod_log_config).

%{cookiename}C (note that this cookie would only be available on requests that come

after the login, not during the login itself) %{headername}o

Why does the web browser present an authentication prompt twice when loading

the same page?

Watch out for redirections which make the web browser think it is contacting a different web

server. Here is an example of this type of problem, where the web browser has to authenticate

over non-SSL only to find out that it has been redirected to an SSL port. The browser assumes

that it is a different server and will prompt again.

<Location /protected.html>

RewriteEngine on

RewriteCond %{SERVER_PORT} =80

RewriteRule ^(.*) https://%{SERVER_NAME}%{REQUEST_URI}

Satisfy all

AuthUserFile /etc/webusers

AuthName Intranet

AuthType basic

Require valid-user

</Location>

In this type of situation, the redirection to SSL should be unauthenticated. Then, the

authentication should happen once the request has been issued to the SSL port. Here is a

solution:

# when request for the protected resource is received over

# non-SSL, redirect to SSL without authenticating

<VirtualHost *:80>

... (existing configuration for this vhost)

<Location /protected.html>

RewriteEngine on

RewriteRule ^(.*) https://%{SERVER_NAME}%{REQUEST_URI}

</Location>

</VirtualHost>

# when request for the protected resource is received over

# SSL, authenticate

<VirtualHost *:443>

... (existing configuration for this vhost)

<Location /protected.html>

Satisfy all

AuthUserFile /etc/webusers

AuthName Intranet

AuthType basic

Require valid-user

</Location>

</VirtualHost>

Can IBM HTTP Server modify Cookie or other request header fields?

mod_headers is provided and allows some limited request header modification. It can:

add an additional request header field

remove an existing request header field

append data to an existing request header field

No other manipulation is provided.

A custom plug-in module would have to be used if a different type of manipulation is required

within IBM HTTP Server, including removing individual cookies from a Cookie header field.

How can I log a response header field such as Set-Cookie?

This is with the LogFormat directive. The format string to use is "%{header-name}o", or

"%{Set-Cookie}o".

Simple example for this existing access log configuration:

LogFormat "%h %l %u %t \"%r\" %>s %b" common

CustomLog logs/access_log common

Add "%{Set-Cookie}o" to the format string on the LogFormat directive, resulting in

LogFormat "%h %l %u %t \"%r\" %>s %b %{Set-Cookie}o" common

CustomLog logs/access_log common

(There may be a number of different LogFormat directives... the one of interest is the one whose

format name (e.g., "common") is actually referenced on your CustomLog directive.)

Do I have to start IBM HTTP Server as root?

Port access on Unix and Linux

Applications running as users other than root are normally prevented from binding to (listening

on) low-numbered ports on Unix and Linux systems. Low-numbered ports are those ports below

1024. The standard ports for most popular Internet protocols, including http and https, are low-

numbered ports.

On Solaris 10, IBM HTTP Server must be started as root to bind to a low-numbered port unless

the user which starts the web server has been granted the net_privaddr privilege.

On AIX, HP-UX, and Linux, and other versions of Solaris, IBM HTTP Server must be started as

root to bind to a low-numbered port. A possible work-around is to utilize a firewall to redirect

requests to port 80 to a high port. The web server will listen on the high-numbered port, thus

avoiding the root requirement.

Port access on z/OS

z/OS can restrict low ports to UID(0) users or authorized programs, allow reservation of

particular ports to specified users or jobs, or allow unrestricted access. We recommend that IBM

HTTP Server be started as a non-UID(0) user and z/OS configuration used to allow access to the

required ports. Refer to Performing required z/OS system configurations in the IBM HTTP

Server InfoCenter for more information.

Log and configuration file access

The user id starting the web server must have read access to the configuration files and write

access to the directory containing log files and other run-time files. This may require starting as

root, or changing the ownership or permission of existing log files, depending on the

configuration.

What happens if I stop IBM HTTP Server using SIGKILL?

Stopping the server by sending SIGTERM to the parent process

no new connections will be accepted, starting almost immediately

existing requests will have a short time to finish and log their results

for most child processes:

o the active request will finish normally

o the active request will be logged

for child processes that don't finish their request in a reasonable amount of time:

o the request will be abruptly terminated

o the active request won't be logged

Stopping the server by sending SIGKILL to all of the processes

no new connections will be accepted, starting almost immediately

all active requests will be abruptly terminated

no active requests will be logged

the pid file won't be removed, so a warning will be logged when the server is started

again

no permanent problems expected

Note: Third-party modules could require manual intervention before restart if they have

resources that they must release at termination.

Can IBM HTTP Server serve files larger than 2GB?

IBM HTTP Server

version Platform

Can files larger than

2GB be served?

1.3.x all platforms No

2.0.x Windows Yes

2.0.x AIX, Linux, HP-UX, Solaris No

6.0.x, 6.1.x Windows, HP-UX/ia64, Solaris/x64, z/OS

(only provided for 6.1.x) Yes

6.0.x, 6.1.x AIX, Linux, HP-UX/PA-RISC, Solaris/SPARC No

7.0.x All Platforms yes

Supporting files larger than 2GB is theoretically possible on other version/platform

combinations, but it breaks binary compatibility with plug-in modules, so the change cannot be

made. 64-bit versions of IBM HTTP Server support files larger than 2GB.

Can IBM HTTP Server write to log files over 2GB?

Web server writing directly to log files

IBM HTTP Server 2.0.42.x and later

Windows

IBM HTTP Server 2.0.42.x and later on Windows can write to log files > 2GB.

Unix and Linux

This is supported, except for rotatelogs, with cumulative i-fix PK01070 or later for 2.0.42.2 and

2.0.47.1, and with IHS 6.0.0.2 and later.

IHS 7.0 and later adds large file support to rotatelogs on all platforms

This means that IHS 7.0 and later does not impose any file size limits beyond what is imposed by

the operating system, file system, and any non-IHS configuration settings such as ulimit. Those

limits apply to IHS as they do any other application.

IBM HTTP Server 1.3.x

Unix and Linux

This will not be supported. The work-around is to configure rotatelogs or another piped log

program to switch log files before they reach 2GB.

# Original access log definition: CustomLog /usr/HTTPServer/logs/access_log

common

# This will create files called "access.timestamp", such as

access.1136764800,

# and rotate every 24 hours (86400 seconds).

CustomLog "|/usr/HTTPServer/bin/rotatelogs /usr/HTTPServer/logs/access 86400"

common

cronolog is a fully featured piped log program from a third party which has many more features

for managing log files.

rotatelogs

Refer to rotatelogs and large files

Third-party piped logger programs

Consult the vendor. Piped logger programs which do not use IBM HTTP Server support libraries

may or may not support large log files, independent of whether or not the web server can.

Are there tools to analyze IBM HTTP Server access logs?

IHS doesn't include any such tools, but there are numerous third-party solutions for log file

analysis. Search for "Apache log file analyzer" using your favorite Internet search engine.

We are aware that some IHS customers are successfully using Webalizer, a freely-distributed

application available from http://www.mrunix.net/webalizer/.

I don't want anybody to know what server I'm running. What can I do?

In IHS 7.0 and later, the directive AddServerHeader can suppress the default Server: HTTP

response header.

In releases prior to 7.0, you can't prevent the product name from being sent to clients in the

Server header field, but you can minimize it to

Server: IBM_HTTP_SERVER

by coding

ServerTokens Prod

in the web server configuration file.

See also the ServerSignature directive for controlling whether information about the server is

included in certain error messages.

Even without the standard Server header field in the response:

any attacker would simply try to exploit vulnerabilities that have affected the software

used by the majority of the servers on the Internet (Apache and IIS), to see if they are

effective

it is expected that the the response of the server to various test requests could be analyzed

to determine which web server software is in use, at least to the point of narrowing it

down to some web server based on Apache.

IHS 2.0.42.x prior to PQ85834 had a defect which allowed CGIs and plug-ins to override the

value of the Server header field.

How can I start IHS during AIX startup?

Here are AIX inittab entries to start IHS 1.3 or IHS 2.0:

: ihshttpd:2:wait:/usr/HTTPServer/bin/httpd > /dev/console 2>&1

ihshttpd:2:wait:/usr/IBMIHS/bin/apachectl start > /dev/console 2>&1

The first entry is commented out (leading ":") and starts IHS 1.3. The second entry is active and

starts IHS 2. For either 1.3 or 2.0, replace the path to httpd or apachectl with the chosen

installation directory. The "apachectl start" command is a valid way to start IHS 1.3 or IHS 2.0.

The "httpd" command is only valid for IHS 1.3.

Why are httpd processes still active when apachectl stop completes?

apachectl stop sends a signal to the parent process, and then exits. As soon as the parent

process receives the signal, it starts terminating the child processes. In many cases, by the time

you can look for child processes after the completion of apachectl stop they will have already

exited. Some of the following are reasons why they will linger for some time:

high system load (perhaps caused by many httpd child processes having to wake up and

exit

active requests being handled by one or more httpd child processes

If a shutdown problem is suspected with IBM HTTP Server 2.0 or above, make sure that you are

using one of the following software levels:

6.1 or later

GA

6.0.x

6.0.0.2 or later

2.0.42.x, 2.0.47.x

PK01070 or later

Why do I see more httpd processes than my configured ServerLimit/MaxClients?

An additional process is created for mod_cgid, mod_mpmstats, and mod_ibm_ssl (SSL

Session Cache daemon, sidd), if enabled.

After a graceful restart, the children that are waiting to complete their work and exit are

not counted against ServerLimit/MaxClients.

If a child process has begun exiting due to a non-zero MaxRequestsPerChild, it is not

counted against ServerLimit/MaxClients and may be replaced before it exits.

Setting MaxRequestsPerChild to zero prevents this occurence.

There is no impact to server operation due to processes exiting in this way.

If a child process has begun exiting due to MaxSpareThreads being reached it is not

counted against ServerLimit/MaxClients and may be replaced before it exits.

Setting MaxSpareThreads equal to MaxClients prevents this occurence.

There is no impact to server operation due to processes exiting in this way.

How can I save mod_status page at intervals?

When customers can't get to mod_status page from a browser, or when there is some load

balancer in front that makes it difficult to get mod_status from a particular server, or when they

want to have mod_status pages saved automatically, they can run something like this script on

the web server system. It requires that perl and wget be installed. Perl usually comes with the

operating system, and wget is an open source program to save a web page in a file.

grabstatus.pl:

#!/usr/bin/perl -w

use strict;

my $STATUS_URL = "http://127.0.0.1/server-status/";

my $SLEEP_INTERVAL = 60; # seconds

while (1) {

my $timestamp = time();

system("wget -O serverstatus.$timestamp $STATUS_URL");

sleep($SLEEP_INTERVAL);

}

If all you want is to know how many threads are busy and in what state, see mod_mpmstats.

How can I configure IBM HTTP Server to serve filename.html when the browser

requests filename?

The mod_negotiation MultiViews feature can automatically select a file with appropriate

extension when the browser does not provide a file extension.

Configuration:

LoadModule negotiation_module modules/mod_negotiation.so

...

<Directory /prefix-for-multiviews/>

Options +MultiViews

</Directory>

How can I disable the HTTP TRACE method?

Refer to this document.

How can I downgrade the server response to HTTP/1.0 for certain requests?

<Location /some/url>

SetEnv downgrade-1.0 1

</Location>

How can I rotate (switch) log files?

Piped log programs

(all platforms)

This uses rotatelogs or a third-party replacement such as cronolog. IBM HTTP Server sends

log records to an external program, referred to as a piped logger, which is responsible for

switching to a new log file when certain criteria are met.

Refer to the Piped Logs section of the documentation for more information. See also common

questions about rotatelogs.

Renaming log files and restarting

(Linux and Unix platforms only)

This method renames log files while the web server is running and still writing to the old files

then restarts the web server to open files under the normal name again.

Refer to the Log Rotation section of the documentation for more information.

Other methods may be equally effective, but if you are having troubles with a different method

or a script provided by a third party, please use the documented methods before contacting IBM

support for help resolving the problem.

I have the LockFile directive specified, but I can't see the lock file in the

filesystem. Why not?

Short answer: This is working as designed; the lock file doesn't show up in directory listing

except for a brief moment during IHS initialization.

Long answer: When IHS initializes an fcntl accept mutex during startup, it opens/creates the lock

file, retains the file descriptor, but "unlinks" the lock file so that it is removed from the system

just in case IHS exits abnormally and is unable to run its normal cleanup code. This procedure is

a standard technique to avoid leaving dangling files after process termination, but it results in the

file being invisible to the ls command. This means that other applications can't mess with the

file, accidentally or not, since they can never open the same lock file used by IHS.

If you really want to see the lock file working, you can pick an IHS child process and run truss

against it. ("truss -p PID") At the end of processing one client, a call like this will appear:

kfcntl(19, F_SETLKW, 0x2000AEE0) (sleeping...)

So file descriptor 19 is the lock file. (This actual number will almost certainly be different in

your environment.) lsof when run against an httpd process ("lsof -p PID") would display that file

descriptor as follows:

httpd 23104 root 19w VREG 10,8 0 2261678 /home (/dev/hd1)

The size (7th column) should be 0 and the filesystem (two last columns) should match the

filesystem used by your LockFile directive.

What are these requests for file favicon.ico in my logs?

A customer sees something like this in his access log:

127.0.0.1 - - [08/Mar/2005:12:51:08 -0500] "GET /favicon.ico HTTP/1.1" 404

304

Requests for favicon.ico are unavoidable. Internet Explorer and some other browsers will blindly

request favicon.ico in case the web site has that file. You may have noticed that on some web

sites, there is a cute icon in the URL box on your web browser; favicon.ico from that web site is

the cute icon. Most web sides don't have that file, so there will be a 404 in the web site's access

log and the browser will use the default icon.

The customer is not in control of whether or not the browser issues that request. They can have

their site designer provide a favicon.ico file or they can ignore the entries in the access log. We

do not recommend that they filter out the entries from the access log, because if there is ever a

question of what requests are hitting the server, then the access log wouldn't be able to answer

that question.

Why do I get 403 Forbidden trying to view server-status reports?

There are two common problems:

1. The server status page is protected, and the client doesn't meet the authorization criteria.

For example, there may be an allow from directive for <Location /server-status>

which is not working.

2. The configured DocumentRoot directory isn't readable by the web server user id (e.g.,

nobody). If this is the cause, the error log will have a message like the following: 3. [Sat Mar 12 06:36:21 2005] [error] [client 127.0.0.1] (13)Permission

denied: access to /server-status/ denied

How does IBM HTTP Server determine when a child process should end? Does it

have a timeout?

There is no timeout. Beyond normal web server termination or restart, here are the situations

where a child process will exit:

All releases of IBM HTTP Server on Windows

A child process will only end if MaxRequestsPerChild is set to non-zero, and the process has

handled at least that many client connections.

IBM HTTP Server 1.3.x on Linux and Unix

If MaxRequestsPerChild is set to non-zero, a child process will exit once it has handled that

many client connections.

While there are more idle processes than the value of MaxSpareServers, one child process will

exit per second.*

*On AIX, if AcceptMutex is set to pthread, idle child process termination often does not work.

Code AcceptMutex fcntl to work around this problem.

IBM HTTP Server 2.0 and higher on Linux and Unix

If MaxRequestsPerChild is set to non-zero, a child process will exit once it has handled that

many client connections.

While there are more idle threads than the value of MaxSpareThreads, one child process will

exit per second.

Linux and Unix: How do I keep IHS from terminating child processes prior to

web server shutdown?

Occasionally, problems with IHS or third-party modules can be attributed to issues which occur

when IHS child processes terminate. In this case, it is helpful to disable child process termination

until the problem can be fully resolved.

IHS 2.0 and above

Set MaxRequestsPerChild to 0 and set MaxSpareThreads to the same value as MaxClients.

IHS 1.3

Set MaxRequestsPerChild to 0 and set MaxSpareServers to the same value as MaxClients.

How do you gracefully shut down IHS?

In IHS 7.0 and later on Unix, apachectl -k graceful-stop will stop listening for new

requests but allow active requests to finish, waiting forever by default, or until

GracefulShutdownTimeout seconds have elapsed.

Otherwise, there is no mechanism to shut down the web server yet allow active requests to

gracefully finish. Active requests must finish within about 7 seconds, or they may be forcefully

terminated when the child process is killed.

Is IBM HTTP Server 32-bit or 64-bit? Will 32-bit IBM HTTP Server run on my

64-bit OS?

IBM HTTP Server is a 64-bit application on HP-UX/ia64 and Solaris/x64. IBM HTTP Server is

a 32-bit* application on other platforms, regardless of which WebSphere Application Server

Supplement CD it was installed from. Many platforms, including AIX, HP-UX, Solaris, and 64-

bit Linux, provide support for both 32-bit and 64-bit applications, so a 32-bit IBM HTTP Server

is able to function properly even though other applications on the system may be 64-bit.

Customers with certain 64-bit Linux platforms must ensure that they have installed both 32-bit

and 64-bit versions of the RPM prerequisites enumerated in the WebSphere Application Server

infocenter.

Prerequisites for IBM HTTP Server 6.1

How do I determine which fixpack to download (32-bit, 64-bit?)

For many operating systems, a 32-bit IHS is bundled with both the 32-bit and 64-bit WebSphere

Application Server. This 32-bit IHS installation is provided on both the "32-bit Supplement" CD

and the "64-bit Supplement" CD.

When selecting the IHS fixpack, you must select the fixpack that matches the architecture of the

supplement CD you installed from.

To determine which supplement CD was used for the initial install, consult

<ihsroot>/uninstal/version.txt and look for the "Architecture" label. This is the architecture of the

installer, not IHS itself and reflects the proper Supplement CD or fixpack architecture.

Determining which Supplements CD was used for the IHS installation

Architecture name in <ihsroot>/uninstal/version.txt where IHS is distributed as 32-bit code on

32-bit and 64-bit Supplement media:

Platform 32-bit string in version.txt 64-bit string in version.txt

Windows ia32 x86_64

Linux ia32 x86_64

z/Linux s390 s390_64

p/Linux ppc32 ppc64

AIX ppc32 ppc64

Solaris sparc sparc64

How do I determine which WASSDK fixpack to download (32-bit, 64-bit?)

For many operating systems, a 32-bit IHS is bundled with both the 32-bit and 64-bit WebSphere

Application Server. This 32-bit IHS installation is provided on both the "32-bit Supplement" CD

and the "64-bit Supplement" CD.

When selecting a WASSDK fixpack for IHS, you must select a fixpack that matches the

architecture of the Java originally installed.

To determine which architecture of java was bundled with your level of IHS, run

<ihsroot>/java/jre/bin/java -version to determine if it is 32-bit or 64-bit. If the output of

the command contains any of s390x, amd64, or ppc64 then the 64-bit WASSDK package

should be used.

With IHS 7.0, the java architecture usually matches the IHS architecture (see apachectl -V|grep

Architecture, z/Linux installed from 64-bit supplements is an exception).

With IHS 6.1, the java architecture usually matches the architecture of the installation source

(64-bit supplements or 32-bit supplements ).

How do I determine which IHS IFIX to download (32-bit, 64-bit?)

In IHS V7 and earlier, one ifix is created for each IHS installed architecture (apachectl

-V|grep Architecture) and the OS operating system is not a factor.

For example, the only AIX ifix available is 7.0.0.19-WS-WASIHS-AixPPC32-

IFPM46234.pak since IHS is always 32-bit in these releases on AIX.

In IHS V8 and later, ifixes may come in two forms:

o A single ifix valid for all installations of IHS such as '8.0.0.0-WS-WASIHS-

MultiOS-IFPM46234.zip'.

o An ifix generated for a particular OS and architecture that can service any IHS

installable on that OS and architecture. For example, 8.0.0.0-WS-WASIHS-

SolarisSparc-IFPM46234.zip and 8.0.0.0-WS-WASIHS-SolarisSparc64-

IFPM46234.zip.

The architecture selected at IHS installation time is not a factor in selecting which

download.

mod_rewrite: a character in my new URL is being escaped as %nn. How can I

avoid that?

This answer has been moved here.

mod_rewrite: My rules are ignored. Nothing is written to the rewrite log.

This answer has been moved here.

How can I avoid writing access log records for images?

Set a variable called image-request when the request is for certain filenames. Then, update the

CustomLog directive to indicate that requests should not be logged when the image-request

variable is set.

SetEnvIf Request_URI \.gif$ image-request

SetEnvIf Request_URI \.jpg$ image-request

# add another SetEnvIf directive for other file extensions to be skipped

CustomLog logs/access_log common env=!image-request

The mod_log_config documentation has an example showing how to put image requests in one

access log and non-image requests in another access log.

My request failed with status nnn. How do I find out why?

Generally speaking, requests can fail in one of the following functional areas:

1. IBM HTTP Server core features (e.g., access was denied, file was not found, etc.)

2. WebSphere plug-in (e.g., communication error occurred trying to contact the application

server)

3. WebSphere Application Server (e.g., customer application returned a failure due to

database problem)

4. third-party module loaded into IBM HTTP Server failed the request (e.g., couldn't contact

LDAP server)

Finding the root cause requires finding which functional area failed the request.

IBM HTTP Server 2.0 and above

These versions have a feature which allows the failing component to be logged:

6.1 and later

GA

6.0.x

6.0.2 and later

2.0.42.x, 2.0.47.x

PK07831 and later

Steps to find the failing component:

1. Load mod_status: 2. LoadModule status_module modules/mod_status.so

3. Enable extended status: 4. ExtendedStatus On

5. Add the RH variable to the information logged in access log: 6. LogFormat "%h %l %u %t \"%r\" %>s %b %{RH}e" common

7. Recreate the request and check the access log for the failing component: 8. 127.0.0.1 - - [23/Jan/2006:08:09:51 -0500] "GET /foo.html HTTP/1.1" 404

317 (core.c/404/handler)

9. 127.0.0.1 - - [23/Jan/2006:08:10:45 -0500] "GET /testcount.jsp HTTP/1.1" 500 644 (mod_was_ap20_http.c/500/handler)

10. 127.0.0.1 - - [23/Jan/2006:08:11:19 -0500] "GET /cgi-bin/printenv

HTTP/1.1" 404 322 (mod_cgid.c/404/handler)

If the module name is... This component failed to handle the request...

core.c internal web server handling of static files

mod_was_ap20_http.c WebSphere plug-in

mod_cgid.c web server support for CGI scripts

mod_sm.c SiteMinder

11. Check the log files of the failing component for more information.

Other levels of IBM HTTP Server

This can usually be determined by checking the log files maintained by the various components.

1. Check the IBM HTTP Server access log to find the entry for the failing request. Example: 2. 127.0.0.1 - - [08/Apr/2005:06:40:08 -0400] "GET /cgi-bin/test-cgi" 500

658 -

3. Check the IBM HTTP Server error log for messages at the same time. Example: 4. [Fri Apr 08 06:40:08 2005] [error] (13)Permission denied: exec of

'test-cgi' failed

5. [Fri Apr 08 06:40:08 2005] [error] [client 127.0.0.1] Premature end of script headers: test-cgi

In this case, an IBM HTTP Server feature failed, and the error log contains more

information.

If no entries were written to the error log at the time of the failure, the problem must have

occurred in an area other than IBM HTTP Server. Proceed with the following checks.

6. Check the WebSphere plug-in trace file for messages at the same time. If the WebSphere

plug-in encountered a processing error (e.g., could not connect to the application server),

it will be reported to the trace file.

If no entries were written to the plug-in trace file, the problem must have occurred in a

different area. Proceed with the following checks.

7. Check WebSphere logs for error messages at the same time. Alternately, turn on detailed

WebSphere plug-in trace and reproduce the problem. With a detailed plug-in trace, the

HTTP status code returned by WebSphere will be traced, and you can see if WebSphere

is the source of the failure (e.g., the functional area which returned status code 500).

If WebSphere didn't process the request, or WebSphere returned a good response code

for the request (e.g., 200 or 302), the problem must have occurred in a different area.

Proceed with the following checks.

8. Check logs of third-party modules (modules from non-IBM source loaded into IBM

HTTP Server) for error messages reported at the same time. Contact third-party module

vendor for explanation.

9. If all else fails, and the platform is Solaris:

It is likely that truss can be used to show which module is failing the request. If at all

practical, re-configure IHS temporarily to use a single child process for processing client

requests. Here is an example with IBM HTTP Server 2.0 or above:

<IfModule worker.c>

ThreadLimit 256

ServerLimit 1

StartServers 1

MaxClients 256

MinSpareThreads 1

MaxSpareThreads 256

ThreadsPerChild 256

MaxRequestsPerChild 0

</IfModule>

Then start IHS as normal, and find the process id of the two IHS child processes via ps.

# cat /opt/IBMIHS/logs/httpd.pid

99999 <- example value

# ps -ef | grep 99999

webuser 10001 99999 .....

webuser 10002 99999 .....

root 99999 1 .....

These two processes with 99999 for the parent are the two IHS child processes. One will

be mod_cgid daemon and one will actually serve requests. We'll just trace both of them

to avoid picking the wrong child process.

# truss -o /tmp/tracefile -u :: -u a.out,\* -p 10001 10002

(Replace 10001 and 10002 with the actual pids of the IHS child

processes.)

Next, reproduce the problem.

Next, interrupt the truss process (<Ctrl>C). The tracing via truss will slow down the web

server significantly and will generate a large amount of output, so reproduce the problem

and stop the tracing as quickly as possible.

Here is the type of information we would expect to find. In this example, I have

configured mod_access to return 403 (access denied) for a certain request:

$ grep 403 /tmp/outfile

11729/27@27: <- mod_access:check_dir_access() =

403

11729/27@27: <- ap_run_access_checker() = 403

11729/27@27: <- decl_die() = 403

11729/27@27: <- ap_process_request_internal() = 403

11729/27@27: <- ap_die() = 403

The first place where 403 showed up (i.e., the module which set 403) was mod_access.

For your situation, search for the bad status code (e.g., 500) in /tmp/outfile and see which

module (mod_sm, mod_access, whatever) set the 500. Send in the trace file for us to

analyze if it isn't clear which module set 500, or if an IBM-provided module set 500. If

the status was set by a third-party module, contact the vendor for diagnosis.

How do I determine which vhost is selected when the request is received?

Add an indication of the selected vhost to your access log format, and then retry the testcase.

Configuration changes:

1. Add SetEnv vhostname MAIN to the main scope of httpd.conf.

2. Add SetEnv vhostname UNIQUE-NAME to each VirtualHost container. Make sure

UNIQUE-NAME is unique for each virtual host.

3. Add the vhostname (%{vhostname}e) to the access log format.

4. Add the target IP address (%A) to the access log format.

5. Add the value of the ServerName associated with the virtual host which served the

request (%v) to the access log format.

Example log format with these changes made:

LogFormat "%h %l %u %t \"%r\" %>s %b %A %v %{vhostname}e" common

Example setting of vhostname:

...

SetEnv vhostname MAIN

...

<VirtualHost something>

...

SetEnv vhostname vhost8443

</VirtualHost>

<VirtualHost something>

...

SetEnv vhostname vhost443

</VirtualHost>

Now restart the web server and try the request again. Check the access log for the destination IP

address and the vhost name:

127.0.0.1 - - [26/Apr/2005:07:10:36 -0400] "GET /file.html HTTP/1.1" 200 1647

9.42.114.51 myhost.example.com MAIN

| | |

IP address connected to by client-

--+ | |

ServerName for selected vhost-----

--------------------+ |

label for selected vhost----------

---------------------------------+

Check if the vhost name logged (e.g., "MAIN") is the expected one. If an unexpected vhost name

is logged, that would explain why your vhost-specific configuration is not applied to the

processing of the request. The IP address and ServerName value which were logged can provide

further hints.

Does IHS support byte range requests, and byte serving of PDF files?

Yes, IHS can satisfy byte range requests for static content but cannot do so for content delivered

via the WebSphere Plugin.

What are the limitations of the MaxClients directive on Unix and Linux systems?

The Apache 1.3 documentation says "To configure more than 256 clients, you must edit the

HARD_SERVER_LIMIT entry in httpd.h and recompile." This statement does not apply to IBM

HTTP Server.

IBM HTTP Server 1.3.x has raised the built-in limit from 256 clients to 4096 clients.

IBM HTTP Server 2.0 and above is essentially limited by the amount of memory. You can

configure up to 20,000 threads per child process, and configure up to 20,000 child processes, for

an overall limit of 400,000,000. However, the address space of an individual child process may

be exceeded with that many threads, and system memory may be exceeded with that many child

processes.

What are the limitations of the ThreadLimit directive on Windows systems?

IBM HTTP Server 1.3.x on Windows has a built-in limit of 4096 threads.

IBM HTTP Server 2.0 and above on Windows has a built-in limit of 15,000 threads, but practical

limits around 2500 or 5000 on 64-bit and 32-bit operating systems, respectively..

How can I recompile IBM HTTP Server?

A customer cannot recompile or relink IBM HTTP Server.

If instructions for a third-party module mention recompiling the web server for integration of the

third-party module, consult with the provider of that third-party module to find out how to load it

into the web server dynamically (using the LoadModule directive).

If the customer requires that they be able to recompile or relink the web server, we recommend

using the Apache web server, for which a plug-in is provided by WebSphere. The Apache web

server is not supported by IBM, but the customer will be able to use it with WebSphere

Application Server using the WebSphere plug-in.

How can I use suexec with IBM HTTP Server?

example suexec implementation

Why does an extra slash appear in URLs sent to the origin (backend) server in

reverse proxy?

For example, why does the origin server receive "http://www.example.com//index.html" as the

URL?

The ProxyPass and ProxyPassReverse directives should have trailing slashes for the path and url

arguments.

Bad example:

ProxyPass /mirror/foo http://foo.com

ProxyPassReverse /mirror/foo http://foo.com

Good example:

ProxyPass /mirror/foo/ http://foo.com/

ProxyPassReverse /mirror/foo/ http://foo.com/

Please explain the %D and %T access log formats.

What operations do these log formats measure?

These formats show the time to serve the request, from the time that the web server reads the

first line of the request from the client to the time the web server processes the %D or %T format

string while logging the results of the request. This logging (and resolution of %D/%T) occurs

after WebSphere Application Server has written the entire response to the WebSphere Plugin,

and the entire* response has been queued to the TCP layer by IHS (*:see Special considerations

below).

%D formats the time in microseconds and %T formats the time in seconds. (%D is not available

with IBM HTTP Server 1.3.)

Special considerations:

The time does not cover the interval where the new connection is queued by the system

TCP layer, before the web server begins processing the connection. Ordinarily this

interval is very brief, and the web server will start processing the connection as soon as

the 3-way TCP handshake completes. But if no available web server thread is available at

the time the 3-way TCP handshake completes, the uncounted time where the request is

not being processed could be considerable.

The time does not cover the SSL handshake, which occurs before the web server reads

the first line of the request.

If there is a subsequent request sent on the same TCP connection before the entire

response has been sent (pipelining), the time may not cover the end of the last buffer of

the response. This is an optimization which results in higher network utilization, but the

logging of a request to access log, and thus the calculation of response time, can occur

prior to the last byte of the response being transmitted.

Even when there is no subsequent request, the response time only covers the interval up

through when all response bytes have been passed to the TCP layer on the web server

system. There may be significant delays before the web client has read the entire

response from the TCP layer on the client system.

Differences in response time handling between IBM HTTP Server 1.3 and later releases

IBM HTTP Server 1.3 handles request start and stop times internally in seconds. The

system rounds the time to an integral number of seconds when the start and stop times are

retrieved. Thus, two significant rounding operations occur before the time is logged,

resulting in an inaccurate response time being logged for relatively small response times.

IBM HTTP Server 2.0 and later releases handle request start and stop times internally in

microseconds. Thus, the rounding operations occur at the microsecond level, resulting in

a far more accurate value for %T with these releases. Only one significant rounding

operation occurs.

Because IBM HTTP Server 2.0 and later releases handle times in microseconds, this level

of granularity has been externalized with the %D log format. No significant rounding

operations are performed. (That level of granularity is not available with IBM HTTP

Server 1.3.)

An example with two web servers connected by mod_proxy

The web browser connects to web server 1, which proxies the request to web server 2, which

serves the request using any mechanism (WebSphere, CGI, static file, etc.).

1. The web browser, directed by the user, starts connecting to web server 1.

The connection is queued in the TCP layer of the web server 1 system until the

handshake completes and a web server 1 thread is available.

2. A thread in web server 1 accepts the connection and reads the first line of the request.

At this point, web server 1 starts counting response time.

3. Web server 1 reads the rest of the request, determines that the request should be proxied

to web server 2, and starts connecting to web server 2.

The connection is queued in the TCP layer of the web server 2 system until the

handshake completes and a web server 2 thread is available.

4. A thread in web server 2 accepts the connection and reads the first line of the request.

At this point, web server 2 starts counting response time.

5. Web server 2 performs the processing required to serve the request, such as forwarding

the request to the WebSphere application server, running a CGI script, or serving a static

page on the filesystem.

6. Web server 2 generates and transfers all of the response to the TCP layer on web server 2,

to be sent to web server 1.

At this point, web server 2 stops counting response time. The access log record is written

with the calculated response time.

Because the client of web server 2 is an IBM HTTP Server proxy, we know that no

request pipelining will occur, so web server 2's response time ends when it has

transferred the last byte of the response to the TCP layer. Web server 1 may not have read

all of the response for some time, however.

7. As web server 1 reads response data, it transfers the data to the TCP layer for sending to

the client.

8. Web server 1 finally reads the last byte of the response from web server 2. Once the

entire response has been read from web server 2:

o If, prior to transferring the last piece of the response to the TCP layer on the web

server 1 system, web server 1 determines that a subsequent request has already

been received from the client, at this point web server 1 stops counting response

time; the access log record is written with the calculated response time. The final

byte of this response will be passed to the TCP layer once the first part of the

subsequent response is passed to the TCP layer.

o If no subsequent request has been received from the client, the last byte of the

response will be transferred to the TCP layer immediately. At this point web

server 1 stops counting response time. The access log record is written with the

calculated response time.

9. Finally, the client reads the last byte of the response from the TCP layer on its system.

But the web server has already written its access log record (and thus calculated the

response time).

What are common issues with custom HTTP (web) client software?

It is remarkably easy to implement a web client which can connect to web servers and send

requests and read responses. But the simplest client may not work in all situations. Here are some

problems we have seen:

response delimiters

There are several ways that the web server can tell the client when they've read the entire

response:

end-of-connection

The end of TCP connection signifies the end of the response. This is signified by the lack

of Content-Length: nnnn or Transfer-Encoding: chunked in the response header.

Any client must be able to handle this.

Content-Length

This is signified by the presence of Content-Length with a byte count in the response

header. The client should read that many bytes from the TCP connection.

Any client must be able to handle this.

chunked transfer encoding

This is signified by the presence of Transfer-Encoding: chunked in the response

header.

A client which cannot handle this form of response must specify HTTP level 1.0 in the

request.

no handling dropped connections for requests sent in keepalive state

(If you don't know what this means, or your client does not handle this properly, ensure that the

header field Connection: close is written in the request header.)

Keepalive state is a term for the state of the connection after a response has been received by the

client. If the connection remains open after a response by consent of the client and server, the

client has the opportunity to reuse the same connection for a subsequent request. Meanwhile, the

server can drop the connection. So when the client sees a dropped connection instead of a

response, it needs to start a new connection and issue the response again. Note: This is not

appropriate when the client sees some part of the response.

If the client does not handle this, it must specify Connection: close in the request header.

lack of User-Agent header field in the request header

User-Agent identifies the type of software and level. It is always helpful for identifying the

software which generated the request. It is sometimes helpful for tailoring the web server to act

differently for a type of client software, or level. (Consider the BrowserMatch directive.)

sending TCP FIN packet before reading the response

The in-kernel cache handler for IBM HTTP Server on Windows does not support clients which

send a FIN packet before the response is sent. Such clients must be modified to interoperate with

this IBM HTTP Server feature.

How can I run more than one instance of IBM HTTP Server from the same

installation directory?

This question covers distributed platforms only. On the z/OS platform, the install_ihs

command creates a separate directory for each instance without creating another copy of the

product.

Operational requirements

These are the minimal requirements that allow multiple web server instances to run from the

same installation directory.

configuration files

A different main configuration file (normally httpd.conf) is needed for each instance. Common

directives can be stored in common files and included from the different main configuration

files.

ports

A combination of listen port and listen IP address cannot be used by more than one instance.

For IBM HTTP Server 2.0 or higher, check the Listen directives. For IBM HTTP Server 1.3,

check the Port and Listen directives.

log and other special files

Anything normally stored in the install_root/logs directory cannot be shared between

instances. So each instance must have unique values for these directives:

1. PidFile (applicable to all configurations)

2. ScriptSock (applicable to non-Windows configurations of IBM HTTP Server 2.0, 6.0,

and 6.1 with mod_cgid enabled, n/a to IHS 7.0 or later. )

3. ErrorLog (applicable to all configurations)

4. CustomLog or TransferLog (applicable to all configurations)

5. SSLCachePortFilename (applicable to all non-Windows configurations with SSL

enabled)

6. SSLCachePath (applicable when ALL of the conditions below are true)

o Platform is not Windows.

o SSL is enabled.

o SSLCacheDisable directive is not configured.

o bin/apachectl has been modified to specify a different -d flag, or

bin/apachectl is launched with an explicit -d flag.

o The directory specified by the -d flag does not contain the file bin/sidd.

AFPA

Only one IHS instance can have AFPA enabled

starting and stopping

With IBM HTTP Server 2.0 or above on Unix and Linux, use these commands to start and

stop:

# cd /install_dir

# bin/apachectl -k start -f conf/this_instance.conf

# bin/apachectl -k stop -f conf/this_instance.conf

With IBM HTTP Server 2.0 or above on Windows , use these commands to setup a new

instance:

cd \install_dir

bin\Apache.exe -f conf/this_instance.conf -k install -n IHS6-this_instance

With IBM HTTP Server 2.0 or above on Windows , choose one of the these commands to start

and stop:

net start IHS6-this_instance

cd \install_dir

bin\Apache.exe -k install -n IHS6-this_instance

Find IHS6-this_instance in the Microsoft Windows "services" GUI.

Alternately, create a copy of apachectl for each instance and update the PIDFILE and HTTPD

variables in each copy to specify the pid file and configuration file of the particular instance.

Example:

# the path to your PID file

PIDFILE=/usr/HTTPServer/logs/app1.pid

#

# the path to your httpd binary, including options if necessary

HTTPD='/usr/HTTPServer/bin/httpd -f conf/app1.conf'

Functional requirements

The functional requirements are the configuration differences which make different web server

instances behave differently, and are in addition to the operational requirements above. You may

wish to have different plug-in configuration files for the different instances

(WebSpherePluginConfig), or serve different static files for the different instances

(DocumentRoot). Different ports or IP addresses will be used for the different instances.

AIX: Can xlC.rte V7 be used?

IBM HTTP Server readmes and supporting software lists typically specify that xlC.rte 6.0 or

higher must be used on AIX V5. xlC.rte V7 is upwardly compatible and can also be used. The

specific V7 xlC.rte that has been tested with IBM HTTP Server is xlC.rte 7.0.0.1.

LoadModule order - When/why is it important?

LoadModule order in IBM HTTP Server 1.3

(ClearModuleList and AddModule also affect this. For the purposes of this discussion, an

AddModule directive after the ClearModuleList directive is equivalent to LoadModule.)

The Apache 1.3 API allows modules to implement one or more hooks to perform initialization or

request processing. Here are a few of the hooks which modules can implement:

post-read-request (run as soon as the client request has been read)

validate user id from request

determine MIME type

generate the response

log the transaction

Occasionally, there are requirements that one module's hook runs before another module's hook.

This commonly occurs when the user has configured some module, such as the WebSphere plug-

in, to process all requests, but they really want some of them to be processed by some other

module, such as mod_rewrite. The Apache 1.3 API has no API to allow modules to declare when

its hooks should run relative to the hooks of other modules. Instead, the order they run is

determined by the LoadModule order. All hooks for modules loaded (or AddModule-d) later will

run before the hooks of modules loaded earlier in httpd.conf.

For the common situation where mod_rewrite should take precedence over (run before) the

WebSphere plug-in, mod_rewrite must be loaded or added after the WebSphere plug-in.

LoadModule order in IBM HTTP Server 2.0 and above

The Apache 2.0 API allows modules to implement one or more hooks to perform initialization or

request processing. Here are a few of the hooks which modules can implement:

post-read-request (run as soon as the client request has been read)

validate user id from request

determine MIME type

generate the response

log the transaction

Occasionally, there are requirements that one module's hook runs before another module's hook.

The Apache 2.0 module API allows modules to indicate, for each request processing phase,

whether the module should be called first or last, or before or after another specific module. The

hook order is defined separately for each hook. For example, a module could indicate that its

transaction logger has to run before the transaction logger of other modules, and that its validate-

user-id hook must run before that of mod_auth.

When modules don't have specific requirements, or when modules declare when they should run

relative to other modules, the LoadModule order is not important. In fact, the LoadModule order

can almost always be ignored with IBM HTTP Server 2.0 or above.

When modules have specific requirements for the order in which they run, but they fail to use the

proper API to declare the required order to the web server, the user may be able to work-around

problems by reversing the LoadModule order. There is no clear rule for the specific order of the

LoadModule directives for module A and module B in order to make module A's hooks run

before those of module B's. On some platforms the LoadModule for module A must come first;

on other platforms, the LoadModule for module B must come first. There is no guarantee that

reversing the LoadModule directives is a permanent change. If the system qsort()

implementation in libc changes with system software maintenance or other changes are made to

the configuration file, the LoadModule directive might have to be reversed again.

AIX: Why am I unable to unmount filesystem containing files served by IHS

(affects HACMP environments)? (IHS 2.0 and above)

IHS 2.0 on AIX normally serves files using the send_file() API. This results in the files being

stored in the AIX Network Buffer Cache. This leaves the files open as long as they are in the

cache, preventing the underlying filesystem from being cleanly unmounted.

To clear files from the cache and unmount the filesystem:

set the size of the network buffer cache to zero temporarily to clear the cache

The old cache size can be displayed by no -o nbc_limit. The cache size can be set to

zero by no -o nbc_limit=0.

unmount the filesystem

restore the previous cache size no -o nbc_limit=old_value

An important IHS configuration directive which relates to this the EnableSendfile

directive. By setting EnableSendfile Off in the IHS configuration file, IHS won't use

the AIX send_file() API, and thus static files served by IHS won't possibly be added to

the network buffer cache.

In newer IHS sample configuration files (starting with PQ85834), send_file() is disabled

by default to eliminate the possibility that customers may encounter occasional sendfile

nuances unless they choose to actually use it.

IHS itself is not aware of which objects are in the network buffer cache and can't remove

such objects. Subject to the constraints of the network buffer cache (smallest/largest

cacheable object, total size), objects (files) are sometimes added to the cache by the AIX

kernel as a side-effect of IHS invoking the AIX send_file() API.

An infrequently used IHS module for AIX is the AFPA cache module. It also interacts

with the network buffer cache and should be disabled if the customer does not wish to

empty the network buffer cache prior to unmounting a filesystem containing files which

were cached.

What about MPM selection and prefork vs. worker? (IHS 2.0 and above)

IBM HTTP Server 2.0 and above uses the worker MPM on Unix and Linux systems, and it

cannot be replaced. Any information about Apache that suggests recompiling the web server for

a different MPM does not apply to IHS, as the MPM is pre-selected and IHS cannot be

recompiled by customers.

In other words, the prefork MPM cannot be used with IBM HTTP Server.

What about mod_dir, mod_rewrite, and the WebSphere plug-in? (IHS 2.0 and

above)

>We would like to know the priority of the following directives.

>- mod_dir(dir_module)

>- mod_rewrite(rewrite_module)

>- WebSpherePlugin(ibm_app_server_http_module)

mod_dir only handles objects which can be served by IHS as static files, so it cannot be used to

redirect requests to WebSphere. mod_dir has the lowest priority of these modules, and the

priority cannot be changed. It will only try to handle a request if the request was for a directory

and no other module has decided to serve the request.

With IHS 2.0, mod_rewrite always takes precedence over the WebSphere plug-in and, with the

proper configuration, mod_rewrite can first rewrite URLs and then the WebSphere plug-in can

see the rewritten URL and decide whether or not to serve it.

Example: Customer wants to use mod_rewrite to change URL /home to /servlet/home/, and

customer has configured the WebSphere plug-in to handle /servlet/*.

Here is a mod_rewrite directive to map /home to /servlet/home, and at the same time pass it

through to the WebSphere plug-in to allow it to see the rewritten URL. The PT flag on the

RewriteRule is what allows the WebSphere plug-in to process the rewritten URL.

RewriteRule ^/home /servlet/home [PT]

Note: In IHS 1.3, the actual order of the LoadModule or AddModule directives also makes a

difference. The LoadModule or AddModule for mod_rewrite needs to come after the WebSphere

plug-in is activated to allow mod_rewrite to rewrite URLs and then have the WebSphere plug-in

process the rewritten URL. This is not the case with IHS 2.0, where mod_rewrite always takes

precedence.

Where is mod_perl to work with IHS 1.3 on AIX?

mod_perl does not work with IHS 1.3 or normal Apache 1.3 on AIX. There is a build trick with

Apache 1.3 to turn on run-time linking, which is required for proper mod_perl support. This

involves building Apache 1.3 from scratch with special build flags to enable run-time linking.

Since IHS can't be rebuilt by the customer and IBM can't change the build of IHS due to

customer migration concerns, customers need to use real Apache 1.3 with mod_perl. Information

about how to build Apache 1.3 to use with mod_perl on AIX can be found on the web.

Why is POST data logged in access log as if it were a request?

request?

A problem existed in all levels of IHS 1.3.x which allowed POST data to be treated as a request

if a non-200 response was sent for the POST (e.g., 301 redirect, 401 authorization required, or

anything else), and an ErrorDocument directive was present for that non-200 response or a third-

party module had registered an error document. Make sure you have one of the following levels

of IBM HTTP Server:

1.3.19.6 with PQ87084 or PQ90262

1.3.26.2 with PQ87084 or later

1.3.28.1

What are the recommendations for AcceptMutex with IHS 1.3 on AIX?

The accept mutex is necessary in multiple child process configurations to prevent the thundering

herd problem, where multiple child processes wake up to handle a single incoming connection.

The accept mutex is used to ensure that only one child process wakes up when an incoming

connection is ready to process.

The accept mutex is always used when there is more than one listening socket. When there is a

single listening socket, the accept mutex is used unless httpd -V (IHS 1.3) displays -D

SINGLE_LISTEN_UNSERIALIZED_ACCEPT.

The default for IHS 1.3.19 through IHS 1.3.26 on AIX is AcceptMutex pthread. This has the

following problems with IHS 1.3:

1. Idle child cleanup often doesn't work, as there is an incompatibility between the interface

to pthread mutexes and the design of Apache 1.3's idle child cleanup. There is no work-

around other than to switch the mutex mechanism to something else.

2. There have been problems with third-party modules crashing in their child exit hook, and

the child exit hook can sometimes be run while the process holds the pthread mutex.

When this type of crash occurs, the server can hang. If fixes for the third-party module

are not available, the mutex mechanism should be changed to something else. (This

second issue has been sidestepped with Apache/IHS >= 1.3.28, as we have changed the

code to release the accept mutex before running the child exit hook, in case the third-

party module crashes there.)

We have never seen this problem with IBM-provided modules (for example, the modules

provided with IHS such as mod_rewrite, and the WebSphere plug-in module). If you are

loading only IBM-provided modules into IHS (LoadModule directives in httpd.conf),

then this is not a concern.

If you are using non-IBM modules, we cannot predict in advance whether or not you will

encounter this type of problem with that module. That depends on whether the exact

version of that module has such a defect which can occur in your environment.

choosing the accept mutex mechanism on AIX (IHS 1.3)

AcceptMutex pthread

This is the default mechanism for IHS 1.3.19 through IHS 1.3.26.x. This mechanism uses the

pthread_mutex_lock() function in the AIX pthread library to serialize access to the listening

socket between processes. The lock is in shared memory, which allows multiple httpd processes

to use it. There is no underlying file associated with this type of mutex, so the LockFile directive

is ignored.

pros

1. high performance

2. no system tuning required

cons

1. mutex ownership not recovered if the mutex owner crashes

2. with IHS 1.3, the pthread mutex mechanism can interfere with idle process cleanup

AcceptMutex sysvsem

This is a possible mechanism for IHS 1.3 (1.3.19.3 and above). This mechanism uses the

semop() and semctl() functions in the AIX kernel to serialize access to the listening socket

between processes. There is no underlying file associated with this type of mutex, so the

LockFile directive is ignored. The semaphore is viewable with the AIX ipcs command.

pros

1. high performance

2. no system tuning required (internal AIX limits are sufficiently high)

cons

1. A semaphore set will be lost if the parent process crashes. The semaphore set will have to

be manually cleaned up by the administrator using the ipcrm command.

AcceptMutex fcntl

This is the default mechanism for IHS 1.3.12 and below and for IHS 1.3.28 and above. This uses

the fcntl() kernel function to serialize access to the listening socket between processes. The httpd

processes wait for exclusive access to a lock file, then they can safely access the listening

socket(s). There is no real file I/O performed. Because the mutex is file-based, a lock file will be

used. Normally, the lock file is stored in the logs directory under the IHS ServerRoot directory.

The LockFile directive needs to be used in the following situations to override the default name

of the lock file:

1. IHS ServerRoot directory is on a network file system; use LockFile directive to place the

lock file on a local directory

2. multiple IHS instances share the same ServerRoot directory; use LockFile directive in

each httpd.conf to specify different files (No operational problem would occur if the

LockFile directive was missing; however, it could be confusing during problem diagnosis

to see open files used by different IHS instances and see that they each are using lock

files with the same name.)

pros

1. no system tuning required

2. widely used with Apache/IHS 1.3 on AIX, with no known problems

cons

1. performance is slightly less than AcceptMutex pthread or AcceptMutex sysvsem; the

actual difference is hard to measure with real world workloads

What format of text file userid/password is supported by IHS 1.3 on Windows?

The authentication module which handles flat files of userids and passwords is mod_auth

(described in the IHS Infocenters or in the Apache 1.3 documentation). On Windows, mod_auth

accepts flat text files of the form

userid:password

There are three allowable forms of the password:

1. unencrypted (not recommended)

Example: 2. jeff:jeff

3. MD5 hash, prefixed with the string "$apr1$"

Example: 4. jeff:$apr1$PN2.....$iPOw99RhtaeLLZ6OnXeGW/

5. SHA1 hash, prefixed with the string "{SHA}"

Example: 6. jeff:{SHA}8+cx36KTx6gxGdiqz6QbXS14C+k=

The traditional "crypt" format of the password is not supported by IHS 1.3 on Windows.

apxs on IHS 1.3.x fails trying to access the regex library. How can this be

corrected?

Example apxs failure with IBM HTTP Server 1.3.28 on AIX:

$ ihsinstall/bin/apxs -c -Wl,-bE:mod_test.exp mod_test.c

xlC_r -DAIX=433 -U__STR__ -DAIX_BIND_PROCESSOR -DUSE_HSREGEX -DUSE_EXPAT -

I../lib/expat-lite -O2 -qcpluscmt -DNO_DL_NEEDED -DSHARED_MODULE -

I/home/trawick/testihs13build/ihsinstall/include -c mod_test.c

ld -L../regex -lregex -H512 -T512 -bhalt:4 -bM:SRE -bnoentry -

bI:/home/trawick/testihs13build/ihsinstall/libexec/httpd.exp -lc -o

mod_test.so mod_test.o

ld: 0706-006 Cannot find or open library file: -l regex

ld:open(): No such file or directory

apxs:Break: Command failed with rc=16711680

Note: The -Wl,-bE:mod_test.exp parameter is AIX-specific. In general, the supplier of the

module should indicate if this or any other special apxs options are required for proper

compilation.

To correct the problem, the apxs script in the IBM HTTP Server bin directory must be modified.

Make a backup copy of apxs.

Edit apxs. Find the definition of $CFG_LD_SHLIB and remove the references to regex.

AIX example:

Original definition: my $CFG_LD_SHLIB = q(ld -L../regex -lregex); #

substituted via Makefile.tmpl

Corrected definition: my $CFG_LD_SHLIB = q(ld); # substituted via Makefile.tmpl

Why do I sometimes see 0 for the %D access log value on Windows?

IHS on Windows uses a system call to obtain two timestamps, one just after the request line is

read and the second when the access log entry is made. Although the Operating System returns a

value that has microsecond granularity, the timer is only updated once every OS timer tick, that

is, 64 times per second. Thus if IHS processes a request in less than 15 milliseconds it is possible

that 0 will be logged for the time taken to serve the request.

Why can't root install GSKit on Solaris?

If a third-party security product (such as eTrust) restricts what root can do, consult the vendor of

the security product if the GSKit installation fails.

One example of such an error:

pkgadd: ERROR: checkinstall script did not complete successfully

Installation of failed (internal error).

How can proxy requests be authenticated?

Specify the authentication directives within a <Proxy > container. An example using file-based

authentication follows:

LoadModule auth_module modules/mod_auth.so

<Proxy *>

AuthType Basic

AuthName "Restricted Files"

AuthUserFile /path-to-password-file

require valid-user

</Proxy>

The mod_proxy documentation contains a simpler example which allows access to the proxy

based on the client IP address.

Can IHS be run in a chroot environment?

IHS running in a chroot environment is untested and unsupported. IHS support cannot assist with

the configuration of such an environment and may require customer to reproduce defects in a

traditional environment.

How can I log the TCP port a request was received on?

IHS cannot directly log the TCP port the request was received on. The %p LogFormat logs the

port number specified in the ServerName or VirtualHost directive for the virtual host that

handled the request. To have a meaningful differentiation via %p you should always a specify a

VirtualHost for each listening port. Alternatively, when the directive UseCanonicalName is set

to off, %p will prefer the port number provided by the client in the HTTP Host: header.

How can I script the use of the ldapstash command?

ldapstash returns 1 for success and 0 for failure (this is counter to normal conventions).

The stash files created by ldapstash can be transferred between systems using any binary-safe

transfer method.

How do I start IHS during the Linux boot process?

The only IHS specific information required for this task is that the full path to

<ihsinst>bin/apachectl should be used to stop and start IHS version 2.0.x and later. Further

apachectl information is available here

Basic example of starting IHS during Linux startup:

1. Determine the default runlevel for your system by running the following command: grep default /etc/inittab

2. As root, create a new file in /etc/init.d/ using a name of your choosing, e.g.

/etc/init.d/IHS_6.1)

3. Contents of an example/etc/init.d/IHS_6.1 script, consult your linux manual for

information on details for creating your own that declares proper dependencies or

interoperates with chkconfig/inssrv. This script is provided AS-IS with no support. 4. #!/bin/bash 5. # SERVICENAME should match this filename 6. SERVICENAME=$(basename $0) 7. LOCKFILE="/var/lock/subsys/${SERVICENAME}" 8. APACHECTL=/opt/IHS61/bin/apachectl 9. 10. # The next lines are for chkconfig on RedHat systems.

11. # chkconfig: 2345 98 02

12. # description: Starts and stops IHS

13.

14. # The next lines are for chkconfig on SuSE systems.

15. ### BEGIN INIT INFO

16. # Provides: IHS_61.1

17. # Required-Start: $network $syslog

18. # Required-Stop:

19. # Default-Start: 2 3 4 5

20. # Default-Stop: 0 6

21. # Short-Description: Starts and stops IHS

22. # Description: Starts and stops IHS

23. ### END INIT INFO

24.

25.

26. case "$1" in

27. start)

28. touch $LOCKFILE

29. ;;

30.

31. stop)

32. rm -f $LOCKFILE

33. ;;

34.

35. *)

36. echo "Usage: $0 {start|stop|status|restart}"

37. exit 1

38. ;;

39. esac

40.

41. $APACHECTL "$@"

42.

43. Mark the file from the previous step as executable by owner: chmod u+x /etc/init.d/IHS_6.1

44. Run chkconfig --add IHS_61 and verify proper symlinks are created. If the symlinks

are not created by chkconfig, create them manually in the desired runlevel directories

(choose high-numbered startup links).

45. Beginning with the next full reboot, the OS will call this script with the parameter "start"

towards the end of system initialization

46. The LOCKFILE manipulation is required on RHEL5 and later, otherwise the service is

not stopped at shutdown.

More elaborate interaction with system facilities is possible as long as the interface to IHS is

apachectl.

Caching Questions

How can I disable caching in Internet Explorer?

Use mod_headers with the following configuration:

Header set Pragma "no-cache"

Header set Cache-Control "no-cache"

Header set Expires "-1"

If you don't want every resource on your webserver to be uncacheable, you have to determine

which resources the rules should apply to and add them to a more specific configuration section:

If you want this to apply to specific types of content served locally from IBM HTTP

Server, surround this with containers such as <Directory>, <DirectoryMatch>, <Files>,

or <FilesMatch<.

Example if your URLs ending in ".pdf" or ".php" should not be cached:

<FilesMatch \.(pdf|php)$>

Header set Pragma "no-cache"

Header set Cache-Control "no-cache"

Header set Expires "-1"

<LocationMatch>

If you want this to apply to specific file extensions served by WebSphere Application

Server, surround this recipe with a <LocationMatch> container.

Example if your URLs ending in ".pdf" should not be cached:

<LocationMatch \.pdf$>

Header set Pragma "no-cache"

Header set Cache-Control "no-cache"

Header set Expires "-1"

<LocationMatch>

For more information about how configuration sections / containers work, see The IBM HTTP

Server information center.

For more information about mod_headers, see the mod_headers documentation.

How can I tell if my cache-related headers are being set by mod_headers?

If you don't know where or not your mod_headers rules are working inside of IBM HTTP

Server, you can log their values by adding the following stanza to the LogFormat directive that is

in use by your CustomLog directives:

%{Pragma}o %{Expires}o %{Cache-Control}o

Example pre-existing LogFormat:

LogFormat "%h %l %u %t \"%r\" %>s %b" common

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

combined

After modification:

LogFormat "%h %l %u %t \"%r\" %>s %b %{Pragma}o %{Expires}o %{Cache-

Control}o" common

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"

%{Pragma}o %{Expires}o %{Cache-Control}o" combined

Other alternatives include wireshark, mod_net_trace, or the Firefox Live HTTP Headers plugin.

How can I tell if mod_cache is working?

UPDATE: You can log a cache miss by using SetEnv CACHE_MISS 1 and adding

%{CACHE_MISS}e in your LogFormat directive. Modules such as mod_env are skipped when a

response is served from the cache, so the CACHE_MISS environment variable can only be set

when the cache is not used.

If you are logging the Request Handler you will see the request handler change from the content

generator (mod_cgid, mod_proxy_http, mod_was_ap20_http, mod_core) to an empty value.

Under some circumstances this will happen on the third, not the second, request for cacheable

content.

Alternatively with LogLevel debug set, the following message is issued when mod_cache has

served the request: cache: serving /foo

Finally, if the "Age" header isn't being set by the content generator or some intermediate

cache/proxy, the presence of the Age header in the response indicates that the file is being served

from the cache. You can log the outgoing Age: header in the access log by adding %{Age}o to

your LogFormat directive.

How does mod_cache interact with the WebSphere Plugin?

mod_cache can cache content generated by the WebSphere Plugin if it has the appropriate HTTP

headers in the response, however this cache does not interact with the Plugin ESI cache. When

mod_cache is cacheing content generated by the WebSphere Plugin you will not see evidence of

the WebSphere Plugin being called for the cached request.

What content is cacheable?

See sections 13 of RFC2616, notably the presence of the E-Tag, Last-Modified, or Expires

headers

Why do I see duplicate content added to mod_mem_cache?

IHS creates up to MaxClients / ThreadsPerChild child processes, and each maintains its own

memory cache. The default httpd.conf is poorly tuned for mod_mem_cache, because it uses a

low value for both ThreadsPerchild and MaxSpareServers. Using many child processes, or a

variable number, will decrease the cache hit ratio.

Tuning suggestions for mod_mem_cache

High ThreadsPerChild allows the cache to be duplicated across fewer child processes and

increases cache hit percentage.

MaxRequestsPerChild 0 (default) prevents graceful child termination, which throws away

anything in a child processes cache.

MaxSpareThreads = MaxClients prevents graceful child termination, which throws away

anything in a child processes cache.

See IBM HTTP Server Performance Tuning for details on adjusting ThreadsPerChild.

Why don't some static files have a Last-Modified header?

URLs configured for mod_include (Server-Side Includes) do not include a Last-Modified header,

because the ultimate response is not necessarily related to the modification of the time passing

through the INCLUDES filter.

Is mod_proxy_balancer supported in IHS 7.0?

mod_proxy_balancer is not supported when IHS is licensed/entitled via WebSphere Application

Server.

This module is distributed alongside IHS on some platforms for use by WebSphere Community

Edition only. It is intentionally excluded from the list of supported Apache modules in the IHS

7.0 infocenter

Note that WebSphere Application Server customers are licensed to use IHS in support of their

WebSphere Application Server and not for any other purpose. The WebSphere plugin provides

the equivalent function for this purpose, and for other purposes customer should use a dedicated

load balancer, caching proxy, or Apache HTTP Server.

How can IHS ignore URL parameters inserted by WebSphere URL session

rewriting?

IBM HTTP Server treats the URL rewriting as part of the filesystem path of static resources

being requested. mod_rewrite can be used to remove this information from URL's, but care has

to be taken to only change requests that really will not be sent to WebSphere.

The first method involves putting the rewrite rules in existing <Directory> containers, because

these will never affect WebSpehre Requests.

Enable mod_rewrite by uncommenting the LoadModule rewrite_module... line in

httpd.conf.

Find the <Directory> container for your DocumentRoot and for any Alias you've added

that will be requested with a URL-rewritten session ID.

Inside each existing <Directory> container for your DocumentRoot and Alias'es, add

this ruleset, substituting the RewriteBase parameter as dictated by the URL-path of the

<Directory> context being updated:

# Note: this must be in an existing <Directory> container

RewriteEngine on

# The RewriteBase is "/" in the case that this <Directory>

block is for the DocumentRoot

# If this <Directory> block is for an Alias, the RewriteBase

below

# Should be the same as the first argument to the Alias

directive.

RewriteBase /

RewriteRule (.*); /$1 [PT]

The second method puts the mod_rewrite rules in <VirtualHost> context, which simplifies

configuration in one way but complicates it in that the user-supplied pattern must be used to

restrict the rewrite to static (local IHS) content. This effectively needs to mimic the WebSphere

Plugin processing to determine which URLs to remove the URL-rewritten session info from.

Enable mod_rewrite by uncommenting the LoadModule rewrite_module... line in

httpd.conf.

Determine what prefix or filename extension you want to limit the rewriting to, and

express it in a Perl Compatible Regular Expression (PCRE).

Inside each existing <VirtualHost> container, and once at the bottom of httpd.conf, add

this ruleset, substituting prefixes and file extensions are your requirements dictate. RewriteEngine on

RewriteRule (.*\.(?:gif|jpg|css); $1 [PT]

RewriteRule (/someprefix/.*\.(?:txt|pdf)); $1 [PT]

Can IHS use SHA-2 (sha224, sha256, sha384, sha512) digest algorithms?

Any version of IBM HTTP Server with GSKit 7.0.4.14 and later can validate SHA-2

certificate signatures at runtime.

Any version of IBM HTTP Server with GSKit 7.0.4.14 and later can use gsk7capicmd to

generate a certificate signing request using a SHA-2 algorithm (e.g. -sigalg sha512).

IBM HTTP Server 7.0 and earlier cannot use any SSL ciphers that use a SHA-2 based

digest, since such ciphers are valid only in TLSv1.2 which is not supported by GSKit 7.

Version 7 of Ikeyman and gsk7cmd cannot create certificate signing requests or self-

signed certificates using SHA-2 digest algorithms, but can be used to view certificates

which have been signed with a SHA-2 algorithm.

How can I use an LDAP server to authenticate my users and control

authorization?

When using mod_ibm_ldap, here are detailed instructions. Note that IHS on z/OS does not

support mod_ibm_ldap, and mod_ibm_ldap is deprecated on all platforms starting from IHS v7.

In those environments, use the Apache standard mod_ldap, for which there is copious

documentation available in books and on the Internet.

Authenticating to an LDAP server is done using an LDAP bind. In your ldap.prop file:

set ldap.url=ldap://hostname:port/baseDN, where baseDN is the base DN for queries

set ldap.application.authType=Basic to tell IHS it needs to bind to the LDAP server

before querying.

set ldap.user.authType=Basic to tell mod_ibm_ldap to expect HTTP Basic authentication

(as opposed to the client providing an SSL certificate for identification)

set ldap.application.DN=xxxx where xxxx is the LDAP distinguished name used when

binding to the LDAP server

run ldapstash to save the password for the bind in a stash file

set ldap.application.password.stashFile=yyyy where yyyy is the path to the stash file

Reminder: all these values have to be determined by the web server and LDAP server

administrators. We have no way of knowing what the correct values are for the customer's

environment.

Example ldap.prop:

ldap.URL=ldap://ldapserverhostname:389/profiletype=user,cn=sdbm

ldap.transport=TCP

ldap.version=3

ldap.application.authType=Basic

ldap.application.DN=racfid=adminuser,profiletype=user,cn=sdbm

ldap.application.password.stashFile=/usr/HTTPServer/keys/ldap.sth

ldap.user.authType=Basic

ldap.user.name.filter=cn=%v1

Then in the httpd.conf file, you can use something like

<Directory /protected/files>

Options IncludesNOEXEC Indexes

LdapConfigFile /usr/HTTPServer/conf/ldap.prop

AuthName "XYZ Corp. Protected Files"

AuthType Basic

Require valid-user

AllowOverride None

</Directory>

Now when a client user provides a userid of USERID and password of PASSWORD,

mod_ibm_ldap will do the equivalent of these two ldapsearch commands. First, it verifies that

the user exists:

ldapsearch -x -h mvs1 -p 389 -P 3 -b "profiletype=user,cn=sdbm" -D

"DN=racfid=adminuser,profiletype=user,cn=sdbm" -w "<password from stash

file>" "cn=USERID"

The filter "cn=USERID" is constructed using the value of ldap.user.name.filter, replacing %v1

with the first word entered by the user (typically just the userid).

If that succeeds (which requires both that the ldap.application.DN and password be acceptable,

and that the filter returns a single user), then it tries to bind using the user's userid & password to

see if the password is correct:

ldapsearch -x -m mvs1 -p 389 -P 3 -D "DN=<whatever DN was returned by the

previous query>" -w "<password entered by user>" xxxx

(Not bothering with the base DN, or showing xxxx here, because it never gets to a query, it just

tries the bind.)

The configuration shown so far is sufficient if you only need to verify that the user is in the

LDAP directory and has the right password. If you need to restrict access to only some of those

users, more configuration is needed.

First, you can specify an LDAP filter that the user's directory entry must match. In httpd.conf in

the same section where "Require valid-user" is configured, add a directive like:

LDAPRequire filter "(&(jobtitle=accountant)(location=newyork))"

Then access will only be allowed if the user's entry has a jobtitle attribute with value

"accountant" and a location attribute with value "newyork".

You might instead need to base authorization on whether the user belongs to an LDAP group.

That is reasonably well documented here, so I won't repeat it.

There's another issue the customer might run into.

In our testing, we've found that when using the LDAP server on z/OS with the SDBM or RACF

backend, not all filters are supported. Simple filters with a single condition, like cn=%v1, work

fine, but compound filters with multiple conditions, such as ((cn=%v1)(objectclass=person)), are

rejected with a server error such as "R000128 Filter is not supported (sdbm_search)". In the error

log, IHS might show something like:

[error] mod_ibm_ldap: failed to search 'LDAP Realm' with filter

'(&(cn=ACID)(objectclass=person))': (53) DSA is unwilling to perform

[warn] mod_ibm_ldap: LDAP server indicates that password is expired or user

id is locked.

The customer should use ldapsearch to verify that their filters work with their LDAP server

before configuring them in IHS.

If the customer does run into unexpected problems and wants to get an idea of what LDAP is

doing, they can add these two lines to IHS_install_dir/bin/envvars:

LDAP_DEBUG=65535

export LDAP_DEBUG

Then all LDAP communication will be logged quite verbosely in the error log, including server

errors like the "Filter is not supported" message mentioned above.

Why won't my IBM HTTP Server service start/stop in my Microsoft Cluster

Server (MSCS) environment?

IBM makes no claims of support for the IBM HTTP Server service running in an MSCS

environment. The IBM HTTP Server service is a 'generic' service that is unaware of MSCS, and

no testing with this environment has taken place. However, Microsoft apparently claims that

MSCS will support generic MSCS-unaware services (such as the IHS service) in a limited way.

Any customers attempting to run the IBM HTTP Server service within an MSCS environment

should contact Microsoft if they experience problems.

We are aware of one instance of a customer attempting to run the generic IHS service in this

environment. In this case the customer had some problems which Microsoft identified as a

known defect in the customer's version of Windows 2008 Cluster Service. The MS Cluster

Service was mistakenly taking the startup parameter as the service name. Microsoft claims this

has since been fixed in the Windows 2008 R2 version of the code. We are unaware of what other

versions may have the same issue. Microsoft was able to provide a workaround solution that

seemed to resolve this particular customer's problem. This workaround solution was to clear out

the startup parameters. For this customer, the command to do this was similar to: Cluster res "IBM HTTP Server 6.1" /priv startupparameters=""

Any direct support for the MSCS environment by IBM HTTP Server would be a new

requirement.

Common questions about using IHS with the WAS plugin

How can I change requests to affect how the plugin handles them?

This is answered extensively in this page.

Requests handled by the plugin/WAS have the wrong Content-Type

The solution to this is almost always to configure WebSphere Application Server to provide the

correct Content-Type with the response, not to try to "fix" it in IHS or the plugin.

If WAS is providing no Content-type in the response, then IHS will add the DefaultType, usually

text/plain. mod_mime is not applied to requests handled by the plugin, so none of those

directives can be used to apply a different Content-type.

If WAS sends the wrong Content-type, then IHS will not override it. Even ForceType is not

applied to plugin responses.

common questions about IBM HTTP Server (IHS) v8.0

What has changed in IHS v8.0?

http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/topic/com.ibm.websphere.ihs.d

oc/info/ihs/ihs/cihs_newfunction.html

Is IHS v8 freely downloadable?

On the Trials and downloads for IBM WebSphere Application Server page, there is a

download link for IBM Installation Manager which includes repository information

built into it for an ILAN-licensed IBM HTTP Server v8.0. The download link is here.

Why doesn't the IHS Admin Server work (@@AdminPort@@ startup error)?

In this release of IBM HTTP Server, the IHS Admin Server is not configured until the

Plugin Configuration Tool (PCT) has been run.

Where's the WebSphere Plugin?

The WebSphere Plugin, as well as the Plugin Configuration Tool (PCT) must be

explicitly selected for installation.

Why doesn't apache.exe -k start "just work"?

At installation time, Windows services for IHS are created with a name matching the

IM "package group name", which users can override and is also incremented for

multiple installs. Coupled with running multiple instances of IHS from the same

installation directory, this means the "right" service name must be specified when

using apache.exe -k.

How do I select a 64-bit IHS?

When installed on a 64-bit OS, the IHS installer uses 64-bit builds (when available) by

default. If more then one architecture is available, there will be sub-choices below IBM

HTTP Server in the "Features" panel of IBM Installation Manager. If multiple

components are being installed, the "Architecture Selection" twistie will not be visible

until the "IBM HTTP Server" twistie is clicked.

Misc. questions that don't fit anywhere else

How high can I set LimitRequestFieldSize?

Performance-wise, as high as you want; the server will only allocate as much memory while

reading the header as it needs to.

However, if you can estimate the largest header you're likely to receive, you might want to just

set LimitRequestFieldSize somewhat larger than that, rather than to some really huge value.

That will offer some protection in case a garbage request comes in that looks like it has a really

long header, keeping the server from continuing to read and allocate memory and maybe running

out.

Does IHS support NTLM or Kerberos?

No support is provided for these authentication protocols in IBM HTTP Server. Customers

requiring this functionality should configure the corresponding technologies in the application

server (e.g. SPNEGO TAI).

How do I turn off automatic directory listings?

By default, if IHS maps a request to a directory name rather than a filename (e.g.

/var/htdocs/images) and there's not an index.html file in the directory, IHS will return an

HTML page listing the files in that directory. You might wish to disable this as a security

measure.

Directory listings are generated by the mod_autoindex module. To disable all directory listings,

you can remove the Loadmodule line for mod_autoindex and any occurrences of configuration

directives that mod_autoindex implements (see the mod_autoindex documentation).

If mod_autoindex is loaded, whether a directory listing will be generated for a particular request

is configured using the Options directive.

To disable directory listings for a specific directory and its subdirectories, turn off the Indexes

option in that directory:

<Directory /var/htdocs/images>

Options -Indexes

</Directory>

You can disable all directory listings by default: <Directory />

Options -Indexes

</Directory>

But note that a more specific <Directory> section can turn indexes back on: <Directory /var/htdocs/images/foo>

Options Indexes

</Directory>

so search your configuration files for "Indexes" to verify that directory listings aren't re-enabled

anywhere that you don't want them.

A .htaccess file in a subdirectory can also turn on directory listings. You can prevent that by

configuring AllowOverride at the server level and omitting the Options argument, e.g.:

AllowOverride AuthConfig FileInfo

Summary: Either remove mod_autoindex completely from the configuration, or use Options

and AllowOverride to disable listings in specific directories.

Links:

index.html:

http://publib.boulder.ibm.com/httpserv/manual60/mod/mod_dir.html#directoryindex

mod_autoindex:

http://publib.boulder.ibm.com/httpserv/manual60/mod/mod_autoindex.html

Options: http://publib.boulder.ibm.com/httpserv/manual60/mod/core.html#options

AllowOverride:

http://publib.boulder.ibm.com/httpserv/manual60/mod/core.html#allowoverride