IHS-FAQ's
-
Upload
lalith-mallakunta -
Category
Documents
-
view
479 -
download
4
Transcript of IHS-FAQ's
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