9

Chapter 9. Web application serving

The Web is changing every aspect of our lives, but no area is undergoing as rapid and
significant a change as the way businesses operate. As businesses incorporate Internet
technology into their core business processes, they start to achieve real business value.

Today, large and small companies are using the Web to communicate with their partners, to
connect to their back-end data systems, and to transact commerce. This is On Demand
Business, where the strength and reliability of traditional IT meet the Internet.

But this On Demand Business world is supported by more than static Hypertext Markup
Language (HTML) pages and images files. To use the Web for business, static HTML pages
are not enough. Special applications are required to process a user’s input and integrate the
Web server with other information systems and data. The programs that extend the Web
server beyond static content are called Web applications. Usually, Web applications use the
data supplied by the HTML form, process the data, and then return the result as a Web page.
The data processing can be achieved by a wide range of application environments and
application programming languages.

Depending on the Web presence required for your environment, you can:
򐂰 Serve static pages for Web presence using HTTP Server (powered by Apache)
򐂰 Use the HTTP Server (powered by Apache) with Common Gateway Interface (CGI),
Net.Data, or other third-party products for data access
For more information, see Chapter 7, “Serving dynamic data” on page 157.
򐂰 Have a Java application running with WebSphere Application Server or Apache Software
Foundation (ASF) Jakarta Tomcat for a more powerful On Demand Business presence
򐂰 Install one of several available editions of the IBM WebSphere Application Server to
support applications based on Java 2 Enterprise Edition (J2EE)

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 191
 As shown in Figure 9-1, there are many options to create, serve, and manage one On
Demand Business application using the iSeries server. The iSeries server aggressively
supports the transformation of business applications to an On Demand Business model,
while minimizing disruption within the enterprise environment. It has business-proven values
(reliability, security, scalability, low cost of ownership) that support the latest enabling
technologies for On Demand Business. In combination, these two qualities make the iSeries
server an excellent choice for extending existing applications and deploying new solutions.

IBM Eserver iSeries

LOB
db Business Application
ILE RPG, COBOL, C, CL and Java

connectors
Web-to-Host Integration
WebSphere Host Integration
web
Host On-Demand
db
Host Publisher
Host Access Transformation
Server (HATS)
Data Access Web Application Servers WebSphere Development Studio
Client
CGI-bin (supports ILE RPG, WebSphere Application Server
COBOL, C, CL, Java and WebFacing Tool
ASF Jakarta Tomcat
PASE) iSeries Access family
Domino for iSeries
Net.Data HATS LE
WebSphere Commerce
WebSphere Host Int: Host iSeries Access for Web
Third party solutions
Access Library Host Publisher
Third party solutions Third-party solutions

Web servers, Domino, and third party

IFS
IBM HTTP Server for iSeries (5722-DG1)
files
HTTP Server (original)
HTTP Server (powered by Apache)
Domino native HTTP server
Third-party HTTP servers

TCP/IP suite and networking protocols

LDAP SMTP RouteD (RIP) VPN
BOOTP Telnet Quality of Service LPD
RADIUS FTP (QoS) IPP
DHCP TFTP SNMP
Dynamic DNS REXEC SNTP

Base OS/400 servers

NetServer: Windows based file/app serving Integrated file system (IFS) provides access to
Network Printing Support OS/400 objects through QSYS.LIB and NFS,
Integrated DB2 UDB for iSeries to provide QDLS, QFileSvr.400, QLANSrv, QNetWare,
native, SQL, ODBC, and JDBC db support QNTC, QOpenSys, QOPT, "root", and UDFS
Built in security (SSL and TLS)

Browser
Figure 9-1 iSeries On Demand Business environments

192 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
9.1 Web application servers for the iSeries server
This section helps to identify the technical differences between WebSphere Application
Server and Apache Software Foundation’s Jakarta Tomcat Web application servers.

WebSphere Application Server Version 5.0 and 5.1

WebSphere Application Server Version 5.0 and 5.1 are available in three editions:
򐂰 IBM WebSphere Application Server 5.0 and 5.1 for iSeries (Base Edition): This edition
ships as a Licensed Program Offering (LPO). It provides support for Java servlets,
JavaServer Pages (JSP), Java Message Service (JMS), and Enterprise JavaBeans
(EJBs). It also supports core Web Services standards such as Extensible Markup
Language (XML), Simple Object Access Protocol (SOAP), Web Service Description
Language (WSDL), and Web Services Invocation Framework (WSIF) for developing
dynamic solutions for On Demand Business.
򐂰 IBM WebSphere Application Server Network Deployment 5.0 and 5.1 for iSeries
(Network Deployment Edition): This edition ships as an LPO. It delivers world-class
caching, high availability, and industry-leading Web services support on top of the base
WebSphere Application Server foundation.
򐂰 IBM WebSphere Application Server 5.0 and 5.1 – Express for iSeries: This edition
offers a low-cost, easy to use, out-of-the box solution that supports simple, dynamic Web
sites based on the Java Servlets, JSPs, and Web services technologies. In addition, it is
now available at no additional charge with i5/OS V5R3M0 and later releases.

WebSphere Application Server Version 3.5 and 4.0

The WebSphere Application Server is a Java-based servlet engine that is built on top of the
native Java Virtual Machine (JVM) on the iSeries server. It provides Java servlet application
programming interface (API) support, which is defined by Sun Microsystems. WebSphere
Application Server for iSeries Versions 3.5 and 4.0 have these editions:
򐂰 Advanced Single Server Edition (Version 4.0 only): This edition lets you use Java
servlets, JSP, and XML to quickly transform static Web sites into vital sources of dynamic
Web content. It also provides a high-performance EJB server to implement EJB
components that incorporate business logic.
򐂰 Advanced Edition (Versions 3.5 and 4.0): This edition supports the same features as the
Advanced Single Server. It also supports multiple machine topologies, distributed
transactions, and transaction processing.
򐂰 Standard Edition (Version 3.5 only): This edition supports Java servlets, JSP, and XML.

End of Service: The end-of-service date for WebSphere Application Server Advanced
Edition for iSeries V3.5.x was 31 December 2002. V3.5.x is not supported after this date.
WebSphere Application Server Advanced Edition for iSeries V3.5.x is only supported on
OS/400 V4R5 and V5R1. V3.5.x is not supported on OS/400 beyond V5R1.

WebSphere provides the application server, which includes:

򐂰 A servlet engine for running servlets and JSPs and, in the case of Advanced Edition, the
container
The container is where Enterprise JavaBeans are deployed.
򐂰 An administrative server that is used to configure the servlets and JSPs in the servlet
engine and the EJBs in the container
򐂰 An administrative console that is used to communicate with the administrative server

Chapter 9. Web application serving 193

 For additional information about WebSphere Application Server, see:
http://www.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/

Apache Software Foundation’s Jakarta Tomcat

HTTP Server (powered by Apache) includes an industry-standard Java servlet and JSP
engine based on technology from the ASF Jakarta Tomcat open source code base.
Lightweight and easy-to-use software extends the HTTP Server (powered by Apache). The
iSeries server supports version 3.2.4 of ASF Jakarta Tomcat at V5R1, V5R2, and V5R3.

For additional information about ASF Jakarta Tomcat, see 9.2, “Apache Software
Foundation’s Jakarta Tomcat on iSeries” on page 197.

9.1.1 Comparing WebSphere Application Server and ASF Jakarta Tomcat

There are some technical differences between the application servers. Most of them relate to
the components they support. Table 9-1 shows some of these differences.
Table 9-1 Web application servers: Versions and support
IBM WebSphere Application Server

V 3.5 Standard V4.0 Single Server 5.0 and 5.0 5.1 and 5.1 Tomcat 3.2.4
and Advanced and Advanced Express Express

Servlets 2.2 + IBM 2.2 + IBM 2.3 + IBM 2.3 + IBM 2.2
extensions extensions extensions extensions

JSP 1.1 1.1 1.1 & 1.2 1.2 1.1

JDK 1.2 and 1.3 1.3 1.3.1 1.4 1.2 and 1.3

EJB 1.0 (Advanced 1.1 1.1 and 2.0 (not 2.0 (not for Not supported
only) for Express) Express)

XML Supported Supported Supported Supported Not provided directly as

part of 5722-DG1, but is
available as part of the
IBM Toolbox for Java

Connection Supported Supported Supported Supported Not supported

pooling

Session IBM extension IBM extension to IBM extension IBM extension Not supported. Sessions,
support to Servlet 2.2 Servlet 2.2 to Servlet 2.3 to Servlet 2.3 as defined in servlet 2.2,
are supported by ASF
Jakarta Tomcat.

J2EE No Yes Yes Yes No

Note: Although Tomcat 5 is not officially supported by IBM at V5R1, V5R2, or V5R3, we
provide the steps that you can use in Appendix B, “Bringing Tomcat Version 5.5 to your
iSeries server” on page 409.

194 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
9.1.2 When to use WebSphere Application Server versus ASF Jakarta Tomcat
Now that we identified some of the components supported by WebSphere Application Server
and ASF Jakarta Tomcat, let’s see how to choose one of the Web application servers to serve
our solution for On Demand Business.

IBM’s strategic Web application server is WebSphere Application Server. The latest version of
WebSphere Application Server is Version 5.0. It includes three editions for iSeries customers:
򐂰 WebSphere Application Server V5.0 for iSeries (Base Edition)
򐂰 WebSphere Application Server Network Deployment V5.0 for iSeries (Network
Deployment Edition)
򐂰 WebSphere Application Server Express for iSeries

These three editions of WebSphere Application Server V5 support servlets, JSP, EJB, and
much more. Customers who require a robust and scalable Web application server select
WebSphere Application Server. WebSphere Application Server is a chargeable product.

ASF Jakarta Tomcat on iSeries is the Web servlet and JSP container engine. This servlet
engine is free of charge and is included with the IBM HTTP Server for iSeries. Table 2-2 on
page 20 for details. The iSeries server supports ASF Jakarta Tomcat Version 3.2.4.

When to use WebSphere Application Server 4.0 Single Server Edition

Use the Single Server Edition when:
򐂰 You need to deploy solutions for On Demand Business that are J2EE compliant.
򐂰 Your application requires full Web services support.
򐂰 Your application benefits from EJB reloads.
򐂰 Your application requires Extensible Stylesheet Language (XSL) support.

When to use WebSphere Application Server 4.0 Advanced Edition

This is the same as 4.0 Standard Edition plus. Use it when:
򐂰 Your environment requires load balancing.
򐂰 You need real-time information about the On Demand Business application’s behavior in
terms of response time and access, because this edition includes the component
Resource Analyzer.
򐂰 The application requires some degree of partitioning.

When to use WebSphere Application Server – Express for iSeries

5.0 or 5.1
Use WebSphere Application Server – Express for iSeries Version 5.1 when:
򐂰 You are looking to deploy your first Web-based application on iSeries or to deploy simple
Web-based applications.
򐂰 You are looking to deploy Web-based applications developed with WebSphere
Development Studio Client for iSeries.
򐂰 You have currently deployed applications in WebSphere Application Server Version 3.02
or Version 3.5, Standard Edition for AS/400, or the ASF Tomcat Web application server for
iSeries.

Chapter 9. Web application serving 195

 When to use WebSphere Application Server V5.0 or 5.1 (Base Edition)
Use WebSphere Application Server V5 (Base Edition) when:
򐂰 You require full J2EE support.
򐂰 You need support for Java Servlets, JSPs, Java Message Service (JMS), and EJBs.
򐂰 Your environment uses core Web services standards such as XML, SOAP, WSDL, and
WSIF for developing dynamic solutions for On Demand Business.

When to use WebSphere Application Server Network Deployment

V5.0 or 5.1
Use this when you need all of the requirements as stated for the (Base Edition) and:
򐂰 You need caching support.
򐂰 You require high availability.
򐂰 You need industry leading Web services support on top of the base WebSphere
Application Server foundation.

Note: All three versions of WebSphere Application Server Version 5.0 and 5.1 have new
and added features that are too numerous to list. We recommend that you go to the
following Web site and review the documentation for these products:
http://www.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/

After carefully reviewing this information, you can make your decision based on what you
need for your business and environment. You should always try to deploy the latest
WebSphere Application Server version to benefit from the latest enhancement.

When to use ASF Jakarta Tomcat

Some iSeries customers want a basic, no-cost Web application server that supports servlets
and JSP. Relying on IBM HTTP Server (powered by Apache) as its Web server, ASF Jakarta
Tomcat provides a basic Web application server for iSeries customers. Use ASF Jakarta
Tomcat when:
򐂰 Your application is based on servlets, JSP, and XML files.
򐂰 Your application does not require EJB support.
򐂰 Your application does not require any database connection manager mechanism.
򐂰 Your application does not require any specific security mechanism, for example Secure
Sockets Layer (SSL).
򐂰 Your solution for On Demand Business does not require a load balancing implementation.
򐂰 Your solution for On Demand Business does not require scalability.

ASF Jakarta Tomcat is the newest component in the solution for On Demand Business
provided by the iSeries server. In the following section, you learn more about this new
member.

For a detailed functional comparison of each of these WebSphere Application Server

editions, see Chapter 5 in WebSphere for the IBM Eserver iSeries Server Buying and
Selling Guide, REDP-3646.

For more information about WebSphere Application Server for iSeries, go to:
http://www.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/

For WebSphere Application Server for Linux on iSeries, see:

http://www.ibm.com/servers/eserver/iseries/linux/websphere

196 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
9.2 Apache Software Foundation’s Jakarta Tomcat on iSeries
This is only ASF Jakarta Tomcat is a servlet engine container that supports servlets, JSP, and Web
supported by Application Archive (WAR) files. This servlet engine is developed and released under the
HTTP Server Apache Software Foundation license. It is integrated in the iSeries server by the IBM HTTP
(powered by Server for iSeries base code (see Table 2-2 on page 20 for the packaging details). ASF
Apache). Jakarta Tomcat requires a Java Runtime Environment (JRE) that has conformity with JRE 1.1
or later, including any Java 2 platform system.

Note: If you want to go directly to an example of application serving using ASF Jakarta
Tomcat, see 9.3.2, “In-process Tomcat configuration” on page 203.

The iSeries server supports Version 3.2.4 on V5R1, V5R2 and V5R3. We provide an example
of how to set up Tomcat 5.5 on your V5R3 iSeries server in Appendix B, “Bringing Tomcat
Version 5.5 to your iSeries server” on page 409.

For ASF Jakarta Tomcat to work with the HTTP Server (powered by Apache), it needs an
agent that resides in the HTTP server and sends it a servlet request. This agent is the Web
server plug-in, jk_module. It allows the communication between the HTTP Server (powered
by Apache) and the ASF Tomcat servlet engine. It must be included in the HTTP configuration
file with the LoadModule directive:
LoadModule jk_module /QSYS.LIB/QHTTPSVR.LIB/QZTCJK.SRVPGM

Although the ASF Tomcat servlet engine is integrated into HTTP Server (powered by
Apache), this does not mean that the servlet engine needs to run in the same process as the
HTTP server. ASF Jakarta Tomcat can be configured to run:
򐂰 In-process: ASF Jakarta Tomcat and HTTP Server (powered by Apache) run in the same
process and communicate through a Java Native Interface (JNI).
򐂰 Out-of-process: ASF Jakarta Tomcat and the HTTP Server (powered by Apache) run in
separate process (even on separate systems) and communicate through Transmission
Control Protocol/Internet Protocol (TCP/IP) sockets. The ASF Tomcat server process runs
in the QSYSWRK subsystem.

Running in-process or out-of-process implies some differences as shown in Table 9-2.

Table 9-2 Differences between running Tomcat in-process and out-of-process
In-process Out-of-process

Uses the jk_module module with the Java invocation Uses the jk_module to communicate with the
API to communicate with the HTTP server. HTTP server.

The HTTP server and ASF Tomcat servlet engine The HTTP server and ASF Jakarta Tomcat
communicate through a JNI. communicate through TCP/IP sockets.

Does not require a new protocol. Requires a new protocol to communicate

(ajp12 and ajp13).

ASF Tomcat server runs in the same JVM as the ASF Tomcat server runs in its own JVM.
HTTP server.

Uses the same security implementation configured Uses its own container managed security
by the HTTP server. implementation.

Works with the SSL configuration of the HTTP The communication between the HTTP server
server. and ASF Jakarta Tomcat does not support
SSL.

Chapter 9. Web application serving 197

 Before you start either the in-process or out-of-process configurations, identify the information
listed in Table 9-3 since it is required during the ASF Jakarta Tomcat configuration process.
This table also helps to identify some of the differences between running Tomcat in-process
and out-of-process.
Table 9-3 ASF Jakarta Tomcat required parameters for both in-process and out-of-process
Parameter In-process Out-of-process

ASF Tomcat server Not required Any name for the servlet engine

ASF Tomcat home Usually the HTTP server root Any directory; the default is
directory /ASFTomcat/server_name

Servlet engine /HTTP_home/conf/server.xml /Tomcat_home/conf/server.xml

configuration file

Java version (JDK) 1.2 or 1.3 1.2 or 1.3

URLs (Mount Uniform Resource Locator URL paths for your application
points) (URL) paths for your application

Application Link between URL and your Link between URL and your application
contexts application directory; similar to directory; similar to pass or alias directive
pass or alias directive used by used by the HTTP server
the HTTP server

IP address Not required The Internet Protocol (IP) address used by

the servlet engine to communicate with the
HTTP server

Port Not required The port used by the servlet engine to

communicate with the HTTP server

Server type Not required The protocol used by the servlet engine to
communicate with the HTTP server, AJP12
or AJP13

Server userid Not required The user ID used to start the servlet engine

9.2.1 ASF Jakarta Tomcat directory structure

This servlet engine runs under its own directory structure. This directory structure is used by
the HTTP server since it is included into the HTTP configuration file. The directory structure
can be located in the root or QOpenSys file systems. Table 9-4 shows the directory structure
used by ASF Jakarta Tomcat.
Table 9-4 ASF Jakarta Tomcat directory structure
ASF Tomcat directory Description

tomcat_home The tomcat_home directory is the base directory for ASF Tomcat.
The tomcat_home directory can be located in the root or QOpenSys
file systems. For an in-process ASF Tomcat configuration, the
default tomcat_home directory is set to the HTTP server directory
(/www/server_name/). For an out-of-process ASF Tomcat
configuration, the default tomcat-home directory is set to
/ASFTomcat/tomcat_server_name/. Within the tomcat_home
directory, there are subdirectories for logs and configuration
information.

tomcat_home/webapps This directory contains WAR files if you have them. All WAR files are
expanded and subdirectories are added as contexts.

198 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 ASF Tomcat directory Description

tomcat_home/webapps/ROOT This directory is required by ASF Tomcat. This directory is required

to support the servlet 1.1 specification.

tomcat_home/webapps/app1 This directory is known as a document base directory. You may

have several document base directories under the webapps
directory. These represent and map a directory structure to a
servlet or JSP application. The subdirectory app1 is your
application directory.

tomcat_home/webapps/app1/ This directory contains the web.xml file for the application. The
WEB-INF web.xml file contains the URL patterns and attributes for your
servlets.

tomcat_home/webapps/app1/ This directory contains any Java class files and associated
WEB-INF/classes resources that are required for your application. This directory is
searched prior to the tomcat_home/webapps/app1/WEB-INF/lib
directory for any servlet .class file that is specified in the URL.

tomcat_home/webapps/app1/ This directory contains any JAR files and associated resources that
WEB-INF/lib are required for your application.

tomcat_home/conf This directory contains the server.xml and workers.properties

configuration files.

tomcat_home/logs This directory contains all log files.

tomcat_home/work This directory is automatically generated by ASF Tomcat as a place

to store intermediate files.

java/lib This directory is created as a place to put .jar and .class files that
you want to add to the class path.

9.2.2 ASF Jakarta Tomcat directives

The ASF Jakarta Tomcat directives are used by the HTTP server to redirect the request of
servlets, JSP, and WAR files to the servlet engine. Before using any of these directives, the
jk_module module must be loaded. The directives are:
򐂰 JkAsfTomcat: This directive allows ASF Jakarta Tomcat to be turned off without deleting
particular ASF Jakarta Tomcat directives from the HTTP Server (powered by Apache)
configuration file. When this directive is set to off, it appears to the user as though ASF
Jakarta Tomcat was never enabled.
򐂰 JkLogFile: The JkLogFile directive is used to describe the full path name of the jk_module
log file. The log file describes the flows of header and data between the HTTP Server
(powered by Apache) and the ASF Tomcat servlet engine. It does not contain information
relative to what happens after a request is forwarded to the servlet engine. The specified
log file is never purged or wrapped. The file may need to be periodically purged by the
administrator.
򐂰 JkLogLevel: The JkLogLevel directive is used to describe the detail of logging that should
occur to the log file defined by JkLogFile. The possible values for this directive are:
– debug
– info
– error
– emerg
򐂰 JkMount: The JkMount directive specifies which Uniform Resource Identifier (URI)
contexts are sent to a ASF Jakarta Tomcat worker.

Chapter 9. Web application serving 199

 򐂰 JkMountCopy: The JkMountCopy directive indicates whether the base server mount
points should be copied to the virtual server. Any mount points defined outside
<VirtualHost> </VirtualHost> are inherited by the virtual host.
򐂰 JkWorkersFile: The JkWorkersFile directive is used to define the name of a file that
contains configuration information (that describes how jk_module attaches to the ASF
Tomcat servlet engine). There is no default. This directive must be specified or ASF
Jakarta Tomcat will not function. The typical file name is workers.properties.

These directives are added into the HTTP configuration file when the ASF Jakarta Tomcat
configuration is created. The directives may look like the following example:
LoadModule jk_module /QSYS.LIB/QHTTPSVR.LIB/QZTCJK.SRVPGM
...
JkWorkersFile /tomcat_home/conf/workers.properties
JkLogFile /http_serverhome/logs/jk.log
JkLogLevel error
JkMount /orderentry/* remote

The workers.properties file

The worker is the ASF Jakarta Tomcat instance that runs to serve servlets and JSP requests
coming from the Web server or, in our case, coming from the HTTP Server (powered by
Apache). This worker can run in-process or out-of process. It is specified in the JkWorkersFile
directive and tells the HTTP Server (powered by Apache) how the ASF Jakarta Tomcat
instance runs. This file contains entries of the following form:
worker.list=<a comma or space separated list of worker name>

Consider the following examples:

worker.list=local, remote
worker.list=local remote

When starting, the Web server plug-in (jk_module) instantiates the workers whose names
appear in the worker.list property. Each named worker should also have a few entries to
provide additional information. Such things as the worker type, port, and other related
information to the ASF Jakarta Tomcat process. The available workers types are:
򐂰 ajp12: This worker forwards requests to the out-of-process ASF Jakarta Tomcat process
using the ajp12 protocol.
򐂰 ajp13: This worker forwards requests to the out-of-process ASF Jakarta Tomcat process
using the ajp13 protocol.
򐂰 jni: This worker forwards requests to the in-process ASF Jakarta Tomcat process using
Java Native Interface (JNI).

The differences between the ajp12 and ajp13 protocols are:

򐂰 The ajp13 protocol is a binary protocol and tries to compress some of the requested data.
򐂰 The ajp13 protocol reuses open sockets and leaves them open for future requests.
򐂰 The ajp13 protocol has special treatment for SSL information.

Defining workers of a certain type should be done with the following property format:
worker.worker name.type=worker type

Consider this example for the ASF Jakarta Tomcat in-process mode:
worker.local.type=jni

Here local is the name of this worker.

200 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Each of these workers has its own group of properties that define the ASF Jakarta Tomcat
attributes such as ports, host names, classpaths, and so on. The attributes are different if
running in-process or out-of-process and if using ajp12 or ajp13 types. Depending on your
ASF Jakarta Tomcat run mode, the workers.properties file should have entries like the ones
shown here.

The following workers.property file specifies the in-process mode, with Java 1.2 and Tomcat
home directory /itso/itso07:
worker.list=local
worker.local.type=jni
worker.local.cmd_line=-config
worker.local.cmd_line=/itso/itso07/conf/server.xml
worker.local.sysprops=java.version=1.2
worker.local.sysprops=tomcat.home=/itso/itso07
worker.inprocess.stdout=/itso/itso07/logs/jvmstdout.txt
worker.inprocess.stderr=/itso/itso07/logs/jvmstderr.txt
worker.local.class_path=/QIBM/ProdData/HTTPA/java/lib/webserver.jar

The following workers.property file specifies out-of-process using ajp13 protocol, on port
8009, and running in the local host in the iSeries server:
worker.list=remote
worker.remote.type=ajp13
worker.remote.port=8009
worker.remote.host=localhost

When you create the ASF Tomcat servlet engine, using the ASF Jakarta Tomcat wizard
provided with the HTTP Server (powered by Apache) server, those entries are created in the
workers.properties file for you. At this point, this information is only supplied as a reference.

If you want to learn more about the workers.property file and its properties, refer to the
Tomcat Workers How To on the Apache Software Foundation’s Web site at:
http://jakarta.apache.org/tomcat/tomcat-3.2-doc/Tomcat-Workers-HowTo.html

9.2.3 ASF Jakarta Tomcat authorities

To run ASF Jakarta Tomcat, there are some authority requirements that the user running the
server must accomplish. The security considerations are related to the way the ASF Tomcat
servlet engine runs, either in-process or out-of-process.

This information is kept current in the Documentation Center’s document “User profiles and
required authorities for the HTTP Server (powered by Apache)”. To find this document, see
the following Web site:
http://www-1.ibm.com/servers/eserver/iseries/software/http/docs/doc.htm

When you reach this site, select the document for the version you are using, either V5R1 or
V5R2. Inside the IBM HTTP Server for iSeries Documentation Center, click HTTP Server
(powered by Apache) →Reference →User profiles and required authorities.

Chapter 9. Web application serving 201

9.2.4 ASF Jakarta Tomcat log files
ASF Jakarta Tomcat has its own set of logs files used to track day-by-day operations and
error messages for problem determination. Each time the ASF Tomcat servlet engine is
started, a set of log files is generated. They are all specified on the configuration file
server.xml. The files are located under the directory structure /ASFTomcat/server_name/logs,
used by ASF Jakarta Tomcat. Under this directory structure, you see the files shown in
Table 9-5.
Table 9-5 ASF Jakarta Tomcat log files
Log file Description

jasper.log This log file contains messages resulting from trying to start or run JSPs.

servlet.log This log file contains messages generated as a result of a servlet running in the ASF
Tomcat servlet engine. When a servlet is initialized, a ServletConfig object is provided
to the servlet. Contained within the ServletConfig object is a ServletContext object
that provides methods for a servlet to communicate to the Servlet container, which is
Tomcat in this case. In the ServletContext object is a log method that allows Web
applications to log to the servlet.log file.

tomcat.log This log file contains ASF Tomcat servlet engine messages.

jvmstderr.txt This log file can contain messages from any Java code that does a
System.err.println().

jvmstdout.txt This log file can contain messages from any Java code that does a
System.out.println().

jk.log This file contains messages generated by jk_module.

It is important to note that the jk.log file is not erased or regenerated when the ASF Tomcat
engine starts. Messages are appended to this file and the size of this file can grow quite large
if errors are logged. You should periodically monitor the size of this file and reduce its size. By
default, the jk.log is set to the logs directory under the HTTP server_home
(/www/server_name/logs/).

9.3 In-process implementation with ASF Jakarta Tomcat

This section serves a simple servlet using an in-process ASF Jakarta Tomcat configuration.

9.3.1 Creating HTTP Server (powered by Apache)

Use the Create New HTTP Server wizard to create a new HTTP Server (powered by Apache)
that will be used for your in-process Tomcat configuration. During the course of the wizard, it
asks you for information. Use the values specified in Table 9-6.

202 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Table 9-6 In-process Tomcat: Create New HTTP Server wizard required parameters
HTTP Server wizard parameter Value

Server name PBATCIN01

Server root /tcp52d01/asfTomcat

Document root /tcp52d01/asfTomcat/htdocs

On which IP address and TCP/IP port do you want your server to IP address: all
listen? Port: 8301

Do you want your new server to use an access log? Yes

With the information you provide, the Create New HTTP Server wizard creates the basic
HTTP configuration file to serve static pages from your document root. The confirmation page
for values specified in Table 9-6 should appear similar to the example in Figure 9-2.

Figure 9-2 In-process Tomcat: Create New HTTP Server wizard confirmation page

Your HTTP Server (powered by Apache) is now ready to be tailored for ASF Jakarta Tomcat.

9.3.2 In-process Tomcat configuration

The ASF Tomcat servlet engine can be configured to run in-process:
1. As shown in Figure 9-3 in the Server list, make sure your server name is selected. From
the Server area list, select Global configuration.
2. In the left pane, select Servlet and JSP Enablement.
3. In the first Servlet and JSP Enablement panel (Figure 9-3), click Next to start the wizard.

Chapter 9. Web application serving 203

 Figure 9-3 In-process Tomcat: Servlet and JSP Enablement wizard

4. As shown in Figure 9-4, select I want to use a servlet or Java Server Page (JSP), and I
either already have them or will provide them later. Click Next.

Tip: An easy way to start the ASF Jakarta Tomcat configuration, directory structure,
and activation process is to select I want a sample ASF Tomcat in-process servlet
engine configured for me. This option creates an in-process configuration for two
sample applications: a sample Calculator servlet and a sample Snoop JSP.

Figure 9-4 In-process Tomcat: Servlet and JSP Enablement wizard using your own servlet

204 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
5. As shown in Figure 9-5, complete these tasks:
a. Select I want to use a servlet. I either already have a class or jar file containing
the servlet or will provide it later.
b. The Server class name field appears. Type the name of the sample servlet class.
Replace the default MyServlet with CalculatorExample.
c. Click Next.

Figure 9-5 In-process Tomcat: Servlet and JSP Enablement wizard naming your servlet

6. As shown in Figure 9-6, click Finish. This page (and the next one) gives you good
information about the URL to access your servlet and where in the integrated file system
(IFS) to place it. You may want to take note of this information since we will use it in the
next step.

Figure 9-6 In-process Tomcat: Servlet and JSP Enablement wizard clicking Finish

7. Click OK on the confirmation page that follows.

8. To make your servlet name simpler than CalculatorExample, you can change the name
used to invoke it. In this case, you can either use the ASF Tomcat Setup Task or ASF
Tomcat Settings found in the left pane of the configuration options.
– ASF Tomcat Setup Task: This multi-form task guides you through the various Apache
configuration settings needed for using the ASF Tomcat servlet engine within a HTTP

Chapter 9. Web application serving 205

 server (powered by Apache). This is almost like a wizard that takes you through the
process of changing the configuration options for your ASF Jakarta Tomcat.
– ASF Tomcat Settings: This single form allows you a single place in which to change
the configuration options for your ASF Jakarta Tomcat.
We use the ASF Tomcat Settings because they provide an all-in-one form for
configuration.
a. As shown in Figure 9-7, in the left pane, select ASF Tomcat Settings.
b. In the right panel, scroll down until you find the Application contexts table. Click
Configure.

Figure 9-7 In-process Tomcat: ASF Tomcat settings

206 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 c. In the ASF Tomcat Application Configuration form (Figure 9-8), follow these steps:
i. Select the row that contains the Servlet classname of CalculatorExample.
ii. Replace the URL pattern of /calculatorexample with the shorter /calc.
iii. Click Continue.
iv. Click OK.

Figure 9-8 In-process Tomcat: ASF Tomcat Settings updating URL patterns

d. In the ASF Tomcat Settings form, click OK.

9. You have finished setting ASF Tomcat in the configuration file. Now continue with these
steps:
a. Locate the CalculatorExample.class file in the /QIBM/ProdData/HTTPA/admin
directory.
b. Copy this file to the /tcp52d01/asfTomcat/webapps/app1/WEB-INF/classes directory.

Chapter 9. Web application serving 207

 10.Start your HTTP Server (powered by Apache) and run the servlet:
a. Start your server PBATCIN01.
b. Enter the following URL in your browser:
http://as20:8301/app1/calc
This opens the CalculatorExample servlet application as shown in Figure 9-9.

Figure 9-9 In-process Tomcat: CalculatorExample.class file running

9.4 Out-of-process implementation with ASF Jakarta Tomcat

This section shows how to serve a simple servlet using an out-of-process ASF Jakarta
Tomcat configuration. The steps to configure ASF Jakarta Tomcat for out-of-process are:
1. Create the ASF Tomcat server.
2. Create the link between the HTTP and ASF Tomcat servers.
3. Test the out-of-process ASF Tomcat server.

This section expects that you have created a fairly standard HTTP Server (powered by
Apache) with the characteristics specified in Table 9-7 or that you will use one of your own.
Table 9-7 In-process Tomcat: Create New HTTP Server wizard required parameters
HTTP Server wizard parameter Value

Server name PBATCOUT01

Server root /tcp52d01/asfTomcatOut

Document root /tcp52d01/asfTomcatOut/htdocs

On which IP address and TCP/IP port do you want your server to IP address: all
listen? Port: 8401

Do you want your new server to use an access log? Yes

208 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 We serve the CalculatorExample.class servlet using this ASF Tomcat server. Before you start
the configuration process, identify some data as shown in Table 9-8. This information is used
to configure the ASF Tomcat server. It is also used to modify your HTTP Server (powered by
Apache) to redirect certain URL patterns to the out-of-process ASF Tomcat server.
Table 9-8 ASF Jakarta Tomcat out-of-process parameters
Parameter Value

ASF Tomcat server name tomcat01

ASF Tomcat home directory /tcp52d01/asfTomcatOut/TomcatHome

Server userid QTMHHTTP

Java version (JDK) 1.2

IP address:port and protocol *:8501 ajp13

URL path /myapp

Application base directory webapps/myapp

URL mount point /myapp/*

Servlet classname CalculatorExample

URL patterns /calc

9.4.1 Creating the ASF Tomcat server

Using the out-of-process approach, you must create the ASF Tomcat server. This server is
the one that receives the servlet or JSP request, processes it, and sends the response back
to the HTTP server. The communication between the HTTP and ASF Tomcat server is
through TCP/IP sockets. For this communication, you need to identify the IP address, port,
and protocol both servers will use to communicate. This is the IP address and port the ASF
Tomcat server works on. It is not related to the IP address and port used by the HTTP server
to receive the user’s request.

The following steps explain how to create an out-of-process ASF Tomcat server. Use the
values specified in Table 9-8 for this configuration.
1. Start the administrative GUI and click the Setup tab as shown in Figure 9-10.
2. In the left pane, under Tasks and Wizards, select Create ASF Tomcat Server.

Chapter 9. Web application serving 209

 3. In the Out-of-Process Engine Creation panel (Figure 9-10), in the ASF Tomcat server
name field, type your ASF Tomcat server name. In this example, we enter tomcat01. This
is the name of the ASF Tomcat server process. This is also the name of the job that will
start in the QSYSWRK subsystem when the ASF Tomcat server is started.
Click Next.

Figure 9-10 Out-of-process Tomcat: Creating an ASF Tomcat Server

210 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
4. The Out-of-Process Engine Configuration page opens as shown in Figure 9-11. Configure
the user profile used to start the ASF Jakarta Tomcat process, the Java version used to
start the server, and the home directory where ASF Jakarta Tomcat looks for property files
and Web application files.
a. Enter the user profile you will use to start the ASF Tomcat server. For this example, we
keep the default Server userid of QTMHHTTP.
b. Select the Java version this server will work with. In this example, we use Java version
(JDK) 1.2.
c. Enter the ASF Jakarta Tomcat home for your environment. For this example, we
change the ASF Jakarta Tomcat home to be /tcp52d01/asfTomcatOut/TomcatHome.
d. Leave the defaults for the Java classpath entries.
e. Click Next.

Figure 9-11 Out-of-process Tomcat: Engine configuration

Chapter 9. Web application serving 211

 5. The Out-of-Process Communication Settings page (Figure 9-12) opens. Follow these
steps:
a. Type the IP address the ASF Tomcat server will listen on. We enter All addresses.
b. Type the port number on which the ASF Tomcat server will listen. We type port 8501.

Note: The default value is normally 8009. Since this is a test system, we change the
port to something unique for this shared iSeries server.

c. Select the server type that the ASF Jakarta Tomcat will use to communicate with the
HTTP server. We select Binary (AJP13).
d. Click Next (not shown).

Figure 9-12 Out-of-process Tomcat: Communication settings

212 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
6. The Out-of-Process Application Context Definition panel (Figure 9-13) opens. Follow
these steps:
a. Click Add to add a new row to the Application contexts table.
b. Enter your URL path. For this example, we use /myapp.
c. The Application base directory specifies the directory where the servlets and JSP are
located. For this example, we use webapps/myapp. Under this directory, the ASF Jakarta
Tomcat out-of-process wizard creates some files and directories required by ASF
Jakarta Tomcat.
d. Click Continue.

Figure 9-13 Out-of-process Tomcat: URL path and application base directory configuration

Note: If this is your first ASF Tomcat server, you see a message indicating that the
web.xml file does not exist. This is normal. Continue with the next step.

7. The page shown in Figure 9-14 opens. Click Configure.

Figure 9-14 Out-of-process Tomcat: Missing web.xml configuration file

Chapter 9. Web application serving 213

 8. The ASF Tomcat Application Configuration page (Figure 9-15) opens. Follow these steps:
a. Click Add to add a new row to the Servlet definitions table.
b. Under Servlet classname, enter your Servlet classname. For this example, we use
/CalculatorExample.
c. Under URL patterns, enter your URL path. For this example, we enter /calc.
d. Click Continue. You can add any number of servlets here.
e. Click OK (not shown). This closes the window and returns you to the Out-of-Process
Application Context Definition window.
f. Click Next (not shown) to continue with the wizard.

Figure 9-15 Out-of-process Tomcat: ASF Tomcat Application Configuration

214 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
9. The Out-of-Process Summary page (Figure 9-16) opens. Complete these steps:
a. Click Finish to create the out-of-process Tomcat server.
b. You receive a message that indicates that your ASF Tomcat servlet engine TOMCAT01
has been successfully created. Click OK to continue.

Figure 9-16 Out-of-process Tomcat: Summary

Chapter 9. Web application serving 215

 Here is what the wizard has done for you. Under your ASF Tomcat home directory
/tcp52d01/asfTomcatOut/TomcatHome, some directories and files were created as shown
in Figure 9-17. The following actions were performed:
a. Created the ASF Tomcat home directory /TomcatHome
b. Created the /conf configuration directory
c. Created the web.xml file
d. Created the /logs directory
e. Created the /webapps directory
f. Created the /myapp directory
g. Created the /WEB-INF directory
h. Created the /classes directory where the CalculatorExample.class file will be placed
10.Place your CalculatorExample.class file into the /TCP52D01/asfTomcatOut/TomcatHome/
webapps/myapp/WEB-INF/classes directory.

a
e
f
g
h

Figure 9-17 Out-of-process Tomcat: Directory structure

9.4.2 Creating the link between the HTTP and ASF Tomcat servers
The ASF Jakarta Tomcat and the HTTP Server (powered by Apache) configurations are now
both created. Now you must include the ASF Tomcat server directives that will cause the
servlet and JSP request made to the HTTP Server (powered by Apache) to be redirected to
the ASF Tomcat engine.
1. Start the administrative GUI and click the Manage tab as shown in Figure 9-18.
2. From the Server list, select the HTTP server you want to work with. For this example, we
select PBATCOUT01.
3. In the left pane, under Server Properties, select ASF Tomcat Setup task.

216 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
4. In the Apache Enablement panel on the right (Figure 9-18), complete these tasks:
a. Select Enable servlets for this HTTP Server.
b. In the Workers definition file field, enter the directory path where the workers file should
be located. In this example, we use the directory suggested by the wizard, which is the
configuration directory of the HTTP server.
c. Click Next.

Figure 9-18 Out-of-process Tomcat: Apache enablement

Chapter 9. Web application serving 217

 5. The Workers Definition page (Figure 9-19) opens. Follow these steps:
a. Deselect the Enable an “in-process” servlet engine check box.
b. Select the Enable “out-of-process” servlet engine connections check box.
c. Click Add to add a row to the Out-of-process workers table.
d. In the Worker name field, type a name. For this example, we enter remote.
e. In the Worker type field, select the communications protocol version that will be used to
communicate between the HTTP Server (powered by Apache) and the Tomcat server.
For this example, we select Binary (AJP13). The server type should be the same as
you selected for the ASF Tomcat server engine creation. See Figure 9-12 on page 212.
f. In the Hostname:Port field, enter the IP address and port the on which Tomcat server
listens. For this example, we enter localhost for the IP address and 8501 for the port.
This value must be the same as the one that was used in Figure 9-12 on page 212.
g. Click Continue.
h. Click Next (not shown).

Figure 9-19 Out-of-process Tomcat: Configuring the Workers Definition file

218 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
6. The URL to Worker Mapping page (Figure 9-20) opens. Here you create the link between
the URL path and the ASF Tomcat server servlet engine.
a. Click Add to add a new row in the URL mappings table.
b. In the URL (Mount point) field, enter the URL path used by the HTTP server to identify
a servlet or JSP request and route the request to the ASF Tomcat server. For this
example, we use /myapp/*. Therefore, each time the HTTP server receives a request
from http://hostname:port/myapp/*, it sends the request to the ASF Tomcat server.
c. In the ASF Tomcat worker field, select the out-of-process worker that this HTTP server
will work with. In this case, we select remote (localhost:8501).
d. Click Continue.
e. Click Next (not shown).

Figure 9-20 Out-of-process Tomcat: URL to worker mapping

7. The Configuration Summary page appears. Review the information and click Finish.
8. Click OK to continue.

Chapter 9. Web application serving 219

 The ASF Tomcat Setup task wizard creates the workers.properties file under the HTTP home
directory as shown in Figure 9-21.

Browse : /TCP52D01/asfTomcatOut/conf/workers.properties
Record : 1 of 10 by 18 Column : 1 76 by 131
Control :

....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+.
************Beginning of data**************
#
# ASF Tomcat workers definition file for IBM HTTP server (powered by Apache)
# Thu Jul 10 19:33:59 UTC 2003
#

worker.list=remote

worker.remote.type=ajp13
worker.remote.host=localhost
worker.remote.port=8501
************End of Data********************

Figure 9-21 Out-of-process Tomcat: Workers.properties file

9.4.3 Testing the out-of-process ASF Tomcat server

Your configuration is now complete. Both the ASF Tomcat server and the HTTP server are
configured to serve the On Demand Business application. Before you start the HTTP server
instance and the ASF Jakarta Tomcat process, verify the following items:
򐂰 The ASF Jakarta Tomcat directory structure has the correct authorities for the user profile
that will start the server. In our case, this is QTMHHTTP.
򐂰 The servlets (.class files) are located in the /TCP52D01/asfTomcatOut/TomcatHome/
webapps/myapp/WEB-INF/classes directory.
򐂰 The user profile used to start the ASF Tomcat server has *READ authority to the servlets
and JSP.

Now, let’s see how the ASF Tomcat server works. First, you must activate the servers and
then test them.

To activate the HTTP Server (powered by Apache), start the administrative GUI and follow
these steps:
1. Click the Manage tab.
2. From the Server list, select PBATCOUT01.
3. Click the Start icon.

To activate the ASF Tomcat server:

1. From the Server list, select Tomcat01 - ASF Tomcat.
2. Click the Start icon.

To test the server, open a Web browser and enter:

http://hostname:8401/myapp/calc

220 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
You should see the CalculatorExample servlet running as shown in Figure 9-22.

Figure 9-22 Out-of-process Tomcat: CalculatorExample servlet in action

If you experience any problems running the application, see Chapter 13, “Problem
determination: When things do not go as planned” on page 323.

For more information

When your application has many JSP and servlets files, consider packaging them in a WAR
file. Then you use the ASF Jakarta Tomcat out-of-process configuration to include a new URL
path to point the WAR file.

For additional information about WAR files, go to the following Web site and enter WAR for the
search criteria:
http://java.sun.com/products/

For additional information about how to include the WAR file in the ASF Tomcat servlet
engine, see the iSeries HTTP documentation center at:
http://www.ibm.com/eserver/iseries/software/http/docs/doc.htm

Chapter 9. Web application serving 221

222 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 10

Chapter 10. Getting the best performance

from HTTP Server (powered by
Apache)
The HTTP Server (powered by Apache) provides excellent performance for Web serving. The
iSeries server has held the number three spot on the SPECweb99 benchmark and the
number two spot on the SPECweb99 Secure Sockets Layer (SSL) benchmark. This is a
significant validation of the overall systems performance of the entire iSeries server. It is the
iSeries’ balanced ability to scale and run enormous On Demand Business workloads that is
the basis for these (and other) benchmark successes. Of course benchmark rankings should
be only one of the considerations for selecting a server.

Our ability to run enormous On Demand Business workloads is due to the integration of the
SSL and Transport Layer Security (TLS) component 5722-AC3 and the HTTP Server
(powered by Apache) integration with OS/400. It is also a result of the pure power of the
iSeries’ 64-bit RISC POWER™ processors, which allow the iSeries to climb near the top of
these benchmarks.

SPECweb99 is a registered trademark of the Standard Performance Evaluation Corporation

(SPEC). For details, see:
򐂰 http://www.specbench.org/osg/web99/
򐂰 http://www.specbench.org/osg/web99ssl/

Tip: The redbook AS/400 HTTP Server Performance and Capacity Planning, SG24-5645,
is based upon the HTTP Server (original) (not the HTTP Server (powered by Apache)) and
V4R4 of OS/400. Yet, this redbook is still very useful because it examines the wider
integration of the HTTP server with OS/400. After all, OS/400 work management has not
changed all that much since V4R4, and an HTTP server is just a “fancy file server”.

Performance in a Web server environment is influenced by many components. Understanding

the components can help you to react quickly when a performance problem occurs at a
crucial time. It can also help you define what exactly you can expect from your iSeries server
and from your environment.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 223
 Several factors can be out of your control, such as network traffic (Internet or intranet), router
capacity, client speeds, and so on, that influence the overall performance environment.

This chapter applies to companies that plan to use the HTTP Server (powered by Apache) on
the iSeries server and who, from the beginning, want to tune their Web server using the
correct features and components for their environment.

There are three major components of a Web server environment as shown in Figure 10-1.
Each has its own performance requirement and limitations. The Web components identify:
򐂰 Client: The client with a Web browser represents the client component. Usually you do not
have direct control over this component.
򐂰 Network: The network is where routers, proxy caching, communications components, and
so on play an important role. This can represent the Internet, your own intranet, or both.
򐂰 Server: The iSeries server represents the server. Here, the performance of the iSeries
server (hardware and OS/400), the HTTP server, and optionally the Web application
server and the Web all work together to determine the overall server behavior in terms of
performance. In general, Figure 9-1 on page 192 shows a high-level view of the layers that
may be involved on your iSeries server.

NETWORK

Client with a
Web browser iSeries server
Figure 10-1 Three Web serving performance components: Client, network, and server

A problem in any of these areas may impact the performance of your Web application.

The focus in this chapter is on the iSeries server. The client and network components directly
impact the Web server performance. We briefly describe each component’s impact on the
overall performance. The first section, 10.1, “iSeries Web server performance components”
on page 226, concentrates on the iSeries server’s behavior.

The client
The client typically contributes up to 25% of the end-to-end Web application response time.
The client performance relies on the following resources:
򐂰 Processor speed: Slower clients may experience performance degradation when the
Web site requires image, forms, and Java applet download and execution.
򐂰 Memory: Memory is an important factor inside the client because many Web-related
tasks use large amounts of memory to complete. If the client does not have enough
memory, the user may perceive performance problems because of the client configuration.
򐂰 Hardware: Each piece of hardware is important. Hard disk and communication adapters
are important when performance is an issue. Keep in mind that clients are not updated as
fast as IT technologies change.

224 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
򐂰 Browser: Since Web browsers are the main interface in Web server, you must update
browsers frequently. Some Web servers, customer applications, and Web application
servers rely on browser capabilities. Most of the time you need to update browser levels
due to security vulnerabilities.

The network
Usually the network has more impact on overall performance than other components. The
network usually contributes up to 50% of the total response time. This is because a wide
variety of factors such as network traffic, bandwidth, and speed of communication lines.
These factors can be understood in more detail by identifying some network components:
򐂰 Routers
򐂰 LAN topology
򐂰 Link speeds
򐂰 Packet filters
򐂰 Proxy and proxy caching
򐂰 Socks servers
򐂰 Compression of the data

With many components involved, you can spend a lot of time trying to gain a better network
response time using tools to measure the behavior and never come up with an exact value.
This is because the components involved in a network are dynamic components from which
you can only expect average measurement and not exact values. Many of those components
can be completely outside your zone of responsibility (for example, the Internet).

The server
Server behavior is impacted by several factors including application, resources, and database
components. Each scenario has its own components. Do your best to create a Web
application with the most current information technologies. The database access should be
done with the most up-to-date utilities to data access. The Web application server and the
Web server itself should be configured using the best performance practices. Figure 10-2
shows server components involved in most of the On Demand Business implementations.

Security Features Application Server

Network

Client with a Web Server Database Server

Web browser

Figure 10-2 Web server components

All of these components can impact server performance, because most of the time, a client
request requires processing in each one of those components.

You must analyze other iSeries internal features (for example memory, bus, and disk) for your
Web application too. If the iSeries server itself does not have the internal resources to handle
the requirements, performance will be impacted. Other applications running on the same
iSeries can affect overall system performance too and you must take them into account.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 225
 Tip: Unique to the iSeries, HTTP server statistics are being saved into collection services
in V5R2. The advantage on the iSeries server is that these reports give you a more holistic
view of system performance. For more information, see 13.2.6, “Collection Services
performance data” on page 345.

10.1 iSeries Web server performance components

Performance of your HTTP Server (powered by Apache) is not defined by a single “silver
bullet”. It is composed of a series of configuration and design options that all work together.
Figure 10-3 presents an overview of the many components that can affect the overall
performance of your Web application.

If you are creating a Web application that can have many active SSL or TLS encrypted
sessions starting and stopping per unit time, this can be a drain on your main iSeries
PowerPC® processor or processors. As an example, most e-commerce Web sites and
client-banking applications have this characteristic. It is specifically for this asymmetric public
and private key exchange that IBM provides some extremely powerful hardware
cryptographic adapters for you to use on the iSeries server (and other IBM Eserver
platforms). For more information, see 10.7, “Cryptographic coprocessors” on page 300.

In Figure 10-3, you immediately notice that Fast Response Cache Accelerator (FRCA) is a
task that runs completely below OS/400’s Machine Interface (MI). This allows FRCA to
perform efficiently as a System Licensed Internal Code (SLIC) task, which avoids the costly
overhead of switching to a user-level server thread such as the HTTP Server (powered by
Apache). FRCA can serve Web content either in the form of a local cache for static content or
in the form of a reverse proxy cache for dynamic content. The effect is an extremely powerful
“HTTP aware” cache running in SLIC. For more information about FRCA, see 10.6, “Fast
Response Cache Accelerator” on page 281.

The Network File Cache (NFC) is another component of OS/400 that was introduced with
V5R2. The NFC provides the capability to efficiently store and retrieve cached files. It is like a
mini-file system (open, read, write, close) for SLIC tasks and is directly used by FRCA. See
“Network File Cache” on page 287 for information about how to configure the NFC for FRCA.

Using the HTTP Server (powered by Apache), you can improve the Web server performance
at two different levels:
򐂰 Using global parameters that allow you to configure the attributes used by all the HTTP
servers in your iSeries server. See 10.2, “Web server: Global performance values” on
page 227.
򐂰 Using specific parameters based on the type of data the client is requesting. These
specific parameters generally revolve around the concept configuration directives that are
place in specific contexts (containers) to provide performance benefits for all files or a type
of file. One example is local caches. Another is using mod_deflate to compress the data
before it is sent across the Transmission Control Protocol/Internet Protocol (TCP/IP)
network. See 10.3, “Web server: Specific performance values” on page 235.

An HTTP server, by itself, is nothing more than a fancy file server. In an On Demand
Business, however, your HTTP server becomes the focal point for all Web transactions. Often
dynamic content is requested of and served from a Web application. And, to avoid the costly
consumption of Central Processing Unit (CPU) and memory, these Web applications often
maintain their own application cache.

226 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 The Triggered Cache Manager (TCM) server is not a cache, but, like the name suggests, a
cache manager. The role of the TCM is to wait for programmatic triggers (most likely as the
result of an update in your Line of Business (LOB) database), which indicate that one or more
Web pages, that are dynamically dependent on that updated data, must be updated. TCM
then proactively regenerates those Web pages and places them in the iSeries integrated file
system (IFS) (which can be thought of as a local cache for TCM) to be served as a local static
file. Until the raw data in the LOB database changes again, the dynamic content is served at
static file speeds by the iSeries HTTP server. The important point is that TCM only needs to
update the content of the IFS if and when the raw data is updated in the LOB database. See
10.5, “Triggered Cache Manager” on page 259, for more information about this component of
IBM HTTP Server for iSeries.

Also directly related to the performance of a Web server is its scalability. That is, your Web
application’s ability to handle large volumes of Web traffic. To this end, the iSeries server
provides a set of application programming interfaces (APIs). See Chapter 14, “High
availability” on page 355.

Figure 10-3 shows the Web server components that are available to improve performance
using the HTTP Server (powered by Apache).

LOB Web application

DB

Triggered Cache Manager appl

cache

HTTP Server (powered by Apache)

IFS
files Specific performance values
Local cache options mod_deflate (compression)
Copy into memory
local
cache
Keep file descriptor open
Memory map of file
Global performance values
Time-outs HostNameLookups
TCP buffers Logging
Denial of Service CGI settings
MI Browser
Network File Cache FRCA TCP/IP
Local cache Hardware assist for
Reverse SSL/TLS handshake
File cryptography
proxy cache

Figure 10-3 iSeries Web server performance components

Another feature that was introduced to OS/400 V5R2 and i5/OS V5R3 is the Real Time
Server Statistics feature. It can help you tune the HTTP server by providing real-time
information, such as number of transactions, cache utilization, and so on. You can find details
about this function in 10.8, “Real Time Server Statistics” on page 301.

10.2 Web server: Global performance values

Global parameters determine the behavior of the Web server in general. These parameters
are checked each time the server receives a client request. Some of these global parameters
directly impact your Web server performance. Others are attributes of the Web server itself.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 227
 Each time the Web server receives a client request, the setting of these global configuration
parameters can affect how the request is processed.

10.2.1 Threads and asynchronous I/O

The HTTP Server (powered by Apache) has its own multi-process model. Each HTTP server
starts two (or three) processes under the QHTTPSVR subsystem:
򐂰 The manager process
򐂰 The primary process
򐂰 The backup process, when configured with the HotBackup directive

Each child process maintains its own thread pool independently.

This setting is one of the most important attributes of the HTTP Server (powered by Apache).
This setting allows you to specify how many threads each child process is allowed to use. The
default value is the same as the value for the maximum number of threads found on the
Global Server Settings form. The directive is ThreadsPerChild.

That is, you can set this parameter at the Global Server Setting to be the default value at
startup for all your Web servers as shown in Figure 10-4. Then you have the option to
override this Global Server Setting for each HTTP Server (powered by Apache).

You can only configure the maximum number of threads that the server opens at startup. The
HTTP Server (powered by Apache) always starts with the maximum number of configured
threads.

When no threads are available, the Web server response time, from the client point of view, is
impacted since the request takes longer because of the lack of available threads. Setting this
number too low impacts the server performance since the client request cannot be processed
until the Web server finds an available thread. But setting the maximum number of threads
too high, in general, requires more system resources to keep those threads available for use.
There is no optimum value for this setting.

With the HTTP Server (powered by Apache) implementation, the HTTP Server processes
communications requests asynchronously. In this asynchronous input/output (I/O) model,
threads are only involved in processing when work is to be done. Threads are dispatched to
perform work as required. When not performing work, the threads are returned to a pool of
available threads making the server process more efficient and improving performance by
using the thread resources better. Asynchronous I/O also makes the server more scalable to
support a high number of users especially when combined with persistent connections. We
recommend that you keep the default value of on (or enabled). The directive is AsyncIO.

Tip: Asynchronous I/O is one of many enhancements to the standard Apache server as
delivered to IBM Rochester by the Apache Software Foundation (ASF). This is just one of
the many reasons that the parenthetical phrase (powered by Apache) means integration.

Setting the maximum number of threads for all HTTP servers

This parameter is configured on the Global Server Settings display for all your HTTP servers
as shown in Figure 10-4. To set the maximum number of threads, follow these steps:
1. From the IBM Web Administration for iSeries interface, select the Advanced tab and then
the Settings subtab.
2. In the left pane, under Global Settings, select Global Server Settings.

228 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 3. In the right panel, for Number of threads, type the maximum number of threads in the
Maximum field.

Figure 10-4 Global Server Settings: Setting the maximum number of threads for all HTTP servers

Setting the maximum number of threads for a single HTTP server

You can also set the maximum number of threads and the option to use asynchronous I/O for
each individual HTTP Server (powered by Apache) as shown in Figure 10-5. Follow these
steps:
1. Select the Manage tab.
2. Make sure you select the server you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select System Resources.
4. Click the Advanced tab.
5. In the right panel, change the Number of threads to process requests to override the
Global Server Settings. Click OK.

10.2.2 Process control: HotBackup

The HotBackup directive is used to specify whether a hot backup server should be started at
server startup time. With the hot backup server active, if the primary server job abnormally
terminates, the hot backup immediately takes over, acts as the primary, and continues
servicing requests. A new hot backup is automatically created, in the background, within one
minute.

If the primary server process failure is not due to the network, all user connections remain
active during the hot backup takeover and the end users do not detect the loss of a server.
However, some HTTP requests in transient may be lost. If the failure is due to the loss of
network, the server must be restarted. With HotBackup off, only one multi-threaded server
child process is started.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 229
 Tip: An example of a loss of network may be if one of two interfaces on the iSeries fail. The
routes bound to the failing interface cause all the connections across that interface to fail. A
good solution to this potential problem is to configure a virtual Internet Protocol (IP)
address (or a circuitless connection) that is an IP interface defined on the system without
being associated with a physical hardware adapter. These addresses can always be active
on the system. For example, if one of two physical interfaces fail, then all network traffic
can be re-routed through the active interface. The applications and HTTP server will never
know of the problem. For more information about using virtual IP addresses, see iSeries IP
Networks: Dynamic!, SG24-6718.

You can configure this setting as explained here and shown in Figure 10-5:
1. Select the Manage tab.
2. For Server, select the server you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select System Resources.
4. Click the Advanced tab.
5. On the Advanced page, select the Initialize a backup process to take over in the event
of server process failure option. Click OK.

Figure 10-5 HotBackup and threads configuration

You can also override the default value found in the Global Server Settings form for the
directive ThreadsPerChild by specifying the number of threads that each child process is
allowed to use.

10.2.3 Logging
Logging is another setting that impacts server performance. Simply stated, as you request a
higher logging level, a greater load is placed on the server to write more information in the log
file. For example, if the logging level is set to Debug and the Web server experiences a
problem, messages written to the error log file increase and the Web server performance may
decrease.

230 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 You can configure this parameter for every HTTP server and for each virtual context within the
HTTP server. If the HTTP server has a different Error Log file for every virtual host context,
consider that a file descriptor is opened for each log file. Opening too many descriptors can
impact system performance.

For more information about logging with the HTTP Server (powered by Apache), see 13.2.3,
“Server logs” on page 331.

10.2.4 HostNameLookups
The HostNameLookups directive enables Domain Name System (DNS) lookups so the host
names can be logged (and passed to Common Gateway Interface (CGI) and server-side
includes (SSI) in the REMOTE_HOST environment variable). That is, it causes your HTTP
server to do a reverse lookup to convert an IP address into a host name and domain. This
may make it easier to track the usage of your Web site (by geography, for example) or to
determine problems.

The default for this directive is off to save on network traffic for those sites that do not truly
need the reverse lookup. Heavily loaded sites should leave this directive set to off, since DNS
lookups can take a considerable amount of time and resource.

You can configure this setting using the HostNameLookups directive. To configure this
directive, in the left pane under Server Properties, click General Server Configuration. Then
in the right panel, click the General Settings tab.

10.2.5 KeepAliveTimeout
The KeepAliveTimeout setting is used to control whether the Web server works with
persistent connections. Persistent connections enable a single TCP connection to be used for
multiple HTTP requests. Normally, each HTTP request is made over a separate connection.
Reusing a connection reduces the overhead, thereby improving performance for that client.

When the server runs with persistent connections, the KeepAliveTimeout setting determines
the number of seconds that the server waits for subsequent requests before closing the
connection. If this value is too low, the server can be impacted in terms of performance since
connections can close frequently. If this value is too high, the Web server can have many
connections open and the server can run out of resources. In this case, using asynchronous
I/O can alleviate (but not eliminate) the problem of running out of resources.

Tip: When migrating an HTTP Server (original) instance to an HTTP Server (powered by
Apache) instance, the value of the KeepAliveTimeout is set to 4 seconds by the migration
utility. This may cause problems for many environments. We recommend that you set the
value to 300 seconds after the migration completed.

You can configure this global setting as explained here (see Figure 10-6):
1. Select the Manage tab.
2. For Server, select the server you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select System Resources.
4. In the right panel, click the HTTP Connections tab.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 231
 5. All the parameters on the HTTP Connections page (Figure 10-6) relate to
KeepAliveTimeout. Click OK.

Figure 10-6 KeepAliveTimeout directive

This value applies to each client request. If the Web server you are working with is used on
the Internet, keep in mind that, since this is a communication setting, the value you select
here can be correct for some environments but not for others. We recommend that you leave
the default value unless you know your environment and have reason to make a change. One
reason may be that you know that persistent connections are not supported all the way
between the client. And you also know that your server or the majority of browsers that
connect to your site do not support persistent connections.

10.2.6 TCP buffer size

The TCP buffer size attribute provides a limit on the number of outgoing bytes that are
buffered by TCP. After this limit is reached, attempts to send additional bytes may result in the
application blocking until the number of outgoing buffered bytes drops below this limit causing
a negative impact in the Web server performance. The default value for this setting is zero.
This means the Web server uses the TCP value configured in the iSeries server for the TCP
send buffer size (TCPSNDBUF) parameter in the Change TCP/IP Attributes (CHGTCPA)
command. The default value for TCPSNDBUF is 102400.

You can configure this setting as explained here (see Figure 10-5 on page 230):
1. Select the Manage tab.
2. For Server, select the server you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select System Resources.
4. In the right panel, click the Advanced tab.
5. In the TCP buffer size field, type the TCP buffer size. The value for the TCP buffer size is
best left as the default of 0, unless application-specific reasons exist for your server. Click
OK.

232 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.2.7 Denial of service
The denial of service attribute is equally both a performance setting and a security setting.
This setting allows you to identify the possibility of an attack based on the data frame size.
The HTTP server may identify an attack because the frame size differs from the one it
expects. Although this setting impacts the server performance as each request is tracked, it
allows you to prevent a more dangerous performance degradation when dealing with a type
of attack that may intentionally slow down or even completely paralyze your server. The HTTP
Server (powered by Apache) includes the following attributes to prevent a denial of service
attack:
򐂰 Maximum message body size: Allows you to limit the size of an HTTP request message
body within the context the directive is given (server, per-directory, per-file, or
per-location). The default value is zero, which indicates that no maximum is size specified.
The directive is LimitRequestBody.
򐂰 Maximum XML message body size: Allows you to limit the size of an Extensible Markup
Language (XML)-based request body. The default value is 1000000 bytes. The directive is
LimitXMLRequestBody.
򐂰 Maximum header fields: Allows you to modify the limit on the number of request header
fields allowed in an HTTP request. The default value is 100. The directive is
LimitRequestFields.
򐂰 Maximum header field size: Allows you to limit the size for an HTTP request header field
below the default size compiled with the server. The default value is 8190. The directive is
LimitRequestFieldSize.
򐂰 Maximum HTTP request-line: Allows you to limit the size for a client’s HTTP request line
below the default size compiled with the server. The default value is 8190. The directive is
LimitRequestLine.

You can configure the denial of service settings as explained here (see Figure 10-7):
1. Select the Manage tab.
2. For Server, select the server you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select System Resources.
4. Click the Denial of Service tab.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 233
 5. On the Denial of Service page (Figure 10-7), enter the values for your environment. Click
OK.

Figure 10-7 Denial of Service page

See Chapter 6, “Defending the IFS” on page 101, for additional information.

Tip: This built-in protection against various denial of service attacks is one of the many
integrated extensions in the standard Apache Web server. Again, it is one of the reasons
for the (powered by Apache) parenthetical phrase in the HTTP Server (powered by
Apache) formal name of the server on the iSeries server.

10.2.8 CGI initialization at server startup

CGI initialization Uniform Resource Locator (URL) support offers the capability to start and
initialize CGI programs, such as Net.Data or other CGI programs, at server startup time. This
can significantly improve performance.

To activate this feature, you have to define prestarted CGI helper jobs (StartCGI directive)
with a corresponding user under which the job will run. Then you must add entries for the
particular CGI programs (CgiInitialUrl directive) that should be started. The entry consists of
the fully qualified physical path of the CGI program along with the user ID. The user ID must
refer to an entry in the CGI helper job section. The server does not start if the directive
CgiInitialUrl is configured without the directive StartCgi. You can set the same definitions for
threaded CGI jobs.

Perform the following steps to configure CGI initialization at server startup time.
1. Select the Manage tab from the IBM Web Administration for iSeries interface.
2. For Server, select the server that you want to manage. For Server area, select Global
configuration.
3. In the left pane, under Server Properties, select Dynamic Content and CGI.
4. Click the Server Startup tab.

234 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 5. On the Server Startup page (Figure 10-8), complete these tasks:
a. Under Prestarted CGI helper jobs, click Add.
b. Select the type of job and enter the number of jobs to be pre-started as well as the user
under which the jobs run. Click Continue to add this entry.
c. Under the Prestarted CGI programs section, click Add.
d. Enter the path of the CGI program in IFS naming format and select the user under
which the program will be run. Click Continue.
e. Click OK to save the new configuration.

Figure 10-8 Dynamic Content and CGI: Server Startup tab

6. Restart the server to activate the changes.

10.3 Web server: Specific performance values

Specific performance values are the settings that you can use to improve Web server
performance based on the type of data the server is going to serve. From a lifetime point of
view, all data is dynamic. It is just that some data is more dynamic than others.

To illustrate this point, you may declare that your home page is static, considering it is made
up of Hypertext Markup Language (HTML), Java script, and GIFs. Even your home page
changes from time to time. When it does, you want it (and all the other popular places in your
Web site) to be cached for the best performance. All Web content is dynamic, in this sense.

To ease our understanding, we define content that does not change that often as static.
Content that changes based on database information and user input is called dynamic.

In the end, however, the best way any Web server can improve its performance is by caching
the content before it is requested. For this purpose, the HTTP Server (powered by Apache)
supports these caching mechanisms:
򐂰 HTTP Server (powered by Apache) local cache
򐂰 HTTP Server (powered by Apache) proxy cache

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 235
 򐂰 Fast Response Cache Accelerator
򐂰 Triggered Cache Manager

Tip: Recall that TCM is not a cache but a cache manager. In effect, the TCM helps you to
be proactive in the update of HTML Web pages that you traditionally thought to be dynamic
and place them where your HTTP Server (powered by Apache) serves them from the IFS
as static content.

The HTTP Server (powered by Apache) local cache mechanism is generally used with static
data. TCM is used to improve performance for dynamic data. FRCA, on the other hand, can
be used to cache both static and dynamic contents. For a review of the components of
performance, including the relationship between the HTTP and TCM servers, FRCA, and the
many caches used by a Web application, see Figure 10-3 on page 227.

In addition to caching, some types of files can be compressed by your HTTP Server (powered
by Apache) before you send through the TCP/IP network. By compressing the files, you are
both allowing more information to be carried by the same size network and, in many cases,
allowing a single transaction to arrive faster. The downside is additional CPU and memory
requirements on both the server and client. For more information, see 10.4, “Increasing
throughput with compression” on page 240.

10.3.1 HTTP Server (powered by Apache) local cache

The local cache is used to cache data in system memory that is more static in nature. Static,
in this case, means the content is not changing based on the user input or database
information. In general, static content includes image files, HTML pages, etc. By keeping this
data loaded in the server’s memory, you can improve server response time for files because
the server can handle the request far more quickly than if it had to read from the file system.
The HTTP Server (powered by Apache) allows you to configure which files will be preloaded
in the server’s memory at server startup and the amount of memory used for this purpose.

The local cache implementation is a two-stage process:

1. Define the memory size for the files to be cached.
2. Define the cache method.

The local cache implementation uses one main storage space for all the local cache files, so
the memory size you define is used for all the cache files. This includes both the files that are
cached at server startup time and any changed or new files cached due to dynamic caching
(see “What to cache?” on page 237). The server directive to identify the memory size is
CacheLocalSizeLimit.

Files can be cached at server startup using any of these three methods:
򐂰 Copy into memory
򐂰 Keep file descriptor open
򐂰 Memory map of file

Tip: By default, the QHTTPSVR subsystem runs in system pool 1. Memory allocated by
the CacheLocalSizeLimit directive is from this pool. To verify which pool is used by the
QHTTPSVR subsystem, enter the 5250 Display Subsystem Description (DSPSBSD)
command:
DSPSBSD SBSD(QHTTPSVR/QHTTPSVR) OUTPUT(*)

Enter option 2 (Pool definitions).

236 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Copy into memory
The copy into memory method allows you to define the file or files that will be pre-loaded in
the iSeries memory, in the memory pool used by the HTTP server at Web server start up. The
memory size can be set up according to your application requirements. There is no limit for
the memory size used to preload the files. The limitation relies on the iSeries memory
capabilities.

The server directive used to cache files using this method is CacheLocalFile.

Keep file descriptor open

The Keep the file descriptor open method allows you to define ASCII file or files whose
descriptors are cached at server startup. Here, files are not copied into memory (they do not
allocate large amount of memory) and yet provide similar performance. Files cached with this
method remain open, shared read, while the server is active.

The server directive used to cache files using this method is CacheLocalFD.

Memory map of file

The memory map of the file method is similar to the copy into memory method. The difference
here is that this method uses a memory pointer to specify files that should be cached at
startup, which means that files are not copied into memory.

The server directive used to cache files using this method is CacheLocalFileMmap.

What to cache?
A powerful pair of options gives your HTTP Server (powered by Apache) server the ability to:

Tip: If the file is updated, then the local cached entry for this file is marked invalid and the
file is served from the IFS for all subsequent requests. Only restarting your HTTP Server
(powered by Apache) causes the file to be placed back into the local cache.

FRCA local cache has an interesting feature. Assume that a file located in the IFS is
cached in the NFC by FRCA. If that file is updated in the IFS, it is also automatically
updated in the NFC and the new content is served by FRCA. For details, see 10.6, “Fast
Response Cache Accelerator” on page 281.

򐂰 Dynamically update the (static) files that were placed in the local cache at server startup
time. The default value is on (or enabled).
This directive (LiveLocalCache) checks to see if the file is updated in the IFS each time it
is requested. If it is not updated, the file is served from the cache. If it is updated, then the
entry for this file in the local cache is marked invalid and the file is served from the IFS for
all subsequent requests. You restart your server to load it back in the local cache.
If LiveLocalCache is off, then your HTTP Server (powered by Apache) server does not
check to see whether the file has changed in the IFS.
Clearly, LiveLocalCache off gives you the best performance for your Web server at the
expense of denying you the ability to update a particular file. LiveLocalCache off is useful
in a directory of all GIFs, for example, that rarely change.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 237
 򐂰 Dynamically add new (static) files to the local cache based on demand. The default value
is off (or disabled).
This directive (DynamicCache) allows dynamic caching of (static) files. There is overhead
involved in determining whether a file being served should be added to the cache that
impacts all the files being served from your Web server. Because of this, we recommend
that you use this directive for sites that generally have less than 1000 files.
Or, to put this another way, if you have less than a 1000 static files to serve and you have
not done an analysis as to which files to populate your local cache at server startup time,
then you may try using DynamicCache on. But, it is always better to identify all the files
you want to add to the local cache at server startup time since this is far more efficient.
The dynamic cache only adds files to the local cache as long as there is still room as
defined by the directive CacheLocalSizeLimit. If the local cache is full, no more files are
added to the cache.

Example configuration of a local cache

The cache file methods are usually configured through the Administration graphical user
interface (GUI). To configure, for example, all the GIF files in your document root to be cached
at server startup, follow the steps as explained here and shown in Figure 10-9.
1. Start the IBM Web Administration for iSeries interface, and select the Manage tab.
2. From the Server list, select the server you want to manage. From the Server area list,
select Global configuration.
3. In the left pane, under Server Properties, select System Resources.
4. Click the Caching tab.
5. On the Caching page, complete these steps:
a. In the Maximum storage size field, type the memory size that you want to configure for
the files to cache. Remember that this size is the main storage size used by all the files
that you decide to preload into memory. For this example, we use the default 2000.
b. Under the Files to cache when server is started table, click Add.
c. In the File path and name column, enter the file path for the static data the Web server
will cache at server startup. For this example, we cache the images (*.gif) files of the
document root /www/tomitso1/htdocs/images/*.gif.
d. In the Cache method column, select the mechanism used to cache the files. For this
example, we select Copy into memory.
e. Click Continue to save the new entry to the list of files to be cached at server startup.
f. Click OK.

238 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 2

Figure 10-9 Web server cache configuration

One Web server configuration can have many cache entries, since one specific environment
can require a different cache method for a group of files. Each directory may have different
static files that are requested frequently. To improve the server response time of those
frequently access files, we decide to preload those files in memory when the server starts.

You can configure the Web server cache entries only from the global settings attributes. You
cannot configure this directive for any other context than the HTTP general context.

Using HTTP server trace to see how the local cache is populated at startup
Starting your Web server with the -vv (very verbose) trace (see 13.2.5, “HTTP server trace”
on page 341, for details about how to start and dump the -vv trace information) causes the
HTTP Server (powered by Apache) to document how many files are added to the local cache.

You can then search the HTTP server trace scanning for the text “cache”. At the beginning of
the trace information, you see many entries reading and interpreting the cache directives
found in the configuration file. Later, you see trace entries similar to this example:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+
000000AB:274632 total number of cache FCs = 51, FDs = 0, FRCAs = 2, and MMAPs = 0.
000000AB:274688 total allocated cache size: LOCAL = 0 80877, FRCA = 0 17435.

The first line indicates that the total number of files cached by copy (FCs) was 51, file
descriptors (FDs) was 0, FRCA was 2 (see 10.6, “Fast Response Cache Accelerator” on
page 281), and files cached as memory mapped (MMAPs) was 0. The second line indicates
the total local cache memory consumed by these cached items is 80,877 bytes.

10.3.2 HTTP Server (powered by Apache) proxy cache

When the HTTP Server (powered by Apache) is acting as either a forward proxy or reverse
proxy it can cache the results of the content received from the remote HTTP server. This can
provide significant performance benefits for multiple Web clients who are all requesting the
same document.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 239
 See 6.5, “Proxy server: Protecting direct access” on page 142, for more information about
both the forward and reverse proxy configurations. You should also see 10.6, “Fast Response
Cache Accelerator” on page 281, which demonstrates another method to configure a reverse
proxy cache.

10.4 Increasing throughput with compression

Data compression is another mechanism that can be used to improve performance. The
HTTP server module that provides compression support is the mod_deflate module. It is a
powerful module that allows you to compress, by configuration, files that are served from your
HTTP Server (powered by Apache). mod_deflate is Apache’s open source equivalent to
mod_gzip. Compressing the data before it is sent by your HTTP Server (powered by Apache)
can dramatically save on network delays caused by bandwidth restrictions. The data is
uncompressed at the remote client’s Web browser. mod_deflate is useful in networks where
individual network links are saturated with traffic or the end user is connected via modem.

As an anecdotal example, the /index.html home page that is served from our NetObjects
Fusion generated sample Web application that we use in this redbook is compressed by
mod_deflate from 10867 to 2002 bytes. Another example shows the HTML output of a
Net.Data macro is compressed from 10631 to 2869 bytes. Some files do not compress as
well. Examples are JPEGs, PDFs, and files that are already compressed. mod_deflate allows
you to configure which types of files are compressed and which are not.

Also, some documents are not supported by browsers in compressed form, such as
JavaScript (.js). In such cases, they must be excluded. They may work in the future, but for
now, it can make more problems than benefits.

And, of course, nothing is for free. This processing takes additional CPU and memory on your
iSeries server as well as the remote client browser. You must determine if the savings in the
size of the documents that you are sending through the network outweigh the performance
impact on the server and client.

Compression was initially added to 5722-DG1 at V5R1 and V5R2 via PTFs. One PTF
contains zlib and the other PTF contains the mod_deflate module plug-in:
򐂰 V5R1: PTFs SI09287 and SI09223
򐂰 V5R2: PTFs SI09286 and SI09224

Initial compression support did not support the configuration via the administration GUI.
However, the GUI configuration support was added with the following group PTFs for V5R1
and V5R2.
򐂰 V5R1 with group PTF SF99156 level 17 (December 2003)
򐂰 V5R2 with group PTF SF99098 level 13 (December 2003)

The GUI configuration support for V5R3 is implemented in the base code.

You can find more information about zlib on the Web at the following site, which announces
that zlib is “A Massively Spiffy Yet Delicately Unobtrusive Compression Library”:
http://www.gzip.org/zlib/

Important: zlib support is provided as a service program (*SRVPGM) in

QHTTPSVR/QZLIBZLIB. Just as mod_deflate uses this service program to compress data,
your applications can too. The IBM Rochester lab brought zlib to the iSeries to support
mod_deflate and not your application. That is, IBM does not support use of this service
program.

240 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.4.1 Compression considerations
You can configure compression individually for input and output traffic. Filters are used to
define the kind of traffic that should be compressed or decompressed. The only valid filter
name that is provided by the HTTP Server (powered by Apache) is DEFLATE. The DEFLATE
filter uses gzip for compression. However, you can write your own compression utilities that
can be plugged into the HTTP server configuration. These compression utilities are
accessible by a filter name of your choice.

Typically, you set up your HTTP server to compress only outbound traffic, because the
amount of data sent to a browser is much higher than the request data received from a
browser. The benefit of reducing the size of data sent from the server to the browser
outweighs the overhead that compression introduces for the CPU. One reason not to use
mod_deflate for inbound traffic is that many browsers do not support compression of HTTP
requests.

Carefully plan for the Multipurpose Internet Mail Extensions (MIME) or file types you want to
compress. As indicated earlier, if you configure the server to compress all outbound traffic,
the server would also compress files, such as JPEG files, that are already compressed. This
can cause more overhead than performance gain.

The IBM Web Administration for iSeries interface GUI provides three configuration tabs under
the category Compression. They provide the configuration options that are described in the
following sections.

Input filters
Input filters can be defined for the global configuration, directory, and virtual host contexts.
They determine how data received from the browser is handled. You have the option to
activate decompression for all traffic received within a specific context or traffic (files) that has
a certain extension. As mentioned previously, this option is not used often due to the lack of
HTTP request compression support for most browsers.

Output filters
As for input filters, output filters can also be defined for the global configuration, directory, and
virtual host contexts. However, output filters provide more configuration flexibility. You can
enable compression for an entire context, for certain browser versions, for certain file
extensions, or for certain MIME types.

Advanced
Using the Advanced tab, you can control the logging of compression information and
fine-tune the compression behavior of the mod_deflate module. In addition, there are several
more configuration tabs that can impact compression, but are not directly related to the
mod_deflate module.

10.4.2 Example configurations

Here are three sample configurations that provide you with a simple starting point for
configuration and use of mod_deflate:
򐂰 Compressing everything in a context
򐂰 Compressing only HTML files for specific Web browsers
򐂰 Compressing only a few MIME types in a context using AddOutputFilterByType

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 241
 Compressing everything in a context
The first configuration example sets up the server to compress outbound traffic for all files that
are served from a specific context (/www/tomitso1/datasheets/). In this case, the context (IFS
directory) contains only HTML and text files.

Note: If the selected directory also contain files, such as JPEG files, the CPU overhead for
compression may outweigh the benefit of reduced data traffic. In this case, compress only
certain types of files as described in “Compressing only a few MIME types in a context” on
page 250.

1. From the IBM Web Administration for iSeries interface, click Manage.
2. From the Server list, select the server that you want to configure.
3. From the Server area list, select the context for which you want to configure compression.
4. In the left pane under Server Properties, click Compression.
5. In the Compression panel (Figure 10-10), select the Output Filters tab.

Figure 10-10 Compression: Output Filters tab

6. On the Output Filters page (Figure 10-11), complete these tasks:

a. Scroll down to the Set output filter section. Click Add to add a new entry.
b. Enter the filter name DEFLATE. This is the only valid filter name that you can enter and
that has an impact on compression unless you have written your own compression
module with your own filter name. The DEFLATE name refers to the gzip compression
library.
c. Click Continue.
d. Click OK to save your settings.

242 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 10-11 Compression: Output Filters tab Set output filter section

7. Restart your server to activate the changes. From now on, all files that are served out of
the context /www/tomitso1/datasheets are compressed when sent to the client.

Example 10-1 shows the key directives that are needed to support compression using the
mod_deflate module in the httpd.conf file in bold. These directives were added by the IBM
Web Administration for iSeries interface. Most of the other directives that do not directly affect
this example were removed.
Example 10-1 mod_deflate: Minimal configuration directives
# Configuration originally created by Create HTTP Server wizard on Wed Sep 22 15:54:41 CEST
2004
LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Listen *:8001
DocumentRoot /www/tomitso1/htdocs
...
<Directory />
Order Deny,Allow
Deny From all
</Directory>
<Directory /www/tomitso1/datasheets>
Order Allow,Deny
Allow From all
SetOutputFilter DEFLATE
</Directory>
<Directory /www/tomitso1/htdocs>
Order Allow,Deny
Allow From all
</Directory>
Alias /datasheets/ /www/tomitso1/datasheets/

Tip: You use RemoveOutputFilter DEFLATE to turn off mod_deflate in a subcontext.

Compressing only HTML files for specific Web browsers

Some versions of Web browsers cannot handle the compression of mod_deflate. In addition,
it is not always good to try to compress graphic files and other files of certain types. The
following example provides a good starting example that compresses only files of type HTML
for all incoming URLs as defined by the <Location /> directive. Example 10-2 highlights the
key directives that we added to a standard httpd.conf file. Most of the other directives that do
not directly affect this example were removed.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 243
 This example uses the recommended configuration found on the Web at:
http://httpd.apache.org/docs-2.0/mod/mod_deflate.html#recommended

Tip: The configuration example at the httpd.apache.org Web site requires minor
modification for it to work in the HTTP Server (powered by Apache). The original syntax at
httpd.apache.org was:
# Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary

We modified the SetEnvIfNoCase directive to this one line syntax (shown in

Example 10-2):
# Do not compress images
SetEnvIfNoCase Request_URI \.(gif|jpe?g|png)$ no-gzip dont-vary

Example 10-2 mod_deflate: Recommended configuration directives from ASF

# Configuration originally created by Apache Setup Wizard Wed Apr 30 15:38:30 UTC 2003
LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Listen *:8000
DocumentRoot /tcp52d00/basicconfig/itsoco
ServerRoot /tcp52d00/basicconfig
...
<Location />
# Insert filter
SetOutputFilter DEFLATE
# Netscape 4.x has some problems...
BrowserMatch ^Mozilla/4 gzip-only-text/html
# Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip
# MSIE masquerades as Netscape, but it is fine
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
# Do not compress images
SetEnvIfNoCase Request_URI \.(gif|jpe?g|png)$ no-gzip dont-vary
# Make sure proxies do not deliver the wrong content
Header append Vary User-Agent env=!dont-vary
</Location>
...
<Directory />
Order Deny,Allow
Deny From all
</Directory>
<Directory /tcp52d00/basicconfig/itsoco>
Order Allow,Deny
Allow From all
</Directory>

You can find this example at the Apache Web site. It uses BrowserMatch directives that were
introduced with the mod_browser module. However, the BrowserMatch directives were
declared obsolete with Apache 1.2 and higher. A replacement for the BrowserMatch directive
is the SetEnvIf directive of the mod_setenvif module. The HTTP Server (powered by Apache)
still accepts the BrowserMatch directive when manually configured, but the IBM Web
Administration for iSeries interface supports only the SetEnvIf directive in the GUI.

The following steps explain how to implement the previous example using the IBM Web
Administration for iSeries interface. This time, the directives apply to a directory context
instead of a location context.

244 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
1. From the IBM Web Administration for iSeries interface, click Manage.
2. From the Server list, select the server you want to configure.
3. From the Server area list, select the context for which you want to configure compression.
4. In the left pane under Server Properties, click Compression.
5. In the Compression panel, select the Output Filters tab.
6. On the Output Filters page, complete these steps:
a. Scroll down to the section Set output filter and click Add to add a new entry.
b. Enter the filter name DEFLATE. This is the only valid filter name that you can enter and
that impacts compression unless you have written your own compression module with
your own filter name. The DEFLATE name refers to the gzip compression library.
c. Click Continue.
d. Click OK to save your settings.

Figure 10-12 Compression: Output Filters tab Set output filter section

7. So far, you have configured the directory context to compress all files that are sent to the
client. In the next steps, you will configure the equivalent directives for the BrowserMatch
directives. These directives restrict compression for certain browser types.
In the left navigation pane, under Server Properties, click Request Processing.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 245
 8. In the Request Processing panel (Figure 10-12), click the Custom Environment
Variables tab.

Figure 10-13 Request Processing: Custom Environment Variables page

246 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
9. On the Custom Environment Variables page, complete these steps:
a. Scroll down to the end of the table and click Add to add a new entry to the table.
b. Enter the following values into the input fields as shown in Figure 10-14:
• Variable: gzip-only-text/html
• Value: Leave empty
• Attribute: User-Agent
• Attribute value: ^Mozilla/4
• Case sensitive: Select this option
Depending on the Case sensitive checkbox setting, the GUI creates a SetEnvIf or
SetEnvIfNoCase directive.
These values generate the following directive:
SetEnvIf User-Agent ^Mozilla/4 gzip-only-text/html
The directive corresponds to the following BrowserMatch directive:
BrowserMatch ^Mozilla/4 gzip-only-text/html

Figure 10-14 Request Processing: New entry on the Custom Environment Variables page

c. Click Continue.
d. Click Add to add another entry to the environment variables section.
e. Enter the following values for the new entry.
• Variable: no-gzip
• Value: Leave empty
• Attribute: User-Agent
• Attribute value: ^Mozilla/4\.0[678]
• Case sensitive: Select this option
This entry further restricts compression in a way that compression is applied to Mozilla
(Netscape) browser Version 4.06 to 4.08. The directive generated by the GUI is:
SetEnvIf User-Agent ^Mozilla/4\.0[678] no-gzip
f. Click Continue to save the entry.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 247
 g. Repeat the previous steps to add the following two entries:
• Variable: !no-gzip
• Value: Leave empty
• Attribute: User-Agent
• Attribute value: \bMSIE
• Case sensitive: Select this option
This entry allows compression for Microsoft Internet Explorer browsers. In fact, it
removes the restriction that was previously introduced with the no-gzip option for all
browsers that report themselves as Mozilla browsers. Also Internet Explorer reports
itself as a Mozilla browser, but adds another value (MSIE) to the user agent string. The
User-Agent variable is selected with the regular expression \bMSIE if the variable
contains somewhere the value MSIE. If it does, compression is allowed via the !no-gzip
parameter.
The second entry removes the restriction for text/html files.
• Variable: !gzip-only-text/html
• Value: Leave empty
• Attribute: User-Agent
• Attribute value: \bMSIE
• Case sensitive: Select this option
The directives generated by the GUI are:
SetEnvIf User-Agent \bMSIE !no-gzip
SetEnvIf User-Agent \bMSIE !gzip-only-text/html
h. Using the following parameter values, add the last two SetEnvIf directives to the HTTP
server configuration:
• Variable: no-gzip
• Value: Leave empty
• Attribute: Request_URI
• Attribute value: \.(gif|jpe?g|png)$
• Case sensitive: Deselect this option
The second directive is required to set the dont-vary variable.
• Variable: dont-vary
• Value: Leave empty
• Attribute: Request_URI
• Attribute value: \.(gif|jpe?g|png)$
• Case sensitive: Deselect this option
The directives generated by the GUI are:
SetEnvIfNoCase Request_URI \.(gif|jpe?g|png)$ no-gzip
SetEnvIfNoCase Request_URI \.(gif|jpe?g|png)$ dont-vary

248 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 After all SetEnvIf and SetEnvIfNoCase directives are defined, the environment
variables section should look like the example in Figure 10-15.

Figure 10-15 Request Routing: Custom Environment Variables

i. Click OK to close the Request Processing window.

Note: When BrowserMatch directives already exist and you change custom
environment variables via the IBM Web Administration for iSeries interface, the
BrowserMatch directives are automatically converted into SetEnvIf directives.

10.The last configuration step prevents proxies to incorrectly handle the content. In the left
navigation pane, click HTTP Responses.
11.In the HTTP Responses panel, click the Response Headers tab.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 249
 12.On the Response Headers page (Figure 10-16), follow these steps:
a. Click Add to add a new entry to the Response headers section.
b. Enter the following information:
• Action: Append
• Header name: Vary
• Value: User-Agent
• Environment variable: !dont-vary
c. Click Continue.
d. Click OK to save your settings.

Figure 10-16 HTTP Responses panel

13.Restart the server to activate the new configuration.

Compressing only a few MIME types in a context

Using AddOutputFilterByType seems to be the preferred way to handle the idiosyncrasies of
the many different Web browsers on the Internet. You can use a more complex example as
demonstrated earlier. However, complexity invites the opportunity for error, either as part of
your configuration or from the Web client’s ability (or lack of ability) to handle a certain MIME
type. For example, you may want to test to see which versions of Netscape can handle
compressed PDFs over an SSL-encrypted session.

In this configuration scenario, only content of the following MIME types are compressed:
򐂰 text/html
򐂰 text/plain
򐂰 text/xml

Perform the following steps to activate outbound compression for these MIME types.
1. From the IBM Web Administration for iSeries interface, click the Manage tab.
2. From the Server list, select the server you want to configure.
3. From the Server area list, select the context you for which want to configure compression.

250 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
4. In the left pane under Server Properties, click Compression.
5. In the Compression panel, select the Output Filters tab.
6. On the Output Filters page (Figure 10-17), complete these steps:
a. Scroll down to the Add output filter by MIME type section and click Add to add a new
entry.
b. Enter the following information to enable compression for the text/html MIME type:
• MIME type: text/html
• Filter name: DEFLATE
c. Click Continue.

Figure 10-17 Compression: Adding an output filter by MIME type on the Output Filters page

d. Click Add again to add the entry for the MIME type text/plain:
• MIME type: text/plain
• Filter name: DEFLATE
e. Click Continue.
f. Click Add again to add the entry for the MIME type text/xml:
• MIME type: text/xml
• Filter name: DEFLATE
g. Click Continue.
h. Click OK.
7. Restart the server to activate the new configuration.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 251
 Example 10-3 shows the key directives needed to support MIME type-based compression
using the mod_deflate module in the httpd.conf file in bold. These directives were added by
the IBM Web Administration for iSeries interface. Most of the other directives that do not
directly affect this example were removed.
Example 10-3 mod_deflate: Minimal configuration directives
# Configuration originally created by Create HTTP Server wizard on Wed Sep 22 15:54:41 CEST
2004
2 LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
3 Listen *:8001
4 DocumentRoot /www/tomitso1/htdocs
...
24 <Directory /www/tomitso1/prodinfo>
25 Order Allow,Deny
26 Allow From all
27 AddOutputFilterByType DEFLATE text/html
28 AddOutputFilterByType DEFLATE text/plain
29 AddOutputFilterByType DEFLATE text/xml
30 </Directory>

This example uses mod_deflate to compress all the files served from the directory
/www/tomitso1/prodinfo (and all subdirectories) of the MIME types listed.

10.4.3 Logging
You can see information about how mod_deflate is performing by using:
򐂰 Custom deflate log file
򐂰 Communications trace
򐂰 HTTP server trace

Custom deflate log file

You can create a special deflate log file to capture the effectiveness of mod_deflate. This first
configuration example simply reports the ratio of the output stream versus the input stream.
Perform the following steps to define the custom log for compression.
1. From the IBM Web Administration for iSeries interface, click the Manage tab.
2. From the Server list, select the server you want to configure.
3. From the Server area list, select the Global configuration context.
4. In the left pane under Server Properties, click Compression.
5. In the Compression panel, select the Advanced tab.
6. On the Advanced page (Figure 10-18), complete these steps:
a. In the Deflate filter note section select the following:
• Filter note type: Ratio
• Filter note name: compratio
The specified parameter generates the following directive:
DeflateFilterNote Ratio compratio
The directive on its own does not cause any log entries to be written. Additional log
options need to be configured to create the desired log.
b. Click OK to save the configuration.

252 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 10-18 Compression: Advanced page Deflate filter note

7. In left navigation pane, click Logging.

8. In the Logging panel, click the Custom Formats tab.
9. On the Custom Formats page (Figure 10-19), complete these tasks:
a. Under Log formats, click Add to add a new log format entry.
b. Enter the following information:
• Format name: deflate
• Log format: %r %b (%{compratio}n)
c. Click Continue.
d. Click Apply to save the new entry.

Figure 10-19 Logging: Custom Formats page

10.Click the Custom Logs tab.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 253
 11.On the Custom Logs page (Figure 10-20), complete these steps:
a. Under Custom logs, click Add.
b. Enter the following information:
• Log: logs/deflate_log
• Attributes / Log format: deflate
c. You can also define additional attributes for log maintenance.
The Log format attribute relates to the custom format name that you defined in
Figure 10-19.

Figure 10-20 Logging: Custom Logs page

d. Click Continue.
e. Click OK to save the configuration.
12.Restart the server, access pages that are configured to be compressed, and open the
deflate_log file to see how the log format looks like.

Example 10-4 shows the directives that were added to your Global configuration server
context.
Example 10-4 mod_deflate: Simple deflate_log to report ratio of output stream to input stream
DeflateFilterNote Ratio compratio
LogFormat "%r %b (%{compratio}n)" deflate
CustomLog logs/deflate_log deflate

A portion of the deflate_log is shown in Example 10-5. After HTTP/1.1 are two numbers. The
first is the number of bytes sent for this request. The second in parentheses is the ratio, which
you can think of as a percentage.

The first line reads 2020 (18). This was for the file index.html, which in our application was
originally 10 876 bytes. That is, mod_deflate caused that file to compress to a file that is
approximately 18% of its original size.

254 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
For another example, consider the third line that reads 337 (101). This GIF file’s original size
is 314 bytes. mod_deflate, in this case, actually expanded the size of the file.

Another good example is the last line that reads 21057 (96). This JPEG file’s original size is
21 705 bytes. mod_deflate in this case barely reduced the size of this JPEG file.
Example 10-5 mod_deflate: Simple deflate_log
"GET / HTTP/1.1" 2020 (18)
"GET /clearpixel.gif HTTP/1.1" 52 (79)
"GET /Background.gif HTTP/1.1" 337 (101)
"GET /Home_Hp3.gif HTTP/1.1" 337 (17)
"GET /Projects_Np1.gif HTTP/1.1" 260 (13)
"GET /People_Np1.gif HTTP/1.1" 252 (13)
"GET /Services_Np1.gif HTTP/1.1" 259 (13)
"GET /Products_Np1.gif HTTP/1.1" 264 (14)
"GET /SiteMap_Np1.gif HTTP/1.1" 270 (14)
"GET /Downloads_Np1.gif HTTP/1.1" 281 (14)
"GET /BuiltByNOF.gif HTTP/1.1" 1130 (67)
"GET /Home_NBanner.GIF HTTP/1.1" 671 (31)
"GET /Ss02043.JPG HTTP/1.1" 21057 (96)

Example 10-6 shows another more complex format that provides more information and more
accurate results.
Example 10-6 mod_deflate: Accurate deflate_log to report ratio of output stream to input stream
DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio compratio
LogFormat "%r %{outstream}n/%{instream}n (%{compratio}n)" deflate
CustomLog logs/deflate_log deflate

Restriction: The LogFormat and CustomLog directives can be defined through the IBM
Web Administration for iSeries interface as explained earlier. However, the Advanced tab of
the Compression page does not allow you to add more than one DeflateFilterNote
directive. Therefore, if you want to set up the more complex compression logging scenario
as shown in Figure 10-6, you have to edit the configuration file and enter the
DeflateFilterNote directives manually.

As shown in Example 10-7, the deflate_log now produces more information. Three numbers
are present after the HTTP/1.1 text. The first number represents the number of bytes output
by mod_deflate. The second is the number of bytes as input to mod_deflate. And the third in
parenthesis is the ratio.
Example 10-7 mod_deflate: More accurate deflate_log
"GET /People/people.html HTTP/1.1" 2069/15190 (13)
"GET /Background.gif HTTP/1.1" -/- (-)
"GET /clearpixel.gif HTTP/1.1" -/- (-)
"GET /Home_Np1.gif HTTP/1.1" -/- (-)
"GET /Products_Np1.gif HTTP/1.1" -/- (-)
"GET /Projects_Np1.gif HTTP/1.1" -/- (-)
"GET /SiteMap_Np1.gif HTTP/1.1" -/- (-)
"GET /Downloads_Np1.gif HTTP/1.1" -/- (-)
"GET /Services_Np1.gif HTTP/1.1" -/- (-)
"GET /a_SatelliteDataIcon_4.gif HTTP/1.1" -/- (-)
"GET /People_Hp3.gif HTTP/1.1" 331/1820 (18)
"GET /BuiltByNOF.gif HTTP/1.1" -/- (-)
"GET /People_NBanner.GIF HTTP/1.1" 727/2159 (33)

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 255
 "GET /DataIcon.GIF HTTP/1.1" 162/175 (92)
"GET /People/a_ArrowLine.gif HTTP/1.1" 99/1620 (6)
"GET /Employees_Ns1.gif HTTP/1.1" 340/1821 (18)

Tip: In Example 10-7, some of the lines show “-/- (-)” for the effects of mod_deflate on
the file being served. This is written to the log file when the if-modified-since rule sends a
304 (not modified) response.

Communications trace
Using the iSeries communications trace, you can see the HTTP headers that are affected by
the use of the mod_deflate module. See 13.2.9, “Communications trace” on page 353, for
information about how to start, stop, print, and then delete an iSeries communications trace.

Example 10-8 shows an example of the HTTP get request from a Web client to the HTTP
Server (powered by Apache) that accepts compression for the file /index.html using
mod_deflate. The HTTP header ACCEPT-ENCODING is highlighted in bold.
Example 10-8 HTTP get: Request showing ACCEPT-ENCODING of GZIP and DEFLATE
*E..A.*@.}..*..*......*.@+T***.***
*P.*.**..GET /INDEX.HTML HTTP/1.1*
*..ACCEPT: */*..REFERER: HTTP://A*
*S20:8000/SITEMAP/SITEMAP.HTML..A*
*CCEPT-LANGUAGE: EN-US,ES-CO;Q=0.*
*5..ACCEPT-ENCODING: GZIP, DEFLAT*
*E..USER-AGENT: MOZILLA/4.0 (COMP*
*ATIBLE; MSIE 6.0; WINDOWS NT 5.1*
*; .NET CLR 1.1.4322)..HOST: AS20*
*:8000..CONNECTION: KEEP-ALIVE...*
*..L.* *

As shown in Example 10-9 here is the reply from the HTTP Server (powered by Apache).
Some comments related to the headers that we have highlighted in bold.
򐂰 CONTENT-ENCODING: GZIP: This header tells the client how the information was
encoded.
򐂰 CONTENT-LENGTH: 2020: This header is found on all replies. The interesting point is
that the original /index.html file was 10867 bytes. This suggests a five-fold decrease in the
size of the document.
Example 10-9 HTTP reply: Content headers indicating that the data was compressed
*E..*..@[email protected].......*..@.**.**+T***
*P.****..HTTP/1.1 200 OK..DATE: T*
*UE, 24 JUN 2003 15:29:52 GMT..SE*
*RVER: APACHE..LAST-MODIFIED: FRI*
*, 29 MAR 2002 01:56:13 GMT..ETAG*
*: "1F601-2A73-35082940"..ACCEPT-*
*RANGES: BYTES..VARY: ACCEPT-ENCO*
*DING,USER-AGENT..CONTENT-ENCODIN*
*G: GZIP..CONTENT-LENGTH: 2020..K*
*EEP-ALIVE: TIMEOUT=300, MAX=95..*
*CONNECTION: KEEP-ALIVE..CONTENT-*
*TYPE: TEXT/HTML; CHARSET=WINDOWS*
*-1252.....*........*Z¢S*8..***.G*
*****.*@HG.R*-*;****LVJ*K*.H****.*
*:******|.L:IOX.****;**S$.?U*.*V**

256 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 **.*R.*****.*P*O*.!*Z***V**%*.2***
*O.!****_**P**O**U**=**C**A*_*****
******<*..*AGHZ=*JJ*.**LZ*'*GD*T6*
...

Tip: A communications trace is a good tool for problem determination with mod_deflate.
For example, if your Internet Explorer browser is configured for proxy, it may not be sending
the accept-encoding HTTP header. The reason is most likely that your Web client is
configured to use HTTP/1.0 for the proxy connection, which does not support deflate. A
communications trace shows that the Web client is not sending in the accept-encoding
HTTP header.

To configure your Internet Explorer Web client to use HTTP/1.1 for the proxy connections,
select Tools →Internet Options. Click the Advanced tab and select Use HTTP 1.1
through proxy connections. If you select this options, you see the accept-encoding
header in your communications trace.

HTTP server trace

You can turn on the HTTP server trace by using option -vv (verbose) to capture details about
the processing of each file by mod_deflate. See 13.2.5, “HTTP server trace” on page 341.

By repetitively searching for Zlib in the spooled file created by the HTTP server trace, we
found the statements shown in Figure 10-10. It is interesting to note that last line in
Example 10-10 for URL /cgi-bin/MACRO1.MBR/run is the output of a Net.Data macro that
was also compressed to about 25% of its original size.
Example 10-10 mod_deflate logging which files were compressed and to what size
000000ED:233144 Zlib: compressed 10867 to 2002 : URL /index.html.
000000EC:057400 Zlib: compressed 6751 to 1290 : URL /Products/products.html.
000000EB:114480 Zlib: compressed 15190 to 2069 : URL /People/people.html.
000000EB:265264 Zlib: compressed 10631 to 2869 : URL /cgi-bin/MACRO1.MBR/run.

10.4.4 Controlling the compression environment

In addition to the directives that control the kind of traffic that is going to be compressed or
decompressed, you can configure directives that control the compression behavior of the
mod_deflate module. The HTTP Server (powered by Apache) provides default values for
these directives. Here is a brief description of the available directives:
򐂰 DeflateBufferSize: Specifies the size in bytes, kilobytes, megabytes, or gigabytes of the
fragments that zlib should compress at one time. The default value is 8096 bytes.
򐂰 DeflateCompressionLevel: Specifies the level of compression to be used. The higher the
value is, the greater the compression is. Higher compression levels require additional CPU
time. The default level value specifies a level of compression that does not significantly
increase CPU time on most systems. The default level value is 6.
򐂰 DeflateMemLevel: Specifies how much memory should be used by zlib for compression,
in 16K increments. A value of 1 equates to 16K, while a value of 8 equates to 128K. The
default value is 9 (144K).
򐂰 DeflateWindowSize: Specifies the zlib compression window size (the history buffer) in
16K increments. A value of 9 equates to 144K, while a value of 15 equates to 240K.
Generally, the higher the window size is, the higher the compression ratio and greater
usage of memory are. The default value is 15 (240K).

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 257
 Note: Modifying these directives can have a positive or negative impact on performance
and CPU load. The default values shipped with the system fit most environments. If you
need to modify the compression environment, familiarize yourself with the compression
module and the impact these directives have. You can find more information at:
򐂰 http://httpd.apache.org/docs-2.0/mod/mod_deflate.html
򐂰 http://www.gzip.org/zlib/zlib_docs.html

Using the IBM Web Administration for iSeries interface, you can modify these directives by
performing the following steps:
1. Select your server and the context for which you want to configure compression.
2. From the left navigation pane, click Compression.
3. On the Compression panel, click the Advanced tab.
4. On the Advanced page (Figure 10-21), modify the performance related compression
directives. Click OK to save the changes.

Figure 10-21 Compression: Advanced tab

5. Restart the server to activate the new settings.

10.4.5 For more information

There is documentation on the Apache Web site about mod_deflate that has information
specific to setting up for compression. That site offers the best place to look for details:
http://httpd.apache.org/docs-2.0/mod/mod_deflate.html

The HTTP Documentation site has some documentation on the use of mod_deflate. See:
http://www-1.ibm.com/servers/eserver/iseries/software/http/docs/doc.htm

258 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 For more information about log formats, go to:
http://httpd.apache.org/docs-2.0/en/mod/mod_log_config.html#formats

10.5 Triggered Cache Manager

As demonstrated in Figure 10-3 on page 227, each time the client requests a page, the HTTP
request must go through this process:
1. It goes through the network and passes each communication component such as firewall,
routers, proxies, and so on.
2. It goes through the HTTP Server (powered by Apache) to identify that the request must be
redirected to an application server.
3. The application server must in turn call the application.
4. The application processing the request may have to rely on many LOB database queries
(or any other required tasks) to generate the dynamic content of the HTML page.
5. Even after the HTML is generated, this response must flow all the way back down the line.

If a different client or even the same client requests the information again, the whole process
must be repeated. Even if the application has an application cache that can reduce the
number of queries into the LOB database, the amount of processing required to get to the
object stored in the application cache can be extremely large.

If you extend this environment to one with hundreds or even thousands of clients, CPU cycles
(alone) required to process the requests increase considerably. At this point, it can be better if
the implementation included a mechanism to serve client requests without going through the
whole process every time.

In this implementation, create the dynamic content in a proactive fashion and copy it to the
iSeries IFS or perhaps a router with a cache mechanism. Either way, now when the client
sends the request, dynamic content is already cached in the iSeries IFS or router. In this way,
the request can be processed with less demand on server resources and the response time
for the client improved.

TCM is a component in the iSeries server that was created exactly for this purpose. This
component is packaged in the IBM HTTP Server, 5722-DG1 Option 1. See Table 2-2 on
page 20 for the details about how 5722-DG1 is packaged.

The TCM is a TCP server. It may be used in conjunction with Web servers and Web
document caching agents to keep Web sites running at peak performance.

TCM is:
򐂰 A cache manager, not a cache or cache server
򐂰 Based on trigger messages
This means you must set up application triggers for the server to work. These messages
are sent to the TCM via the HTTP/1.0 protocol.
򐂰 A stand-alone server that can work with multiple types of caching mechanisms, for
example caching routers, proxy caches, and so on
It is useful in the environment we describe here for the HTTP Server (powered by
Apache), but it can be used for the HTTP Server (original), Domino, or WebSphere
Application Server environments as well.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 259
 TCM is proactive (based upon updates to an LOB database) in the update of Web content.
TCM causes the Web content to be dynamically regenerated and then placed in a location
(usually the iSeries IFS) that was configured to be served as static content by your Web
server. The TCM is most effective for a Web site that has a large number of requests for
content that is somewhat constant, but changes frequently.

One of IBM’s first uses of the TCM concept was to drive the 1996 Summer Olympic Games
Web site. Think of a downhill skiing results page (mostly HTML) that is composed of hundreds
of dynamic items including names, times, scores, and so on for a particular event. If, for every
request of that page, the application server had to re-run all the database queries to
dynamically calculate the content. That level of activity had the potential to bog down the
server with many repetitive actions. If only when the application LOB data was updated with
new results, then the application server was used to update a standard results page to be
served from a “static” portion of your Web site. This tremendously reduced the burden on the
application server.

10.5.1 TCM system requirements

The TCM server requires the following components to run:
򐂰 TCP/IP Connectivity Utilities, 5722-TC1 licensed program
򐂰 IBM Developer Kit for Java, 5722-JV1 licensed program

Note: TCM does not require IBM Developer Kit for Java, 5722-JV1. It uses Java
support shipped with OS/400. Currently the Start TCP/IP Server (STRTCPSVR)
command erroneously checks for 5722-JV1. A V5R1 PTF (SI02889 for product
5722-SS1) corrects this problem. This level of support is built into OS/400 starting with
V5R2.

򐂰 IBM HTTP Server, 5722-DG1 licensed program

򐂰 Triggered Cache Manager, 5722-DG1 option 1
򐂰 The latest 5722-DG1 group PTF:
– V5R1: SF99156
– V5R2: SF99098
– V5R3: SF99099

Note: If you plan on using TCM with WebSphere Application Server (as the configured
Data Source), then you need a special 5722-DG1 PTF:
򐂰 V5R1: SI09801
򐂰 V5R2: SI09799

This fix is integrated into i5/OS V5R3 of 5722-DG1.

The TCM server runs under its own user profile, which is QTCM.

The TCM configuration process should be done using the GUI. Do not edit the TCM
configuration files directly. Configuration APIs are also available if you want to create your
own configuration utility. See the following section.

260 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.5.2 TCM documentation
The following documents provide greater detail about the workings of TCM:
򐂰 A complete list of APIs to allow you to configure TCM in HTTP Server for iSeries
Programming, GC41-5435. The configuration GUI that IBM provides for you as part of
5722-DG1 option 1 uses these APIs. Most likely, you do not have to use these APIs.
򐂰 Articles in the iSeries Information Center about TCM:
http://publib.boulder.ibm.com/iseries/v5r3/ic2924/index.htm
Then search for TCM.
– Triggered Cache Manager: An overview of TCM
Follow these links: e-business and Web serving →HTTP
Server →Concepts →Triggered Cache Manager
– Trigger Messages: A description of the types and formats of the trigger messages that
are sent to the TCM server. These messages use the HTTP/1.0 protocol.
Follow these links: e-business and Web serving →HTTP
Server →Concepts →Trigger messages
– Set up Triggered Cache Manager
Follow these links: e-business and Web serving →HTTP
Server →Tasks →Triggered Cache Manager →Set up Triggered Cache Manager
This article demonstrates how to use the default configuration that is shipped with TCM
on the iSeries server. Depending on how your Web application is configured, this may
be an easy way to see TCM working quickly.
This article also has a custom configuration example that leads you through all the
options available when configuring TCM on the iSeries server.

Note: You can find a working example using a subset of all the complexity that is
offered by a full implementation of TCM in 10.5.5, “Configuring a working TCM
example” on page 264.

10.5.3 TCM directory structure and authorization

The TCM server has its own directory structure (Table 10-1), which is used to keep
configuration and log files and various other data files required by the server.
Table 10-1 TCM directory structure
Directory Description

/QIBM/UserData/TCM/instance/ This is the TCM root directory. Under this directory, the TCM
server configuration process creates the directory used by each
TCM server.

/QIBM/UserData/TCM/instance/ This is the root directory of your server_name TCM server.

server_name

/QIBM/UserData/TCM/instance/ This is the TCM configuration file.

server_name/daedalus.ini

The user profile QTCM requires *RWX data authorities and *ALL object authorities to the
/QIBM/UserData/TCM directory and all files within it.

Tip: You should use only the configuration GUI or the APIs to alter the configuration files.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 261
10.5.4 How the TCM server works
The steps involved before and during the TCM process are explained here:
1. Your HTTP server is configured to serve static content from a subdirectory in the IFS. The
content in this subdirectory is undefined at this point. These files may be missing or
contain old data.
2. Monitor for data changes.
Either your application or possibly a DB2® Universal Database™ (DB2 UDB) database
trigger can be used to determine that data was changed. And, this is not just any data, but
data upon which one or more dynamic Web pages depends.

Tip: It is beyond the scope of this IBM Redbook to explain how to write an application to
create trigger messages. Here are some suggestions:
򐂰 Write a sockets client application that connects to the TCM server at the default port
of 7049 and establish a connection. You have to simulate the HTTP/1.0 protocol,
which is similar to the simulation we do by Telnet in this section. On the iSeries
server, you can do this in any programming language.
򐂰 Write a Java application and take advantage of the java.net.HttpURLConnection and
java.net.URL class files.

3. Send a trigger message to the TCM trigger handler with the information about the data
that was changed.
Trigger request handlers perform the fundamental operations of a TCM server and are the
key server feature. When a server starts, it creates a request handler for each description.
The descriptions tell the server which type of trigger handler to create, the resources it
must use, the process rules it must follow, and other various settings required for the
particular type of defined handler. Trigger messages sent to a TCM server must address
one of the request trigger handlers.
For example, TCM defines a standard trigger handler for administration named admin. As
another example, if you configure a trigger handler by the name of PRODUCTLIST, the
name created by TCM at startup is TRH_PRODUCTLIST.
TCM supports two types of trigger handlers:
– Update Cache: Tells the TCM server to create a trigger request handler that performs
basic data transfers. It transfers (or copies) data from a data source to one or more
cache targets. A description of this type contains:
• A reference to a data source description, describing where data is located and how
to obtain it.
• References to one or more cache target descriptions, describing where the caches
are located and how to work with them.
• References to one or more acknowledgment target descriptions, describing where
to send completion messages.
• Various other settings required for trigger request handlers.

Tip: The easier choice is to use Update Cache. The data source is the Web
application (WebSphere Application Server or Net.Data are two examples). The
cache target is a subdirectory in the IFS.

262 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 – Publish: Tells the TCM server to create a trigger request handler that performs
document publishing. A publish handler receives a list of document fragment names as
input. It fetches each fragment from the configured data source, passes them through a
dependency parser to update the object dependency graph, assembles the fragments
into documents that can be served, and transfers (or copies) the fragments and
documents to one or more cache targets. A description of this type contains everything
an Update Cache type has as well as:
• A reference to an Object Dependency Graph (ODG) description, describing where
persistent publishing data may be stored
TCM determines which pages need to be updated by consulting an ODG. This
ODG is a data repository used to store dependency relationships for the pages the
server handle. Therefore, when the data changes, TCM finds out what pages
depend on the changed data. After all of the pages that are affected by the change
are located, they are removed from cache and restored with the newly updated
content. This then allows the dynamic update of the caching without restarting the
server.
• A reference to a rule set description, describing how to process document
fragments and servable documents and files
• Various other settings
4. Allow TCM to request the dynamic page from the data source.
When a TCM server needs to retrieve data (HTML documents, images, and video clips, for
example) it uses information from a data source description to determine where the data is
located and how to obtain it.
TCM supports two types of data sources:
– File System: Tells the TCM server it must use a file system to retrieve data. The server
retrieves data by reading files from the iSeries IFS. A description of this type contains a
directory path serving as the root to data files.

Tip: This option allows you to retrieve a file that is physically in the same iSeries
server as is the TCM server. Using tools such as Network File System (NFS) or
QFileSvr.400, the file can be physically located anywhere in your TCP/IP network.

– HTTP Server : Tells the TCM server it must communicate with a Web server to retrieve
data. The TCM server retrieves data by using HTTP to request files from a Web server.
A description of this type contains information about the system hosting the Web
server, the TCP port the server is using, the URL path for the data files, and other
required settings.

Tip: The HTTP server can be located anywhere in your TCP/IP network since it is
referenced using a fully qualified URL. This includes sending the request to an
HTTP server running on the same iSeries server that is running your TCM server.

5. Allow TCM to update the dynamic page content stored in the IFS or other cache targets.
When a TCM server needs to manage data in a cache, it uses information from a cache
target description to determine where the cache is located and how to work with it. A
description may list one or more targets. Each listed target is managed in a similar
manner.
TCM supports three types of cache targets:

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 263
 – HTTP Server : Tells the TCM server that it must communicate with a Web server to
manage cache data. The server manages cache data by using HTTP to get, put, and
delete files from a Web server. A description of this type contains a list of systems
hosting Web servers, the TCP port the servers are using, the URL path for the cache
data files, and other required settings.

Tip: While TCM on the iSeries server provides the mechanism to get, put, and
delete files to a remote (or local) Web server, a complete solution for this option
must include a CGI application running on the target HTTP server. IBM does not
provide any example CGI applications. You are the one who must write this CGI
application to handle the POST data.

– Router : Tells the TCM server that it must communicate with a router to manage cache
data. The server manages cache data by using special protocols, such as External
Cache Communication Protocol (ECCP) or Web Cache Control Protocol (WCCP), to
work with files in the router’s Web document cache. A description of this type contains
a list of routers hosting Web document caches, the TCP port the routers are using, and
various other settings.

Tip: The only routers we know that support this are the IBM Model 2212 and 2216
network routers via the ECCP protocol.

– File System: Tells the TCM server that it must use a file system to manage cache data.
The server manages cache data by reading, writing, and deleting files in iSeries IFS. A
description of this type contains directory paths serving as roots to data files.
This is the easiest method because TCM simply writes file into the IFS on your iSeries
server. This is also the most practical solution. In this case the IFS can be thought of as
a cache target for TCM. Remember, that TCM is not a cache, but a cache manager.

Tip: This option allows you to place a file into the IFS on the same iSeries server
that the TCM server is. Using such tools as NFS or QFileSvr.400, you can physically
move the file to anywhere in your TCP/IP network.

There are multiple scenarios where you can use TCM. One for example can be an HTTP
server with one TCM server. Another example is multiple HTTP servers with multiple TCM
servers. Or there can be a combination between HTTP and TCM servers. All scenarios occur
on one or many iSeries servers.

10.5.5 Configuring a working TCM example

This section documents a TCM server working in cooperation with an existing Web
application. The steps that are involved are:
1. Define the environment.
2. Create and configure the HTTP Server (powered by Apache).
3. Create and configure the TCM server.
4. Test the TCM server.
5. Test interaction between TCM and HTTP Server (powered by Apache).

264 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Defining the environment
For an example of the power of TCM, we provide a fairly simple Web application as shown in
Figure 10-22 on page 266. An HTTP Server (powered by Apache) named PBATCM00 serves
both:
򐂰 Primarily static content from the iSeries IFS under the DocumentRoot of
/tcp52d00/TCM/ITSOco. Specifically, a file in <DocumentRoot>/Products/products.html is
also configured to be served as static content even though TCM is dynamically updating
the products.html file whenever it receives a specially coded trigger message.
򐂰 A single dynamic page that is generated by an SQL select query against a table in an LOB
database file. The URL to evoke the Net.Data application is:
http://as20:8700/cgi-bin/MACRO1.MBR/run

A TCM server named TCMserv00 waits for a trigger message via the HTTP/1.0 protocol.
When it receives this trigger message, it updates the static IFS file products.html from the
dynamic content found in the LOB database table.

The following steps explain how this works. Each step corresponds to the number in
Figure 10-22.
1. Both the TCM and HTTP Server (powered by Apache) servers are configured and started.
The content of <DocumentRoot>/Products/products.html is undefined at this stage. That
is, a file may be either missing or have old data in it from the last time it was updated.
2. A trigger message is sent to the TCMserv00 TCM server’s Trigger Handler
PRODUCTLIST. This message was most likely generated by an update to an SQL table
that caused the static HTML in the products.html file to become out-of-date. Some events
may include:
– A database trigger, coded as part of the LOB database, detects that a table is updated.
– An application running on the iSeries directly updates the LOB database.
– An event occurs, such as the HTTP Server (powered by Apache) server has started.
The protocol for the trigger message is HTTP Version 1.0. The syntax of the trigger
message is:
-update -from /MACRO1.MBR/run -to /products.html
Notice the following explanation:
– -update: Indicates that this trigger message is to update a cache target
– -from: Defines the data source
– -to: Defines the cache target
3. The TCM server behaves as an HTTP client and prepares an HTTP GET request for the
URL:
http://as20:8700/cgi-bin/MACRO1.MBR/run
This URL is generated based on the TCM server’s configuration (see Figure 10-22 for all
the configuration values used in this scenario) and the text /MACRO1.MBR/run, which
immediately followed the -from parameter. In this case, the URL is:
http://<Host>:<TCP Port>/<Root Directory>/MACRO1.MBR/run
4. The HTTP Server (powered by Apache) PBATCM00 is configured to evoke a Net.Data
macro that dynamically generates HTML and returns it to the client.

Tip: In general, the URL http://as20:8700/cgi-bin/MACRO1.MBR/run is a hidden way

into your Web application. Normally your (non-TCM) Web clients do not link this URL in
any HTML page.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 265
 5. The HTML result of the Net.Data macro invocation is returned to the TCM server by the
HTTP Server (powered by Apache).
6. The TCM server then writes the HTML results as a file to the iSeries IFS:
/tcp52d00/TCM/ITSOco/Products/products.html
The path and name of this file are generated based on the TCM server’s configuration
(see Figure 10-22) and the text /products.html, which immediately followed the -to
parameter on the trigger message. In this case, the path and name are:
<Target Directory>/products.html
7. The next and all subsequent requests for the URL
http://as20:8700/Products/products.html are served as static HTML content by the
HTTP Server (powered by Apache) PBATCM00.

Tip: You may be inclined to also use the HTTP Server (powered by Apache) local
cache to further cache the resultant HTML file. But, HTTP Server (powered by Apache)
local cache with dynamic update simply invalidates the local cache entry (forcing the
HTTP server to go to the IFS anyway) and does not recache the file. And, worse, the
dynamic update option for the local cache causes the HTTP Server (powered by
Apache) to always check to see if the file is updated. This causes extra I/O operations,
slowing down your HTTP server. See “What to cache?” on page 237 for more details
about the local cache options.

FRCA local cache does work in this environment. This is because FRCA local cache
automatically updates the contents of the NFC when a static file in the IFS changes.
See 10.6.2, “How FRCA local cache works” on page 283.

Triggered Cache Manager Trigger message via HTTP/1.0: 2

TCM Server: TCMserv00 -update -from /MACRO1.MBR/run -to /products.html LOB
Listen: *:7049 DB
Host: as20.itsoroch.ibm.com
Data Source: GenerateProductList 3 Web application
TCP Port: 8700
Type: Net.Data as PBATCM00's CGI
Root Directory: /cgi-bin
URL to evoke SQL query of LOB DB:
Cache Target: TargetProductList
http://as20:8700/cgi-bin/MACRO1.MBR/run
6 Target Directory:
/tcp52d00/TCM/ITSOco/Products
Trigger Handler:PRODUCTLIST
5 4
HTTP Server (powered by Apache)
IFS 7 Server: PBATCM00
files Listen: *:8700
ServerRoot: /tcp52d00/TCM
<DocumentRoot>/Products/products.html
DocumentRoot: /tcp52d00/TCM/ITSOco

MI
Browser
TCP/IP

Figure 10-22 TCM: The environment defined

After you understand all the pieces of the configuration, the actual configuration steps are
quite simple and straight forward.

266 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Creating and configuring the HTTP Server (powered by Apache)
You must now create an HTTP Server (powered by Apache) with the characteristics defined
in Table 10-2.
Table 10-2 TCM: HTTP Server (powered by Apache) used to serve Web application
Parameter Value

Server name PBATCM00

Server root /tcp52d00/TCM

Document root /tcp52d00/TCM/ITSOco

IP address All

Port 8700

ScriptAlias /cgi-bin/ /qsys.lib/tcp52lmast.lib/db2www.pgm/

Example 10-11 shows the final configuration file for the PBATCM00 HTTP Server (powered
by Apache). This is a fairly standard configuration. Most of the work that this server does is to:
򐂰 Serve static files from the DocumentRoot /tcp52d00/tcm/itsoco and all subdirectories. One
of the subdirectories that we are interested in is /tcp52d00/tcm/itsoco/products because
this is where TCM will place the HTML results file named products.html.
򐂰 Using the ScriptAlias directive and the directives found within the <Directory
/qsys.lib/tcp52lmast.lib/> content, allow this HTTP Server to evoke a Net.Data macro that
does an SQL select into a table.
Example 10-11 TCM: Configuration file for PBATCM00 HTTP Server (powered by Apache)
# Configuration originally created by Apache Setup Wizard Tue May 27 21:30:43 UTC 2003
ScriptAlias /cgi-bin/ /qsys.lib/tcp52lmast.lib/db2www.pgm/
Listen *:8700
DocumentRoot /tcp52d00/tcm/itsoco
ServerRoot /tcp52d00/tcm
DefaultType text/plain
Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes -IncludesNoExec -Indexes
-MultiViews
ErrorLog logs/error_log
LogLevel Warn
DirectoryIndex index.html
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%{Cookie}n \"%r\" %t" cookie
LogFormat "%{User-agent}i" agent
LogFormat "%{Referer}i -> %U" referer
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log combined
SetEnvIf "User-Agent" "Mozilla/2" nokeepalive
SetEnvIf "User-Agent" "JDK/1\.0" force-response-1.0
SetEnvIf "User-Agent" "Java/1\.0" force-response-1.0
SetEnvIf "User-Agent" "RealPlayer 4\.0" force-response-1.0
SetEnvIf "User-Agent" "MSIE 4\.0b2;" nokeepalive
SetEnvIf "User-Agent" "MSIE 4\.0b2;" force-response-1.0
<Directory />
Order Deny,Allow
Deny From all
</Directory>
<Directory /tcp52d00/tcm/itsoco>
Order Allow,Deny
Allow From all

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 267
 </Directory>
<Directory /qsys.lib/tcp52lmast.lib/>
Order Allow,Deny
Allow From all
Options +ExecCGI
</Directory>

Creating and configuring the TCM server

Follow these steps to create a new TCM server named TCMserv00. After a new server is
created, it may be custom configured and managed using the other forms available from the
navigation frame.
1. From the IBM Web Administration for iSeries interface, click the Advanced tab and then
the TCM subtab.
2. In the left pane, click Create server.
3. In the right panel, for Server Name, enter your TCM server name. In our example, this is
TCMserv00. Leave the other parameters as the defaults. Click Create.

Figure 10-23 TCM: Creating the server TCMserv00

268 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
4. As shown in Figure 10-24, in the left pane, select your TCM server from the list. All the
configuration settings that you specify are then applied to this TCM server so make sure
that you select the correct ones.

Tip: You may have to refresh your Web client view of this frame to see your new TCM
server. In Internet Explorer, press F5.

Figure 10-24 TCM: Selecting your TCM server by name

Now that the TCM server TCMserv00 is created, simply use the left pane to configure this
server one object at a time. TCM allows for a flexible configuration with many named
objects that can be used and reused by many different trigger monitors. Our path is
simple.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 269
 5. As shown in Figure 10-25, click Basic settings to change any of the basic settings for the
TCM server. For this example, we do not make any changes. At any point, you can click
the help icon which is a little question mark (?) in a circle.

Tip: One of the interesting parameters is the number of threads. It specifies the number
of concurrent threads that are spawned by the TCM server when it communicates with
remote clients and servers. TCM operates as a multi-threaded server application. It is
also queue-based because it uses messages between the threads to request work and
manage work load. It is possible on a busy iSeries that a single or group of HTTP client
requests for a dynamic page can take some time. As TCM waits for the HTML response
from the Data Source, more work can queue up.

You can monitor these queues and the work involved to help you determine if changing
this number to something bigger can help you for your Web application. See step b on
page 277 for an example of determining the status of all the TCM queues.

Figure 10-25 TCM: Changing the basic settings

270 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
6. As shown in Figure 10-26, click Hosts to define configuration settings used to describe
computer systems that host servers of interest to a TCM server. Computer systems (such
as an iSeries server) may host a number of different server types. When a TCM server
needs to communicate with another server, it reads a host description to obtain the IP
address or host name of the system hosting the server. Again, use the help icon for more
details.
7. In our case, we can use the default LOCALHOST since the host servers we will use are all
on the same server. But, we create a host description for our local system. To do this, click
Create New Description and enter your iSeries host name. Click Create.

Tip: You must list host names that can be resolved to IP addresses. That is, do not
specify host names that do not exist.

Figure 10-26 TCM: Creating a host description

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 271
 8. Click Data sources to describe a data source to a TCM server. When the TCM server
needs to retrieve data, it uses information from a data source description to determine
where the data is located and how to obtain it.
TCM supports two types of data sources: file system and HTTP server. In our scenario, we
use an HTTP Server as a data source.
9. Click Create New Description.
10.Complete the following steps (see Figure 10-27):
a. In the Name field, type the name of your data source. In our case, we enter
GenerateProductList.
b. For the Type, select HTTP Server.
c. Click Next to see the rest of the parameters needed for this data source.
d. For Host, select as20.itsoroch.ibm.com, which was created earlier.
e. For TCP Port (1-65535), type 8700, which is the port on which our HTTP Server
(powered by Apache) Web application is listening.
f. For the Root Directory, type /cgi-bin, which is a sort of prefix used to create the
Uniform Resource Identifier (URI) for the data source. This can be “/”, but it requires
every trigger message to be longer.
g. Click Create.

Figure 10-27 TCM: Creating a data source description

11.Click Cache targets to configuration settings used to describe data caches to a TCM
server. TCM supports three types of cache targets: HTTP server, router, and file system.
In our scenario, we use the file system as the cache target.
12.Click Create New Description.

272 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
13.Complete the following steps (see Figure 10-28):
a. In the Name field, type the name of your cache target. In this case, we enter
TargetProductList.
b. For Type, select File System.
c. Click Next to see the rest of the parameters needed for this cache target.
d. For Directory, type /tcp52d00/TCM/ITSOco/Products, which is sort of a prefix for the
path in the IFS to place the result file. This can be “/”, but it requires every trigger
message to be longer.
e. Click Create.

Figure 10-28 TCM: Creating a cache target description

14.In the left pane, Acknowledgement targets are descriptions of configuration settings used
to describe where a TCM server sends completion messages after handling requests.
When a TCM server completes a request, it may optionally send completion messages to
inform someone (or something) that it handled a request. It uses information from an
acknowledgment target description to determine where to send such messages. A
description may list one or more targets. Each listed target is sent identical messages.
For this example, we do not specify an Acknowledgement target.
Click Trigger handlers to describe internal trigger request handlers for a TCM server.
TCM supports two types of trigger handlers: publish and update cache. In our scenario,
we use update cache.
15.Click Create New Description.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 273
 16.Complete the following steps (see Figure 10-29):
a. In the Name field, type the name that you will use for your trigger handler. In our case,
we enter PRODUCTLIST.
b. For Type, select Update Cache.
c. Click Next to see the rest of the parameters needed for this trigger handler.
d. For Data Source, select GenerateProductList.
e. For Cache Targets, select TargetProductList.

Tip: You can select multiple cache targets by holding down the Ctrl key and selecting
each item in the list.

f. For the remaining parameters, accept the defaults.

g. Click Create.

Figure 10-29 TCM: Creating a trigger handler description

This completes the configuration for the trigger handler PRODUCTLIST. The next step is to
test the TCM server.

Testing the TCM server

First, you must start the TCM server and pass it a few simple requests to make sure it is
running properly. These requests must be in the form of trigger messages.

274 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Before continuing, we explain how TCM trigger messages are formed. First, TCM uses HTTP
Version 1.0 (written as HTTP/1.0) as the protocol to carry the trigger messages. HTTP was
chosen because it is a common protocol and easy to pass between systems and through
firewalls. It is this requirement for HTTP/1.0 that leads us to the requirement that TCM’s
trigger messages be created by an application since there is really no native way on the
iSeries server to generate the HTTP/1.0 protocol as a client. This application can reside on
your iSeries or on any other system in your network.

Tip: It is beyond the scope of this IBM Redbook to explain how to write an application to
create trigger messages. For this scenario, we use a Telnet VT100 client to simulate an
HTTP client. You need a Telnet client that can locally echo the characters you are typing as
you emulate an HTTP client when sending trigger messages to the TCM server. We used
ZOC/Pro 4.11. You may download a 30-day evaluation copy from the Web at:
http://www.emtec.com/main.html

We made a configuration change to the defaults with ZOC. This was to change the session
options to always “start session with local echo on”. Select Options →Edit Session
Profile... Select the Device tab. For the Telnet I/O Device, select Start session with local
echo on. Click Save.

Second, we use the HTTP post method to send trigger messages to the TCM server. Here is
an example for the syntax to query the /admin/ trigger handler for its -v[ersion].
post /admin/ http/1.0<Enter>
content-length: 3<Enter>
<Enter>
-v<Enter>

Tip: The syntax for the HTTP protocol is specific and unforgiving.
򐂰 <Enter> means to press the Enter key (or carriage return). And, yes, the third line in the
sample above is asking you to press the Enter key all by itself.
򐂰 The content-length value must be precise. It should include all the characters including
spaces and the <Enter> for the line that immediately follows it.
򐂰 If you make a mistake while typing the post syntax, the only way to fix it is start all over
again. The Backspace key on your keyboard is not recognized by the TCM (nor any
other HTTP) server.
򐂰 If you are going to use this Telnet client to emulate an HTTP client repeatedly, you may
want to investigate using macros to record your keystrokes so you can accurately
repeat them without making a mistake.
򐂰 The URI path information is case sensitive. For example, the following path causes the
TCM server to send the HTTP/1.0 404 (file not found) to the client:
post /Admin/ http/1.0<Enter>

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 275
 OK, now we are ready to start the TCM server and test it:
1. Start the TCM server. Click Work with servers, select the server you want to start (we
selected TCMserv00) and click Start (see Figure 10-30). This process seems to take a bit
of time. The server should not stay with a Starting status for more than one minute. Click
Refresh until the status becomes Active.

Figure 10-30 TCM: Working with servers and clicking Start

2. Determine the version of TCM that is running on your iSeries server. Follow these steps:
a. Use ZOC to Telnet to port 7049 on your iSeries server. Figure 10-31 shows the settings
that we used for this client connection. Click Options to turn on local echo if it is not
already enabled for this terminal session.

Figure 10-31 TCM: Using ZOC to Telnet to the iSeries TCM server at port 7049

b. In ZOC, type the following HTTP/1.0 syntax. -v is a shorthand notation for -version.
post /admin/ http/1.0<Enter>
content-length: 3<Enter>
<Enter>
-v<Enter>

276 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 The TCM server should reply with something similar to:
HTTP/1.0 200
content-type: application/x-trigger-msglist
Content-length: 75

1152 0 0 admin ! Version: Daedalus 04042000A Started: 09/24/2004 14:44:37

[TELNET] INFO: DISCONNECTED

Tip: Daedalus was the IBM code name for the project that created TCM.

3. Determine the status of all the TCM queues. Follow these steps:
a. Use ZOC to Telnet to port 7049 on your iSeries server.
b. In ZOC, type the following HTTP/1.0 syntax:
post /admin/ http/1.0<Enter>
content-length: 8<Enter>
<Enter>
-queues<Enter>
The TCM server should reply with something similar to:
HTTP/1.0 200
content-type: application/x-trigger-msglist
Content-length: 1107

1140 1 1 admin ! SNK_LOCAL_DIRECTORY: active=0 queued=0 lifetime-total=0

lifetime-failed=0 lifetime-retried=0 threads=5
1140 1 1 admin ! SNK_TargetProductList: active=0 queued=0 lifetime-total=0
lifetime-failed=0 lifetime-retried=0 threads=5
1140 1 1 admin ! TRH_UPDATE_CACHE: active=0 queued=0 lifetime-total=0
lifetime-failed=0 lifetime-retried=0 threads=10
1140 1 1 admin ! SRC_LOCAL_HTTP: active=0 queued=0 lifetime-total=0
lifetime-failed=0 lifetime-retried=0 threads=5
1140 1 1 admin ! TRH_PUBLISH: active=0 queued=0 lifetime-total=0 lifetime-failed=0
lifetime-retried=0 threads=10
1140 1 1 admin ! admin: active=0 queued=0 lifetime-total=2 lifetime-failed=0
lifetime-retried=0 threads=0
1140 1 1 admin ! TRH_PRODUCTLIST: active=0 queued=0 lifetime-total=0
lifetime-failed=0 lifetime-retried=0 threads=10
1140 1 1 admin ! SRC_GenerateProductList: active=0 queued=0 lifetime-total=0
lifetime-failed=0 lifetime-retried=0 threads=5
1140 1 1 admin ! DeferQueue: active=0 queued=0 lifetime-total=0 lifetime-failed=0
lifetime-retried=0 threads=-1
1141 1 1 admin ! Lifetime total server requests=2
[TELNET] INFO: DISCONNECTED
As you can see, TCM uses many queues and many different handlers to operate even a
simple configuration like ours. The one we are interested in is TRH_PRODUCTLIST,
which is TCM’s name for the trigger handler PRODUCTLIST we created in “Creating and
configuring the TCM server” on page 268.

Testing interaction between TCM and HTTP Server (powered by Apache)

For this second part of the test, we start the HTTP Server (powered by Apache) and test the
interaction. For this step, we send the trigger handler TRH_PRODUCTLIST a trigger
message:
-update -from /MACRO1.MBR/run -to /products.html

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 277
 This trigger message causes TCM to make an HTTP request to the URL:
http://as20:8700/cgi-bin/MACRO1.MBR/run

And then TCM places the resulting HTML in the iSeries IFS path and file. Refer to
Figure 10-22 on page 266 to see how the configuration of TCM generates the desired output.
/tcp52d00/TCM/ITSOco/Products/products.html

Follow these steps to perform this task:

1. Start the HTTP Server (powered by Apache) PBATCM00.
2. Verify for yourself that the directory /tcp52d00/TCM/ITSOco/Products/ is empty. If it is not
empty, you may want to delete the file Products.html as a way to prove to yourself that
TCM has dynamically generated the file. Choose one of the following options:
– Map a network drive to the iSeries IFS or use the Work with Object Links (WRKLNK)
command as follows:
WRKLNK OBJ('/tcp52d00/TCM/ITSOco/Products/*')
If no objects are in the directory /Products, you should see the Work with Object Links
display (Figure 10-32).

Work with Object Links

Directory . . . . : /tcp52d00/TCM/ITSOco/Products

Type options, press Enter.

2=Edit 3=Copy 4=Remove 5=Display 7=Rename 8=Display attributes
11=Change current directory ...

Opt Object link Type Attribute Text

(Cannot find object to match specified name.)

Figure 10-32 Work with Object Links (WRKLNK) of /Products subdirectory

– Use a Web client to request the products.html document directly as shown in

Figure 10-33. Use the URL:
http://as20:8700/products/products.html

278 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 10-33 TCM: The /Products/products.html page is not found (yet!)

3. Send the trigger message to the TCM server. Follow these steps:
a. Use ZOC to Telnet to port 7049 on your iSeries server.
b. In ZOC, type the following HTTP/1.0 syntax:
post /TRH_PRODUCTLIST/ http/1.0<Enter>
content-length: 49<Enter>
<Enter>
-update -from /MACRO1.MBR/run -to /products.html<Enter>
The TCM server should reply with something similar to:
HTTP/1.0 202
content-type: application/x-trigger-msglist
Content-length: 58

1102 2 2 TRH_PRODUCTLIST ! update-sink request is queued

[TELNET] INFO: DISCONNECTED
As you can see, TCM queues the request on the TRH_PRODUCTLIST trigger handler.

Tip: The URI path information on the post is case sensitive.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 279
 4. To verify that the directory /tcp52d00/TCM/ITSOco/Products/ now has a file Product.html,
use a Web client as shown in Figure 10-34 using the URL:
http://as20:8700/products/products.html

Figure 10-34 TCM: The /Products/products.html page created by TCM’s actions

If this was a real Web application, the trigger message that was sent to the trigger handler
TRH_PRODUCTLIST would be sent by your custom-written application. At this point, the
HTTP Server (powered by Apache) PBATCM00 serves the static results file
/Products/Products.html at static file speeds.

When the raw data in the SQL table is updated (for example, if the price of one of the items
changes or a new item is added to the table), your application needs to send a new trigger
message to the trigger handler to cause the /Products/Products.html file to be updated.

280 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.6 Fast Response Cache Accelerator

Note: With permission from iSeries Network, we include material from an article written for
iSeries Network as a basis for this section. For the original article, see:
http://www.iseriesnetwork.com

FRCA (affectionately pronounced “Frica” by the Rochester developers) is a significant leap

forward in caching architecture for your HTTP Server (powered by Apache). FRCA is dramatic
in two ways. First, it can serve Web content at a whopping seven times faster than a file from
the IFS. And, it serves over four times faster than the traditional local cache in the HTTP
Server (powered by Apache). Second, FRCA does this with approximately four to seven times
less CPU per transaction.

To back up this claim, see iSeries Performance Capabilities Reference Version 5, Release 3,
SC41-0607, which is the center of release-to-release performance information about the
iSeries server. You can find it on the Web at:
http://www-1.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm

In this publication, see Section 6.1, which is dedicated to the HTTP Server (powered by
Apache). Table 10-3 is a subset of the information provided.
Table 10-3 iSeries Web serving capacity planning various transaction types
Transaction type Capacity CPU time
Metric: trans/sec per CPW Metric: CPW per trans/sec

Static Page (IFS) 1.75 0.57

Static Page (cache) 2.79 0.35

Static Page (FRCA) 13.01 0.08

For a rough guide as to the number of static pages you can serve from either the IFS, cached
(from the local cache of the HTTP Server (powered by Apache)) or the new FRCA cache,
multiply the published CPW of your iSeries server by the number you find in the Capacity
column.

For example, if you take an average iSeries Model 810 with 1470 Commercial Processing
Workloads (CPWs), you should expect the HTTP Server (powered by Apache) to serve
around 2570 static pages from the IFS per second. For the same system, you should expect
4100 from the HTTP Server (powered by Apache) local cache. For FRCA, expect 19,100!

The CPU Time column is equally exciting. If, on the same Model 810, you need to serve 2000
static pages per second, you can expect 1140 CPWs consumed every second served from
the IFS. The same files served from the local cache consume 700 CPWs per second. For
FRCA, expect just 160 CPWs per second!

FRCA provides a Fast Response Cache, and it accelerates the overall performance of your
system by freeing up your main processor or processors to do other things. To see where
FRCA fits into the overall performance picture of your HTTP Server (powered by Apache),
see Figure 10-3 on page 227.

FRCA, as we will see, can also cache “dynamic” content that you expire using a timer. But,
while TCM seems like the better choice for caching dynamic content, it requires programming
to make it work. FRCA, on the other hand, is just simple configuration.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 281
10.6.1 What FRCA is
FRCA is the external product name given to a software architecture named Adaptive Fast
Path Architecture (AFPA) developed by IBM Research. This architecture dramatically
improves the capacity/performance of Web and other TCP servers.

Only one application on the iSeries server takes advantage of FRCA in OS/400 V5R2 and
i5/OS V5R3. That is the HTTP Server (powered by Apache). That is, the architecture can be
used by any iSeries TCP application, but only the HTTP Server (powered by Apache) has
done so to date. To be clear, FRCA requires OS/400 at V5R2 or higher, plus the LPP IBM
HTTP Server (5722-DG1).

FRCA directives are simply embedded within the HTTP Server (powered by Apache)
configuration file (httpd.conf). This enables your HTTP server to use the FRCA cache. FRCA
can be enabled for each listen port in the server configuration. This allows you to make a
choice whether you use FRCA cache for each Listen on a specific <IP address:port>.

You can cache static content by specifying a specific file name or a group of files using wild
cards, such as the asterisk (*). The loading of the cache occurs during HTTP server startup or
at runtime depending on your configuration. Here is an example:
FRCACacheLocalFileStartup /ITSO/ITSOco/Downloads/*.html

Dynamic content, such as result of an HTTP request to a content server, can be cached by
specifying a URI to identify the request that is then mapped to a fully qualified URL. This is a
reverse proxy cache support. It allows you to access an HTTP server on this same iSeries or
anywhere on your intranet or Internet to provide dynamic content that is automatically cached
in the NFC. A timer is used to determine when cached items are stale. See the following
example:
FRCAProxyPass /cgi-bin/ http://as21.domain.com:9999/cgi-bin/
FRCAProxyCacheRefreshInterval /cgi-bin/ 180

At this point, it is important for you to realize that FRCA is two vastly different caching
mechanisms wrapped into one package. That is, FRCA is both a:
򐂰 Local cache for IFS files that are generally static in nature.
򐂰 Reverse proxy cache for content that was generated by a dynamic content server either
running on your local iSeries server or connected via a TCP/IP network.

Content server: A content server can be any content created by a Web application
using the HTTP protocol. Good examples are:
򐂰 WebSphere Application Server serving servlets and Enterprise JavaBeans (EJBs)
򐂰 Tomcat serving servlets
򐂰 A CGI application, for example, Net.Data or Hypertext Preprocessor (PHP)

282 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.6.2 How FRCA local cache works
This section shows a series of diagrams that demonstrate the dramatic shift in processing
from above the MI to below as we follow each client get request.

FRCA: Local cache miss scenario

Figure 10-35 shows a FRCA local cache miss scenario. The steps are:
1. An HTTP request is received by TCP and passed to FRCA.
2. FRCA intercepts the HTTP request and passes it to the SLIC HTTP Server code.
3. The SLIC HTTP server code parses the HTTP request and uses the URL as a search key
into the hash table, one per server instance.
4. When the HTTP logical cache lookup fails, the HTTP request is redirected to the HTTP
Server (powered by Apache) using the normal sockets interface.
5. The HTTP Server (powered by Apache) parses the HTTP request, maps the URL to an
IFS file, builds the HTTP response from the IFS file, and calls Sockets send() to send the
HTTP response. This is business as usual for the HTTP Server (powered by Apache).
6. After sending the HTTP response, the FrcaLoadFile() system API is called to load the file
in the NFC.
7. FRCA calls the NFC to load a single copy of the file in the Network File Cache.

IFS
Apache
5 open File
or read
copy
close
Socket API FRCA SPI
send FrcaLoadFile()
MI 4
SLIC Sockets 6 SLIC HTTP Server Code
lookup Hash Table
FRCA & fail Handle
2 3

1 7 File
TCP/IP
Network File Cache
HTTP response
request
Network Web
browser

Figure 10-35 FRCA: Local cache miss scenario

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 283
 FRCA: Local cache hit scenario
Figure 10-36 shows a FRCA local cache hit scenario. The steps from request through
response are:
1. An HTTP request is received by TCP and passed to FRCA.
2. FRCA intercepts the HTTP request and passes it to the SLIC HTTP server code.
3. The SLIC HTTP server code parses the HTTP request and uses the URL as a search key
into the hash table.
4. When the HTTP logical cache lookup is successful, NFC is called to locate the file data
using the NFC handle found in the hash table.
5. NFC finds the file using the handle and returns it to the SLIC HTTP server code.
6. The SLIC HTTP Server code builds the HTTP response header, links the file data to it, and
sends it as a response through TCP/IP.

Tip: FRCA local cache has an interesting feature. Assume that a file located in the IFS is
cached in the NFC by FRCA. If that file is updated in the IFS, it is also automatically
updated in the NFC and the new content is served by FRCA.

Compare this behavior to the HTTP Server (powered by Apache) local cache directive
LiveLocalCache. LiveLocalCache checks to see if the file is updated in the IFS each time it
is requested. If it is not updated, the file is served from the cache. If it is updated, then the
entry for this file in the local cache is marked invalid and the file is served from the IFS for
all subsequent requests. You have to restart your server to cause it to be loaded back in
the local cache. See 10.3.1, “HTTP Server (powered by Apache) local cache” on
page 236, for more information.

Apache IFS

File

Socket API FRCA SPI

FrcaLoadFile()
MI
SLIC Sockets SLIC HTTP Server Code
lookup Hash Table
& hit! 4
FRCA 2 3
Handle
locate

send 5
File
TCP/IP 1 6
Network File Cache
HTTP response
request Web
Network
browser

Figure 10-36 FRCA: Local cache hit scenario

284 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.6.3 How FRCA reverse proxy cache works
This section offers a series of diagrams that show the dramatic shift in processing from above
the MI to below as we follow each client get request.

FRCA: Reverse proxy miss scenario

Figure 10-37 shows a FRCA reverse proxy miss scenario. That is, when FRCA recognizes
that content for an incoming URI should be cached but is not.

The steps from request through response are:

1. An HTTP request is received by TCP and passed to FRCA.
2. FRCA uses the URI as part of the lookup key to see if this dynamic content is cached in
the FRCA network proxy cache. It has not (miss!).
3. As part of the configuration of the FRCA reverse proxy, a new HTTP request is sent to the
configured URL (for this URI). This dynamic content server (called an origin server) is
contacted via TCP/IP. This origin server can be located on the same iSeries server or
anyplace connected via TCP/IP.
4. The origin server returns the content.
5. FRCA caches the content and updates the hash table (for the next time).
6. The content is sent back to the Web browser.

Apache
CGI/WAS CGI/WAS
Plug-in Process Content
Server

Socket API
http://server/URI
3
MI
SLIC Sockets SLIC HTTP Server Code
lookup & 2 Hash Table
FRCA miss! Handle 4
HTML response
6 5
Proxy
TCP/IP 1 Cache
send Network Proxy Cache
HTTP response
request Web
Network
browser

Figure 10-37 FRCA: Reverse proxy miss scenario

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 285
 FRCA: Reverse proxy hit scenario
Figure 10-38 shows an FRCA reverse proxy hit scenario. The steps from request through
response are:
1. An HTTP request is received by TCP and passed to FRCA.
2. FRCA uses the URI as part of the lookup key to see if this dynamic content is cached in
the FRCA network proxy cache. It is (hit!).
3. FRCA reads the content in the network proxy cache.
4. FRCA sends the content back to the Web browser.

Apache
CGI/WAS CGI/WAS
Plug-in Process Content
Server

Socket API

MI
SLIC Sockets SLIC HTTP Server Code
lookup & 2 Hash Table
FRCA hit! Handle

4 3
Proxy
TCP/IP 1 Cache
send Network Proxy Cache
HTTP response
request Web
Network
browser

Figure 10-38 FRCA: Reverse proxy hit scenario

10.6.4 FRCA limitations

All the limitations mentioned in this section are the result of one reason. That is that FRCA is
a SLIC task running below the MI. Therefore, it cannot take advantage of some of the server
API as provided in OS/400.
򐂰 FRCA does not support SSL or TLS. Therefore you cannot enable FRCA cache for the
sessions or ports with SSL/TLS. The reason is that applications (above the MI) write to the
sockets API, which is currently unavailable to FRCA. FRCA can be configured for a
non-secured port, such as port 80, for example, even in the same HTTP server that is also
listening on a SSL encrypted port of 443.
򐂰 After the file loaded into the NFC, it can be accessed by any users accessing files in the
same server instance. For this reason, you should enable the FRCA cache only for the
contents that can be public. If some HTML files in IFS can be accessed only by
authenticated users and one of the authenticated users has accessed such a file, the file
is loaded in to the NFC by FRCA. Now when an unauthenticated user requests the same
file, FRCA serves this file without user authentication.
򐂰 Similarly, since the code conversion is also performed above MI, code conversion is not
supported. IFS files are read in binary and loaded into the cache as is. Generally, we don't
use code conversion for IFS files so this limitation should have little impact.

286 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Due to these limitations, the basic rule for FRCA is to use it to help serve the public portions
of your Web application. Consider your public home page and all GIFs and JPEGs as an
example. If and when the customer enters, a portion of your Web application that is secured
with Basic Authentication or SSL/TLS turns off FRCA.

The presence of any of the following headers in an HTTP request forces FRCA to pass the
request directly to the local HTTP Server (powered by Apache) or remote content server (via
reverse proxy) without checking the cache:
򐂰 authorization
򐂰 allow
򐂰 cache-control
򐂰 content-base
򐂰 content-encoding
򐂰 content-language
򐂰 content-location
򐂰 content-md5
򐂰 content-range
򐂰 date
򐂰 etag
򐂰 expires
򐂰 if-match
򐂰 if-none-match
򐂰 if-range
򐂰 last-modified
򐂰 max-forwards
򐂰 proxy-authorization
򐂰 public
򐂰 protocol-request
򐂰 range
򐂰 retryafter
򐂰 transfer-encoding
򐂰 upgrade
򐂰 vary
򐂰 www-authenticate
򐂰 warning

10.6.5 FRCA configuration examples

Refer to the following examples of using FRCA:
򐂰 “Configuring FRCA for local cache” on page 288
򐂰 “Configuring FRCA for reverse proxy cache” on page 292
򐂰 “A more complete FRCA configuration example” on page 295

Before getting started with FRCA, configure the Network File Cache.

Network File Cache

FRCA local cache (only) uses the NFC component of OS/400. The NFC is a SLIC component
that is basically a file system that allows other SLIC tasks to open, read, write, and close
stream files. All this happens below the MI as shown in Figure 10-3 on page 227.

Starting from V5R2, by default, the NFC is enabled and has a size of 10 MB allocated out of
the base user pool. Due to OS/400’s single-level store, even if you do not use the NFC, it
simply pages out to direct access storage device (DASD) and it does not disturb the running
of your other applications.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 287
 The size you define for the NFC is the maximum amount of storage available to all the
individual instances of the HTTP Server (powered by Apache) that are configured to use
FRCA combined. For example, you may have three instances of the HTTP Server (powered
by Apache) that are using FRCA, each with the FRCACacheLocalSizeLimit set to 1 MB. In
this case, configure the NFC to have a size of 3 MB.

You can change the parameters of the NFC using the Change TCP/IP Attributes (CHGTCPA)
command. CHGTCPA NFC(*YES 300 10) changes the settings for the NFC to the defaults.

Tip: FRCA reverse proxy cache simply allocates main store memory out of the base user
pool to hold the HTML results pages from the remote content servers. As shown in
Figure 10-37 on page 285 and Figure 10-38 on page 286, this cache is named network
proxy cache, although it really does not have a proper name. Generally, these HTML
results pages are small. It was thought to be more efficient to maintain an in-memory
cache, rather than to add the overhead of the NFC.

Configuring FRCA for local cache

This scenario uses FRCA local cache to cache all the files in a SiteMap/* subdirectory.
Table 10-4 shows all the important characteristics of this Web application. This Web
application ran in a shared environment in the International Technical Support Organization
(ITSO), which explains the ports names such as 8000 (equivalent to port 80) and
SSL-enabled port 44300 (equivalent to port 443).
Table 10-4 FRCA: HTTP Server (powered by Apache) used for local cache
Parameter Value

Server name PBABASIC00

Server root /http53d00/basicConfig

Document root /http53d00/basicConfig/ITSOco

Directory to be cached by FRCA local cache /http53d00/basicConfig/ITSOco/SiteMap/*

IP address All

Ports 8000 (FRCA enabled)

44300 (for SSL, not FRCA enabled)

We recommend that before you start to configure FRCA, test your Web application to verify it
is working as expected. In our case, everyone has access to the files in the SiteMap/*
subdirectory.

To configure FRCA local cache, follow these steps. In this first part, we enable FRCA for port
8000 only.
1. From the Server list, select you server.
2. From the Server area list, select Global configuration. This is where all FRCA
configuration should take place.
3. In the left pane, under Server Properties, select FRCA.
4. Select the General Settings tab.

288 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
5. On the General Settings page (Figure 10-39), complete these steps:
a. Select the radio button for the port for which you want to enable FRCA. In this case, we
are using port 8000 for the public traffic and port 44300 for the SSL encrypted traffic.
b. Under the FRCA column, select Enabled. This configuration feature allows you to
enable, by port, FRCA caching.
c. Click Continue to keep the changed configuration and to stay on this form.

Figure 10-39 FRCA: Enabled for a specific port

6. Configure the FRCA local cache to cache all the contents of a Directory context. Select
the FRCA File Cache tab.
7. On the FRCA File Cache page (Figure 10-40), complete these tasks:
a. For FRCA file cache capabilities, select Enabled. This option allows you to turn FRCA
local cache on and off with ease, without having to resort to commenting out or deleting
all the FRCA local cache configuration directives.
b. Optional: Restrict the maximum size of the FRCA local cache and define the maximum
file size to be cached with these parameters. To keep our example simple, we keep
them as the defaults.
c. Under Files to cache during server startup, click Add.
d. A new row is added to the table in which you can enter the file path and names that you
want FRCA to cache. For our example, we typed SiteMap/*. Here are some comments
about FRCA directives:
• Since SiteMap/* does not have a leading slash (/), we assume it to be relative to
Document root.
• FRCA configuration directives are case sensitive, unlike Apache configuration
directives.
• FRCA configuration directives are not recursive, unlike Apache configuration
directives. That is, in this situation you are telling FRCA to cache files in the
SiteMap/* directory only. If you need to cache multiple subdirectories or multiple file
types, you have one FRCA directive for each.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 289
 Tip: You can choose to have FRCA local cache files during server runtime or at
startup. The choice is a subtle one, however. Both choices behave in a similar way in
that the first request for a file in the SiteMap/* subdirectory is served by the HTTP
Server (powered by Apache) and the second and all subsequent requests are served
by FRCA.

Caching at server startup requires some additional CPU at server startup time to
ready FRCA for caching the file at the first request. When the first request is made for
the file and served from the HTTP Server (powered by Apache), the CPU time it
takes to load the NFC with the file is reduced.

Caching at server runtime requires less CPU at server startup time. When the first
request is made for the file and served from the HTTP Server (powered by Apache),
the CPU time it takes to load the NFC with the file is greater than if you selected to
cache at server startup.

e. Click Continue. If you have more files or file types that you want to cache, repeat
step c.
f. Click OK to save all your configuration changes.

Figure 10-40 FRCA: Configuring for caching the contents of a Directory context

If you follow these steps, you have these three directives in your HTTP Server (powered by
Apache) configuration file:
Listen *:8000 FRCA
FRCAEnableFileCache On
FRCACacheLocalFileStartUp SiteMap/*

290 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
And, finally test your server. It is a bit difficult to tell whether your HTTP Server (powered by
Apache) served a file or if it was done by FRCA. The end result to the Web client is the same,
of course. One sure way is to use Start Communications Trace (STRCMNTRC) command.

The HTTP Server (powered by Apache) may return an HTTP response that looks something
like the following example (the key text is highlighted in bold):
*.....E...*G..@.*K.*.*.**P"*.**.**
*.**.*P. .DN..HTTP/1.1 200 OK..DA*
*TE: SAT, 03 AUG 2002 13:15:47 GM*
*T..SERVER: APACHE..LAST-MODIFIED*
*: SAT, 03 AUG 2002 01:37:39 GMT.*
*.ETAG: "4B33-3CB-C07A7EC0"..ACCE*
*PT-RANGES: BYTES..CONTENT-LENGTH*
*: 971..KEEP-ALIVE: TIMEOUT=15, M*
*AX=100..CONNECTION: KEEP-ALIVE..*
*CONTENT-TYPE: TEXT/HTML; CHARSET*
*=ISO-8859-1....<HTML>.FRI AUG 02*

FRCA local cache returns this (the key text is highlighted in bold):
*.....E..**J..@.**.*.*.**P"*.**.**
*@****P..-**..HTTP/1.1 200 OK..DA*
*TE: SAT, 03 AUG 2002 13:15:54 GM*
*T..SERVER: APACHE/2.0.43(FRCA)..*
*ACCEPT-RANGES: BYTES..CONNECTION*
*: KEEP-ALIVE..LAST-MODIFIED: SAT*
*, 03 AUG 2002 13:15:48 GMT..CONT*
*ENT-TYPE: TEXT/HTML..CONTENT-LEN*
*GTH: 971..X-CACHE: HIT FROM APAC*
*HE/2.0.43(FRCA)....<HTML>.FRI AU*

Tip: It may look like the FRCA server is based on or uses code borrowed from ASF to
provide this HTTP server function below the MI. This is not the case, however. FRCA is a
mini-HTTP server that has been written by IBM specifically for this purpose.

You can find more details about communications trace in 13.2.9, “Communications trace” on
page 353. To test FRCA on your iSeries using communications trace, follow these steps:
1. Start your HTTP Server (powered by Apache) instance.
2. Enter the Start Communications Trace (STRCMNTRC) command.
3. Request a file from the SiteMap/* subdirectory from a Web client. This first request is
served from the HTTP Server (powered by Apache) since FRCA stores this file in the
NFC.
4. Clear the local cache from your Web client. Microsoft Internet Explorer has a habit of
caching files when you least expect it. For Internet Explorer, select Tools →Internet
Options →Delete Files.
5. Request the same file again from SiteMap/* should cause FRCA to serve that file directly
from the NFC.
6. Enter the End Communications Trace (ENDCMNTRC) command.
7. Enter the Print Communications Trace (PRTCMNTRC) command. Then open the spooled
trace file. Searching for “(FRCA)” usually finds the place where FRCA served the file.
8. Make sure to enter the Delete Communications Trace (DLTCMNTRC) command for the next
time you want to start a communications trace.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 291
 Configuring FRCA for reverse proxy cache
Dynamic content, such as result of an HTTP request to a content server, can be cached by
specifying a URI to identify the request that is then mapped to a fully qualified URL. This is
reverse proxy cache support that allows you to access an HTTP server either on this same
iSeries or anywhere on your intranet (or Internet) to provide dynamic content that is
automatically cached in FRCA. A timer is used to determine when cached items are stale. An
example is:
FRCAProxyPass /cgi-bin/ http://as20.domain.com:9999/cgi-bin/

For this scenario, we want to cache a document that is generated dynamically by a Net.Data
macro (this is our content server) each time a Web client requests that page. Net.Data is a
good scripting language from IBM that is similar to PHP in the Apache world and JavaServer
Pages (JSPs) and servlets in the Java 2 Platform, Enterprise Edition (J2EE) world. But, if your
iSeries has to serve hundreds, if not thousands, of these Net.Data generated pages, you may
want to find a way to cache the results.

We assume that the Web server PBABASIC00 defined in Table 10-4 on page 288 will perform
the function of our content server. We create a new HTTP Server (powered by Apache) based
on the values in Table 10-5.
Table 10-5 FRCA: HTTP Server (powered by Apache) used for reverse proxy cache
Parameter Value

Server name PBAFRCA00

Server root /http53d00/FRCA

Document root /http53d00/FRCA/ITSOco

IP address All

Port 8600

If incoming URI is… /cgi-bin/MACRO1.MBR/

Send request to content server URL http://as20:8000/cgi-bin/MACRO1.MBR/

Content Server Server PBABASIC00 as defined by Table 10-4 on

page 288

Nothing can stop you from doing all this work in the same Apache instance on your iSeries
server. It is easier to conceptualize as two different servers. PBABASIC00 is the remote
content server, and PBAFRCA00 is used as a front end to the remote content server.

To configure FRCA reverse proxy cache, follow these steps. The first step is to enable FRCA
for port 8600. The configuration steps for this new server PBAFRCA00 are similar to those
shown in Figure 10-39 on page 289.
1. From the Server list, select you server. For Server area, select Global configuration. This
is where all FRCA configuration should take place.
2. In the left pane, under Server Properties, select FRCA.
3. Select the General Settings tab.
4. Select the radio button for the port for which you want to enable FRCA. In this case, we are
using port 8600. Under the FRCA column, select Enabled.
5. Click Continue to keep the changed configuration and to stay on this form.

292 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
6. Enable FRCA for reverse proxy cache as shown in Figure 10-41.
a. Select the FRCA Reverse Proxy Cache tab.
b. For the FRCA reverse proxy cache capabilities, select Enabled. This option allows you
to turn FRCA reverse proxy cache on and off with ease, without resorting to
commenting out or deleting all the FRCA reverse proxy cache configuration directives.
c. Optional: Restrict the maximum size of the FRCA reverse proxy cache and define the
maximum file size to be cached with these parameters. To keep our example simple,
we keep them as the defaults.
d. Under Proxy requests to remote servers, click Add. A new row is added to the table in
which you can enter the local virtual path (URI) and the remote server URL. For our
example, we entered /cgi-bin/MACRO1.MBR/ and
http://as20:8000/cgi-bin/MACRO1.MBR/ respectively. The same comments about
FRCA directives apply here as they did for FRCA local cache.
In addition, FRCA reverse proxy cache handles the incoming URI in the same way you
expect any reverse proxy cache. The matching URI text is stripped off. Additional text
to the right is saved and appended to the end of the fully qualified remote server URL.
As you can see in our example, we repeat the string /cgi-bin/MACRO1.MBR/ as part of
the remote server URL so we do not lose this information.
e. Click Continue.

Figure 10-41 FRCA: Configuring for reverse proxy caching

f. Under Document refresh policies, click Add. Type /cgi-bin/MACRO1.MBR/ for Match
URL and 300 seconds for Period. In this example, we tell FRCA that the proxy cache
item will expire when the minimum of the FrcaProxyCacheExpiryLimit and the HTTP
response expiration time is reached. FRCA reverse proxy only caches responses that
do not contain headers that prohibit caching (that is MaxAge=0).

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 293
 The response is cached the first time it is received from the content server and then is
continually refreshed at the specified interval. If multiple responses are cached by the
same FrcaProxyCacheRefreshInterval, the refresh is distributed evenly across the
specified refresh interval, to prevent all of the responses from being refreshed at the
same time. The main advantage of the FrcaProxyCacheRefreshInterval is that once a
response is cached, a valid copy always exists in the proxy cache. There is never a
need to wait for the response to be retrieved from the content server.
g. Click Continue.
h. Click OK to save all your configuration changes.

If you follow these steps, you change and add four directives in your HTTP Server (powered
by Apache) configuration file:
Listen *:8600 FRCA
FRCAEnableProxy On
FRCAProxyPass /cgi-bin/MACRO1.MBR/ http://as20:8000/cgi-bin/MACRO1.MBR/
FRCAProxyCacheRefreshInterval /cgi-bin/MACRO1.MBR/ 300

Finally, test your server. In this case, two instances of the HTTP Server (powered by Apache)
are running. To determine if FRCA is caching the HTML result pages from our content server,
simply monitor the iSeries thread that is handling the Net.Data macro invocation in the
PBABASIC00 server. That is, regardless of the number of times FRCA reverse proxy serves
the HTML results page, the CPU seconds for the content server should not increase.

On your iSeries server, follow these steps:

1. Start both of the HTTP Server (powered by Apache) instances PBABASIC00 and
PBAFRCA00.
2. From a 5250 session, enter the Work with Active Jobs (WRKACTJOB) command to find the
tasks associated with the remote content server PBABASIC00. It should look similar to the
example in Figure 10-42.

Opt Subsystem/Job User Type CPU % Function Status

PBABASIC00 QTMHHTTP BCH .0 PGM-QZHBHTTP SIGW
PBABASIC00 QTMHHTTP BCI .0 PGM-QZSRLOG SIGW
PBABASIC00 QTMHHTTP BCI .0 PGM-QZSRLOG SIGW
PBABASIC00 QTMHHTTP BCI .0 PGM-QZSRHTTP SIGW
PBABASIC00 QTMHHTTP BCI .0 PGM-QZSRHTTP SIGW
12 PBABASIC00 QTMHHTTP BCI .0 PGM-QZSRCGI TIMW

Figure 10-42 WRKACTJOB: Displaying the list of threads; PGM-QZSRCGI is the CGI thread

3. Enter option 12 (Work with threads) next to the BCI job running as a CGI as indicated by
the function PGM-QZSRCGI. As shown in Figure 10-43, you should see a single line that
indicates how many CPU seconds this thread has used.

Total Aux Run

Opt Thread Status CPU I/O Priority
0000002E TIMW .521 484 25

Figure 10-43 WRKACTJOB: Option 12 (Work with threads)

4. From your Web client, enter the URL:

http://as20:8600/cgi-bin/MACRO1.MBR/run

294 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Port 8600 is the HTTP Server (powered by Apache) instance PBAFRCA00. Your FRCA
reverse proxy configuration redirects this request to the PBABASIC00 instance at port
8000 on the same iSeries server.
5. Back on your 5250 session, press F5 (Refresh). You should see the Total CPU seconds for
this thread handling the Net.Data CGI invocation.
6. Back on your Web client, click Refresh (which is also F5). In fact, click Refresh as many
times as you want, clear the client cache, or do what every you want. You do not see the
Net.Data task on the iSeries spend any CPU because FRCA is serving the resulting
HTML from its cache.

A more complete FRCA configuration example

As shown in Figure 10-44 on page 296, this example is more complex and complete of FRCA
configuration for a Web application. This example includes:
򐂰 Static HTML and GIF content as served from the subdirectory contexts of /Downloads and
/People.
򐂰 Dynamic content from:
– A WebSphere Application Server content server running on the local iSeries server
defined as as20.itsoroch.ibm.com
– A CGI content server running on a remote iSeries server defined as
as21.itsoroch.ibm.com

We do not show you all the steps to configure FRCA via the administration GUI, but instead
offer a description of the FRCA directive and its effect on your Web application. The following
numbers correspond to the line number of the directives found in the httpd.conf configuration
file in Figure 10-44. Figure 10-44 also shows pairs of numbers. The configuration directives in
the lower part of this figure match the functional diagram in the upper part of the figure.
2 Listen 10.5.92.14:8080 FRCA
Specifying the Listen directive with the parameter FRCA enables FRCA cache for this
port.
5 FRCAEnableFileCache On
This directive enables FRCA cache for this server instance ITSO99. The other directives
for specific settings of FRCA all depends on this directive is on or off.
11 FRCACacheLocalFileStartUp /ITSO/itso99/ITSOco/Downloads/*.html
By specifying this directive, the files that have an .html extension in the directory
/ITSO/itso99/ITSOco/Downloads are all cached when you start the server ITSO99.
12 FRCACacheLocalFileRunTime /ITSO/itso99/ITSOco/People/*
This directive makes all files in the directory /ITSO/itso99/ITSOco/People available to be
cached when they are accessed. In this example, the files in the subdirectory /Employees
are not cached because file name matching is not recursive.
15 FRCAEnableProxy On
This directive enables FRCA proxy.
16 FRCAProxyPass /servlet/ http://10.5.92.14:8080/servlet/
In this example, specifying /servlet in URI causes it to run a servlet on the application
server. By specifying the directive FRCAProxyPass as in this example, the result of the
servlet can be cached in the NFC for a certain period, that is specified by the directive
FRCAProxyCacheRefreshInterval.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 295
 In this example, the target URL has the same IP address and port as the ones on which
this server listens. In this case, FRCA recognizes that this URL is for the same server and
passes the request to the HTTP Server (powered by Apache) without any looping
problem.
17 FRCAProxyCacheRefreshInterval /servlet/ 300
As described above, this directive specifies the interval of refreshing cached data of FRCA
proxy.
20 FRCAProxyPass /cgi-bin/ http://as21.itsoroch.ibm.com:9999 /cgi-bin/
By specifying this directive, the request for CGI program is rerouted to the remote iSeries
as21.itsoroch.ibm.com:9999. The result is cached in the NFC on as20.itsoroch.ibm.com.
21 FRCAProxyCacheRefreshInterval /cgi-bin/ 180
As described earlier, this directive specifies the interval of refreshing cached data of FRCA
proxy.

as20.itsoroch.ibm.com IP address: 10.5.92.14 port: 8080 1

NFC Web
Application as21.itsoroch.ibm.com
xxx.html
xxx.html Server

2 xxx.gif
Servlet DB
xxx.html

3 results 4
DB
results
5
...
httpd.conf:
2 Listen 10.5.92.14:8080 FRCA 1
...
5 FRCAEnableFileCache On
...
11 FRCACacheLocalFileStartup /ITSO/itso99/ITSOco/Downloads/*.html2
12 FRCACacheLocalFileRuntime /ITSO/itso99/ITSOco/People/*3
...
15 FRCAEnableProxy On
16 FRCAProxyPass /servlet/ http://10.5.92.14:8080/servlet/ 4
17 FRCAProxyCacheRefreshInterval /servlet/ 300
...
5 20 FRCAProxyPass /cgi-bin/ http://as21.itsoroch.ibm.com:9999/cgi-bin/
21 FRCAProxyCacheRefreshInterval /cgi-bin/ 180

Figure 10-44 FRCA: Complete configuration example

10.6.6 Miscellaneous FRCA directives beyond the online help

Most FRCA directives are defined in the online help associated with your HTTP Server
(powered by Apache). While you are managing the details of any Apache server, you can
click Directive Index under Tools. All the FRCA directives, except Listen, start with “FRCA” so
you can find them easily. Here is a list to get you started:
FRCACacheLocalFileRunTime
FRCACacheLocalFileSizeLimit
FRCACacheLocalFileStartUp
FRCACacheLocalSizeLimit
FRCACustomLog
FRCAEnableFileCache
FRCAEnableProxy
FRCAProxyCacheEntitySizeLimit

296 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
FRCAProxyCacheExpiryLimit
FRCAProxyCacheRefreshInterval
FRCAProxyCacheSizeLimit
FRCAProxyPass
Listen (with the FRCA parameter)

Some, however, are not defined in the GUI online help text. These are:
FRCACookieAware
FRCAEndOfURLMarker
FRCAMaxCommBufferSize
FRCAMaxCommTime
FRCARandomizeResponse

As far as we can tell, these directives are not formally documented anywhere. They are used
to perform specific services to dramatically improve the performance of FRCA. These FRCA
directives are documented in the following sections.

FRCACookieAware
Syntax:
FRCACookieAware <path>

Example:
FRCACookieAware /some_path_segment

This FRCA directive indicates a URL prefix for which the cookie should be included in cache
lookup. This directive makes it possible to serve a cached entity only for the requests with the
same cookie. This allows content that is intended for specific individuals to be cached
separately.

FRCAEndofURLMarker
Syntax:
FRCAEndofURLMarker <marker>

Example:
FRCAEndofURLMarker ###

FRCA support can identify the end of the original URL (link) before it is modified or padded by
the client. Specify the unique string that identifies the end of URLs. Suppose a link in an
HTML page is:
http://some.org/some_path/some_parms###

Before a client sends this request to the server, it may pad the URL with some data such as
client_padded_data. In this case, your HTTP Server (powered by Apache) receives the path:
/some_path/some_parms###client_padded_data

Specify the following directive:

FRCAEndofURLMarker ###

FRCA support can identify the end of the original URL (link) before it is modified (padded) by
the client.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 297
 FRCAMaxCommBufferSize
Syntax:
FRCAMaxCommBufferSize <bytes>

Example:
FRCAMaxCommBufferSize 4000000

This directive sets the communication buffer size (in bytes) in FRCA for performance. The
data being sent to the HTTP Server (powered by Apache) consists of log data, message data,
and collection services data. FRCA buffers the size of data specified until the buffer is full.
After the buffer is full, the data is transmitted to the HTTP Server (powered by Apache) for
processing.

FRCAMaxCommTime
Syntax:
FRCAMaxCommTime <seconds>

Example:
FRCAMaxCommTime 240

This directive sets the maximum number of seconds to wait before the data buffer is sent from
FRCA to the HTTP Server (powered by Apache). The data being sent to the HTTP Server
(powered by Apache) consists of log data, message data, and collection services data. After
the time limit is reached, the data is transmitted to the HTTP Server (powered by Apache) for
processing.

FRCARandomizeResponse
Syntax:
FRCARandomizeResponse <path> <string> <nnn> <mmm>

Note the following explanation:

򐂰 <path>: A valid path in the form:
/some_path_segment/some_partial_file_nameNNN.ext
The NNN marker is replaced with a randomly generated whole number by FRCA before
serving the response.
򐂰 <string>: The replacement string marker (NNN) in the path.
򐂰 <nnn>: Lower bound of the random numbers (whole number integers) that FRCA
generates.
򐂰 <mmm>: Upper bound of the random numbers (whole number integers) that FRCA
generates.

Examples:
FRCARandomizeResponse /some_path/fileNNN.html NNN 1 999
FRCARandomizeResponse /some_path/fileXXX.html XXX 200 300

Specify the path template, the replacement string marker, and the random number range that
you want FRCA to use to randomly select and serve files of that template.

298 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 The most likely place this is used is on your home page. Normally, FRCA caches the content
of your home page for a configurable period of time. During that period of time, your
advertising banner is the same for everybody. It does not change. This configuration directive
allows you to create NNN home pages (index.html) and have FRCA randomly select from its
cache which one to send as an individual response to each and every request. Even the
same client using the refresh key randomly receives a different advertising banner.

For example, if you have 999 “advertising” files with the names file1.html through file999.html
in your server document root, then configure:
FRCARandomizeResponse /document_root_alias_path/fileNNN.html NNN 1 999

Then request the URL:

http://some_host:port/dirpath/fileNNN.html

FRCA randomly selects and serves one of the 999 files.

10.6.7 The FRCA challenge

You now can see how easy it is to take advantage of FRCA’s local and reverse proxy caching.
It is simply a matter of configuration. FRCA really can be thought of as providing both a local
cache for public documents that tend to be static and reverse proxy for documents that tend to
be dynamic. For the FRCA challenge, use:
򐂰 FRCA local cache to cache graphic files (GIFs, JPEGs, and so on). These graphic files
tend to be the caching world's equivalent of “low-hanging fruit” for a Web application.
򐂰 FRCA reverse proxy cache to cache just a single dynamic page: your index.html, or home
page. This single HTML page is usually the most popular page and most likely is thick with
dynamic content.

Over time, you will become more comfortable with FRCA on your iSeries HTTP Server
(powered by Apache). Then you can expand the range of items cached with a bit of simple
configuration and testing.

10.6.8 For more information

Here are some pointers to more information about FRCA:
򐂰 iSeries Performance Capabilities Reference Version 5, Release 3, SC41-0607
http://www-1.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm
򐂰 Detailed reference documentation on FRCA and its configuration directives, which is
located in the iSeries Information Center at:
http://publib.boulder.ibm.com/html/as400/infocenter.html
򐂰 The online help associated with your HTTP Server (powered by Apache), which defines
most of the FRCA directives. While you are managing the details of any Apache server,
click Tools →Directive Index. All the FRCA directives start with “FRCA” so you can find
them easily.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 299
10.7 Cryptographic coprocessors
IBM offers two cryptographic hardware solutions for customers that require a high level of
security for data stored on their iSeries server and for SSL/TLS transactions. These options
have a lot to offer iSeries server customers, including enhanced SSL/TLS performance. IBM
offers the following cryptographic hardware options:
򐂰 IBM 2058 e-business Cryptographic Accelerator (hardware feature code: 4805)
򐂰 IBM 4758 Cryptographic Coprocessor (hardware feature codes: 4801 or 4802)

The benefits of each cryptographic hardware option include:

򐂰 IBM 2058 e-business Cryptographic Accelerator:
– Offers a large capacity for accelerating SSL transactions
– Minimal installation and configuration effort
– Minimal management requirements
򐂰 IBM 4758 e-business Cryptographic Coprocessor:
– Tamper-resistant hardware features
– Numerous configuration options, enabling you to customize functions to fit your needs
– Provides secure key storage for applications and SSL transactions
– Offers a rich set of cryptographic functions for applications, including Triple-DES, RSA
digital signature support, financial PIN processing, and robust key management
services

These cryptographic accelerator coprocessors are used by the system on an SSL/TLS

connection handshake process (negotiates the level of SSL support and key exchange
information to be used by an SSL session). Your configuration and use of the DCM and client
or server digital certificates does not change.

iSeries Performance Capabilities Reference Version 5, Release 3, SC41-0607, has test

results that show the handshaking performance improvements for both the older 4758
technology and the new technology 2058. The 2058 supports the same algorithms as the
4758. The 2058 does not support any secure key usage or key management. See the
following Web site for more information:
http://www-1.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm

Tip: The iSeries already held the number three spot on the SPECweb99 and the number
two spot on the SPECweb99 SSL benchmarks. This is a significant validation of the overall
systems performance of the entire iSeries server. It is the iSeries’ balanced ability to scale
and run enormous On Demand Business workloads that is the basis for these (and other)
benchmark successes. Note that FRCA and the cryptographic accelerator coprocessors
where not used for the iSeries SPECweb99 SSL benchmark. FRCA could not due to an
architectural limitation. The 4758 and 2058 cryptographic accelerator coprocessors could
not since the SPECweb99 SSL benchmark does not allow hardware assist.

And, our ability to run enormous On Demand Business workloads is due to the integration
of the SSL and TLS component 5722-AC3, the HTTP Server (powered by Apache)
integration with OS/400. It is also due to the pure power of the iSeries’ 64-bit RISC
POWER processors, which allow the iSeries to climb to near the top of these benchmarks,
even without using the cryptographic accelerator coprocessors.

You can find detailed information about these features in the V5R3 Information Center, under
Security. You should also refer to the redbook IBM Eserver iSeries Wired Network Security:
OS/400 V5R1 DCM and Cryptographic Enhancements, SG24-6168.

300 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
10.8 Real Time Server Statistics
This function was introduced as PTF for OS/400 V5R1 and V5R2 and was implemented with
i5/OS V5R3 in the base version. Besides other enhancements, forms on the HTTP
administrative GUI are provided for displaying HTTP Server statistics that are recorded for
collection services (similar to the Original server monitor form).

The Real Time Server Statistics form and tabs in the IBM Web Administration for iSeries GUI
provide information about server performance. You can only view statistics for running
servers. You may choose this form to automatically refresh every 10 or 30 seconds, or 1, 5 or
10 minutes, by changing the Refresh Interval in the upper half of the right panel. The default is
to refresh the data manually using the Refresh button located at the bottom of the form.

As shown in Figure 10-45, the upper part always describes the server, when it started, the
current date and time, and the period of time the data has been measured. The lower part of
the Real Time Server Statistics form contains five tabs. Each contains a different set of
statistical information.

The type of information displayed depends on the activity of the HTTP Server (powered by
Apache) and the functions that are enabled. Only statistical information for enabled or active
functions are displayed. Each column heading identifies what enabled function or associated
server is being surveyed for statistical information.

Tip: The Real Time Server Statistics provide real-time information about the running
server environment. The information can help you determine if you server is set up
correctly or if it needs some performance tuning. Following are a few examples that show
how the statistics can help you detect configuration or performance problems:
򐂰 One piece of information that can help in several ways is the number of error
responses. In today’s complex Web content structure with many interlinked pages, it is
likely that links may be broken and a user may receive a 404 (file not found) error
message. Whenever this or other errors occur, the error response counter is updated.
For example, if you see over a period of time a huge number of error responses, you
know that something strange happens on your server. You can then go to the error log
to determine the problems.
򐂰 The data provided for non-cache and cache responses tell you at a glance whether
your cache configuration is working efficiently. For example, you may have decided to
cache all HTML and GIF files from a certain directory, because you expected a huge
number of hits for these resources. However, it turns out that the cached responses are
quite low and the number of non-cached responses very high. In that case, you know
that you cached the wrong resources and that you should use a Web analyzer to
evaluate your access logs to see what resources were requested most.

Statistical information is cumulative. If a value is greater than 264-1 in any column, the value
resets to 0. All values reset to 0 if the server is stopped and then started.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 301
 Figure 10-45 IBM Web Administration for iSeries: Real Time Server Statistics

Statistical information may be obtained for the following functions:

򐂰 Server handled: This column displays the number of completed server transactions by
the server since the server was started. For example, it includes the completed
transactions for static HTML pages, HTML pages containing SSIs, and images.
򐂰 Proxy: This column displays the number of completed server transactions that used proxy
since the server was started. Proxy statistics are only available if proxy is enabled.
򐂰 CGI: This column displays the number of completed server transactions that were handled
as CGI since the server was started. CGI statistics are available only if CGI is enabled.
򐂰 Using SSL: This column displays the number of completed server transactions that used
SSL since the server was started. SSL statistics are available only if SSL in enabled.
򐂰 WebSphere: This column displays the number of completed server transactions that used
an associated application server since HTTP Server (powered by Apache) was started. If
the associated application server is not running, the information is still displayed but
equals 0. WebSphere statistics are available only if a WebSphere Application Server is
associated with an HTTP Server (powered by Apache).
򐂰 Tomcat: This column displays the number of completed server transactions that used an
in-process or out-of-process ASF Tomcat server since HTTP Server (powered by Apache)
was started.
򐂰 Customer module: This column displays the number of completed server transactions
that used a customer or third-party module.
򐂰 FRCA Stats: This column displays the number of completed server transactions that used
FRCA since the server was started. FRCA statistics are available only if FRCA is enabled.

302 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
򐂰 FRCA Proxy: This column displays the number of completed server transactions that
used the FRCA proxy since the server was started. FRCA statistics are only available if
FRCA is enabled.

The General tab as shown in Figure 10-45 displays basic information about the active server
since the server was started. Statistical information displayed includes:
򐂰 Active threads: This field displays the number of currently active threads on the server.
Active threads are typically processing a server request, such as serving a static page,
calling a CGI script, or routing data to an application server.
򐂰 Idle threads: This field displays the number of currently idle threads active on the server.
An idle thread is a portion of a program that is waiting for either a response or a request
before it can continue. Idle threads are most often waiting for an HTTP request to process.
򐂰 Normal connections: This field displays the number of total normal (non-secure)
connections to the server.
򐂰 SSL connections: This field displays the number of total SSL (secure) connections
currently active.
򐂰 Requests: This field displays the number of total requests to the server since the server
was started.
򐂰 Responses: This field displays the number of total responses from the server since the
server was started.
򐂰 Requests rejected: This field displays the number of total rejected requests issued by the
server since the server was started.

The Absolute and Delta tabs display statistical information about currently enabled functions
or associated servers. The absolute value, as shown in our example in Figure 10-46, is a
measurement of the total transactions since the server was started.

Figure 10-46 Real Time Server Statistics: Absolute tab

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 303
 The delta value shown in Figure 10-47 is a measurement of the total transactions since the
server statistics were refreshed.

Figure 10-47 Real Time Server Statistics: Delta tab

The absolute and delta statistical information may be displayed separately or side by side for
comparison as in Figure 10-48.

Figure 10-48 Real Time Server Statistics: Absolute and Delta tab

Each column heading identifies what enabled function or associated server is being surveyed
for statistical information. Each row identifies what statistical information is being retrieved.
Statistical information displayed for each column includes:
򐂰 Requests: This field displays the number of requests to the enabled function or
associated server identified at the top of the column.
򐂰 Responses: This field displays the number of responses sent by the enabled function or
associated server identified at the top of the column.

304 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
򐂰 Error responses: This field displays the number of error responses sent by the enabled
function or associated server identified at the top of the column. An error response
example is the 404 “Page Not Found” response.
򐂰 Non-cache responses: This field displays the number of non-cached responses sent by
the enabled function or associated server identified at the top of the column.
򐂰 Cache responses: This field displays the number of local memory cached responses sent
by the enabled function or associated server identified at the top of the column.
򐂰 Bytes received: This field displays the number of bytes received by the enabled function
or associated server identified at the top of the column.
򐂰 Bytes sent: This field displays the number of bytes sent by the enabled function or
associated server identified at the top of the column.
򐂰 Non-cache Processing (seconds): This field displays the number of seconds of
non-cached processing activity completed by the enabled function or associated server
identified at the top of the column.
򐂰 Cache Processing (seconds): This field displays the number of seconds of cached
processing activity completed by the enabled function or associated server identified at
the top of the column.

The server Averages tab, shown in Figure 10-49 displays the average length of activity, in
seconds, completed by the enabled function or associated server identified at the top of the
column.

Figure 10-49 Real Time Server Statistics: Average tab

Each column heading identifies what enabled function or associated server is being surveyed
for statistical information. Each row identifies what statistical information is being retrieved.
Statistical information displayed for each column includes:
򐂰 Total (seconds): This field displays the total time of activity completed by the enabled
function or associated server identified at the top of the column.
򐂰 Non-cached (seconds): This field displays the average length of time of non-cached
activity completed by the enabled function or associated server identified at the top of the
column.
򐂰 Cached (seconds): This field displays the average length of time of cached activity
completed by the enabled function or associated server identified at the top of the column.

Chapter 10. Getting the best performance from HTTP Server (powered by Apache) 305
10.9 References
Here are some other resources for you to read and learn more about how to improve the
performance of your HTTP Server (powered by Apache) Web server:
򐂰 The iSeries Information Center is a good starting point for performance-related topics that
include the logging of information with iSeries Collection Services:
http://publib.boulder.ibm.com/iseries/v5r3/ic2924/info/rzahx/rzahxebushttp.htm
򐂰 iSeries Performance Capabilities Reference Version 5, Release 3, SC41-0607, is the
definitive guide to performance on the iSeries server. This manual, which is updated
regularly, has a good chapter on Web serving and communications performance. You can
find it on the Web at:
http://www-1.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm
򐂰 AS/400 HTTP Server Performance and Capacity Planning, SG24-5645, is an IBM
Redbook intended for iSeries programmers, network and system management
professionals, and other information technologists that are responsible for designing,
developing, and deploying Web-based applications and information systems. This IBM
Redbook was written before the HTTP Server (powered by Apache) was brought to the
iSeries server. Yet, it contains some useful advice on getting the best performance out of
your Web application.
򐂰 Performance Tools for iSeries, SC41-5340, provides programmers with the information
needed to collect data about the system, job, or program performance. It includes tips for
printing and analyzing performance data to identify and correct inefficiencies that may
exist. It also includes information about the manager and agent feature.

306 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 11

Chapter 11. Getting started with Webserver

Search Engine and Web Crawler

An interesting The key to any successful Web site is to offer a good clean way for people to navigate through
analogy may the myriad of Web pages to find that one piece of information they need. The problem is that
be OS/400. there are many different types of people that come to your Web site looking for information.
Users are
given the ability Some people like to follow a well thought out and defined hierarchy of information. You can
to follow use nested levels of navigation bars on the left, top, and right side of your Web pages to give
menus, search a logical order to your site. You can also use site maps to give these type of people the big
for commands, picture view of your site. Some like to follow the hypertext links found throughout the text and
or directly enter graphics that you have prepared. In a way, they read their way through to the information they
commands.
are looking for. And some people simply like to search.
They can also
prompt for
The webmaster’s job is to provide all of these forms of navigation to your customers since you
additional
cannot control what kind of person they are. A good search engine, then, is part of the critical
context-
sensitive items you must add to your Web site.
information. All
are designed On the iSeries server, the search engine comes in two logical pieces that are related to each
for different other:
types of users. 򐂰 iSeries Webserver Search Engine
– Collects all documents into a single directory
– Creates a search index
– Creates a document list that contains a list of all the document paths
– Customizes your search forms with supplied HTML section
– Sets up your HTTP server correctly for the search forms
– Keeps your index up to date
򐂰 iSeries Webserver Search Engine Web Crawler
– Crawls the URL you provide and downloads the Web page
– Builds a document list using downloaded Web pages
– Create a search index using the document list

These two search engines are further explained in 11.1, “iSeries Webserver Search Engine”
on page 308, and 11.2, “iSeries Webserver Search Engine Web Crawler” on page 309.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 307
11.1 iSeries Webserver Search Engine
If you want to allow others to search through documents on your server, you need to set up
your system to be a searchable site. Doing this is easy with the new iSeries Webserver
Search Engine. There are just a few administrative tasks you need to do.

These tasks are summarized here:

1. Collect all of the related documents into a single directory on your iSeries server. You may
use either the root (/) directory of the integrated file system (IFS) or the QSYS.LIB file
system. Using the IFS system allows you to easily port your files from a PC onto the
iSeries server.
2. Create a search index. An index is a collection of all of the selected documents in your
directory. The documents are stored in a special indexed form. In the indexing process, the
search engine takes each document provided in a document list and parses through it to
create keys that are used in searches. The Webserver Search Engine uses very short
character string keys. This indexed form allows for faster searching than can be done on
documents that are not indexed.
3. The documents provided to the indexing function are contained in a document list that is
automatically created when you create an index. A list can also be created through
administrative forms or by hand.
4. After you create the search index, you can test it from the search administration form. This
allows you to see all of the different options available to select for a search, such as fuzzy
or precise.
5. Now you are ready to set up the Webserver Search Engine to run on your Web site. A
short Hypertext Markup Language (HTML) section is supplied that you can add to your
Web page. A Net.Data macro is also supplied that contains all of the HTML you need. This
allows you to customize your search and search results forms. You may use the short
HTML form supplying a few values if you are not comfortable using Net.Data. However,
you must still copy the sample macro to your directory to make all of this work.
6. After you decide how you want to present your search forms, you need to make sure the
HTTP server you use contains the correct directives in the configuration to run the
Net.Data macro. You must also make sure that users can view the documents found on a
search. A simple set of steps to do the necessary setup is provided for the HTTP Server
(powered by Apache) and HTTP Server (original).
7. When all of this is completed, you are ready to perform searches.
8. You must keep your index up to date. If you modify your documents from time to time,
make sure that your users can find the most current information. We supply a way for you
to update your index. You can use the same document list you used when you originally
created your index. We index any changed files that were previously indexed. You can also
add a new set of documents to an index that already exists and delete some of the
documents from your index. This is a matter of supplying different lists when you update
the index.

For more information about how to use the iSeries Webserver Search Engine, see:
http://www.ibm.com/servers/eserver/iseries/software/http/services/searchinfo.htm

The online “How to” documentation is good for this feature. If you have not done so, we
recommend that you consult the online documentation at this same Web site.

308 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
11.2 iSeries Webserver Search Engine Web Crawler
Web Crawler is a program that you can start from the same Search Setup forms that you use
to set up your search engine. It works in much the same way as when you enter a Uniform
Resource Locator (URL) on your browser and then click various links to go to new Web
pages.

The crawling program starts by finding the URL that you provide. It downloads this Web page
to your system and then continues to follow the links it finds. Each Web page that it links to is
also downloaded until there are no more links to follow or your timer expires.

Web Crawler Web Crawler extends the capability for building a document list. As each file is downloaded,
was introduced the local path, plus the original URL, are added to your document list. You can then use this
to the HTTP document list to create a search index. Search results for this type of index display the URL
Server where the document was originally found rather than the local copy. When you find one of
(powered by these documents in your search results, you are taken to the actual page that was found
Apache) with during crawling.
OS/400 V5R1.
When you choose to build a document list by crawling Web sites, the session always runs as
a background task whether it is initiated from the browser or one of the search CL commands.
It takes several minutes to run at a minimum, depending, of course, on the maximum time you
selected for the session to run, as well as other attributes you specified.

Web Crawler has some special features. It can go to any Web site, English or non-English,
and process the downloaded files correctly for indexing and searching. If a site requires
authentication, you can provide the necessary setup. Since Web Crawlers can run for quite a
long time and consume a lot of your system storage, you can limit the time the crawler runs,
the size of the files it can download, and the amount of storage it can consume. In addition,
you can stop, pause, and resume your crawling session.

All of these features are on the Search Setup forms that are part of the HTTP Server
Configuration and Administration.

For more information about how to use the iSeries Webserver Search Engine Web Crawler,
see:
http://www.ibm.com/servers/eserver/iseries/software/http/services/webcrawler.htm

Chapter 11. Getting started with Webserver Search Engine and Web Crawler 309
310 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 12

Chapter 12. Apache Portable Runtime:

Extending your core functionality
Consider these scenarios:
򐂰 What if you need to provide some kind of dynamic content to your Web site and it needs to
be as efficient as possible?
򐂰 What if you want to perform some special logging that is outside what either your Web
application or the HTTP Server (powered by Apache) does?
򐂰 What if you need to implement your own authentication of remote users for your Web
application?
򐂰 What if you want to implement your own version of a server-side include (SSI) that would
recognize a pattern of text in the outgoing Hypertext Markup Language (HTML) and
replace it with some dynamic content?

The answer to all these “what if” questions is Apache Portable Runtime (APR). The APR is all
about extending the core functionality of the Apache server in a manner that is portable
between platforms. This chapter explores the APR Version 2.0 and writes a module for the
iSeries server.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 311
12.1 Apache module design overview
The design of the HTTP Server (powered by Apache) defines modules. Modules are
operating system objects that can be dynamically linked and loaded to extend the nature of
the HTTP Server (powered by Apache). Depending on the operating system, this is similar to:
򐂰 Windows Dynamic Link Libraries (DLL)
򐂰 UNIX shared object libraries
򐂰 OS/400 Integrate Language Environment (ILE) Service Programs

In this way, the Apache modules provide a way to extend a server's function. Functions
commonly added by optional modules include:
򐂰 Authentication
򐂰 Encryption
򐂰 Application support
򐂰 Logging
򐂰 Support for different content types
򐂰 Diagnostics

A good example of a module that is shipped with your HTTP Server (powered by Apache) that
extends the reach of the core Apache server is:
LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

This service program is only loaded, linked, and used when you configure the LoadModule
directive because you decided to encrypt your data using Secure Sockets Layer (SSL). The
advantage of this is that the core Apache program can stay relatively small and tight until a
particular function (as provided by a plug-in module) is needed. Then, with just a LoadModule
directive and optionally some configuration directives, you can increase the functionality of
your Web server with a corresponding increase in the working set size.

Apache core functions are those available in a standard Apache installation with no
nonstandard modules. iSeries Apache Version 2.0 supports about 137 directives. Of those,
53 are in the core functions. The remainder are in separate modules that are compiled into
the code. The LoadModule directive must be used to activate the directives in these modules.

As shown in Figure 12-1, the

HTTP Server (powered by
Apache)’s core functions are CGI SSL
module module
extended with a variety of different
modules. In some cases
(Common Gateway Interface
Server core
(CGI) module and a Cookie functions
module), the modules are built-in
extensions to the server’s core
functions and do not need an User
Cookies written
explicit LoadModule to use. In module module
other cases (for example, the SSL
module), the modules are
provided with the HTTP Server Figure 12-1 Modules expanding the functionality of the core
(powered by Apache) product on Apache Web server
the iSeries but must be explicitly
loaded with the LoadModule directive.

You can also write your own module to extend the core functionality of the HTTP Server
(powered by Apache). This, in fact, is one of the biggest drawing points to the Apache Web
server and a good example of why it is a popular HTTP server.

312 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
To understand how modules are plugged into the Apache server, you need a good
understanding of request handling. Request handing is done in a series of steps called
phases. The phases are:
򐂰 Post read request: Set of hooks called immediately after the incoming request is read.
򐂰 URI to filename translation: Hooks for mapping the incoming Uniform Resource
Identifier (URI) to the physical file. Examples include aliasing, redirecting, rewriting, and so
on.
򐂰 Parse headers: Hooks that need to read the incoming HTML headers and perform tasks
based on what is in them.
򐂰 Check access: Hooks that determine whether the current context is restricted.
򐂰 Authentication ID checking: Hooks that verify who the user is.
򐂰 Authentication access checking: Hooks that verify if the user is authorized in the current
context.
򐂰 Type checker: Hooks to determine the Multipurpose Internet Mail Extensions (MIME)
type of the object requested.
򐂰 Fixups: Hooks that don't really fit anywhere else, such as ASCII/EBCDIC conversions or
setting/resetting environment variables.
򐂰 Insert filters: Hooks for inserting input or output filters. A module either does this or
registers the filter at startup time. If a module registers filters at startup time, the server
adds those filters during this phase.
򐂰 Sending a response back (handlers): Hooks that possibly handle the request and
respond to the client.
򐂰 Logging: Hooks to log any data to a log file that the module defines.

Tip: The example provided in 12.2, “Creating a module for the iSeries server” on page 315,
is an example of a response handler (Sending a response back (handlers) in the list
above). In this phase, buckets and brigades (see the next paragraph) are lined up and our
code steps in to make a minor modification to the HTML right before it is sent back to the
client.

For Version 2.0 of the Apache server, the Apache Software Foundation (ASF) provides the
ability to modify data that was generated by an earlier module. This concept is called buckets
and brigades as seen in Figure 12-2. The premise is that, after all is said and done, Web
pages are nothing more than chunks of information:
򐂰 Each chunk is stored in a bucket.
򐂰 A list of buckets form a brigade.
򐂰 Lists of brigades can form a Web document.
򐂰 Filters operate on one brigade at a time.

The C language
implementation of the
structure shown in bucket A bucket B bucket C bucket D

Figure 12-2 is a linked list

of buckets.
Figure 12-2 Many buckets in a row become a brigade

Chapter 12. Apache Portable Runtime: Extending your core functionality 313
 As you now know, the iSeries has integrated the 2.0 version of the Apache server with the
IBM HTTP Server for iSeries. Much of the rest of the world, however, is still back at version
1.3 of the Apache server. A big difference between version 1.3 and 2.0 of the Apache server
is that the APR is new for version 2.0. To bring a module written to version 1.3 to the iSeries
server, you should first update it to the new version 2.0 APR module. Then, the port to iSeries
should be fairly easy.

The APR found with version 2.0 of the Apache server is actually independent of the Apache
HTTP 2.0 server. Technically, APR is a separate Apache product altogether and can exist
alone. Users of APR can create their own applications using APR and not touch the Apache
HTTP 2.0 server.

12.1.1 Documentation and resources

For you to successfully implement a more complex module using the APR of Apache, you
need to study the following documentation:
򐂰 V5R3 HTTP Server Documentation Center:
Select the document depending on the version you are using, V5R3, V5R2, or V5R1.
Inside the V5R3 IBM HTTP Server for iSeries Documentation Center, click
Programming →HTTP Server (powered by Apache) and Apache portable runtime
application programming interfaces →Compile and configure modules on HTTP
Server (powered by Apache). You can find the documentation center at:
http://www.ibm.com/servers/eserver/iseries/software/http/docs/doc.htm
򐂰 Apache Software Foundation home page:
http://www.apache.org
򐂰 Apache Software Foundation documentation:
http://httpd.apache.org/
Select Apache 2.0 under Documentation.
򐂰 Links to many Apache Software Foundation resources on APR:
http://apr.apache.org/
򐂰 Apache modules registry:
http://modules.apache.org/

These online magazines often provide Apache 2.0 leading edge advice and support,
especially in the area of writing modules:
򐂰 ApacheToday news and information online:
http://www.apachetoday.com
򐂰 Apache Week news and information online:
http://www.apacheweek.com
򐂰 Onlamp news and information online:
http://www.onlamp.com/apache/

314 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
12.2 Creating a module for the iSeries server
The best way to learn how to create a module for the iSeries server is to just do it.

12.2.1 The task at hand

Our goal is to create a module that adds text (most likely HTML) to the start of a Web page.
We do so only within the context in which we define an output filter handler. That is, we use
the same way that all Apache directives can inherit or override the settings of directives found
above this context. This, in effect, provides private storage for our module. There is one per
Directory context.

In our example, Table 12-1 defines many of the features of our module.
Table 12-1 Definition of the HeaderFilter module
Feature How is it defined or used

DocumentRoot /tcp52d00/basicconfig/itsoco

HeaderFilter active in context <Directory /tcp52d00/basicconfig/itsoco/people>

Define the text that will be added just before HeaderText “<center><B><i>Listen to all the
the start of the <html> tag with all pages People</i></B></center>”
sent from within the active context.

Cause the header_module module to be LoadModule header_module

loaded /QSYS.LIB/TCP52L00.LIB/MOD_HEADER.SRVPGM

12.2.2 Source code and comments

This section provides the C language source code and annotated comments to help guide
your understanding of the logic behind the code.

mod_header.c source code and annotation

Example 12-1 shows the C language source code of the module mod_header.c. The
numbered annotations found in the source code are described in “Comments to
mod_header.c” on page 318.

You can find this source code in:

򐂰 Library: TCP52L00
򐂰 Source file: QCSRC
򐂰 Member: MOD_HEADER
Example 12-1 C language source code for the mod_header.c module
/* 1 */
#include "apr_strings.h"
#include "apr_xlate.h"
#include "ap_config.h"
#include "util_filter.h"
#include "httpd.h"
#include "http_config.h"
#include "http_request.h"
#include "http_core.h"
#include "http_protocol.h"
#include "http_log.h"
#include "http_main.h"
#include "util_script.h"
#include "http_core.h"

Chapter 12. Apache Portable Runtime: Extending your core functionality 315
 #include "util_charset.h"

module AP_MODULE_DECLARE_DATA header_module; /* 2 */

/* 3 */
typedef struct header_rec {
const char *headert;
} header_rec;

/*
* 4 Handle the HeaderText directive
*/
static const char *add_header_text(cmd_parms *cmd, void *dummy,
const char *arg)
{
header_rec *d = dummy;

/* store the text for the header. */

d->headert = apr_pstrdup(cmd->pool, arg);
return NULL;
}

/*
* 5 Define the directives
*/
static const command_rec dir_cmds[] =
{
AP_INIT_TAKE1("HeaderText", add_header_text, NULL,
ACCESS_CONF || OR_FILEINFO,
"text for a header"),
{NULL}
};

/*
* 6 Create the module specific structure
*/
static void *create_header_config(apr_pool_t *p, char *dummy)
{
header_rec *new =
(header_rec *) apr_pcalloc(p, sizeof(header_rec));

new->headert = NULL;
return (void *) new;
}
/* 7 */
typedef struct header_struct {
int state;
} header_struct;

/*
* 8 Define the filter to add the header text to the request.
*/
static int header_filter(ap_filter_t *f, apr_bucket_brigade *bb)
{
header_struct *ctx = f->ctx;
header_rec *conf;
apr_bucket *e;

/* get the module specific structure for the current context. */

conf = (header_rec *)ap_get_module_config(

316 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 f->r->per_dir_config,
&header_module);

/* If the current context has not been created, create one */

if (ctx == NULL) {
f->ctx = ctx = apr_pcalloc(f->r->pool, sizeof(*ctx));
}

/*
* If the context state is 0 (meaning we haven't yet done this)
* AND if the current object being processed is text/html
* Then we will process what was defined in the HeaderText directive
*/
if((ctx->state == 0) &&
(!strcasecmp(ap_field_noparam(f->r->pool, f->r->content_type),
"text/html"))) {
ctx->state = 1; /* Indicate that we've been here */
/* If HeaderText directive has been defined for the current context...*/
if (conf->headert) {
char *headertext = apr_pcalloc(f->r->pool,
strlen(conf->headert));
apr_size_t in_length = strlen(conf->headert);
apr_size_t out_length = in_length;
/* We must convert the text string from EBCDIC to ASCII.
* ap_locale_to_ascii is defined by the server at startup time.
*/
apr_xlate_conv_buffer(ap_locale_to_ascii,
conf->headert, &in_length,
headertext, &out_length);

/* Create the bucket to store the ASCII text */

e = apr_bucket_immortal_create(headertext,
strlen(conf->headert));
/* Insert the bucket t the beginning. */
APR_BRIGADE_INSERT_HEAD(bb, e);
}
}

/* Pass the brigade on... */

ap_pass_brigade(f->next, bb);
return APR_SUCCESS;
}

/*
* 9 Register any hooks or filters needed for this module
*/
static void header_register_hook(apr_pool_t *p)
{
ap_register_output_filter("HEADERFILTER",
header_filter,
NULL,
AP_FTYPE_CONTENT);
}
/* 2 */
module AP_MODULE_DECLARE_DATA header_module = {
STANDARD20_MODULE_STUFF,
create_header_config, /* create per-directory config structure */
NULL, /* merge per-directory config structures */
NULL, /* create per-server config structure */
NULL, /* merge per-server config structures */

Chapter 12. Apache Portable Runtime: Extending your core functionality 317
 dir_cmds, /* command apr_table_t */
header_register_hook /* register hooks */
};

Comments to mod_header.c
Here are the comments to the code presented in the previous section. Each numbers
corresponds to the bold numbers in Example 12-1 on page 315:
1. The header files included in this example are only to define all application programming
interfaces (APIs) used in the example. These and a lot more header files are located in
your iSeries server’s integrated file system (IFS) directory
/QIBM/ProdData/HTTPA/include/.
2. This is the Command Module Structure, which is well known to the server. It contains:
– Standard Apache 2.0 module items
– Function pointer to create per-directory configuration structure
– Function pointer to merge per-directory configuration structures
– Function pointer to create per-server configuration structure
– Function pointer to merge per-server configuration structures
– Pointer to command table
– Function pointer to register hooks function
This module also needs to be exported from the service program that you create. See
12.2.3, “Compiling, linking, and exporting your service program” on page 319.
3. Here we declare some module specific storage that will later be used to store the header
text that will come from the configuration file’s HeaderText <center><B><i>Listen to all
the People</i></B></center> directive.
4. This is the add_header_text function. It is one of the parameters used in the command
table.
5. The command table and command handler define:
– The server directives
– Functions to handle those directives
The command table is composed of:
– Directive name
– Configuration action routine. In our case, this is the add_header_file function.
– Additional argument to include in call
– Where directive is valid
– Directive description
The APR module support at 2.0 defines a series of directive initializers used to define how
many arguments (parameters) are passed.
In our case, we use AP_INIT_TAKE1. Since we defined the directive to take one argument
(AP_INIT_TAKE1), the string following the directive in the configuration file needs to be
quoted like this:
HeaderText "<center><B><i>Listen to all thePeople</i></B></center>"
See 12.2.4, “Activating via configuration” on page 320, for the details.
The list of directive initializers include:
– AP_INIT_RAW_ARGS: Function parses the command line itself
– AP_INIT_TAKE1: One argument
– AP_INIT_TAKE2: Two arguments
– AP_INIT_ITERATE: One argument, occurring multiple times
– AP_INIT_ITERATE2: Two arguments; the second occurs multiple times

318 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 – AP_INIT_FLAG: Values “On” or “Off”
– AP_INIT_NO_ARGS: No arguments
– AP_INIT_TAKE12: One or two arguments
– AP_INIT_TAKE3: Three arguments
– AP_INIT_TAKE23: Two or three arguments
6. Create a per-directory configuration. This, in effect, provides private storage for our
module. One per Directory context. This can be merged with previous context in the tree in
the same way that all Apache directives can inherent or override the settings of directives
found above this context.
7. Define the filter context structure. This structure is designed to keep track of things needed
in case this filter is called multiple times in a context.
8. This is the main declaration and code that is our output filter.
9. Register the output filter hook. All register hooks are called at startup time. They are
designed for modules to register the filters (as in this example) and to specify which
phases the module wants to hook. This can be done by calling APIs for specific hooks (for
example calling ap_hook_translate_name to hook the URI to filename translation phase).

12.2.3 Compiling, linking, and exporting your service program

After you create your module, it is time to compile and then create and export the
header_module service program.

Note: A change to the HTTP Server (powered by Apache) in V5R2 requires a new
parameter TERASPACE(*YES) on the Create C Module (CRTCMOD) command. If you
recompile your programs with this option and then rebuild your service program, the
performance of your service program should improve.

Compiling the service program

For V5R2 and V5R3, you enter the following command (all as one command):
CRTCMOD MODULE(TCP52L00/MOD_HEADER)
SRCSTMF('/QSYS.LIB/TCP52L00.LIB/QCSRC.FILE/MOD_HEADER.MBR') DEFINE(AS400)
LOCALETYPE(*LOCALE) TERASPACE(*YES) INCDIR('/qibm/proddata/httpa/include')

For V5R1, you enter the following command (all as one command):
CRTCMOD MODULE(TCP52L00/MOD_HEADER)
SRCSTMF('/QSYS.LIB/TCP52L00.LIB/QCSRC.FILE/MOD_HEADER.MBR') DEFINE(AS400)
LOCALETYPE(*LOCALE) INCDIR('/qibm/proddata/httpa/include')

For V4R5, you enter the following commands:

CHGCURDIR DIR('/qibm/proddata/httpa/include')

CRTCMOD MODULE(TCP52L00/MOD_HEADER)
SRCSTMF('/QSYS.LIB/TCP52L00.LIB/QCSRC.FILE/MOD_HEADER.MBR') DEFINE(AS400 '_MULTI_THREADED')
LOCALETYPE(*LOCALE)

Creating and exporting the service program

For either V5R3, V5R2, V5R1, or V4R5, you create a service program export source member.
You can find this source code in:
򐂰 Library: TCP52L00
򐂰 Source file: QSRVSRC
򐂰 Member: MOD_HEADER

Chapter 12. Apache Portable Runtime: Extending your core functionality 319
 It contains:
STRPGMEXP PGMLVL(*CURRENT)
EXPORT SYMBOL("header_module")
ENDPGMEXP

Then create the mod_header service program:

CRTSRVPGM SRVPGM(TCP52L00/MOD_HEADER) MODULE(TCP52L00/MOD_HEADER) EXPORT(*SRCFILE)
SRCFILE(TCP52L00/QSRVSRC) SRCMBR(MOD_HEADER) BNDSRVPGM(QHTTPSVR/QZSRAPR QHTTPSVR/QZSRCORE
QHTTPSVR/QZSRXMLP QHTTPSVR/QZSRSDBM)

Note: If you create a module with *PUBLIC *RWX authority, there should be no authority
considerations. If *PUBLIC is *EXCLUDE, authority has to be granted explicitly to the
profile that the server instance will run under as well as user profile QTMHHTTP.

12.2.4 Activating via configuration

Then add these directives to your configuration file:
򐂰 To cause the module header_module to be loaded by the HTTP Server (powered by
Apache) at server startup time:
LoadModule header_module /QSYS.LIB/TCP52L00.LIB/MOD_HEADER.SRVPGM
򐂰 Within the context in which you want the module header_module to be executed, use
HeaderText as a directive to define the HTML text that will be added to the start of any
HTML page within this context. Consider this example:
<Directory /tcp52d00/basicconfig/itsoco/people>
HeaderText "<center><B><i>Listen to all the People</i></B></center>"
</Directory>

Attention: When using the Display Configuration File option of the IBM Web
Administration for iSeries interface, the administration program checks for syntax errors. A
directive with an incorrect syntax is displayed in red. Directives that are added via user
modules are also displayed in red even if they are correct.

12.2.5 Testing header_module

To test header_module, save your configuration file and then start your server:
򐂰 Server: PBABASIC00
򐂰 Listen: port 8000
򐂰 DocumentRoot: /tcp52d00/basicconfig/itsoco

With the Uniform Resource Locator (URL) http://as20:8000/index.html, you should see
your normal home page unchanged as shown in Figure 12-3.

320 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 12-3 header_module is not evoked for this context; no changes to HTML

Next, using the navigation bar on the left, click People. The pages to support the People
section of our small Web application are defined within the context in which header_module is
registered. This causes the People page to look like the example in Figure 12-4.

Figure 12-4 header_module evoked for this context; notice ‘Listen to all the People’

Further, if you view the source for the page, you see:
<center><B><i>Listen to all the People</i></B></center>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<META NAME="Generator" CONTENT="NetObjects Fusion 5.0.1 for Windows">
<TITLE>People</TITLE>
</HEAD>
<BODY ...

Chapter 12. Apache Portable Runtime: Extending your core functionality 321
12.2.6 Debugging
Here are two methods to debug your module:
򐂰 Compile your module with debug views turned on, for example:
CRTCMOD MODULE(TCP52L00/MOD_HEADER) DBGVIEW(*ALL)
SRCSTMF('/QSYS.LIB/TCP52L00.LIB/QCSRC.FILE/MOD_HEADER.MBR') DEFINE(AS400)
LOCALETYPE(*LOCALE) TERASPACE(*YES) INCDIR('/qibm/proddata/httpa/include')
You can then use the Start Service Job (STRSRVJOB) and Start Debug (STRDBG)
commands to set breakpoints in your module.
򐂰 You can directly add trace points into your code. These trace points can be turned on and
off with the Trace TCP/IP Application (TRCTCPAPP) CL command.
The APIs for this are defined in the API guide. For more information about this, click the
Reference documentation for HTTP Server link on the iSeries Information Center at:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/ic2924/index.htm
Using AP_ERROR_TRACE, AP_INFO_TRACE, or AP_VERBOSE_TRACE at various
places in the code accomplishes this. Then the user only has to use the TRCTCPAPP
command to turn on and off the trace for the instance. The trace points that were added
appear in the TRCTCPAPP output depending on the level coded versus the level
requested.

322 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 13

Chapter 13. Problem determination: When

things do not go as planned
Setting up and tuning an HTTP server requires time, testing, and patience. This chapter helps
you face the problems that you may encounter in both phases. It gives you a better
understanding of the practices and tools to assist you in your work.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 323
13.1 The art of problem determination
This section is by no means a ready solution for all of your Web serving woes. It is only
intended as a quick guide to help solve the most common problems you will encounter when
configuring and managing your HTTP Server (powered by Apache).

If you are experiencing a special problem, skip Table 13-1. Instead read 13.2, “Tools of the
trade” on page 327, which explains the detailed problem determination tools and techniques.
Use Table 13-1 as a quick checklist and a guide during problem determination.

Note: If the graphical user interface (GUI) is not doing what you want it to do, then see
Table 13-2.

Table 13-1 Problem determination checklist

Symptom What to do

The server does not 򐂰 Manually start your server from a green screen using the Start TCP/IP Server
start or does not stay (STRTCPSVR) command. Look for messages in your job log. The completion message
active. CPC1221 informs you that job NNNNNN/QTMHHTTP/SERVERNAME was submitted.
You can use this data in the Work with Job (WRKJOB) command to retrieve the server job
log. Refer to 13.2.1, “Working with configuration files” on page 327, for detailed
information about server job logs.
򐂰 Make sure that the user profile QTMHHTTP or the profile you chose as the default (see
Figure 13-5 on page 330) fits this profile:
– Exists on the server
– Is enabled
– Has no password expiration date set
򐂰 If using Net.Data or Common Gateway Interface (CGI) programs, repeat the previous
step for user profile QTMHHTP1.
򐂰 Check that all software requirements are met. Refer to Chapter 2, “From zero to powered
by Apache” on page 17, for additional information.

We can't find the 򐂰 Verify that the HTTP server is active. Also PING the server using both the name and
“myserver” message Internet Protocol (IP) address. If name fails and IP succeeds, this is a Domain Name
using Internet System (DNS) problem. Either add the server name and IP to your client’s hosts table or
Explorer. contact your DNS server administrator.

There was no 򐂰 Make sure that you enter the Uniform Resource Locator (URL) in your address bar
response. The server exactly like the following examples if you are using Secure Sockets Layer (SSL) or
must be down or is not Transport Layer Security (TLS):
responding to the http://servername:port
message using https://servername:secureport
Netscape. 򐂰 Check your browser’s proxy setting and set it appropriately. If your Web client is
connected directly to the HTTP Server (powered by Apache), then try deleting the client
proxy configuration to see if that makes a difference.
򐂰 Use the Work with Subsystem Jobs (WRKSBSJOB) command to see whether the
QHTTPSVR subsystem is hosting your HTTP server jobs. If you are using Web
application servers that run on top of the HTTP server, such as WebSphere or Tomcat,
use the Work with Active Jobs (WRKACTJOB) command and set the JOB parameter to
your server name instead.

324 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Symptom What to do

Continued – If you don’t see any job named after your server, refer to the previous tip “The server
does not start”.
– If the jobs are active, use the Work with TCP/IP Network Status (NETSTAT) command
with the *CNN option. Look at the port numbers listed in the Local Port column. You
should be able to find port 80 (or the port you chose for your server).
– If your port is not listed, look for clues in the server job logs. See 13.2.2, “Job logs” on
page 329, for details.
Note: When you are unable to bind to a specific port, the HTTP server jobs remain active for
approximately five minutes. During this time, the bind operation is attempted every five
seconds, and the message HTP803D is posted to the job log. Should this occur, make sure
that no other application is already using the same port.

HTTP error message 򐂰 Make sure that the file you requested meets this criteria:
404 - File not found. – Exists in your document root or in your current path.
– Can at least be read by your server user profile. Use the Display Authority (DSPAUT)
command for this purpose. See Figure 13-5 on page 330 if you don’t know which user
profile is running the server.
򐂰 Look at the access_log and error_log files. You’ll find more information about log files in
13.2.3, “Server logs” on page 331.

CGI program or 򐂰 Use the Display Authority (DSPAUT) command to verify that the program can be run by
Net.Data macro is not user QTMHHTP1.
running. 򐂰 Check the server job log for obvious clues.
򐂰 Refer to HTTP Server for iSeries Programming, GC41-5435, for CGI program debugging
tips. See 13.2.4, “Net.Data logs and traces” on page 340, for information about Net.Data
debug procedures, or look at a sample Net.Data configuration in 7.3, “Net.Data: A
ready-made scripting tool” on page 161.

Unsatisfying 򐂰 See 10.1, “iSeries Web server performance components” on page 226.
performance.

LDAP authentication When Lightweight Directory Access Protocol (LDAP) user authentication fails for HTTP basic
does not work authentication, the error_log of your HTTP server instance is the starting point for debugging.
There can be multiple reasons why LDAP authentication fails. The following examples give
some hints on where to look for possible causes.
򐂰 Error message in error_log:
[Fri Oct 01 13:35:18 2004] [error] ZSRV_MSG0080: Unable to authenticate HTTP
server for realm 'FRA822 LDAP Server': Error is Invalid credentials.
When using LDAP authentication, the HTTP server is an LDAP client that needs to bind
to the LDAP server. The LDAP configuration file (see 6.2.3, “Authentication by LDAP
entries” on page 113) contains the bind distinguished name (DN) and the password that
is used by the HTTP server to authenticate to the LDAP server. When receiving the
previous message, the HTTP server was not able to authenticate to the LDAP server. To
correct the problem, check the administrator DN and password.
򐂰 Error message in error log:
[Fri Oct 01 13:32:53 2004] [error] ZSRV_MSG0066: Unable to find entry with
search filter '(&(objectclass=person)(!(cn=barle *)(uid=barle)))': Returning
401 error
This message indicates that the HTTP server successfully bound to the LDAP server and
used the search filter '(&(objectclass=person)(!(cn=barle *)(uid=barle)))' to look for an
entry where the objectclass is person and the common name (cn) attribute or the uid
attribute contains the value barle. In this case, the user does not exist. However, the
message is also issued when the search filter contains errors. To correct the problem,
verify that the user as displayed in the search filter part of the log does exist.

Chapter 13. Problem determination: When things do not go as planned 325

 Symptom What to do

LDAP authentication You can also verify the search filter definition in the LDAP properties file you created
does not work during the LDAP authentication setup.
(continued) 򐂰 Error message in error_log:
[Fri Oct 01 13:49:16 2004] [warn] ZSRV_MSG0063: Basic authentication failure
for user 'cn=Thomas Barlen,o=company00': Error is Invalid credentials
When you receive an error such as this, the HTTP server successfully connected to the
LDAP server and looked up an entry with the specified search filter. Also the LDAP server
returned the hashed password to the HTTP server. You can easily recognize this by the
DN of the entry in the log file. However, this time the password is the problem. To correct
the problem, the user must enter the correct password or the administrator needs to reset
the password for the user.

Table 13-2 identifies some common problems with the Administration GUI used to configure
and manage your HTTP Server (powered by Apache).
Table 13-2 Common GUI problems
A common problem What you can do

msgCEE0200 is in the Verify that JDK 1.3 (5722-JV1 option 5) is installed on your system. See Chapter 2, “From zero
ADMIN job log. to powered by Apache” on page 17, for a list of pre-requisites.

Password prompt Check your browser security setting. Both JavaScript and Cookies must be enabled.
appears several times.

Frames do not display

properly.

Buttons do not work.

The page is too large Most GUI pages are best viewed at a 1024x768 screen resolution. Here are other tips for
to fit in the browser adjusting the view:
window. 򐂰 The frames you see on the screen can be resized. Click a frame border and drag it to a
different position. This new layout is maintained for the whole session.
򐂰 Try a smaller font size. Select View →Text Size from the menu options in Internet
Explorer, View →Decrease Font in Netscape Navigator, or Document Zoom in the
Opera list.

ADMIN does not start. Use the Work with Job (WRKJOB) CL command to retrieve the server job log, and look for
significant clues.

ZUI_50004: OS/400 Remember that you are ultimately dealing with OS/400 configuration files. OS/400 requires
user profile *IOSYSCFG authority from any user attempting to alter configuration files. Sign on with a more
USERNAME does not powerful profile.
have *IOSYSCFG
authority, which is
required to use the
configuration and
administration
interface of IBM HTTP
Server for iSeries.

Other interesting tips. DSPAUT OBJ('/') should not show *EXCLUDE for *PUBLIC.

Use the Work with Object Links (WRKLNK) CL command to browse the IFS path
/QIBM/UserData/HTTPA/admin/logs where the ADMIN error logs are stored. For additional
information, see the following section.

326 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
13.2 Tools of the trade
Let us now look at the tools that make our everyday tasks easier. We identify what they are
and how we can make the most out of them. This section takes you deeper into problem
determination and shows how to work with configuration files, logs, and iSeries native
instruments such as job logs and application traces.

13.2.1 Working with configuration files

Manually editing the configuration file requires care, patience, knowledge of the configuration
directives, and a good backup of the original file. We recommend that you do not manually
edit your httpd.conf file unless you really know what you are doing and you have solid
experience with the Apache configuration directives.

The recommended way to change or create your HTTP Server (powered by Apache)
configuration is to use the GUI. The GUI also supports good tools for displaying and editing
configuration files.

From the main Configuration panel, select the Display Configuration File option. This opens
the content of your configuration file just as the server sees it. This is really important if you
manually altered the configuration file using the green screen Edit File (EDTF) utility. EDTF is
a quick and handy tool for editing files on the iSeries server, but it doesn’t provide the
additional error highlighting that the GUI has.

Note: This check on the configuration file is similar to what the Apache native -t switch
does. See 13.2.7, “Other startup parameters” on page 351, for -t and other switches.

For an example, look at the second to last line in Figure 13-1, where we purposely added the
unsupported directive AddModule to our httpd.conf file.

Edit file: /www/itsonew/conf/httpd.conf

Record : 1 of 28 by 18 Column : 1 101 by 131
Control :

....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+...
************Beginning of data**************
# Configuration originally created by Create HTTP Server wizard on Wed Sep 29 15:03:49 C
Listen *:8022
DocumentRoot /www/itsonew/htdocs
Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes -IncludesNoExec
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%{Cookie}n \"%r\" %t" cookie
LogFormat "%{User-agent}i" agent
LogFormat "%{Referer}i -> %U" referer
LogFormat "%h %l %u %t \"%r\" %>s %b" common
LogMaint logs/error_log 7 0
AddModule mod_cgi
SetEnvIf "User-Agent" "Mozilla/2" nokeepalive

Figure 13-1 The EDTF utility to edit the httpd.conf file

We save the file, and then go back to the GUI main configuration panel (Figure 13-2). Locate
the Tools section at the bottom of the display and click Display Configuration File.

Chapter 13. Problem determination: When things do not go as planned 327

 The latest selection displays the content of the httpd.conf file as shown in Figure 13-2. As you
can see, the unsupported directive is highlighted and a comment is placed underneath. Each
line is also numbered, making errors easier to spot. Also notice that the directives used by
default are crossed out and are destined to be deleted.

Note: Since directives contain default values, which is what the server uses if it does not
find them, there is no reason to have them in the configuration. To limit the configuration file
size and improve its readability, they are deleted. This occurs when you are in the
configuration GUI for the specific directive and click OK or Apply.

Figure 13-2 Display Configuration File: Line 10 indicates a problem with the configuration file

Let’s see what happens if we try to start the server using this configuration file. The server
ends immediately after parsing the invalid AddModule directive in line 10. The HTP8006 and
HTP8008 error messages in the job log (as shown in Figure 13-3) clearly indicate where the
problem lies. Now refer back to Figure 13-2 to see that line 10 of our configuration file is
indeed the invalid AddModule directive.

Note: Not all directives that are marked as not recognized are actually incorrect directives.
The GUI checks for directives that it knows. You could still see a directive in error for
directives that belong to modules you have written or modules that are not part of the IBM
HTTP Server for iSeries product. However, the joblog and the GUI are an excellent starting
point for problem determination.

For more information about collecting, locating, and analyzing job logs, continue with the
following section.

328 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Display Spooled File
File . . . . . : QPJOBLOG Page/Line 1/28
Control . . . . . Columns 1 - 130
Find . . . . . .
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+....2....+
HTP8006 Diagnostic 40 05/01/03 13:21:51.124792 QZSRAPR QHTTPSVR *STMT QZSRCORE QHTTPSVR *STMT
From module . . . . . . . . : QZSRSNDM
From procedure . . . . . . : sendMessageToJobLog
Statement . . . . . . . . . : 11
To module . . . . . . . . . : HTTP_CONFI
To procedure . . . . . . . : ap_walk_config_sub
Statement . . . . . . . . . : 11
Message . . . . : Directive not recognized.
Cause . . . . . : Directive AddModule is not a recognized HTTP server
directive. The HTTP server did not start. Recovery . . . : Correct or
remove the directive. Then start the HTTP server again. Technical
description . . . . . . . . : See the HTTP server documentation on
configuration and administration for more information.
HTP8008 Escape 40 05/01/03 13:21:51.126128 QZSRAPR QHTTPSVR *STMT QZHBHTTP QHTTPSVR *STMT
From module . . . . . . . . : QZSRSNDM
From procedure . . . . . . : sendEscapeWithMessageFile
Statement . . . . . . . . . : 4
To module . . . . . . . . . : HTDAEMON
To procedure . . . . . . . : BigSwitch__FiPPc
Statement . . . . . . . . . : 1070
Message . . . . : HTTP Server Instance ITSONEW failed during start-up.
Cause . . . . . : HTTP Server instance ITSONEW failed because of a
configuration error on line 10 in configuration file
/www/itsonew/conf/httpd.conf. Note: If the specified directive is either a
container directive (e.g. <Directory>), or a directive within a container,
the line number identified above may not be correct. In that case, you will
need to verify that all directives in the container, and the container
itself do not have configuration errors. Recovery . . . : See previous
job log messages. Correct the problem and start the server again.

Figure 13-3 Display spooled file: HTP8006 and HTP8008

13.2.2 Job logs

HTTP server job logs are the first place to look for information whenever an abnormal ending
occurs. Their content can be more or less detailed, depending on the message logging
settings in the job description (JOBD) in use. The JOBD used by the HTTP Server (powered
by Apache) is QZHBHTTP in the QHTTPSVR library. Changing its message logging settings
always influences the content of your server job logs. Figure 13-4 shows the default values for
this IBM-supplied JOBD.

Changing the Text setting from *NOLIST to *MSG or *SECLVL can be extremely useful for
debugging purposes. See the online help for the Change Job Description (CHGJOBD) CL
command for usage information. Also remember that *SECLVL generates a highly verbose
job log for every server job. Therefore, do not choose it as a default setting.

Chapter 13. Problem determination: When things do not go as planned 329

 Display Job Description
System: ASM20
Job description: QZHBHTTP Library: QHTTPSVR

Message logging:
Level . . . . . . . . . . . . . . . . . . . . : 4
Severity . . . . . . . . . . . . . . . . . . . : 0
Text . . . . . . . . . . . . . . . . . . . . . : *NOLIST
Log CL program commands . . . . . . . . . . . . : *NO
Accounting code . . . . . . . . . . . . . . . . : *USRPRF
Print text . . . . . . . . . . . . . . . . . . . : *SYSVAL

Routing data . . . . . . . . . . . . . . . . . . : HTTPWWW

Request data . . . . . . . . . . . . . . . . . . : *NONE

Device recovery action . . . . . . . . . . . . . : *SYSVAL

More...
Press Enter to continue.

F3=Exit F12=Cancel

Figure 13-4 Display Job Description: Default message logging

Job logs are always produced under the default QTMHHTTP profile unless you choose to use
a different one, adding a ServerUserID directive in your configuration file. Figure 13-5 and the
following steps show how to set a default user using the GUI:
1. In the left pane, under Server Properties, click General Server Configuration.
2. In the General Server Configuration panel, click the Advanced tab.
3. In the Server user profile field, type the user profile name that is used by the HTTP server.
If no user profile is specified, it defaults to QTMHHTTP.

Figure 13-5 General Server Configuration: Server user profile

330 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Messages in your server job logs often contain helpful hints for problem determination, for
example:
򐂰 The name of a failing module
򐂰 Illegal configuration options
򐂰 Usage of a deprecated directive
򐂰 The number of the line where an error was found

To determine where the problem lies, you can also look up the line number referred to in the
message body with the Display Configuration File menu option as explained in 13.2.1,
“Working with configuration files” on page 327.

13.2.3 Server logs

Server logs are most useful for monitoring server activity and keeping track of user access, as
well as being a valid aid in debugging. By carefully examining these logs, you can discover
the reason behind the most common error messages and eventually point out configuration
errors. Figure 13-6 shows the logging options.

Figure 13-6 Logging server activity: General Settings page

General settings
The General Settings page allows you to configure settings that apply to all server log files
such as selecting which time format each log entry time stamp will follow, controlling how
often log files are closed and new log files created, and limiting the size of any defined log file.
This is also a security mechanism, to protect the server in case of a denial of service attack
from filling up direct access storage device (DASD) by producing huge log files.

The Log cycle parameter controls how often log files are closed and new log files created.
Maximum log file size limits the size of any defined log file on the system.

Chapter 13. Problem determination: When things do not go as planned 331

 Custom logs
The Custom Logs page allows you to configure various log attributes, such as the format for
the information in the log file, rules for excluding entries from the log file, and client side
information logging. Each server configuration file contains information about the type of log
files the server will create. Logging information allows you to track and generate reports on
your server's activity. Figure 13-7 shows a sample access log configuration, which is
automatically created during the basic configuration with the Wizard. See 2.3.1, “Your first
HTTP Server (powered by Apache) via a wizard” on page 24.

Figure 13-7 Access log settings and log formats

What the setup means

Notice that our access log uses the combined format. It expires after 10 days and it is allowed
to have a maximum cumulative size of 10 MB. That means, that, based on the General
settings page, a new log file is created daily. It’s allowed to grow up to 20 MB. If the server
encounters a denial of service attack, it fills up the log file to its maximum size and stops
logging. Otherwise it closes the log file and opens a new one. If the cumulative size of all
access_log files is beyond the configured 10 MB, the server starts to delete the expired ones.
If it’s still too large, all other log files are deleted, beginning from the oldest, until the
cumulative size is reached, or less.

Log files that are currently in use are not processed. The previous explanation is valid for all
custom logs as well as for error and Fast Response Cache Accelerator (FRCA) logs.

Tip: There is no restriction on the maximum amount of customized logs you define, but
consider that every log file (and log maintenance) produces overhead for your HTTP
Server (powered by Apache).

332 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Log management options
As shown in Figure 13-7, you can set an expiration period and a maximum cumulative size for
log files. Following is an explanation of the two log management options:
򐂰 Expiration: This option specifies an integer value that indicates the number of days before
a log file expires. Files older than this value are deleted. A value of 0 means the log file will
never expire. The age of the log file is determined by the file creation date (as reported by
the operating system). A log file that is currently open and active in the server instance is
not deleted.

Note: By default, the HTTP server starts the deletion process every day at midnight.
That means, if your server instance is not up and running at midnight, log maintenance
will not occur. A new directive, which was not available via the IBM Web Administration
for iSeries interface at the time of writing the redbook, can be used to change the time
at which the server instance is running the log deletion process. The following example
shows the directive that needs to be added to start the log maintenance process at
10:00 o’clock in the morning.

LogMaintHour 10

The deletion process starts at the top of the hour that is specified as a parameter to the
LogMaintHour directive. Valid values are 0 - 23. Note that this directive is displayed in
the GUI as not recognized.

򐂰 Maximum cumulative size: This option specifies an integer value indicating the
maximum aggregate size of log files. When the combined log files exceeds this value in
bytes, files are deleted starting with the oldest file. Log files are deleted until the
cumulative size is within the specified value. A value of 0 means there is no size limit. If
both the expiration and maximum cumulative size are configured to non-zero values, the
expired log files are deleted first. If the maximum cumulative size is still exceeded after the
expired files are deleted, the server continues deleting log files (oldest files first) until the
cumulative size is achieved.

Chapter 13. Problem determination: When things do not go as planned 333

 What is stored in these logs
Let’s see what kind of information is stored in these three logs based on the log format we
chose. Figure 13-8 shows five user-defined formats and the type of information that we want
them to collect. Each of the case-sensitive tokens that we can use in a format definition
represents different information about the client, the request received, or the status of
client-server communications.

Figure 13-8 Log formats

We now analyze an access log entry, looking for the data that we included in the associated
log format. Let’s say we want to access our server’s sample home page. We open a browser
window and type http://servername:port in the address bar, as shown in Figure 13-9.

Figure 13-9 Sample home page

334 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 The last line in our server’s access log now looks like the one in Figure 13-10.

Browse : /www/itsonew/logs/access_log
Record : 1 of 1 by 18 Column : 1 130 by 131
Control :

....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....
9.146.221.156 - - ¬01/Oct/2004:13:11:11 +0200| "GET / HTTP/1.1" 200 717 "-" "Mozilla/4.0 (compatible; MS
************End of Data********************

Figure 13-10 Analyzing the access log

Table 13-3 breaks down our string and identifies the relationship between what we chose to
log in Figure 13-8 and the data our server collected.
Table 13-3 Understanding the access log
Access log Token Meaning

9.146.221.156 %h The remote host’s IP address.

- %l The user logged on to the remote system. In this case, the browser did not
provide the user’s name for security reasons.

- %u Name of the authenticated user (no user authentication was performed

yet).

01/Oct/2004:13:11:11 %t Date and time the request was served. +0200 is the difference from UTC.
+0200 See system value QUTCOFFSET

"GET / HTTP/1.1" %r The request received. We can identify the method (GET), the Uniform
Resource Identifier (URI) ( /, since we did not request any specific
document) and the protocol used for this transaction (HTTP version 1.1).

200 %>s The HTTP status code. 200 means that this transaction was successful.
See 13.2.8, “HTTP status codes” on page 352, for more information.

717 %b The amount of data transmitted, in bytes.

"-" %{Referer} The page we came from. There is none in this case, since we manually
typed our address.

"Mozilla/4.0 %{User-Agent} Information about the browser and operating system on the remote client.
(compatible; MSIE In this case, Microsoft Internet Explorer on a Microsoft Windows 2000
6.0; Windows NT® operating system.
5.0)”

There is much more information you can log. For more information about customizing log
formats, see the log format article in the HTTP Server documentation center at:
http://www-1.ibm.com/servers/eserver/iseries/software/http/docs/doc.htm

You should also see the Worldwide Web Consortium (W3C) logfile standards at:
http://www.w3.org

Error logs
Servers created using the GUI wizard always produce an error log by default. Look for error
log files in the /logs subdirectory of your server root. Basic error logs are most useful for
debugging configuration problems, such as when a document is not accessible or the URI
(the path you add after the server address) you’re pointing to is not working as expected.
Error logs also keep track of configuration changes, server end/restart, and record some

Chapter 13. Problem determination: When things do not go as planned 335

 system errors. Be aware that any problem detected after server initialization is most likely not
recorded in the server job logs (unless a critical condition occurs), but in the error log. As you
can see in Figure 13-11, error logs are really easy to configure. Figure 13-11 shows the
configuration panel that results in the following directives in the configuration file:
򐂰 ErrorLog logs/error_log
򐂰 LogLevel warn

Figure 13-11 Error Logs settings and resulting directives

Note: The HTTP Server (powered by Apache) uses error logs per default. You may not be
able to see the directives ErrorLog and LogLevel in the configuration file, although errors
are being logged. To disable error logging, simply change the configuration directive to
ErrorLog Off or use the GUI (Figure 13-11) and set it to DISABLED.

Script logs
Script logs record all CGI parsed data and, therefore, can have a significant impact on CGI
performance. They should be used for debug purposes only and not be kept active all the
time. Being a mere debug tool, they are not customizable, but saved for the maximum amount
of data to be collected. The Script log settings in Figure 13-12 result in these directives:
򐂰 ScriptLog logs/script_log (see Script log)
򐂰 ScriptLogLength 10385760 (see Maximum log file size)
򐂰 ScriptLogBuffer 1024 (see Maximum log entry size)

336 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 13-12 Script Logs settings

Custom formats
Each server configuration file contains information about the type of log files the server
creates. Logging information allows you to track and generate reports on your server's
activity. This page allows you to add and remove unique format names and their associated
formats. After you define them, you can specify a format name on one or more CustomLog or
FRCACustomLog directives. The format defines the information that is recorded with each
entry in the log file. Figure 13-13 shows the benefit of using this page. The list provides an
explanation for each token.

Figure 13-13 Custom Formats page

Chapter 13. Problem determination: When things do not go as planned 337

 FRCA logs
This log is used to log FRCA requests to the server (Figure 13-14). You perform the setup in
the same way as in “Custom logs” on page 332.

Tip: FRCA collects logging data in System Licensed Internal Code (SLIC), based on
FRCAMaxCommTime and FRCAMaxCommBufferSize directives (see 10.6.6,
“Miscellaneous FRCA directives beyond the online help” on page 296, for configuration
details). When it sends the data to the HTTP Server (powered by Apache), which is above
the Machine Interface (MI), this data comes as a “chunk”. The log files entries can be
out-of-order and may be more difficult to read. All the log data is there, but not in the same
order as the requests were processed.

This is done to improve the overall performance of the HTTP Server (powered by Apache)
and FRCA servers.

For more information about FRCA, see 10.6, “Fast Response Cache Accelerator” on
page 281.

Figure 13-14 Setting up for FRCA logs

338 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
User tracking (cookies)
This page provides options for tracking user requests via client-side cookies (Figure 13-15).

Figure 13-15 Setting up user tracking

Chapter 13. Problem determination: When things do not go as planned 339

 Customer environment variables
This page allows you to add and remove environment variables and their associated attribute
values (Figure 13-16).

Figure 13-16 Adding customized environment variables

Log analyzers
You can extract access reports, usage statistic, and other interesting data from your HTTP
Server (powered by Apache) logs. A wide range of both commercial and freeware products is
available for this purpose, from the powerful IBM Tivoli Web Site Analyzer suite to simple log
parsing scripts. See:
http://www-306.ibm.com/software/tivoli/products/web-site-analyzer/

13.2.4 Net.Data logs and traces

You can activate Net.Data traces and logs by adding the following directives to your Net.Data
INI file:
DTW_ERROR_LOG_DIR [=] full_directory_path
DTW_ERROR_LOG_LEVEL [=] OFF | INFORMATION | ERROR | INFORMATION+ERROR | ALL
DTW_TRACE_LOG_DIR [=] full_directory_path
DTW_TRACE_LOG_LEVEL [=] OFF | APPLICATION | SERVICE
DTW_TRACE_MERGE_RECORDS [=] YES | NO

Remember that the server user profiles QTMHHTTP and QTMHHTP1 need access to the
Net.Data log folder.

340 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Note: Net.Data logging and tracing support is available through the latest Net.Data or
HTTP group PTFs. See the iSeries Net.Data Web site for updated information:
http://www.iseries.ibm.com/netdata

You should also refer to 7.3, “Net.Data: A ready-made scripting tool” on page 161.

13.2.5 HTTP server trace

An HTTP server trace provides additional information about server operations, from process
management to URI interpretation. Server traces can be activated from the GUI Manage
HTTP Servers display by starting the server with the lowercase -ve, -vi, and -vv startup
parameters. The Start TCP/IP Server (STRTCPSVR) CL command also supports these
startup options. You can collect the same data when the server is already active using the
Trace TCP/IP Application (TRCTCPAPP) and Dump User Trace (DMPUSRTRC) commands.
Be advised that this tracing facility does not support concurrent tracing of multiple HTTP
servers.

Note: The HTTP Server (powered by Apache) does not support the -vi, -ve, and -vv
switches on server restart. If you are unable to end all server jobs, use the Trace TCP/IP
Application (TRCTCPAPP) command instead (see Figure 13-17).

Trace TCP/IP Application (TRCTCPAPP)

Type choices, press Enter.

TCP/IP application . . . . . . . > *HTTP *FTP, *SMTPSVR, *SMTPCLT...

Trace option setting . . . . . . *ON *ON, *OFF, *END, *CHK
Maximum storage for trace . . . *APP 1-16000, *APP
Trace full action . . . . . . . *WRAP *WRAP, *STOPTRC
HTTP server instance . . . . . . > MYSERVER Character value
Trace level . . . . . . . . . . *ERROR *ERROR, *INFO, *VERBOSE

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

Figure 13-17 Trace TCP/IP Application (TRCTCPAPP): Turning on trace

The HTTP server trace can be set to operate at three different levels: error, information, and
verbose. User trace data for both parent and child helper jobs is automatically dumped as
soon as a failure condition is detected. The Dump User Trace (DMPUSRTRC) command is
otherwise used to direct trace output to the same database file while server jobs are still
active. Job name, number, and user profile for each one of your HTTP server jobs are
required. Trace output is dumped to file QAP0ZDMP in QTEMP in a member called
QP0Znnnnnn (where nnnnnn is the HTTP server job number you gave to the DMPUSRTRC
command).

Chapter 13. Problem determination: When things do not go as planned 341

 Table 13-4 shows the usage and purpose of this tracing facility.
Table 13-4 Service trace activation
Startup switch TRCTCPAPP Trace output

-ve *ERROR Server startup only. Nothing else is recorded unless an error
occurs.

-vi *INFO Server startup and initialization, including directive processing,

character conversion, and client request handling.

-vv *VERBOSE All the above plus application programming interface (API) and
module invocation, HTTP headers, error messages.

Here are three examples of how an HTTP server trace can be collected in different
environments:
򐂰 A test environment, an ideal situation in which you have complete control over the server
򐂰 A business-critical application, where the HTTP server is the core component of your On
Demand Business infrastructure and must be available at any time
򐂰 Somewhere in between, a third scenario that fits in between the two extremes

A test environment
You are testing a stand-alone HTTP Server (powered by Apache) configuration that is not
working as you expected. The server stopped and you are ready to collect an HTTP trace.
1. Start the HTTP server with the -ve, -vi, or -vv option. Look for completion message
CPCA984 (see Figure 13-18) in the server job log for confirmation that the trace option
you specified was accepted.

Additional Message Information

Message ID . . . . . . : CPCA984 Severity . . . . . . . : 00

Message type . . . . . : Completion
Date sent . . . . . . : 10/09/01 Time sent . . . . . . : 09:09:09

Message . . . . : User Trace option changed for job

032335/QTMHHTTP/ITSOSRV1.

Bottom
Press Enter to continue.

F3=Exit F6=Print F9=Display message details F12=Cancel

F21=Select assistance level

Figure 13-18 Additional Message Information: CPCA984 - A successful activation

2. Reproduce the failure. Skip the next step if the server jobs already ended.
3. Stop the HTTP server.

342 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
4. Use the Work with Spooled Files (WRKSPLF) CL command or iSeries Navigator
(Operations Navigator for V5R1) to retrieve QZSRHTTPTR spooled files for the
QTMHHTTP user profile (see Figure 13-19).

Work with All Spooled Files

Type options, press Enter.

1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages
8=Attributes 9=Work with printing status

Device or Total Cur

Opt File User Queue User Data Sts Pages Page Copy
QZSRHTTPTR QTMHHTTP PRT01 QSRV035027 HLD 28 1
QZSRHTTPTR QTMHHTTP PRT01 QSRV035029 HLD 29 1
QZSRHTTPTR QTMHHTTP PRT01 QSRV035028 HLD 44 1

Bottom
Parameters for options 1, 2, 3 or command
===> WRKSPLF SELECT(QTMHHTTP)
F17=Top F18=Bottom F21=Select assistance level F24=More keys

Figure 13-19 Work with All Spooled Files: Startup switch output

A business-critical application
The HTTP Server (powered by Apache) is a business-critical application running full time. It
cannot be stopped. You are experiencing occasional problems and need a server trace to
identify the source of your troubles.
1. Start the trace using the command:
TRCTCPAPP APP(*HTTP) SET(*ON) HTTPSVR(SERVERNAME) TRCLVL(*VERBOSE)
Select an appropriate level of information. Message CPC1129 (see Figure 13-21) is
posted to the server job log.
2. Reproduce the failure. Skip the next step if server jobs already ended.
3. Stop the trace with the command:
TRCTCPAPP APP(*HTTP) SET(*OFF)

Chapter 13. Problem determination: When things do not go as planned 343

 4. Use the Work with Spooled Files (WRKSPLF) CL command or iSeries Navigator to
retrieve the QZSRHTTPTR spooled files for the user profile you used for signon (see
Figure 13-20).

Work with All Spooled Files

Type options, press Enter.

1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages
8=Attributes 9=Work with printing status

Device or Total Cur

Opt File User Queue User Data Sts Pages Page Copy
QZSRHTTPTR GBANCHELLI PRT01 QSRV035077 HLD 1 1
QZSRHTTPTR GBANCHELLI PRT01 QSRV035078 HLD 1 1
QZSRHTTPTR GBANCHELLI PRT01 QSRV035076 HLD 1 1

Bottom
Parameters for options 1, 2, 3 or command
===>
F3=Exit F10=View 4 F11=View 2 F12=Cancel F22=Printers F24=More keys

Figure 13-20 TRCTCPAPP output

Somewhere in between
You are developing an intranet application, but you constantly run into an error. The server
cannot be stopped, but you are free to choose your debugging options.
1. Start the trace using the command:
TRCTCPAPP APP(*HTTP) SET(*ON) HTTPSVR(SERVERNAME) TRCLVL(*VERBOSE)
Select an appropriate level of information. Message CPC1129 (see Figure 13-21) is
posted to the server job logs.

Additional Message Information

Message ID . . . . . . : CPC1129 Severity . . . . . . . : 00

Message type . . . . . : Completion
Date sent . . . . . . : 10/11/01 Time sent . . . . . . : 17:30:11

Message . . . . : Job 035076/QTMHHTTP/GERONIMO changed by GBANCHELLI.

Bottom
Press Enter to continue.

F3=Exit F6=Print F9=Display message details F12=Cancel

F21=Select assistance level

Figure 13-21 CPC1129: The trace is active

2. Reproduce the error.

344 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 3. At this point, you want to examine the data collected so far, but you still need to keep
tracing server activity. Retrieve job numbers for your HTTP server jobs and feed them to
the DMPUSRTRC command. Message CPCA986 is posted to your job log (see
Figure 13-22).

Additional Message Information

Message ID . . . . . . : CPCA986 Severity . . . . . . . : 00

Message type . . . . . : Completion
Date sent . . . . . . : 10/11/01 Time sent . . . . . . : 17:31:43

Message . . . . : User Trace data for job 035076/QTMHHTTP/GERONIMO dumped to

member QP0Z035076 in file QAP0ZDMP in library QTEMP.
Cause . . . . . : The User Trace records associated with job
035076/QTMHHTTP/GERONIMO were successfully dumped to member QP0Z035076 in
file QAP0ZDMP in library QTEMP.

Bottom
Press Enter to continue.

F3=Exit F6=Print F9=Display message details F12=Cancel

F21=Select assistance level

Figure 13-22 CPCA986: Trace data has been dumped

4. Look for the file QAP0ZDMP in QTEMP. This file contains a QP0Znnnnnn member for
each one of the server job numbers (nnnnnn) you used in the DMPUSRTRC command.

Tips: Never forget to stop the trace with TRCTCPAPP APP(*HTTP) SET(*OFF) when it
is no longer needed. Also remember that you can access only the content of the
QTEMP library from your current session. It is discarded as soon as you sign off.

13.2.6 Collection Services performance data

Web-based transaction processing and Web-serving environments continue to grow in
importance and complexity. Your HTTP Server (powered by Apache) is the focal point of
many different kinds of On Demand Business environments including SSL, cache
accelerators such as FRCA, and WebSphere Application Server.

Tip: The iSeries HTTP Server (powered by Apache) does not support mod_status. This
simple module allows a Web administrator to take a picture of an Apache server and see
performance-related statistics that drill down to the work performed by each individual
thread.

mod_status was adjusted to work with the Apache 2.0 threaded server by the Apache
Software Foundation (ASF). However the fact that iSeries implements asynchronous
input/output (I/O) (see 10.2.1, “Threads and asynchronous I/O” on page 228) provides
complex challenges for implementing mod_status on the iSeries server.

Unique to the iSeries, HTTP server statistics are saved into collection services in V5R2.
The advantage on the iSeries server is that these reports can provide a more holistic view
of system performance. For example, it helps in situations where you may say, “Ah, I see
the reason that the HTTP Server (powered by Apache) is running so slow. That
programmer recompiled the entire LOB application again on the production server!”

Chapter 13. Problem determination: When things do not go as planned 345

 Beginning in V5R2, you can define your own performance collection categories with iSeries
Collection Services. The HTTP Server (powered by Apache) uses this new feature to
integrate performance data into Collection Services.

As shown Figure 13-23, the Standard plus protocol profile (the default used by Collection
Services) automatically collects HTTP Server (powered by Apache) if Collection Services
detects this application server is active on the system. As with all Collection Services
“collection object data”, the new statistics are placed into the following files via the currently
available iSeries Navigator “Create performance database files” function or the OS/400
Create Performance Data (CRTPFRDTA) command:
򐂰 QAPMHTTPB: Contains the basic data for HTTP Server (powered by Apache)
򐂰 QAPMHTTPD: Contains detailed data for HTTP Server (powered by Apache)

HTTP data collection category to contain HTTP performance data for Collection Services.
The HTTP performance data can then be queried to analyze HTTP server activity and better
understand what types of HTTP transactions are being processed by the iSeries (for
example, static files, CGI, or Java Servlets).

In addition, V5R2 Performance Tools for iSeries, 5722-PT1, has new sections in the System
and Component Reports for HTTP statistics.

Figure 13-23 Start Collection Services: Data to Collect page

The types of data collected are broken down into the following ways. Note that this is per
server job and the statistics are shown for each interval and request type within the interval.

346 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
򐂰 SR: Requests handled internally by the server itself. No program processing is necessary.
򐂰 SL: Requests of all types received via SSL. Reports activity that occurred over an SSL
connection even though that activity is also reported with other applicable request types.
򐂰 PX: Proxy requests.
򐂰 CG: CGI requests.
򐂰 WS: WebSphere requests.
򐂰 JV: IBM Java Servlet Engine requests.
򐂰 UM: Requests handled by user modules.
򐂰 FS: Static requests handled by FRCA.
򐂰 FX: Requests proxied by FRCA.

Starting Collection Services for the HTTP Server (powered by Apache)

We use iSeries Navigator to start and work with Collection Services. To start Collection
Services, as shown in Figure 13-23, follow these steps:
1. Log on to your iSeries server using with iSeries Navigator.
2. Expand your server →Configuration and Service.
3. Right-click Collection Services and select Start Collecting...
4. You see the Start Collection Services window (Figure 13-24). For the most part, you may
accept all the defaults.
Take note of the library to store collections since you need to know this later to find the
files. Also, we chose to set the Default collection interval for detailed data to 5 minutes.
5. Click OK to start Collection Services.

Chapter 13. Problem determination: When things do not go as planned 347

 Figure 13-24 Start Collection Services: General page

At this point, your HTTP Server (powered by Apache) server and related applications should
be up and running in a “steady state”. Collect the data for as long as you need.

When you are done collecting the data, stop Collection Services:
1. Right-click Collection Services and select Stop Collecting...
2. In the Stop Collection Services panel, click OK.

Performance Tools reports

Performance Tools for iSeries were enhanced in V5R2 to generate reports based on the
HTTP performance data. The reports contain information about the transactions processed
by HTTP server jobs. Follow these steps to see the System and Component reports for the
HTTP server:
1. From a 5250 session, enter the Start Performance Tools (STRPFRT) command.
2. Select option 3 (Print performance report).
3. Change the Library to QMPGDATA. Or, specify the library in which you saved the collection
data. Press Enter to refresh the list of collections.

348 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 4. In the Print Performance Report - Sample data display (Figure 13-25), type option 1
(System report) to the left of the collection data member. Use the Date and Time columns
to make sure you select the correct one.

Print Performance Report - Sample data

Library . . . . . . QMPGDATA

Type option, press Enter.

1=System report 2=Component report 3=Job report 4=Pool report
5=Resource report

Option Member Text Date Time

1 Q168151618 06/17/03 15:16:18
Q168125025 06/17/03 12:50:25
Q143095558 05/23/03 09:55:58

Figure 13-25 Performance Tools: Option 1 (System report)

5. In the Select Sections for Report display, press F6 to print the entire report.
6. In the Select Categories for Report display, press F6 to print the entire report.
7. In the Specify Report Options display, enter a meaningful report title.

Tip: We like to copy this System Report title so we can paste it to the Component
Report title later. This allows us to match these pairs of reports in the future.

8. Press Enter to submit this work to the batch queue.

9. In the Print Performance Report - Sample data display (Figure 13-25), type option 2
(Component report).
10.Repeat steps 5 through 8 for the Component report.

When the batch jobs finish, you should have two new spool files in OUTQ QPFROUTQ.
Figure 13-26 shows the output of the System Report.

Display Spooled File

File . . . . . : QPPTSYSR Page/Line 9/1
Control . . . . . +5 Columns 1 - 130
Find . . . . . .
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+....2....+....3
System Report 052303 10:22:0
HTTP Server Summary Page 000
Batch jobs
Member . . . : Q143095558 Model/Serial . : 270/10-4RT9M Main storage . . : 8000.0 MB Started . . . . : 05/23/03 09:55:5
Library . . : QMPGDATA System name . . : ASM27 Version/Release : 5/ 2.0 Stopped . . . . : 05/23/03 10:15:0
Partition ID : 000 Feature Code . : 22AB-2253-1520
Server Server job Server job Server start ------- Threads ------- -- Inbound Connections -- Requests Responses
name user number date/time Active Idle Non-SSL SSL received sent
---------- ---------- ---------- -------------- ---------- ---------- ------------ ------------ ----------- -----------
ADMIN QTMHHTTP 050851 05/22/03 11:04 0 40 0 0 0 0
HATSLEHTTP QTMHHTTP 051068 05/22/03 11:16 0 40 0 0 0 0
IAXHTTPEXA QTMHHTTP 051477 05/23/03 08:47 0 40 0 0 0 0
IAXHTTPEXB QTMHHTTP 051045 05/22/03 11:15 1 39 39 0 39 39
IAXHTTPSSL QTMHHTTP 051352 05/23/03 08:45 0 40 0 321 321 321
IWA QTMHHTTP 051022 05/22/03 11:13 0 40 0 0 0 0

Figure 13-26 Performance Tools: System Report - HTTP Server Summary

Chapter 13. Problem determination: When things do not go as planned 349

 Figure 13-27 shows the output of the Component Report for the HTTP server activity. This
example is for the same HTTP server - IAXHTTPSSL included in the System Report HTTP
statistics example. Here you can see that, of the 321 requests shown to be processed by this
server in the System Report example, 308 were processed during the 5 minute interval ended
at 10:00. Thirteen were processed during the 5 minute interval ended at 10:05. You can also
see the average “K bytes” (1024 bytes) sent each second was 5 KB and received was 1 KB
during the 10:00 interval.

Looking closely, you can tell via the SL Request Type (all requests handled under an SSL
connection) that all such requests were handled by some application running under a
WebSphere Application Server (WS Request Type). As defined on the next page, SL counts
also appear under another request type. You have to adjust to this accounting method to
know that actually 321 requests were received from browsers, not the 642 (2 x 321) shown as
total requests received and responses sent.

This example shows that no response was rejected or considered “in error”. High error or
reject values need to be investigated.

Note also the algorithm used when computing average K bytes per second. The Performance
Tools code knows that SL and WS values represent duplicates of each other. Using our 2
intervals example, we have 5K Bytes and 0K bytes per second transmitted averaged as 2K
bytes per second and 1K Bytes and 0K bytes per second received averaged as 0 K bytes per
second.

Component Report 5/23/03 10:22:0

HTTP Server Activity Page 2
Batch jobs
Member : Q143095558 Model/Serial . : 270/10-4RT9M Main storage . . : 8000.0 MB Started . . . . : 05/23/03 09:55:5
Library . . : QMPGDATA System name . . :ASM27 Version/Release : 5/ 2.0 Stopped . . . . : 05/23/03 10:15:0
Partition ID : 000 Feature Code . :22AB-2253-1520
Server : 051352/QTMHHTTP/IAXHTTPSSL
----------- Requests ---------- -------- Responses --------- KB KB
Itv Req Pct Pct Transmitted Received
End type Received Rejected Rejected Sent Error Error /Second /Second
----- ---- ----------- -------- -------- ----------- -------- ----- ----------- -----------
10:00 SL 308 0 .00 308 0 .00 5 1
10:00 WS 308 0 .00 308 0 .00 5 1
10:05 SL 13 0 .00 13 0 .00 0 0
10:05 WS 13 0 .00 13 0 .00 0 0
Column Total Average
------------------------------ ---------------- ----------------
Requests Received 642
Requests Rejected 0
Pct Requests Rejected .000
Responses Sent 642
Responses in error 0
Pct Responses in error .000
KB Transmitted/Second 2
KB Received/Second 0
Itv End -- Interval end time (hour and minute)
Req type -- The type of request being reported
Requests Received -- The number of requests received by the server
Requests Rejected -- The number of requests received that were not valid
Pct Requests Rejected -- Percentage of requests received that were not valid
Responses Sent -- The number of responses sent
Error Responses -- The number of responses in error
Pct Error Responses -- Percentage of responses in error
KB Transmitted/Second -- Number of kilobytes (1024 bytes) transmitted per second
KB Received/Second -- Number of kilobytes (1024 bytes) received per second

Figure 13-27 Performance Tools: Component Report - HTTP Server Activity

350 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 For more information
For further study of this topic, refer to the following resources:
򐂰 The iSeries Information Center has a starting point for performance-related topics that
include the logging of information with iSeries Collection Services:
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/rzahx/rzahxebushttp.htm
򐂰 Two Redbooks deal with collection services at V5R1. They do not have specific
information about the HTTP Server (powered by Apache) information that is collected at
V5R2.
– Managing OS/400 with Operations Navigator V5R1 Volume 1: Overview and More,
SG24-6226
– Managing OS/400 with Operations Navigator V5R1 Volume 5: Performance
Management, SG24-6565

13.2.7 Other startup parameters

Server startup parameters can also aid in problem determination and in testing your server
configuration. In addition to the more debug-oriented -ve, -vi, -vv startup parameters
discussed in 13.2.5, “HTTP server trace” on page 341, the following options are available:

Tip: These parameters are case sensitive.

򐂰 -netccsid [nnn]: Overrides the DefaultNetCCSID directive.

򐂰 -fsccsid [nnn]: Overrides the default DefaultFsCCSID directive.
򐂰 -d [serverroot]: Sets the initial value for the ServerRoot variable to serverroot. This can
be overridden by the ServerRoot directive.
򐂰 -f [configuration]: Uses the values in the configuration variable on startup. If the
configuration does not begin with a /, then it is treated as a path relative to the ServerRoot.
For example, the following command advises your server to use the configuration file from
the fully qualified path that is specified:
STRTCPSVR SERVER(*HTTP) HTTPSVR(ITSONEW '-f /www/apachedft/conf/httpd.conf')
The following command loads the file from the [serverroot]/conf directory:
STRTCPSVR SERVER(*HTTP) HTTPSVR(ITSONEW '-f conf/httpd.conf')
򐂰 -C [directive]: Processes the given directive as though it was part of the configuration.
򐂰 -c [directive]: Processes the given directive after reading all the regular configuration
files.
򐂰 -V: Displays the base version of the server, build date, and a list of compile time settings to
your 5250 session. You may use the Page Up and Page Down keys to review the
information. Press Enter to quit the terminal session. The server is not started. Here is an
example printout:
Server version: Apache/2.0.43
Server built: Nov 26 2002 15:57:01
Server's Module Magic Number: 20020903:0
Architecture: 128-bit
Server compiled with....
-D APR_HAS_SENDFILE
-D NO_LINGCLOSE
-D APR_USE_FCNTL_SERIALIZE
-D APR_USE_PTHREAD_SERIALIZE
-D APR_PROCESS_LOCK_IS_GLOBAL

Chapter 13. Problem determination: When things do not go as planned 351

 -D APR_HAS_OTHER_CHILD
-D APR_CHARSET_EBCDIC
-D APACHE_XLATE
-D HTTPD_ROOT="/QIBM/UserData/HTTPA"
-D AS400
-D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
-D DEFAULT_ERRORLOG="logs/error_log"
-D AP_TYPES_CONFIG_FILE="conf/mime.types"
-D SERVER_CONFIG_FILE="conf/httpd.conf"
Press ENTER to end terminal session.
򐂰 -l: Displays a list of all modules compiled.
򐂰 -t: Tests the configuration file syntax but does not start the server. This command checks
to see if all DocumentRoot entries exist and are directories. The command STRTCPSVR
SERVER(*HTTP) HTTPSVR(ITSONEW '-t’) results in:
Syntax OK
Press ENTER to end terminal session.

13.2.8 HTTP status codes

In some cases, your HTTP server responds with standard three-digit codes, such as 404,
500, and so on to a client request. These are known as HTTP status codes. They often
provide additional information about the cause of a failure. Table 13-5 offers a quick guide on
HTTP status codes.
Table 13-5 HTTP status codes
Status Meaning Example
code group

1xx Informational. Contains a 101 Switching Protocols

provisional response that Sent when an updated version of the HTTP
influences the client’s behavior. protocol has been negotiated.

2xx Successful. Also returns 200 OK

information about the status of The client request is fulfilled. Can contain
negotiations and transactions. additional information in the reply to GET,
POST, HEAD, TRACE methods.

3xx Redirection. Requests an action 304 Not Modified

from the user agent. Often used in an answer to conditional
requests, usually when caching is involved.

4xx Client error. They are sent to your 404 Not Found
browser window when the page The server is unable to find anything matching
you requested cannot be served. the client request. Also used for security
reasons when the requesting user should not
have access to a particular resource.

5xx Server error. Sent to your browser 503 Service Unavailable

window when the server is unable The server has encountered a temporary
to fulfill your request because of condition that is preventing the fulfillment of a
an internal problem. client request.

For more information about HTTP status codes and their meaning, refer to Request for
Comments (RFC) 2616 on the HTTP 1.1 protocol standard.

352 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
13.2.9 Communications trace
A communications trace is also a powerful tool for problem determination. It is useful for
gathering information about the connection status and response time, and if you are
experiencing troubles with the encoding of your files.

Here is a quick example of using a communications trace to all the IP datagrams received and
sent from the iSeries point of view. The 5250 communication trace commands used are:
򐂰 Start Communications Trace (STRCMNTRC)
򐂰 End Communications Trace (ENDCMNTRC)
򐂰 Dump Communications Trace (DMPCMNTRC)
򐂰 Print Communications Trace (PRTCMNTRC)
򐂰 Delete Communications Trace (DLTCMNTRC)

This assumes that your configuration line object’s name is ETHLINE. Enter the commands
and perform the following actions in the order shown:
1. Enter the following command:
STRCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN) MAXSTG(256K) USRDTA(*MAX)
2. Start your HTTP Server (powered by Apache) and Web client and test your Web
application. Keep your work at a minimum to lessen the amount of data collected.
3. Enter the following command:
ENDCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN)
4. The next step is to output the trace information. You have two options:
– Print the trace in to a spooled file using the following command:
PRTCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN) CODE(*ASCII) FMTBCD(*NO)
This option prints the trace in MAC layer format. If you want to print, for example, a
trace in IP formatting for server port 80, you could enter the following command:
PRTCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN) CODE(*ASCII) FMTTCP(*YES) SLTPORT(80)
FMTBCD(*NO)

Note: The spooled file of the communications trace output contains on the right side
a so called eye-catcher. This is an area where all text in a trace is formatted in a
readable format. However, when using the PRTCMNTRC command with the options
as previously shown, all text, whether uppercase or lowercase, will be displayed in
the spooled file in uppercase. In certain situations, it is necessary to consider the
case. The following command flow creates a spooled file where case-sensitivity is
considered.

– The following commands create a spooled file where uppercase and lowercase
characters are displayed correctly in the eye-catcher area.
DMPCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN) TOSTMF('/barlen/trace01Oct04')
PRTCMNTRC FROMSTMF('/barlen/trace01Oct04') CODE(*ASCII) SLTPORT(80)
This example also formats the trace for IP and contains only data for port 80.
5. Enter the Work with Job (WRKJOB) command and select option 4 (Work with spooled files).
This is a fast way to find the spool file created by the PRTCMNTRC command.
6. Enter the following command:
DLTCMNTRC CFGOBJ(ETHLINE) CFGTYPE(*LIN)

For more information about how to take a communications trace, refer to IBM iSeries Support
Line Knowledge Base document TCP/IP Communications Trace Instructions, 23825849.

Chapter 13. Problem determination: When things do not go as planned 353

13.2.10 Additional resources
For more information, consult the following sources:
򐂰 RFC Index
http://www.rfc-editor.org/rfc.html
򐂰 iSeries Support Line Knowledge Base
http://www-912.ibm.com/s_dir/slkbase.nsf/slkbase

354 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 14

Chapter 14. High availability

If Web serving is a critical aspect of your business, you may want a highly available Web
server environment. Highly available HTTP servers take advantage of iSeries clustering
technology and make it possible to build a highly available Web site. This improves the
availability of business-critical Web applications built with static Hypertext Markup Language
(HTML) pages or Common Gateway Interface (CGI) programs. This enhancement is available
with both the HTTP Server (powered by Apache) in addition to the HTTP Server (original).

Highly available HTTP servers are not supported on versions prior to V5R1.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 355
14.1 Highly available Web server cluster on the HTTP server
The Web server cluster solution can provide:
򐂰 Planned downtime: If a Web server requires planned maintenance, it is possible to transfer
the work to another node without visible service interruptions to the client.
򐂰 No unplanned downtime: If a machine fails, the work is transferred to another node with no
human involvement and without visible service interruptions to the client.
򐂰 Scalability: When employing multiple nodes, it is possible to distribute the Web site
workload over the cluster nodes.

Clusters are a collection of complete systems that work together to provide a single, unified
computing capability.

A liveness monitor checks the state of the Web server. It interacts with the Web server and
the clustering resource services in the event that a Web server fails (failover), or a manual
switchover takes place (ensures no interruption of Web server services).

You can use the clustered hash table (part of the state replication mechanism) to replicate
highly available CGI program state data across the cluster nodes. That way the state data is
available to all nodes in the event that a Web server fails (failover) or is switched-over
manually (switchover). To take advantage of this capability, an existing CGI program must be
enabled in a highly available Web server environment. CGI programs write to the CGI
application programming interfaces (APIs) to indicate what data is replicated. See HTTP
Server for iSeries Programming, GC41-5435.

Three Web server cluster models are supported:

򐂰 Primary or backup with takeover Internet Protocol (IP) model
򐂰 Primary or backup with a network dispatcher model
򐂰 Peer model

14.1.1 Primary or backup with takeover IP model

In this model, the Web server runs on the primary and all backup nodes. The backup node or
nodes are in an idle state, ready to become the primary Web server should the primary Web
server fail (failover) or a switchover takes place. All client requests are always served by the
primary node. Figure 14-1 illustrates a primary or backup with takeover IP model.

When the primary node fails (failover), or is brought down by the administrator, the
failover/switchover process begins. The following steps are performed during
failover/switchover:
1. One of the backup servers becomes the primary (the first backup in the switchover order).
2. Client requests are redirected to the new primary node. Assuming this client was not in the
process of running a persistent CGI application, the failover is completely transparent.

Tip: You can provide a high availability (HA) environment with two iSeries servers, each
with one instance of the HTTP Server (powered by Apache). Each of these instances
serves the identical (a copy) HTML and images and from identical (a copy) httpd.conf
configuration files. You can do this with a simple configuration. You do not need
third-party software. This is assuming, however, that you are not providing a HA
environment for your CGI application.

356 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
3. If the new primary receives a user request that belongs to a long-running-session (a CGI
program that is updated to be a highly available CGI program), the server restores the
request's state. The new primary retrieves that highly available CGI program's state
information from the clustered hash table. The clustered hash table is part of the state
replication mechanism.
Most non-HA CGI applications behave in the following manner:
a. The client clicks the Submit button to send a new request to the Web server and your
CGI application.
b. Your persistent CGI application “wakes up”. Its state information is saved in static
variables to determine what happened in the past with this client and what to do now.
Parameters found in the URL are parsed and actions are taken. New state information
is saved in the static variables for the next time this client returns to this iSeries server.
HTML code is generated and sent to standard out for presentation to the remote client.
c. The above “cycle” continues until the entire transaction is complete.
Most HA CGI applications behave in the following manner:
a. The client clicks the Submit button, which sends a new request to the Web server and
your CGI application.
b. Your persistent CGI application “wakes up”. Its state information is saved in the
clustered hash table. It reads from the clustered hash table and updates local variables
to determine what happened in the past with this client and what it must do now.
Parameters found in the URL are parsed and actions are taken. New state information
is written to the clustered hash table for the next time this same client returns to this (or
the backup) iSeries server. HA support ensures that the information written to the
clustered hash table on one iSeries server is replicated to the backup server. HTML
code is generated and sent to standard out for presentation to the remote client.
c. The above “cycle” continues until the entire transaction is complete.
4. After the failed node recovers, you can restart the highly available Web server instance,
which then becomes the backup system. If the system administrator wants the failed node
to become primary again, they must perform a manual switchover. They can accomplish
this with the IBM Simple Cluster Management interface available through iSeries
Navigator (Operations Navigator in V5R1), a 5250 CL interface, or a business partner tool.

Network

Client
iSeries Web
Server Cluster

Liveness Clustered Hash Liveness

Monitor Table Monitor

State Replication
Mechanism

Backup Primary

Figure 14-1 High availability: Primary or backup with takeover IP model

Chapter 14. High availability 357

 For an example, see 14.2, “A working primary or backup with takeover IP model” on
page 359.

14.1.2 Primary or backup with a network dispatcher model

In this model, as with the primary or backup with takeover IP model, the Web server runs on
the primary and all backup nodes. The backup nodes are in an idle state and all client
requests are served by the primary node. A network dispatcher, such as the IBM WebSphere
Edge Server, sends client requests to the Web server.

When the primary node fails (failover), or a switchover takes place, the failover/switchover
process begins. The following steps are performed during failover/switchover:
1. One of the backup servers becomes the primary (the first backup in the switchover order).
2. The client requests are sent to the new primary node by the network dispatcher.
3. If the new primary receives a user request that belongs to a long-running-session, the
server needs to restore the request's state. The new primary searches for the state either
locally or in the clustered hash table. The clustered hash table is part of the state
replication mechanism.
4. After the failed node recovers, the system administrator can restart the Web server
instance and it becomes a backup Web server. If the system administrator wants the failed
node to become primary again, they must perform a manual switchover.

Note: A node can join a recovery domain as a primary only if the Cluster Resource Group
(CRG) is in inactive mode.

Figure 14-2 illustrates a primary or backup with a network dispatcher model.

Network

Network Client
Dispatcher

Liveness Clustered Hash Liveness

Monitor Table Monitor

State Replication
Mechanism

Backup Primary

Figure 14-2 High availability: Primary or backup with a network dispatcher model

358 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
14.1.3 Peer model
In this model, there is no declared primary node. All nodes are in an active state and serve
client requests. A network dispatcher, such as IBM WebSphere Edge Server, evenly
distributes requests to different cluster nodes. This guarantees distribution of resources in
case of a heavy load. Linear scalability is not guaranteed beyond a small number of nodes.
After some nodes are added, scalability can disappear, and the cluster performance can
deteriorate.

Figure 14-3 illustrates the peer model.

Network

Network Client
Dispatcher

Liveness Clustered Hash Liveness

Monitor Table Monitor

State Replication
Mechanism

Server 1 Server 2
Figure 14-3 High availability: Peer model

In the event that one node fails (failover), the failed Web server traffic is routed to one of the
other operational Web servers according to the configuration of the network dispatcher.

14.2 A working primary or backup with takeover IP model

This scenario provides the steps that are necessary to get a simple HA environment up and
running between two iSeries servers. On each server is an identical, yet separate, instance of
the HTTP Server (powered by Apache).

14.2.1 Problem definition

For this scenario, let’s suppose that a customer has a network as presented in Figure 14-4.
They have two iSeries servers that are available for serving a standard Web application
across either a public or private network. This Web application involves the serving of
standard HTML and graphics only. The primary iSeries as23 may be down for any reason:
򐂰 Planned outages such as hardware or software maintenance
򐂰 Unplanned outages such as power loss, fire, and so on

They want the ability to seamlessly move all active clients to the backup server as24. And,
when the primary server as23 is brought back online, they want to move back seamlessly all
the clients.

Chapter 14. High availability 359

 Network

Client
iSeries Web
Server Cluster

Backup: Primary:
as24.itsoroch.ibm.com as23.itsoroch.ibm.com

Figure 14-4 Primary or backup with IP takeover: Problem definition

14.2.2 Solution definition

The solution is to take advantage of the Highly Available HTTP Server first introduced at
V5R1 for OS/400 Web applications. As shown in Figure 14-5, it takes advantage of the two
separate iSeries servers as23 and as24 to provide a primary or backup with IP takeover HA
solution.

Network

Cluster Information:
Cluster: ITSOTEST Client
Nodes: AS23 and AS24 iSeries Web
Cluster Resouce Group: PBABASIC00 Server Cluster

Liveness Clustered Hash Liveness

Monitor Table Monitor

State Replication
Mechanism

Backup: Primary:
iSeries host and domain: as24.itsoroch.ibm.com iSeries host and domain: as23.itsoroch.ibm.com
as24 'primary IP address': 10.5.92.38 as23 'primary IP address': 10.5.92.30
Clustered IP address: 10.5.92.51 Clustered IP address: 10.5.92.51

Figure 14-5 Primary or backup with IP takeover: Solution definition

14.2.3 Assumptions
The software and hardware used in this scenario has the following characteristics:
򐂰 We are using V5R2 of OS/400. This scenario can also be created for V5R1, but some of
the interfaces to iSeries clustering have changed.
򐂰 If you plan to use iSeries Navigator and the Simple Cluster Management interface to
configure the cluster, you must install 5722-SS1 OS/400 Option 41 (HA Switchable
Resources). OS/400 Option 41 is not necessary if you plan on using the 5250 commands
to configure your cluster.

360 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 򐂰 Both iSeries servers must have a routable IP address that is accessible from each other
server. This is shown in Figure 14-5 that as23 can PING 10.5.92.38 and as24 can PING
10.5.92.30.

Tip: Do not confuse these IP addresses on both iSeries servers with the clustered IP
address of 10.5.92.51. This clustered IP address is routable (that is, if a client on the
same subnet wants to communicate to this IP address, it uses ARP to resolve the MAC
address on the iSeries) but cannot be active on both systems at the same time.

14.2.4 How to
To configure the primary and backup servers in this scenario, perform the following tasks as
explained in the sections that follow:
򐂰 Step 1: Validate system and TCP/IP settings on both iSeries servers
򐂰 Step 2: Creating the HA cluster for ITSOTEST for nodes AS23 and AS24
򐂰 Step 3: Adding HA clustering directives to both httpd.conf configurations
򐂰 Step 4: Testing the primary and backup servers

Note: iSeries Navigator provides a simple graphical user interface (GUI) tool to manage a
cluster of iSeries servers. We chose to use a 5250 command entry in our configuration of
HA clustering on the iSeries at V5R2 because the CL commands that are provided offer
more features and choices not provided by the GUI. Be sure to make your own choice.

Step 1: Validate system and TCP/IP settings on both iSeries servers

Tip: In addition the steps outlined in this section, you must review the Information Center’s
resources for clustering:
http://publib.boulder.ibm.com/html/as400/infocenter.html

On this site, select your version and language, and click GO! Search for “clusters”. The
document that helps you the most in this step is entitled “Cluster configuration checklist”.

Before you start, you need to validate and possibly modify some of the system and TCP/IP
configuration settings on both iSeries servers. These instructions demonstrate what is
needed on both systems by showing you what we did on as23. In your own environment, you
must perform these steps for both the primary and backup servers.
1. Ensure that clustering is enabled for both iSeries servers:
a. Enter the Display Network Attributes (DSPNETA) command. On this Display Network
Attributes display, page down until you see the value set for the Allow add to cluster as
highlighted in Figure 14-6. This value should be set to *ANY on both iSeries servers.

Display Network Attributes

System: AS23
Allow add to cluster . . . . . . . . . . . . . . : *ANY
Modem country or region ID . . . . . . . . . . . :
Bottom
Press Enter to continue.

F3=Exit F12=Cancel

Figure 14-6 Primary or backup with IP takeover: Allow add to cluster should be *ANY

Chapter 14. High availability 361

 b. If necessary, you can change this value using the Change Network Attributes
(CHGNETA) command:
CHGNETA ALWADDCLU(*ANY)
2. Create the same routable IP address on both iSeries servers to be used as the clustered
IP address. This IP address is the “well-known” IP address at which your Web application
is bound to via the Listen directive. That is, a Domain Name System (DNS) server must
have an A record that maps the primary host’s name of as23.itsoroch.ibm.com to
10.5.92.51.

Tip: It may feel strange to create the same routable IP address on both iSeries. But, as
long as both are not active at the same time this is OK. It is the IP address takeover
feature of OS/400’s HA clustering that automatically allows only one of the iSeries
servers to have 10.5.92.51 active at one time. To be clear, you never manually make
10.5.92.51 active on either iSeries server. HA clustering’s IP takeover does this for you.

Available with V5R2 of OS/400 is a new feature called Virtual IP Address with proxy ARP
(VIPA with proxy Apache Portable Runtime (ARP)). This VIPA is routable in the same
subnet as the other IP addresses associated with the physical Network Interface Cards
(NIC) on your iSeries servers. VIPAs can provide extremely valuable fault tolerance for
situations where you have two or more NICs configured to all be in the same subnet on the
same iSeries. This scenario proceeds to create a clustered IP address on both iSeries as
VIPA with proxy ARP.
The added feature of fault tolerance (for a failure in a NIC) using the VIPA addresses is
detailed in iSeries IP Networks: Dynamic!, SG24-6718.
This scenario works equally well with new local area network (LAN) interfaces (rather than
the virtual IP addresses that we use) of 10.5.92.51 on both iSeries. These can be created
using 5250 commands such as Add TCP/IP Interface (ADDTCPIFC).
But, if you want HA for your Web server, you should follow up and implement VIPA with
proxy ARP as part of a total solution that includes fault tolerance for a failure in one of your
NICs.
a. Using iSeries Navigator create a VIPA with proxy ARP that will be the clustered IP
address on both iSeries servers. Start iSeries Navigator and connect to as23. Expand
Network →TCP/IP Configuration →IPv4.

Note: 5250 command entry cannot be used to create VIPA with proxy ARP in V5R2.
You must use iSeries Navigator.

b. Right-click Interfaces and select New Interface →Virtual IP.

c. Follow the New IPv4 Interface wizard to create the new VIPA interface. When
prompted, specify the following values:
• IP address: 10.5.92.51
• Description: VIPA with proxy ARP
• Subnet mask: 255.255.255.255
• Do you want to start this TCP/IP interface every time TCP/IP is started?: No
• Do you want to start this TCP/IP interface now?: No
d. Change the properties of this VIPA address to “turn on” the proxy ARP feature:
i. Right-click the IP address 10.5.92.51 and select Properties.
ii. Select the Advanced tab and click Enable proxy ARP.
iii. Click OK to save your changes.

362 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 14-7 Primary or backup with IP takeover: Changing the VIPA address to enable proxy ARP

3. Make sure that the loopback IP address 127.0.0.1 is configured and started on both
iSeries servers.
4. Make sure that the Internet Daemon (INETD) server is started on both iSeries servers:
a. Using iSeries Navigator, expand Network →Servers and then click TCP/IP. In the
panel on the right, a list of TCP/IP servers and their status (started or stopped) is
updated. Make sure the INETD server has the status of started.
b. If the INETD server has the status of stopped, right-click INETD and select Start.

Tip: Because INETD is needed for the proper operation of HA clustering on your
iSeries servers, we recommend that you change the properties of the INETD to
Start when TCP/IP is started.

5. Make sure that Liveness Monitor can run unimpeded in the QBATCH subsystem on both
iSeries servers. OS/400’s HA clustering uses a batch job to slow poll the primary server to
determine if this system is still available to the network. By default, this batch job is started
in QBATCH. You must ensure that the job queue for QBATCH is large enough to always
allow this job to run.
a. To check the QBATCH subsystem, use the 5250 command Display Subsystem
Description (DSPSBSD):
DSPSBSD SBSD(QBATCH)
Select option 6 (Job queue entries). As highlighted in Figure 14-8 on iSeries as23, the
maximum active jobs allowed in QBATCH is 4.

Display Job Queue Entries

System: AS23
Subsystem description: QBATCH Status: ACTIVE

Seq Job Max ---------Max by Priority----------

Nbr Queue Library Active 1 2 3 4 5 6 7 8 9
10 QBATCH QGPL 4 * * * * * * * * *
20 QS36EVOKE QGPL *NOMAX * * * * * * * * *
50 QTXTSRCH QGPL *NOMAX * * * * * * * * *

Figure 14-8 Primary or backup with IP takeover: Max Active for QBATCH showing 4

Chapter 14. High availability 363

 b. To ensure the testing will succeed, use the Change Job Queue Entry (CHGJOBQE)
command to change the maximum active to no maximum:
CHGJOBQE SBSD(QBATCH) JOBQ(QBATCH) MAXACT(*NOMAX)
6. Verify that the basic TCP/IP configuration is correct.
Test the interconnectivity of all the servers and clients to ensure that the Step 2 has the
best chance of succeeding. Refer to the network diagram in Figure 14-5 on page 360.
a. Verify that primary as23 can verify TCP/IP Connection (PING) backup as24 at IP
address 10.5.92.38.
b. Verify that backup as24 can PING primary as23 at IP address 10.5.92.30.
c. Conversely, make sure that a PING to clustered IP address 10.5.92.51 times out. That
is, this IP address should not be active on any host in the 10.5.92.0 subnetwork.
d. Verify that when the client PINGs the primary as23.itsoroch.ibm.com, the name is
resolved to 10.5.92.51. However, this PING should time out.

Step 2: Creating the HA cluster for ITSOTEST for nodes AS23 and AS24
You can perform the following steps on either iSeries server as23 or as24. For the purposes
of demonstration, we create the HA cluster ITSOTEST from as23.

Tip: The 5250 command GO CMDCLU provides a list of HA clustering commands that are
available.

1. On iSeries server as23, use the Create Cluster (CRTCLU) command to create the cluster
ITSOTEST and node AS23.
CRTCLU CLUSTER(ITSOTEST) NODE((AS23 ('10.5.92.30')))
The CRTCLU command should complete without errors.
2. To see the status of your newly created cluster ITSOTEST, enter the Display Cluster
Information (DSPCLUINF) command:
DSPCLUINF CLUSTER(ITSOTEST)
As shown in Figure 14-9, your cluster is created. Currently the cluster has one node. In our
case, this node is named AS23 and it has the active interface of 10.5.92.30.

Display Cluster Information

Cluster . . . . . . . . . . . . . : ITSOTEST
Consistent information in cluster : *YES
Current cluster version . . . . . : 3
Current cluster modification level : 0
Configuration tuning level . . . . : *NORMAL
Number of cluster nodes . . . . . : 1
Detail . . . . . . . . . . . . . . : *BASIC

Cluster Membership List

Potential
Node Mod Device
Node Status Vers Level Domain ------Interface Addresses
AS23 Active 3 0 *NONE 10.5.92.30

Figure 14-9 Primary or backup with IP takeover: Display cluster information showing one node AS23

364 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
3. Create the second cluster node AS24 by entering the Add Cluster Node Entry
(ADDCLUNODE) command (on iSeries server as23):
ADDCLUNODE CLUSTER(ITSOTEST) NODE(AS24 ('10.5.92.38'))
The ADDCLUNODE command should complete without errors.
4. To see the status of your newly created node AS24 in cluster ITSOTEST, enter the
DSPCLUINF command:
DSPCLUINF CLUSTER(ITSOTEST)
As shown in Figure 14-10, node AS24 is added to your cluster ITSOTEST.

Display Cluster Information

Cluster . . . . . . . . . . . . . : ITSOTEST
Consistent information in cluster : *YES
Current cluster version . . . . . : 3
Current cluster modification level : 0
Configuration tuning level . . . . : *NORMAL
Number of cluster nodes . . . . . : 2
Detail . . . . . . . . . . . . . . : *BASIC

Cluster Membership List

Potential
Node Mod Device
Node Status Vers Level Domain ------Interface Addresses
AS23 Active 3 0 *NONE 10.5.92.30
AS24 Active 3 0 *NONE 10.5.92.38

Figure 14-10 Primary or backup with IP takeover: Display cluster information two nodes: AS23, AS24

Step 3: Adding HA clustering directives to both httpd.conf

configurations
Now that you established a cluster between the two iSeries servers as23 and as24, it is time
to add to this cluster a CRG. You do this by creating a basic HTTP Server (powered by
Apache) configuration on iSeries server as23 and then adding the necessary HA server
directives. Then you make an identical copy of this HTTP Server (powered by Apache)
configuration and Web site on iSeries server as24.
1. Using the administration GUI create on iSeries server as23 an HTTP Server (powered by
Apache) server with the attributes shown in Table 14-1.

Tip: Make a special note of the server name and IP address.

Chapter 14. High availability 365

 Table 14-1 Primary or backup with IP takeover: Create New HTTP Server wizard required parameters
Create HTTP Server wizard parameter Value

Server name PBABASIC00

Note: This server name also becomes the
name of the CRG.

Server root /tcp52d00/basicConfig

Document root /tcp52d00/basicConfig/ITSOco

On which IP address and TCP/IP port do you want IP address: 10.5.92.51

your server to listen? Note: This is the address of the clustered IP
address shown in Figure 14-5 on page 360.
Port: 8000

Do you want your new server to use an access log? Yes

2. Add the HA server directives to the PBABASIC00 server on as23:

a. Select the Manage tab.
b. For Server, select PBABASIC00. For Server area, select Global configuration.
c. In the left pane, click System Resources.
d. Select the Highly Available Server tab.
e. Select Enable HTTP server to be highly available. This expands your options for this
tab as shown in Figure 14-11. Specify the following options:
i. Select Primary/backup with IP takeover.
ii. Deselect Enable highly available CGI programs.
iii. In the Liveness monitor settings area, enter the Liveness check URL:
http://10.5.92.51:8000/index.html
This URL is slow polled (as defined by the Time between liveness checks field
which is next) by the backup server to determine if the primary has failed. We
recommend that this page not be a complex dynamic page but rather one that is
simply HTML. Avoid HTML pages that include server-side includes (SSIs) too. Our
simple Web application’s index.html (home page) has static content only and makes
a good liveness test.
iv. For the remaining parameters, keep the defaults.
f. Click OK.

366 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Figure 14-11 Primary or backup with IP takeover: Enabling HA for the PBABASIC00 server on as23

3. Display the httpd.conf configuration file to view three new directives that are added as
shown in Figure 14-12.

2 LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

...
19 HAModel PrimaryBackupWithIPTakeover
20 LmURLCheck http://10.5.92.51:8000/index.html
...

Figure 14-12 Primary or backup with IP takeover: Three new directives to support HA in PBABASIC00

4. Create an identical HTTP Server (powered by Apache) configuration and Web application
on your backup iSeries server as24. There are many ways to accomplish this. As a
high-level overview, we recommend this method:
a. Copy and paste the entire Web application’s HTML, GIFs, and other collateral from the
IFS on as23 to as24. Place these files in a similar directory structure.
b. Use the administrative GUI to create another PBABASIC00 HTTP Server (powered by
Apache) configuration on as24 using the same information found in Table 14-1.
c. Copy and paste the new HA directives from the PBABASIC00 httpd.conf configuration
file on as23 to as24.

Chapter 14. High availability 367

 Tip: In the end, your objective is to have the same Web application and configuration
file on both as23 and as24.

5. Since this is a test, we took the liberty to make some minor modifications to the index.html
(home page) on both the primary as23 and backup as24 iSeries servers. We added the
text “Welcome to Primary” on server as23 and “Welcome to Backup” on server as24. We
did this so the client Web browser could see the difference when it is automatically and
seamlessly switched from the primary to the backup iSeries server. Otherwise, it is difficult
to tell. You can see the differences in the index.html file on both servers in Figure 14-13
and Figure 14-16 on page 370.

Step 4: Testing the primary and backup servers

To test the HA server environment, start the PBABASIC00 server on as23 and then start
PBABASIC00 on as24.
1. Start the primary HTTP server PBABASIC00 on as23. Using the administrative GUI, make
sure select server PBABASIC00 on iSeries server as23 and then click Start. This starts
the HTTP Server (powered by Apache) PBABASIC00. This also automatically starts the
IP address 10.5.92.51 on iSeries server as23. The primary server is started first and the
backup server is started second.

Tip: The CRG is not started because the backup server is still inactive. However, your
Web site is up and running on the primary, you see in the next step.

2. Verify that your primary server is up and running. From a Web browser, enter the URL:
http://10.5.92.51:8000
You should see your home page as shown in Figure 14-13. The modification we made to
the index.html file to say, “Welcome to Primary” to distinguish this page from the similar
one on the backup server.

Figure 14-13 Primary or backup with IP takeover: Primary server on as23 up and running

368 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
3. Start the backup HTTP server PBABASIC00 on as24. Using the administrative GUI, make
sure you select server PBABASIC00 on iSeries server as24 and then click Start. This
starts the HTTP Server (powered by Apache) PBABASIC00.

Tip: This does not start the IP address 10.5.92.51 on iSeries server as24. Only during
a failure of the primary iSeries server as23 does as24 take over and make active this IP
address.

4. Now that the backup server is started, this automatically creates and starts the CRG
PBABASIC00. To list all the CRGs in cluster ITSOTEST, enter the Display CRG
Information (DSPCRGINF) command:
DSPCRGINF CLUSTER(ITSOTEST) CRG(*LIST)
As highlighted in Figure 14-14, our CRG PBABASIC00 is active on primary node AS23.

Tip: Use the following 5250 command for even greater detail about the CRG:
DSPCRGINF CLUSTER(ITSOTEST) CRG(PBABASIC00)

Display CRG Information

Cluster . . . . . . . . . . . . : ITSOTEST
Cluster Resource Group . . . . . : *LIST
Consistent Information in Cluster: *YES
Number of Cluster Resource Groups: 2

Cluster Resource Group List

Cluster Resource Group CRG Type Status Primary Node

PBABASIC00 Application Active AS23
PBABFL0ARB Data Inactive AS23

Figure 14-14 Primary or backup with IP takeover: CRG PBABASIC00 is active on primary node AS23

5. Use the Change CRG Primary (CHGCRGPRI) command to switch the clustered
application PBABASIC00 from the primary node AS23 to the backup node AS24:
CHGCRGPRI CLUSTER(ITSOTEST) CRG(PBABASIC00)
The CHGCRGPRI command should complete without errors.

Tip: One of the major effects of this command is that iSeries server as24 does an IP
takeover of the IP address 10.5.92.51. That is, after the CHGCRGPRI command has
completed, the IP address 10.5.92.51 is inactive on server as23 and active on server
as24.

Chapter 14. High availability 369

 6. Now node AS24 is the primary server for the CRG PBABASIC00. Enter the Display CRG
Information (DSPCRGINF) command:
DSPCRGINF CLUSTER(ITSOTEST) CRG(*LIST)
As highlighted in Figure 14-15, CRG PBABASIC00 is now active on (the new) primary
node AS24.

Display CRG Information

Cluster . . . . . . . . . . . . : ITSOTEST
Cluster Resource Group . . . . . : *LIST
Consistent Information in Cluster: *YES
Number of Cluster Resource Groups: 2

Cluster Resource Group List

Cluster Resource Group CRG Type Status Primary Node

PBABASIC00 Application Active AS24
PBABFL0ARB Data Inactive AS23

Figure 14-15 Primary or backup with IP takeover: CRG PBABASIC00 is active on primary node AS24

7. As a final confirmation, simply refresh the Web browser which still has
http://10.5.92.51:8000 for the URL. As shown in Figure 14-16, the Web client was
seamlessly moved to the backup HTTP server on iSeries as24. The only way you can
really tell from the client’s point of view is from the “Welcome to Backup” text we modified
in the index.html home page.

Figure 14-16 Primary or backup with IP takeover: Backup server on as24 ‘up and running’

The ability of the HTTP Server (powered by Apache) to take advantage of the iSeries HA
APIs is a powerful enhancement to the Apache server. This is another demonstration of the
integration that the Rochester lab has done to bring the Apache server to the iSeries server.

370 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
14.3 For more information
Highly available HTTP servers and iSeries clustering resources include:
򐂰 HTTP Server: What’s new, which includes information about the 17 December 2001
Highly Available HTTP Server announcement
http://www.ibm.com/servers/eserver/iseries/software/http/news/sitenews.html
򐂰 Documentation Center information about highly available Web servers
http://www-1.ibm.com/servers/eserver/iseries/software/http/docs/doc.htm
On this site, search for “high availability”.
򐂰 High Availability and Clusters home page
http://www.ibm.com/servers/eserver/iseries/ha/
򐂰 Clustering documentation in the iSeries Information Center
http://publib.boulder.ibm.com/html/as400/infocenter.html
On this site, select your version and language, and click GO! Then search for “clusters”.
򐂰 The IBM Redbook Clustering and IASPs for Higher Availability on the IBM Eserver
iSeries Server, SG24-5194

Chapter 14. High availability 371

372 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 15

Chapter 15. National language

considerations
This chapter discusses national language considerations on the iSeries server as they relate
to the HTTP Server (powered by Apache). It also discusses many associated applications
such as the Digital Certificate Manager (DCM) and the Cryptographic Service Provider, for
example. It provides information for you to view these applications in many of the world’s
languages.

Tip: It is interesting to note that some of the applications found on the iSeries Tasks page
have their graphical user interface (GUI) driven by Net.Data (for example the DCM). Others
have their GUI driven by servlet (for example the administration GUI for HTTP Server
(powered by Apache)). Because of this underlying difference, each handles national
language support (NLS) in a different manner!

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 373
15.1 Installing secondary languages
The GUI used to configure the HTTP Server (powered by Apache) can be installed in many
different languages. To use different languages, you must install the licensed product:
򐂰 5722-DG1: If you need different languages for the administration GUI
򐂰 5722-SS1, option *BASE and 3: For the initial iSeries TASK page
򐂰 5722-SS1, option 34: For the Digital Certificate Manager (DCM)
򐂰 5722-AC3: For the Cryptographic Service Provider
򐂰 5722-JV1 Developer Kit for Java

Before we can work with different languages, we have to check if the licensed program is
installed and if it is installed in the needed language. To check this, follow these steps:
1. Enter the OS/400 command GO LICPGM and press Page Down.
2. You should now see the Work with Licensed Programs display (Figure 15-1). From here
choose option 20 (Display installed secondary languages) to check if any secondary
languages are installed.

LICPGM Work with Licensed Programs

System: AS20
Select one of the following:

Secondary Languages
20. Display installed secondary languages
21. Install secondary languages
22. Delete secondary languages

Redistribution
40. Create distribution media
41. Work with installation profiles

Completion Status
50. Display log for messages

More...
Selection or command
===>

F3=Exit F4=Prompt F9=Retrieve F12=Cancel F13=Information Assistant

F16=AS/400 Main menu

Figure 15-1 Work with Licensed Programs: Page down

374 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 3. You now see the Display Installed Secondary Languages display (Figure 15-2). In our
case, 2924 (English) is the primary, and 2929 (German) is the secondary language. Enter
5 (Display installed Licensed Program) to see the installed licensed programs associated
with that secondary language.

Tip: You can find a national language feature code matching table on the Web at:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/ic2924/index.htm?info/rzahc/rza
hcnlvfeaturecodes.htm

Display Installed Secondary Languages

System: AS20
Primary language . . . . . . : 2924
Description . . . . . . . . : English

Type options, press Enter.

5=Display installed Licensed Program

Option Language Description

5 2929 German

Figure 15-2 Display Installed Secondary Languages

4. In the Display Installed Secondary Language Licensed Programs display (Figure 15-3),
verify the Installed Status of the products. If any of these is in status *ERROR, try to
re-install the product or contact your local service representative.

Display Installed Secondary Language Licensed Programs

System: AS20
Secondary language . . . . . : 2929
Description . . . . . . . . : German

Licensed Installed
Program Status Description
5722SS1 *COMPATIBLE OS/400 - Digital Certificate Manager
5722DG1 *COMPATIBLE IBM HTTP-Server
5722DG1 *COMPATIBLE Triggered Cache Manager

Figure 15-3 Display Installed Secondary Languages: Option 5 (LPPs)

If no secondary language is installed on your system, refer to iSeries Information Center or to

Chapter 10 in Software Installation V5R2, SC41-5120.

15.2 Net.Data based: iSeries Tasks page and DCM

Both, the iSeries Tasks page and the DCM are implemented as a Net.Data application.
Net.Data based GUIs use iSeries host settings to determine which language they should
present to the client. Therefore, you must check the language settings in the user profile that
you used to sign on to the iSeries Tasks page, to display the correct language. As shown in
Figure 15-4, use the OS/400 command Display User Profile (DSPUSRPRF)
USRPRF(WOLFGANGP) to check the settings for your OS/400 user profile.

Chapter 15. National language considerations 375

 Display User Profile - Basic

User profile . . . . . . . . . . . . . . . : WOLFGANGP

Previous sign-on . . . . . . . . . . . . . : 05/07/03 10:11:16

Sign-on attempts not valid . . . . . . . . : 0
Status . . . . . . . . . . . . . . . . . . : *ENABLED
Date password last changed . . . . . . . . : 04/29/03
Password expiration interval . . . . . . . : *SYSVAL
Date password expires . . . . . . . . . : 11/01/03
Set password to expired . . . . . . . . . : *NO
.
.
.
Language identifier. . . . . . . . . . . . : *SYSVAL

Figure 15-4 Display User Profile: Language identifier

If the language ID is set to *SYSVAL (which is the default), the OS/400 system value
QLANGID is used to identify the desired language. To display the system value, use the
OS/400 command Display System Value (DSPSYSVAL SYSVAL(QLANGID)). You should
see the Display System Value display as shown in Figure 15-5.

Display System Value

System value . . . . . : QLANGID

Description . . . . . : Language identifier

Language identifier . : ENU Language abbreviation

Figure 15-5 Display System Value: QLANGID

In our case, this display shows ENU which means US - English. If you have some users that
need to work with other languages (for example German), you can change the Language
identifier parameter to DEU. The next time the user connects to any site pages served by
Net.Data on this iSeries server, they see them in German.

Tip: It is important to learn that if the Web pages are served by Net.Data, the iSeries
server examines the language settings of your browser. It only uses the information found
in either your OS/400 user profile or the default system value. For more information about
using the browser’s language settings to influence the national language chosen by the
iSeries, see the following section.

15.3 Servlet based: Administration GUI

The administrative GUI can be served in any language that is installed on your iSeries server.

Tip: You have to restart the Admin instance after installing the secondary languages to
take advantage of the change.

376 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
How the language recognition works
The HTTP Server (powered by Apache) (and we are focusing on the administrative GUI in
this section) determines which language it has to serve based on the Accept-Language
request header. This is determined on the first request that is done from the browser to the
server. All future requests from the same browser session to the HTTP Server (powered by
Apache) are served in this language. If you change the language settings in your Web
browser in the middle of a session, you have to restart it to see the new language.

The configuration in your browser is simple.

For Microsoft Internet Explorer

Follow these steps to configure the client’s language choices:
1. Click Start →Settings →Control Panel →Internet Options.
2. The Internet Properties window (Figure 15-6) opens. Click Languages.

Figure 15-6 Microsoft Internet Explorer Internet Properties window

Chapter 15. National language considerations 377

 3. In the Language Preference window (Figure 15-7), click Add.

Figure 15-7 Language Preference window

4. In the Add Language window (Figure 15-8), choose the appropriate language. In our case
we chose German. Click OK.

Figure 15-8 Add Language window

5. Click OK on the Language Preference window (Figure 15-7) and on the Internet
Properties window (Figure 15-6) to save all your changes.

378 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
For Netscape Navigator
Follow these steps to configure the client’s language choices:
1. From the menu bar, click Edit →Preferences as shown in Figure 15-9.

Figure 15-9 Using Netscape Navigator to select a language

2. In the Preferences window (Figure 15-10), under Category, expand Navigator and select
Languages to see what language the browser is configured to request.
3. To add a new language, click Add and select the appropriate one.

Figure 15-10 Preferences window in Netscape Navigator

Chapter 15. National language considerations 379

 4. In the Add Languages window (Figure 15-11), select the language or languages you need
and click OK.

Figure 15-11 Add Languages window

5. Click OK on the Preferences window.

After you complete these steps, restart your browser. The next request to the administrative
GUI (and only this interface) appears in the correct language.

Attention: Use care in regard to the sort order of the configured languages. The browser
initially requests the first language in the list and steps through all configured ones. If none
of the configured languages matches the ones that the HTTP Server (powered by Apache)
can serve, it reverts to the LANGID parameter of the authenticated user profile. This kind of
language selection, for example, is used by the IBM Web Administration for iSeries
interface.

15.4 Other programs linked from iSeries Task page

Many other licensed programs use the iSeries Tasks page as their initial enter page. It is also
possible to display those pages in a different language.

15.4.1 Internet Printing Protocol server for the iSeries server

This licensed product is included in 5722-SS1, option 3 (OS/400 - Extended Base Directory
Support). If you want to use different languages, you have to verify that it is also installed as a
secondary language.

The language recognition is the same as for the administration GUI (see 15.3, “Servlet based:
Administration GUI” on page 376). If the product is installed in the needed language, you only
have to check your browser’s setup and the correct language.

For more information about the Internet Printing Protocol (IPP) GUI, see IBM Publication IBM
Eserver iSeries Printing VI: Delivering the Output of e-business, SG24-6250.

380 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
15.4.2 WebSphere family
Refer to the following documentation on the WebSphere on iSeries home page at:
http://www.ibm.com/eserver/iseries/software/websphere

15.4.3 4758 Cryptographic Coprocessor

The GUI to set up the 4758 Cryptographic Coprocessor is only translated in the following
languages:
򐂰 Brazilian Portuguese
򐂰 Italian
򐂰 Japanese
򐂰 Korean
򐂰 Simplified Chinese
򐂰 Spanish
򐂰 Swiss Italian

If you do not have installed any of the above languages, the GUI is always displayed in
English (if 5722-AC3 is installed in English (2924) on your system either as the primary or as
secondary language). It uses the same mechanism as in 15.2, “Net.Data based: iSeries
Tasks page and DCM” on page 375, to display the GUI in one of the previous languages.

15.5 Serving your own Web site in the world’s languages

To serve your own language-based sites, you do not have to install any secondary language
or additional software on your iSeries server. The choice of language that the HTTP Server
(powered by Apache) serves is mainly based on the Accept-Language request header, so it
depends on your browsers language settings, your HTTP Server configuration, and the Web
application that you are serving.

Follow these steps to prepare your HTTP Server (powered by Apache) to serve the correct
language based page:
1. As shown in Figure 15-12, for Server, select your server. For Server area, select Global
configuration.

Tip: You can configure these settings for your server’s global configuration or for an
individual container.

2. In the left pane, under Server Properties, select Content Settings.

3. Select the MIME tab.

MIME: MIME stands for Multipurpose Internet Mail Extensions. It refers to an official
Internet standard that specifies how messages must be formatted so that they can be
exchanged between different systems.

Chapter 15. National language considerations 381

 4. On the MIME page (Figure 15-12), complete these steps:
a. Under Specify individual Meta (MIME) information for file extensions, click Add. You
add one row for each national language that you will serve from this HTTP Server
(powered by Apache).
Add all the file extensions you want to serve. Select Content-language as the type of
content encoding. Both the Type and Value lists show all the possibilities. In this
section, you associate a file extension to the language requested from the browser in
the Accept-Language request header.
That is, a browser that is setup to request [en] encoded pages asks the HTTP Server
(powered by Apache) to search for files that contain the configured file extension in the
file name. In this case, for an incoming request with the Uniform Resource Identifier
(URI) of /index, a search is made for the file /index.en.html or /index.html.en.
b. When your are done adding all the languages you will be serving, click Apply.

Figure 15-12 Serving language-based pages: Content Settings

382 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
5. Select the Multi-views tab as shown in Figure 15-13.
6. On the Multi-views page, you enable the server to honor client request options, such as
the language setting. Enable the HTTP Server (powered by Apache) to search the files in
the IFS that correlates to the requested language.

Figure 15-13 Serving language-based pages: Enabling multi-views

Chapter 15. National language considerations 383

 7. It is possible for the client’s Web browser to request a language that you are not prepared
to serve. To prevent the client from seeing the HTTP error 406 - Not acceptable, configure
the HTTP Server (powered by Apache) to serve a default language.
As shown in Figure 15-14, select the Content Negotiation tab.
8. On the Content Negotiation page, click Add to add a default language. For Force
language priority, select Prefer/Fallback.

Figure 15-14 Serving language-based pages: Default language

Figure 15-15 shows the configuration directives we changed or added.

Options +MultiViews
AddLanguage de .de
AddLanguage en .en
LanguagePriority en
ForceLanguagePriority Prefer Fallback

Figure 15-15 Serving language-based pages: Directive changes

After you apply all configuration changes, restart your server.

If you are using welcome pages, you must take care of your HTML files. Due to the setup and
renaming of the files, they are not named index.html anymore. They are named index.en.html
or index.html.en. When the HTTP Server (powered by Apache) searches for those files and it
is configured to display the welcome page index.html, it only finds the appropriate one when
the filename is index.html.en. In this case, HTTP error 403 or the directory listing is sent back
to the client. To prevent this, set the directive DirectoryIndex to index.

384 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Part 4

Part 4 Appendixes
To complete this IBM Redbook, we include appendixes on porting different open source
projects to the iSeries server. An advantage of using the Apache server is that you do not
have to wait for the developers in Rochester, Minnesota, to provide you with new features or
functions. You can do it yourself.

In addition, all the examples provided in this redbook can be downloaded from the Web,
allowing you to reduce the time in your transition from reading to understanding and
implementation. See Appendix D, “Additional material” on page 421.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 385
386 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 A

Appendix A. Bringing PHP to your iSeries

server
Hypertext Preprocessor (PHP) is a powerful server-side scripting language for the Apache
Web server. PHP is popular for its ability to process database information and create dynamic
Web pages. Server-side refers to the fact that PHP language statements, which are included
directly in your Hypertext Markup Language (HTML), are processed by the Web server.
Scripting language means that PHP is not compiled. Since the results of processing PHP
language statements is standard HTML, PHP-generated Web pages are quick to display and
are compatible with most all Web browsers and platforms. PHP is for the open source Apache
community as Net.Data is for the IBM community.

Restriction: PHP is not supported on the iSeries server by IBM. We provide these
instructions for you to download a public domain open-source copy of a PHP engine to
allow you to run PHP scripts on the iSeries server.

Specifically, IBM does not support:

򐂰 The open-source CGI based PHP engine
򐂰 Any of the PHP scripts that you would write against this PHP engine
򐂰 The other open source tools described in this IBM Redbook used for building the PHP
engine

IBM fully supports:

򐂰 5722-SS1 Option 33 OS/400: Portable Application Solutions Environment (OS/400
PASE) and all the utilities supplied with it
򐂰 The VisualAge® C++ compilers
򐂰 The HTTP Server (powered by Apache) support for OS/400 PASE Common Gateway
Interfaces (CGIs)

To “run” PHP scripts with your HTTP Server (powered by Apache), a PHP engine is required
on your iSeries server. The PHP engine is an open source product. This chapter explains how
to download, compile, install, and then configure PHP on your iSeries. It explains how to
install versions 4.3.0 and the older version 4.2.2 of PHP.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 387
 The PHP engine is available both as an Apache module and a CGI. Support for PHP as a
module is not yet available for OS/400. The step-by-step implementation discussed in this
chapter involves the CGI version of PHP running in OS/400 PASE. For a general discussion
on the CGI support with the HTTP Server (powered by Apache), see 7.2, “Everything
dynamic with CGI support” on page 160. This allows you to run AIX binaries directly on an
iSeries. It includes the necessary patches for the minor modifications needed to the PHP
source code.

Note: If you want to know why this is so great, see the article “Programming with PHP on
the iSeries” for iSeries Network by David Larson and Tim Massaro. You can find this article
(requires login) on the Web at:
http://www.iseriesnetwork.com/resources/artarchive/index.cfm?fuseaction=viewarticle&CO_C
ontentID=15746&channel=art&PageView=Search

With permission from iSeries Network, we include the article in this IBM Redbook. To skip
the article, go to “Prerequisites” on page 398.

Programming with PHP on the iSeries server

Hypertext Preprocessor Language is a powerful, server-side scripting language for Web page
creation. Scripting language means PHP requires no compilation, much like Perl or Rexx.
Because PHP is a server-side language, you can include it directly in HTML, and it is
recognized and processed by a Web server.

The first “P” in PHP is a remnant from the original acronym for Personalized Home Page. This
was the term that PHP creator Rasmus Lerdorf used when he first used a set of Perl scripts to
monitor access to his online resume. Since then, however, PHP has become the most
popular optional module configured on Web servers. See the following Web sites:
򐂰 http://www.netcraft.com/survey
򐂰 http://www.securityspace.com/s_survey/data/man.200304/apachemods.html

This section introduces the PHP language and explains how to configure PHP to access DB2
Universal Database (UDB) from your Apache Web server. Then, you see examples of how
iSeries shops can use PHP to create dynamic Web pages based on new or existing iSeries
DB2 UDB databases.

What PHP is
PHP code can easily access database files and output HTML, resulting in non-static,
up-to-date Web pages. It's a technique similar to JavaServer Pages (JSPs) or CGI binary
(often called CGI-BIN) programming. Also, PHP is an open-source project. Open-source code
can be useful if you want to tweak the behavior of PHP, but it's even more valuable because
there are many open-source PHP applications and code samples available on the Web. This
means you can get a new PHP Web project up and running quickly with little investment.

Hundreds of ready-made applications written in PHP are available as shareware, and many
commercial products employ it. Until recently, PHP enjoyed a reputation for reliability and
security. See “Beware of PHP bugs” on page 397.

388 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Figure A-1 shows the difference
between standard static Web
pages and dynamic Web pages
using server-side PHP processing.
In the first scenario on the left, a
standard URL request arrives at
the Web server asking for Web
page:
http://www.example.com/index.html

The Web server sees this request

and returns the HTML that is in the
file somepage.html.

Still looking at Figure A-1 with the

second scenario on the right, the Figure A-1 Left: Standard request for a Web page
index.php file contains the special Right: Request with PHP
<?php tag that tells the Web server
to process embedded PHP statements. After PHP processes those statements, it returns
HTML statements to the Web server. Those statements are then sent back to the user
included in the original HTML found in the file index.php. Because the PHP statements can
run a command or Structured Query Language (SQL) statement, we say that the Web page is
dynamically generated, as opposed to our previous static HTML page.

Why PHP
Besides the fact that PHP is so popular, why would you want to use it? There are several
reasons:
򐂰 Easy to use: As mentioned earlier, PHP is a scripting language included directly in HTML.
This means that getting started is easy. There’s no need to compile PHP programs or
spend time learning tools that create PHP. You can simply insert statements and get quick
turnaround as you make changes.
򐂰 Fully functional: The PHP language has built-in functions to access your favorite
database. With PHP, your HTML pages can reflect current information by querying those
databases, or you can use information about the user viewing your HTML Web page to
customize the page specifically for that user. In addition to good relational database
support, PHP is a complete language that includes powerful functions. You can create
classes for object-oriented programming and use flat file or Lightweight Directory Access
Protocol (LDAP) databases. Plus, it includes a spell checker, Extensible Markup Language
(XML) functions, image generation functions, and more.
򐂰 Compatible and quick: Because PHP generates plain HTML, it's compatible with all Web
browsers and refreshes quickly.
򐂰 Secure: Although PHP is open source, it’s a secure environment. One of its advantages
(over, JavaScript, for example) is that all that Web clients see is pure HTML. Because the
logic of the PHP program is never exposed to the client, security exposures are reduced.
򐂰 Open source: Another reason to use PHP is because it's an open-source project, which
makes it easy to find examples and get started quickly. Here are two examples of Web
sites that offer a place where PHP scripts are shared:
– http://www.sourceforge.net
– http://www.phpresourceindex.com

Appendix A. Bringing PHP to your iSeries server 389

A code example
Example A-1 shows us a simple "HelloWorld!" example. This is as simple as it gets. The file
starts as a normal HTML file. We simply insert PHP statements following the <?PHP tag. The
<?PHP tag is the signal to the HTML processor that PHP processing is necessary. The print
statement is a PHP statement.
Example: A-1 HelloWorld PHP example
<html>
<head><title>Standard HTML Page with PHP
HelloWorld</title>
<body>
<?PHP
print "Hello World";
print "<br> Generated with <b>PHP</b>";
?>
</body>
</html>

To make this example a little more useful, we add the statements shown in Example A-2 to
query the state of our Web server.
Example: A-2 Changes made to HelloWorld
<?PHP
print "Hello World from System:" .
$HTTP_SERVER_VARS['HTTP_HOST'];
print phpinfo();
?>

The result of our PHP program is similar to what is shown in Figure A-2. This is a dynamic
Web page that contains the name of our Web server and a table built by PHP with details
about how PHP is configured on our Web server. This is accomplished by using one of
several predefined PHP variables (for example HTTP_HOST) and the PHP function phpinfo.

390 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 Figure A-2 Dynamic Web page generated by the PHP ‘Hello World’ script

PHP on the iSeries server

An iSeries user has two options to set up PHP. You can use PHP with OS/400 PASE and the
HTTP Server (powered by Apache). Or you can install a Linux logical partition (LPAR) and run
Apache and PHP in that partition. Table A-1 shows factors to consider before you make this
decision.
Table A-1 Which is for you? PHP as a CGI in OS/400 PASE versus PHP in a Linux LPAR
Factors to consider PHP in OS/400 PASE and Apache PHP in Linux LPAR

OS/400 You should have V5R1 or newer. This You must have V5R1 or newer with
requirements should work for V4R5, but we have not specific hardware to run Linux.
tried it ourselves.

Cost A cost is associated with OS/400 PASE A cost is associated with Linux
(becomes free in V5R2). In V5R1 and distribution.
prior releases, OS/400 PASE was a
nominal fee of around $100 US.

Appendix A. Bringing PHP to your iSeries server 391

 Factors to consider PHP in OS/400 PASE and Apache PHP in Linux LPAR

Setup required No setup is required to use PASE. Some setup associated with the
creation of a Linux partition, user
IDs, and so on, and extra LPAR
requires some dedicated
processor resource.

Availability and You must obtain PHP from these Linux is most compatible with new
compatibility instructions and have AIX skills to versions of PHP as they are
compile PHP as new versions come released.
out.

mySQL mySQL is unavailable in PASE by mySQL is available as an

default. You must download and alternative database (it is fairly
compile it if desired. common to use mySQL with PHP
applications).

Web server module PHP cannot be a Web server module. PHP can be installed as an
It must be a CGI process only. This Apache module.
matters only in extremely performance-
critical Web sites.

Database An Open Database Connectivity To use iSeries DB2 UDB, you must
(ODBC) driver is not necessary. download, install, and configure
iSeries ODBC Driver for Linux.
This UNIX-based ODBC is free
from IBM. It uses sockets to
communicate between the Linux
LPAR and the iSeries LPAR.

If you plan to install PHP on an iSeries server, you need to be at V5R1 or later. As mentioned
in Table A-1, this can work for V4R5, but we have not tried it ourselves. You must also have
installed OS/400 PASE. PASE is the AIX runtime support for iSeries. See “Prerequisites” on
page 398 to see if you have the requirements for running PASE on your AS/400 or iSeries
hardware.

If you plan to install PHP on a Linux LPAR, PHP is most likely included with your Linux
distribution. If it is not included, the installation instructions are virtually identical to those
found in the PHP distribution itself and in the PHP site frequently asked questions (FAQs) at:
http://cvs.php.net/cvs.php?login=1

Regardless of where you install PHP in OS/400, the configuration is the same. For the
Apache Web server to recognize PHP files, you must change the Web server configuration
file to recognize script aliases and allow access to the directory in which the PHP CGI
executes. See Example A-3. The directory where PHP is installed may differ.
Example: A-3 Script aliases for PHP
ScriptAlias /php-bin/ /usr/local/php/bin
AddType application/x-httpd-php .php
Action application/x-httpd-php /php-bin/php
<Directory /QOpenSys/php/bin>
Options +ExecCGI
order allow,deny
allow from all
</Directory>

392 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
PHP as a CGI program
The next example shows a traditional HTML form that uses the Action tag to invoke a CGI
program when a user clicks the Submit button. In this example, the CGI program is actually a
PHP program that processes the fields in the HTML form and uses that information to query a
DB2 database.

The database we use is called SAMPLE. SAMPLE is actually shipped with V5R1. To create it,
follow the instructions in “Creating a sample database” on page 405.

Figure A-3 shows the basic HTML form that we use to perform a database query. Our system
name is LPAR3NVM.

Figure A-3 Basic HTML form used to perform a database query

Appendix A. Bringing PHP to your iSeries server 393

 Figure A-4 shows the results of our query. Each record returned was placed in a table row.

Figure A-4 The result of the query

Example A-4 shows the dbqueryphp.php script where the actual work is done.
Example: A-4 The dbqueryphp.php script
<HTML>
<HEAD>
<TITLE>PHP DB Query Tester </TITLE>
</HEAD>
<BODY>
<!--dbqueryphp.php -->
<!--Called by dbqueryhtml.html -connect to sample db2 database and run an SQL
statement -->
<?php
$host = $_POST['host'];
$database = $_POST['database'];
$query = $_POST['query'];
if ($host && $database && $query) {
$link =odbc_connect($host, "", "");
if(!odbc_setoption($link,1,SQL_ATTR_COMMIT,SQL_TXN_NO_COMMIT)){
echo "ERROR:unable to turn off commitment control!\n";
}
if(!odbc_setoption($link,1,SQL_ATTR_DBC_DEFAULT_LIB,$database)){
echo "ERROR:unable to set default library to $database!\n";
}
$querynoslash =stripSlashes($query);
$result =odbc_exec($link,$querynoslash);
?>
Query performed:<B><?php echo ($querynoslash);?></B><HR>
Results:<br>
<?php
if ($result ==0):
echo ("<B>Error ".odbc_error().":".odbc_errormsg()."</B>");
elseif (odbc_num_rows($result)==0):

394 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 echo("<B>Query ran successfully</B>");
else:
?>
<TABLE BORDER=1>
<TR>
<?php
for ($i =0;$i <odbc_num_fields($result);$i++){
echo("<TH>".odbc_field_name($result,$i+1)."</TH>");
}
?>
</TR>
<?php
while(odbc_fetch_into($result,$row_array)!=FALSE){
echo("<TR>");
for ($j =0;$j <odbc_num_fields($result);$j++){
echo("<TD>".$row_array [$j ] . "</TD>");
}
echo("</TR>");
}
echo("</TABLE>");
endif;
} elseif ($host || $database || $query) {
echo("All three fields must be filled in for a query<BR>");
} else {
echo("Use PHP to run an SQL Query on an iSeries database:<BR>");
}
?>
<HR><BR>
<FORM ACTION=" <?php echo($_SERVER['PHP_SELF']) ?>" METHOD=POST>
<TABLE BORDER=1><TR>
<TD>iSeries Host:</TD>
<TD><INPUT TYPE=TEXT NAME="host" VALUE="<?php echo ($host);?>"></TD>
</TR></TABLE>
<BR>
Library of the database to query:<BR>
<INPUT TYPE=TEXT NAME="database" VALUE="<?php echo ($database);?>">
<HR>
Please enter the SQL query to be run:<BR>
<TEXTAREA name="query" cols="40" rows="5">
<?php echo ($query); ?>
</TEXTAREA>
<BR>
<INPUT TYPE=SUBMIT VALUE="Execute query">
</FORM>
<p>View PHP <a href="dbqueryphp.php.source"target="_blank">Source for this Query</a>
</BODY>
</HTML>

The highlights include:

򐂰 odbc_connect: This is the “Open” of the database. The link variable is used by other
ODBC functions later in the script.
򐂰 odbc_exec: The variable filled in on the HTML form contains the string that we run as an
SQL statement. odbc_exe runs the SQL statement and returns results in the $result
variable.
򐂰 odbc_numfields: A function determines the number of columns that are returned for this
record. We use this value to place HTML <TH></TH> tags around each cell.

Appendix A. Bringing PHP to your iSeries server 395

Another PHP script
For one additional PHP example, let us include a script that works only in the OS/400 PASE
version of PHP. This example takes advantage of the fact that the OS/400 PASE “system”
command writes any spooled output, produced by a command, to standard output. That is,
you can run any commands with an OUTPUT(*PRINT) parameter in the OS/400 PASE shell
and have the results sent to STDOUT.

For example, if you're on the OS/400 PASE command line QP2TERM, you can type the
system wrkactjob command (for the Work with Active Jobs (WRKACTJOB) command of
OS/400) and see the results as they scroll across the screen. Our example, phpactjob, simply
formats this output into an HTML table. Figure A-5 shows the output of this script.

Figure A-5 PHP formats the result of Work with Active Jobs (WRKACTJOB) at an HTML table

Example A-5 shows the phpactjob source code. Note that we use reverse single quotation
marks (``) to run the Work with Active Jobs (WRKACTJOB) command and capture the
output. This output is then broken into lines by searching for the new line character “\n” using
the strtok function of PHP.
Example: A-5 Source code for PHPACTJOB
<html>
<head>
<title>PHPACTJOB Test PHP with WRKACTJOB Output</title>
</head>
<p>PHP Running WRKACTJOB in PASE<br>
<?PHP
$lsout=`/QOpenSys/usr/bin/system 'wrkactjob'`;

396 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 $line = strtok($lsout,"\n");
print "<table border CELLSPACING=0 CELLPADDING=0 BGCOLOR=\"#96FB84\">";
print "<tr>";
print "<td><pre>";
print $line;
print "</pre></td>";
print "</tr>";
while ($line = strtok("\n"))
{
print "<tr>";
print "<td><pre>$line</pre></td>";
print "</tr>";
}
print "</table>";
print "thend";
?>
</body>
</html>

For more information

You have been introduced to PHP and how to use it on the iSeries server. Use this IBM
Redbook as a starting point to find other examples and documentation that can have you
running PHP in no time.
򐂰 PHP project Web site for help, tutorials, and examples about PHP
http://www.php.net
򐂰 OS/400 PASE on iSeries PartnerWorld Web site
http://www-919.ibm.com/developer/factory/pase/overview.html
򐂰 Linux on iSeries home page
http://www.iseries.ibm.com/linux
򐂰 A demo application showing PHP using ODBC Driver for Linux
http://www-1.ibm.com/servers/eserver/iseries/linux/odbc/guide/demoindex.html
This demo includes PHP using binary large objects (BLOBs) that contain employee
photos in the sample iSeries EMPLOYEE database.
򐂰 ASP to PHP Web site for ASP users who should consider migrating to PHP
http://asp2php.naken.cc/

Beware of PHP bugs

In the past, a few security holes were discovered in PHP. The most recently discovered one
involves the code for handling file uploads. This flaw lets hackers easily crash the PHP server
and possibly take it over remotely. The flaw affects PHP versions 4.2.0 and 4.2.1. CERT rates
the problem as critical.

The PHP Group announced a fix release, version 4.2.2, that all PHP users employing PHP’s
file-upload facility should install immediately. The fix is available on the Web at:
http://www.php.net/release_4_2_2.php

Appendix A. Bringing PHP to your iSeries server 397

Prerequisites
This section assumes that you have the following hardware and software on your iSeries
server:
򐂰 5722-SS1 OS/400 (5722-SS1) at V5R2: The same basic steps should work on an iSeries
server at V5R1
򐂰 5722-SS1 Option 13 OS/400 System Openness Includes
򐂰 5722-SS1 Option 33 OS/400 PASE

Note: In this IBM Redbook, we assume that you are running at V5R2 of OS/400. If you
have OS/400 V5R2, then you must make sure that 5722-SS1 Option 33 OS/400 PASE
is installed.

Since OS/400 V5R1 supports some levels of AS/400 hardware that are not supported
by OS/400 PASE (requires a certain version (level) of PowerPC processor), you must
first determine whether your AS/400 hardware supports OS/400 PASE. You can find a
detailed list of processors on which OS/400 PASE can run on the Web at:
http://www-919.ibm.com/servers/eserver/iseries/developer/factory/pase/ehardware.html

򐂰 5722-DG1 IBM HTTP Server for iSeries: This Licensed Program Product (LPP) contains
the HTTP Server (powered by Apache), which is the only HTTP server for which PHP
works. Also, install the latest Apache group PTF package. For V5R2, the group PTF
package number is SF99098.
򐂰 The make command: You can find the make command in OS/400 PASE for V5R2. If you
are using V5R1 of OS/400, then you must download the make command. We recommend
that you use the GNU make command that can download from:
http://www.gnu.org/directory/gnu/make.html
򐂰 5799-PTL PRPQ iSeries Tools for Developers (Optional): This toolkit is optional for this
work, but you may find it useful for some other similar projects. For details, see:
http://www.iseries.ibm.com/developer/factory/tools

We also assume that you have the following hardware and software on your build machine.
The build machine can be either a separate IBM Eserver pSeries® server running AIX or an
iSeries running OS/400 with the following software:
򐂰 The patch command: The patch command is included in OS/400 PASE in V5R2. If you
do not have a patch program on your system, try the GNU patch. The GNU patch program
is usually not on AIX or OS/400 machines. You can download version 2.5 (not 2.5.4) from:
ftp://ftp.gnu.org/pub/gnu/patch
To compile the source, follow these steps:
a. Untar the source using the tar command.
b. Type cd to go to the directory.
c. Perform a ./configure.
d. Run the make command.
e. Run the make install command.
򐂰 GNU gzip command: Compresses and decompresses files. You can download this from:
http://www.gnu.org/directory/GNU/gzip.html

398 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 򐂰 VisualAge C++ compiler for AIX: You can find information about this compiler at:
http://www.ibm.com/software/ad/vacpp/
If your build machine is AIX (not OS/400), you must match the AIX version to the target
OS/400 PASE version. That is, the application binary created on AIX needs to be
compatible with the version of OS/400 PASE in which you want to the application to run. To
help you plan this issue, see:
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/rzalf/rzalfplanning.htm
We tested these instructions on AIX 4.3 and newer. Alternatively, V5R2 of OS/400 PASE
now supports installation of either the IBM VisualAge C++ Professional for AIX Version 6.0
or the IBM C for AIX Version 6.0 software products. This means you can compile OS/400
PASE applications within OS/400 PASE. A separate AIX system is not required. IBM
VisualAge C++ Professional for AIX Version 6.0 (5765-F56) and IBM C for AIX (5765-F57)
are separately available program products from IBM. Note that the VisualAge C++
Professional for AIX compiler product also includes the C for AIX compiler product.
򐂰 Perl scripting language: This is needed to install VisualAge C++. You can download Perl
to your iSeries from the Web at:
http://www.cpan.org/ports/index.html#os400

Installing PHP on the iSeries server

Follow these steps to download and prepare the PHP source files for compile.

Important: The installation steps described in the following sections use the PHP source
package. This package is patched for DB2 UDB for iSeries and then compiled. However,
we also found a Web page that provides PHP binary versions for iSeries. Go to:
http://www.mcind.com/php/

At the time of writing this publication, the Web site contained PHP up to version 4.3.5.

Pre-preparation for installation

If you want to perform the complete installation on your iSeries server, you have to install
VisualAge C++ and Perl first.

Installing the Perl scripting language

Follow these steps:
1. Download the binary distribution (see “Prerequisites” on page 398 for the location of this
code).
2. Place it under the /home/yourid directory. The file should have the name
[email protected].
3. Start an OS/400 PASE terminal and change into the directory in which you placed the file.

Note: To get an OS/400 PASE (instead of a Qshell) terminal session, enter the
following command from an OS/400 command line:
CALL QP2TERM

Appendix A. Bringing PHP to your iSeries server 399

 4. Use the following command to unzip the binary distribution:
gunzip [email protected]
5. Change to the root directory (cd /) and run the command:
tar -xvf /home/yourid/[email protected]
The distribution is already archived from QOpenSys, so it places the files into the correct
directory path.
6. To finish the Perl installation, generate symbolic links for Perl commands:
ln -s /QOpenSys/perl/bin/* /QOpenSys/usr/bin

Installing VisualAge C++

As soon as you finish downloading the trial version of VisualAge C++ and complete the Perl
installation, install VisualAge C++ on your iSeries server:
1. Open a new, or return to your, OS/400 PASE terminal and create the source installation
directory. We use vacpkg in this example:
mkdir /QOpenSys/vacpkg
2. Place the VisualAge C++ distribution into this directory (using File Transfer Protocol
(FTP)). The file should be named vacpp.60.tnb.tar.Z.
3. In your terminal session, change to the directory /QOpenSys/vacpkg and extract the file:
gunzip vacpp.60.tnb.tar.Z
4. Use tar for extraction:
tar -xvf vacpp.60.tnb.tar
5. A work-around is needed to get a working installation and let the install script run correctly:
mv usr/sys/inst.images/vacpp.tnb usr/sys/inst.images/vacpp.lic
mv usr/sys/inst.images/vac.tnb usr/sys/inst.images/vac.lic
6. Restore the script:
restore -qf usr/sys/inst.images/vacpp.ndi ./usr/vacpp/bin/vacppndi
7. Use Perl to install the application:
perl usr/vacpp/bin/vacppndi -d /QOpenSys/vacpkg/usr/sys/inst.images -b /QOpenSys/vac600
The script takes a while to complete. Finally it installs VisualAge C++ into the directory
/QOpenSys/vac600.
8. Add the symbolic links for VisualAge:
ln -s /QOpenSys/vac600/usr/vacpp/bin/* /QOpenSys/usr/bin

After these two steps of pre-installation, you can continue with the installation of PHP itself.

Downloading PHP
Download the version of PHP you need for your iSeries server.

Note: We include the patch files for both the 4.3.0 and the older 4.2.2 versions of PHP.
These instructions, however, are written for version 4.3.0.

1. Download the tar file php-4.3.0.tar.gz for PHP 4.3.0 from the following Web site:
http://www.php.net

400 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 2. Using FTP, send this file to the machine on which you will build PHP. This may be the AIX
machine or the iSeries machine with the VisualAge compiler. We call this your build
machine.

Tip: During our installation and testing, we noticed that the best location to place the
php-4.3.0.tar.gz files is under the /home directory tree, when using your iSeries as the
build machine. The following configuration installs PHP in the directory /QOpenSys/php.

3. Untar the file by using the following commands:

gunzip php-4.3.0.tar.gz
tar -xvf php-4.3.0.tar

Patching the source code file

A patch is required to run PHP on the iSeries server. We included patch files for both the 4.3.0
and the older 4.2.2 versions of PHP. The patch changes the default PHP DB2 support from
AIX DB2 to OS/400 DB2.
1. Download and save the patch file to the build machine. See Appendix D, “Additional
material” on page 421, for information about downloading the file. Download the patch file
into the same directory from which you ran the tar command.
2. Change directory (cd) to that directory and run the following patch command:
cd php-4.3.0
patch -p1 < ../php430.patch
The -p1 says to remove a level from the patch filenames, so it looks for
ext/odbc/php_odbc.c instead of php-4.3.0/ext/odbc/php_odbc.c.
This has the advantage that, if you download a version of PHP that has not changed too
much from the one for which we provided a patch, it works. For example, you can actually
use PHP 4.3.1 with the 4.3.0 patch because the files we patched did not change.

Locating iSeries-specific files

You must locate and bring to your build machine the following iSeries files:
򐂰 The sqlcli.h and the libdb400.exp files that contain DB2 UDB AS/400 support.
򐂰 The as400_libc.exp file is an iSeries-specific extension to the AIX file libc.a. This file is part
of 5722-SS1 Option 13 OS/400 - System Openness Includes.

Follow these instructions to obtain these files from your iSeries server:
1. Enter the following command:
CPY OBJ('/QIBM/include/sqlcli.h') TODIR('/home/yourid') TOCCSID(*STDASCII) DTAFMT(*TEXT)
2. Using FTP, place the /home/yourid/sqlcli.h file from your iSeries server to the build
machine.
3. Using FTP, send the libdb400.exp and as400_libc.exp files from the iSeries directory
/QOpenSys/QIBM/ProdData/OS400/PASE/lib to the AIX build machine.

Note: Skip steps 2 and 3 if the build machine is your iSeries server.

Appendix A. Bringing PHP to your iSeries server 401

Preparing for the PHP compile
Follow these steps to prepare the files and directories needed for the successful compile of
PHP on your build machine. These steps assume that you are using ksh.
1. Set the CFLAGS, CC, and CPPFLAGS environment variables as follows. You must enter
the export CFLAGS=’.........’ command all on one line. There is no “\” continuation
character.:

Note: The flags for -I and -bI are the uppercase format of the letter “i”.

– If the build machine is an AIX server, enter:

export CFLAGS='-ma -DPASE -I /home/yourid -bI:/home/yourid/libdb400.exp
-bI:/home/yourid/as400_libc.exp'
export CC=xlc
export CPPFLAGS=-qflag=e:e
– If the build machine is your iSeries server, enter:
export CFLAGS='-ma -DPASE -I /home/yourid
-bI:/QOpenSys/QIBM/ProdData/OS400/PASE/lib/libdb400.exp
-bI:/QOpenSys/QIBM/ProdData/OS400/PASE/lib/as400_libc.exp'
export CC=xlc
export CPPFLAGS=-qflag=e:e
2. Change to the php-4.3.0 directory using the cd command.
3. Change the authority to Execute on the files config.guess and config.sub. You can do this
by using the command:
chmod +x config.guess
chmod +x config.sub
4. Run the following command (it configures the script to install PHP in the directory
/QOpenSys/php). The continuation character (‘\’) is not necessary if you type it all on one
line.
./configure --with-ibm-db2 \
--with-config-file-path=/QOpenSys/php/etc \
--prefix=/QOpenSys/php/ \
--enable-force-cgi-redirect \
--without-mysql \
--disable-mysql
5. If you are compiling directly in OS/400 PASE on iSeries, add the following configure flags.

Note: The continuation character (\) is not necessary if you type it all on one line.

--build=ibm-aix4.3.3.0 \
--host=powerpc-ibm
The configuration should take some time to run. After it finishes, you need to make final
adjustments to the files listed in the following steps.

402 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 6. Edit the Makefile:

Note: The Makefile is generated with lines greater than 2048 characters. Some editors,
such as vi, cannot handle the long lines, so you need to use a different editor. Send the
Makefile, using FTP, to a different machine and back if necessary.

If you are compiling on your iSeries server, you can use the Edit File (EDTF) command,
but be careful with lines, that go beyond the window size. If you change such lines,
verify the correctness by using the Display File (DSPF) utility.

remove -ldb2 from ODBC_LIBS

remove -ldb2 from EXTRA_LIBS
7. Edit the config_vars.mk file:

Note: PHP version 4.3.0 does not have a config_vars.mk. This step is for PHP version
4.2.2 only.

remove -ldb2 from ODBC_LIBS

remove -ldb2 -lbind from EXTRA_LIBS
8. Edit the main/build-defs.h file:

Tip: You can see that the ./configure command worked, when all of the configuration
files that should be changed contain the mentioned statements.

remove -ldb2 from PHP_ODBC_LIBS

9. Edit the main/php_config.h file:
Delete #define HAVE_MMAP 1
Delete #define HAVE_SETITIMER 1
If you run this on a V5R1 OS/400 server, edit:
Delete #define HAVE_STATVFS 1
Delete #define HAVE_PREAD 1
Delete #define HAVE_PWRITE 1

Note: When editing text files (such as Makefile, php-config.ini, or any other script) in a
Windows Notepad or WordPad, make sure to remove the carriage return (\r) from the file
before you use it. You can do this in OS/400 PASE by using the commands:
tr -d "\r" < Makefile > Makefile.new
mv Makefile.new Makefile

Compile (make)
You have two choices depending on whether you are compiling in AIX on the pSeries server
or in OS/400 PASE on the iSeries server.

Compiling in OS/400 PASE on the iSeries server

Note: To get a POS/400 ASE (instead of a Qshell) terminal session, enter the following
command from an OS/400 command line:
CALL QP2TERM

Appendix A. Bringing PHP to your iSeries server 403

 Follow these steps if you are compiling the PHP source code on your iSeries server:
make
make install
mkdir /QOpenSys/php/etc
cp php.ini-dist /QOpenSys/php/etc/php.ini

This installs and puts all the files in the correct directory. You need write access to the
/QOpenSys directory.

At this point, you may skip to “Testing PHP” on page 405.

Compiling in AIX on the pSeries server

Follow these steps if you are compiling the PHP source code on your pSeries:
1. Edit the Makefile (see the note in step 6 on page 403 about the long lines of the Makefile)
for the line "install_targets =",remove "install-pear".
2. Enter the following commands in the order shown:
mkdir /tmp/QOpenSys
3. At the AIX prompt, run the following commands:
make
make install INSTALL_ROOT=/tmp/
This installs PHP into /tmp/QOpenSys/php.
4. Enter the following commands in the order shown:
mkdir /tmp/QOpenSys/php/etc
cp php.ini-dist /tmp/QOpenSys/php/etc/php.ini
5. Edit the Makefile (see the note in step 6 on page 403 about the long lines of the Makefile)
for the line "install_targets =",add "install-pear".
If the location of your home directory on your AIX box is different than the location of your
home directory in OS/400 PASE (for example, on AIX your home directory is
/usr/home/usr4/jdoe and on OS/400 PASE it is /home/john), replace all occurrences of
"/usr/home/usr4/jdoe/" to "/home/john/" in the Makefile. Make sure that you include the
first and last “/” so you don't lose your directory separator.
6. Enter the following commands in the order shown:
cd /tmp
tar -cvf ~/php430pasebin.tar QOpenSys
cd ~
tar -cvf php430pasesrc.tar php-4.3.0
7. Using FTP, send both php430pasebin.tar and php430pasesrc.tar to your home directory
on the iSeries server.
8. Enter the following commands in the order shown:

Note: The following steps are all done in OS/400 PASE on the iSeries and not in AIX.

cd /
tar -xvf ~/php430pasebin.tar
cd ~
tar -xvf php430pasesrc.tar
cd php-4.3.0
make install-pear

404 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
Testing PHP
From the OS/400 PASE shell, run the command:
/QOpenSys/php/bin/php -v

This should tell you the version of PHP you have.

Note: If you try running the PHP binary in OS/400 PASE and it dies with an illegal
instruction, check for the existence of a job log. Several things can cause an illegal
instruction signal and kill a OS/400 PASE application. If the illegal instruction was caused
by an unsupported system call, the name of the system call is specified in the job log.

The job log should tell you the name of the illegal instruction. Next find the corresponding
HAVE_ line in the php_config.h and delete it. Then recompile. This should only happen if
you're compiling on a version of AIX that supports certain syscalls that OS/400 PASE does
not support (in addition to the five noted earlier).

Configuring HTTP Server (powered by Apache) to use PHP

Edit the file httpd.conf using the Apache GUI interface. The key statements needed are:
ScriptAlias /php-bin/ /QOpenSys/php/bin/
AddType application/x-httpd-php .php
Action application/x-httpd-php /php-bin/php
ServerUserID userprofile
<Directory /QOpenSys/php/bin>
Options +ExecCGI
order allow,deny
allow from all
</Directory>

Stop and start your HTTP Server (powered by Apache) Web server.

File permissions: If you can serve index.html without problems, but cannot serve
index.php, this is most likely due to the fact that PHP is running as OS/400 user profile
QTMHTTP1. QTMHTTP1 is the default OS/400 profile used for CGI applications. The
default OS/400 profile for serving static files is QTMHHTTP, which most likely has the
proper authorities.

To solve this problem, give access to both the file (read) and all the directories above the
file (read and execute) in the IFS to the user profile QTMHTTP1.

Creating a sample database

Here we can add the creation of the sample database as supplied with the system. Starting in
V5R1, a sample database is shipped with the system. This is explained on the DB2 Universal
Database Web site at:
http://www.ibm.com/servers/eserver/iseries/db2/sqldata.htm

To unpack and create the sample database, invoke the procedure from any SQL interface:
CALL QSYS.CREATE_SQL_SAMPLE('SAMPLE')

Here SAMPLE is the name of the schema that you want to create. However, currently the
sample PHP requires updates. For example, OS/400 PASE PHP runs as a CGI and cannot
use the $_SERVER ['PHP_AUTH_USER'] and $_SERVER ['PHP_AUTH_PW'] values.

Appendix A. Bringing PHP to your iSeries server 405

 Also, when connecting to a database, you may normally use something like this example:
$dsn = "DRIVER=iSeries Access ODBC Driver;SYSTEM=$isdb_system;DBQ=$isdb_database";
$db = odbc_connect($dsn, $user, $password);

In OS/400 PASE, you use something like this example:

$db = odbc_connect($isdb_system, "", "");
odbc_setoption($db, 1, SQL_ATTR_DBC_DEFAULT_LIB, $isdb_database);

Note: It does not matter which user ID and password you use when you connect to the
ODBC database. It uses the authority of the user profile that is running the Web server
process. Use the ServerUserID directive in the Apache configuration to change this. It is
actually somewhat of a security hole if you allow others to make a Web page and do not
configure the Apache Web server to run the under a different user.

Limitations
Since PHP runs as a CGI application and not as an Apache module, some things do not work
in this implementation on the iSeries server:
򐂰 HTTP authentication does not work, so any script that tries using the variables
$_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] does not work. You need to
use user accounts and make a form that gets the user name and password and sets a
cookie instead.
򐂰 PHP_SELF does not work. There is a bug in the CGI version of PHP 4.3.0 that corrupts
the $_SERVER['PHP_SELF'] variable. For more details about this bug, see the PHP page:
http://bugs.php.net/bug.php?id=21261
By the time you read this, that page may have a patch that fixes the issue. If it does, then
apply the patch. If it doesn't, use the fix suggested by [email protected] in the bug report,
which says to follow these steps:
a. Create a file called “self_fix.php” in /QOpenSys/php/lib/php/ with the following script:
<?
$_SERVER['SCRIPT_NAME'] = substr($_SERVER['PATH_TRANSLATED'],
strlen($_SERVER['DOCUMENT_ROOT']));
$PHP_SELF = $SCRIPT_NAME = $_SERVER['PHP_SELF'] = $_SERVER['SCRIPT_NAME'];
?>
b. In /QOpenSys/php/etc/php.ini, look for the line that says:
auto_prepend_file =
c. Change this line to:
auto_prepend_file = self_fix.php
This should fix the $_SERVER['PHP_SELF'] bug.

Note: Since this is a bug in PHP, there is no support if these steps do not solve the
problem. See the restriction statement at the beginning of this chapter for more
information.

򐂰 PHP and Net.Data both use the SQL Call Level Interface (CLI) application programming
interface (API) to access the database. The problem arises when two different applications
use the SQL CLI interface in the same job. Unfortunately, the SQL CLI provides no way to
isolate different applications that use the SQL CLI. Within a job, there is only one SQL
environment handle. Anyone who uses the SQL CLI uses the same environment handle.

406 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 When Net.Data performs a database operation and then PHP comes in to do the same,
problems occur. PHP and Net.Data cannot coexist within the same CGI job if the both
interact with the database. This is true for any CGI application that uses the SQL CLI.
If you want to use the same HTTP server for both applications, you can circumvent this by
ensuring that Net.Data runs under one user profile and PHP under another. Unfortunately,
about the only way to enforce this in your HTTP Server (powered by Apache) is to use
basic authentication to force the HTTP server to adopt the authority of a different user
profile for each of the clients. This, of course, is not always an option.

PHP 4.2.2 errata

The biggest change from 4.2.2 to 4.3.0 was the configuration process. To make this
document apply to 4.2.2, make the following changes to the steps listed in the previously
sections as noted:
򐂰 For “Locating iSeries-specific files” on page 401:
– Step 6 on page 403: Ignore the note about the long line Makefile because it does not
exist.
– Step 7 on page 403: PHP version 4.3.0 does not have config_vars.mk. This step is for
PHP version 4.2.2 only.
򐂰 For “Compiling in AIX on the pSeries server” on page 404, follow these steps instead. This
is because it does not use PHP itself to try to install PEAR.
cd php-4.2.2
make
cd ..
tar -cvf php422pasesrc.tar php-4.2.2
Using FTP, send the tar file to OS/400 PASE.
The following steps are all done in OS/400 PASE on the iSeries and not in AIX:
cd ~
tar -xvf php422pasesrc.tar
cd php-4.2.2
make install

Appendix A. Bringing PHP to your iSeries server 407

408 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 B

Appendix B. Bringing Tomcat Version 5.5 to

your iSeries server
Tomcat is a servlet and JavaServer Pages (JSP) container that is used in the official
Reference Implementation for the Java servlet and JSP technologies. The Java servlet and
JSP specifications are developed by Sun under the Java Community Process.

Tomcat is developed in an open and participatory environment and released under the
Apache Software License. Tomcat is intended to be a collaboration of the best-of-breed
developers from around the world.

The iSeries supports Tomcat Version 3.2.4 as a component of 5722-DG1. See Table 2-2 on
page 20 for details of the packaging on the iSeries. You can learn about the IBM supported
version of the Tomcat server on the iSeries in 9.2, “Apache Software Foundation’s Jakarta
Tomcat on iSeries” on page 197.

It may not be so surprising that the HTTP Server (powered by Apache) administrative GUI
also uses the built-in Jakarta Tomcat servlet container engine at version 3.2.4 to generate the
content.

Why would you spend the extra time and effort to bring Tomcat Version 5.5 to your iSeries
server? Tomcat 5.5, compared to Version 3.2, offers a lot of enhancements for your iSeries
server. It implements the Servlet 2.4 and JSP 2.0 specifications. The Eclipse Java
Development Tools (JDT) is now the default compiler in Jasper. For a complete listing of the
old and new functions, see the Jakarta Tomcat home page at:
http://jakarta.apache.org/tomcat

Jakarta Tomcat Version 5.5 on iSeries is not supported by IBM. We provide these instructions
for you to download a public domain open-source copy of ASF Jakarta Tomcat so you can
implement the new functions on your iSeries server. This chapter explains how to get the new
version of Tomcat to your iSeries server.

Attention: Jakarta Tomcat Version 5.5 on iSeries is not supported by IBM. Use it at your own risk.

© Copyright IBM Corp. 2002, 2003, 2005. All rights reserved. 409
Software prerequisites
At the time of writing this redbook, the latest available version of Jakarta Tomcat was 5.5.1,
which we use for this implementation. Tomcat 5.5.2 was still alpha code. Here is a detailed list
of all software requirements:
򐂰 5722-SS1 i5/OS at V5R3: The same basic steps should work on an iSeries server at
V5R2.
򐂰 5722-SS1 Option 30 i5/OS - Qshell Interpreter

Note: For releases prior to V5R3, an OS/400 PTF corrects several Qshell problems.
We recommend that you install this PTF:
򐂰 V5R1: SI08114
򐂰 V5R2: SI08117

򐂰 5722-DG1 IBM HTTP Server for iSeries: This is not mandatory, because Jakarta Tomcat
Version 5 has a built-in Web server that can serve the included examples. Nevertheless
we highly recommend it, so that you can configure your HTTP Server (powered by
Apache) to connect to the Tomcat servlet engine.
򐂰 5722-JV1 Developer Kit for Java
򐂰 5722-JV1 Option 5 Java Developer Kit 1.3 or 5722-JV1 Option 5 Java Developer Kit
1.4: The Jakarta Tomcat server needs it to run.
򐂰 Binary distribution of Jakarta Tomcat version 5.5.1: You can download it from:
http://archive.apache.org/dist/jakarta/tomcat-5
You may also want to check the following site for archived versions:
http://archive.apache.org/dist/jakarta/tomcat-5/archive/
򐂰 Binary distribution of Jakarta Tomcat version 5.5.1 compatibilty package: You can
find the compatibility package for a specific Tomcat version in the corresponding bin
directory.

Tip: We used the binary ZIP distribution (file named jakarta-tomcat-5.5.1.zip and
jakarta-tomcat-5.5.1-compat.zip) of Tomcat 5.5 for the installation. If you do not have
ZIP available on your iSeries server, see Appendix C, “Bringing Zip and Unzip to
OS/400 PASE and Qshell environments” on page 419.

򐂰 Jakarta Tomcat connector mod_jk for AJP 1.3 on your iSeries: You can download this
(as a ready made save file) from:
http://www.apache.de/dist/jakarta/tomcat-connectors/jk/binaries/iseries/
Select the version of the zipped mod_jk file you need and download it to your PC. We
tested with v1.2.6.

Installation
The installation procedure is divided into three steps as explained in the following sections:
1. Install Tomcat 5.5 on your iSeries server.
2. Install the Tomcat 5.5 compatibility package.
3. Start Tomcat 5.5 on the iSeries server.

410 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers
 4. Install mod_jk connector.
5. Configure your HTTP Server (powered by Apache).

Installing Tomcat 5.5 on your iSeries server

Follow these steps to install Tomcat 5.5 on your iSeries server:
1. Download the binary distribution of Jakarta Tomcat 5.5.1 to your iSeries and place it in the
/home directory. Name this file jakarta-tomcat-5.5.1.zip.
2. Start a Qshell terminal by entering Start QSH (STRQSH) on the 5250 command line.
3. Enter the following command to make /home your current working directory:
cd /home
4. Enter the following command to unzip the file:
unzip jakarta-tomcat-5.5.1.zip
Unzip places the file in the /home directory as /jakarta-tomcat-5.5.1.

Tip: We used the binary ZIP distribution (file named jakarta-tomcat-5.5.1.zip) of Tomcat
5.5 for the installation. If you do not have ZIP available on your iSeries server, see
Appendix C, “Bringing Zip and Unzip to OS/400 PASE and Qshell environments” on
page 419.

Another method to unzip the jakarta-tomcat-5.5.1.zip file is to use jar. Assuming you put
the zip file in a directory called /home, the following commands unzip it into /home using
jar:
qsh
cd /home
jar -xf jakarta-tomcat-5.5.1.zip
5. Enter the following command to change into this directory:
cd /home/jakarta-tomcat-5.5.1/bin
6. Set the environment variables as shown in Figure B-1 using the Work with Object Links
(WRKLNK) command. Start a new 5250 session to your iSeries. On the 5250 command
line, enter:
WRKLNK ‘/home/jakarta-tomcat-5.5.1/bin/*’
Another option for this is to press F12 from the Qshell command line and then work with
the 5250 command line. When you finish, enter STRQSH on the 5250 command line to
restart your Qshell session. It returns you to where you left off earlier.
7. Edit the setclasspath.sh file. Select 2 (Edit). See Figure B-1:
a. Add the following line:
export -s JAVA_HOME=/qibm/proddata/java400/jdk13
b. Change the line to read:
if [ ! -r "$JAVA_HOME"/bin/java -o ! -r "$JAVA_HOME"/bin/javac ];

Appendix B. Bringing Tomcat Version 5.5 to your iSeries server 411

 Browse : /home/jakarta-tomcat-5.5.1/bin/setclasspath.sh
Record : 1 of 49 by 14 Column : 1 79 by 79
Control :

....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
************Beginning of data**************
# -----------------------------------------------------------------------------
# Set CLASSPATH and Java options
#
# $Id: setclasspath.sh,v 1.8 2004/07/26 22:01:19 markt Exp $
# -----------------------------------------------------------------------------
export -s JAVA_HOME=/qibm/proddata/java400/jdk13 7a
# Make sure prerequisite environment variables are set
if [ -z "$JAVA_HOME" ]; then
echo "The JAVA_HOME environment variable is not defined"
echo "This environment variable is needed to run this program"
exit 1
fi
if [ ! -r "$JAVA_HOME"/bin/java -o ! -r "$JAVA_HOME"/bin/javac ]; then 7b
echo "The JAVA_HOME environment variable is not defined correctly"

F3=Exit F10=Display Hex F12=Exit F15=Services F16=Repeat find

F19=Left F20=Right

Figure B-1 Editing the setclasspath.sh file: Setting the environment variables

Note: We edited out the variable for the Java debugger because we did not have this
option on the system. If you have this option on the system, this statement does not
have to be edited. The statement we removed was:
! -r "$JAVA_HOME"/bin/jdb -o

8. At this point, verify that ports 8080 and 8009 are available on your iSeries server. You can
do this by using the 5250 command Work with TCP/IP Network Status (NETSTAT) and
select option *CNN. If you need to change the port number on which the server listens,
you can refer to the Jakarta Tomcat documentation at:
http://jakarta.apache.org/tomcat

Installing the Tomcat 5.5 compatibility package

Tomcat 5.5. requires, by default, the Java 2 Standard Edition Runtime Environment version
5.0 (also known as JDK 1.5) or later. To run Tomcat 5.5 on earlier versions of Java Runtime
Environments (JRE), you need to install an additional package. This package is called the
compat package and provides support to run Tomcat 5.5 under JDK 1.3 or JDK 1.4. Refer to
“Software prerequisites” on page 410 for a description about how to obtain the package.

Follow these steps to install the Tomcat 5.5.1 compatibility package on your iSeries server:
1. Download the binary distribution (jakarta-tomcat-5.5.1-compat.zip)of Jakarta Tomcat 5.5.1
compatibility package to your iSeries and place it in the /home directory. Name this file
jakarta-tomcat-5.5.1-compat.zip.

412 IBM HTTP Server (powered by Apache): An Integrated Solution for IBM Eserver iSeries Servers