Caching Proxy Administration Guide
WebSphere(R) Application Server
Caching Proxy Administration Guide
Version 5.0
Document Number GC09-4601-00
First edition (November 2002)
This edition applies to:
- WebSphere Application Server, Version 5.0
and to all subsequent releases and modifications until otherwise indicated
in new editions.
Order publications through your IBM representative or through the IBM
branch office serving your locality.
(C) Copyright International Business Machines Corporation 2002. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Getting started with the Caching Proxy
Configuring and tuning the Caching Proxy process
Configuring Caching Proxy behavior
Configuring proxy server caching.
Configuring Caching Proxy security
Monitoring the Caching Proxy
Appendixes
- Delving
This preface describes the audience and purpose of this book, its
organization, accessibility features, conventions and terminology, and related
documents.
The Caching Proxy Administration Guide is written for
experienced network and system administrators who are familiar with their
operating systems and with providing Internet services. Prior exposure
to the Caching Proxy is not required.
This book is not intended to support previous releases of Caching
Proxy.
This documentation uses the following typographical and keying
conventions.
Table 1. Conventions used in this book
| Convention
| Meaning
|
| Bold
| When referring to graphical user interfaces (GUIs), bold face indicates
menus, menu items, labels, buttons, icons, and folders. It also can be
used to emphasize command names that otherwise might be confused with the
surrounding text.
|
| Monospace
| Indicates text you must enter at a command prompt. Monospace also
indicates screen text, code examples, and file excerpts.
|
| Italics
| Indicates variable values that you must provide (for example, you supply
the name of a file for fileName). Italics also indicates
emphasis and the titles of books.
|
| Ctrl-x
| Where x is the name of a key, indicates a control-character
sequence. For example, Ctrl-c means hold down the Ctrl key while you
press the c key.
|
| Return
| Refers to the key labeled with the word Return, the word Enter, or the
left arrow.
|
| %
| Represents the UNIX command-shell prompt for a command that does not
require root privileges.
|
| #
| Represents the UNIX command-shell prompt for a command that requires root
privileges.
|
| C:\
| Represents the Windows command prompt.
|
| Entering commands
| When instructed to "enter" or "issue" a command, type the
command and then press Return. For example, the instruction "Enter
the ls command" means type ls at a command prompt
and then press Return.
|
| [ ]
| Enclose optional items in syntax descriptions.
|
| { }
| Enclose lists from which you must choose an item in syntax
descriptions.
|
| |
| Separates items in a list of choices enclosed in { }(braces) in syntax
descriptions.
|
| ...
| Ellipses in syntax descriptions indicate that you can repeat the
preceding item one or more times. Ellipses in examples indicate that
information was omitted from the example for the sake of brevity.
|
Accessibility features help a user who has a physical disability, such as
restricted mobility or limited vision, to use software products
successfully. These are the major accessibility features in WebSphere
Application Server, Version 5.0:
- You can use screen-reader software and a digital speech synthesizer to
hear what is displayed on the screen. You can also use voice
recognition software, such as IBM(R) ViaVoice(TM), to enter data and to
navigate the user interface.
- You can operate features by using the keyboard instead of the
mouse.
- You can configure and administer Application Server features by using
standard text editors or command-line interfaces instead of the graphical
interfaces provided. For more information about the accessibility of
particular features, refer to the documentation about those features.
Your feedback is important in helping to provide the most accurate and
high-quality information. If you have any comments about this book or
any other documentation about the Edge components of WebSphere Application
Server:
- Send your comments by e-mail to fsdoc@us.ibm.com. Be sure to include the
name of the book, the part number of the book, the version of WebSphere
Application Server, and, if applicable, the specific location of the text you
are commenting on (for example, a page number or table number).
This part provides an overview of the Caching Proxy component, instructions
for using the Configuration and Administration forms and Configuration Wizard,
instructions for manually editing the ibmproxy.conf file, and
procedures for starting and stopping the proxy server.
This part contains the following topics:
Overview
Using the Configuration and Administration forms
Using the Configuration Wizard
Manually editing the ibmproxy.conf file
Starting and stopping the Caching Proxy
The Caching Proxy intercepts data requests from a client, retrieves the
requested information from content-hosting machines, and delivers that content
back to the client. Most commonly, the requests are for documents
stored on Web server machines (also called origin servers or content hosts)
and delivered via the Hypertext Transfer Protocol (HTTP). However, you
can configure the Caching Proxy to handle other protocols, such as File
Transfer Protocol (FTP), and Gopher.
The Caching Proxy stores cacheable content in a local cache before
delivering it to the requester. Examples of cacheable content include
static Web pages and JavaServer Pages (JSP) with dynamically generated but
infrequently changing fragments. Caching enables the Caching Proxy to
satisfy subsequent requests for the same content by delivering it directly
from the local cache, which is much quicker than retrieving it again from the
content host.
The Caching Proxy comes with HTML forms that can be served to requesting
clients and used to configure the proxy server. These forms run CGI
programs that edit the local proxy server configuration file,
ibmproxy.conf. To use these forms, the proxy server must be
running and must be configured to pass the forms from the local directory
where they reside.
By default, Caching Proxy is installed with Pass directives included in the
ibmproxy.conf file that enable access to the Configuration and
Administration forms. When a client requests the default home page from
this proxy server, Frntpage.html is served. This page contains a
hypertext link to the Configuration and Administration forms start page,
wte.html.
The Configuration and Administration forms are protected and require client
authentication before they are served. For instructions on setting the
administrator's ID and password, refer to Setting the administrator password.
A Web browser used to access the Configuration and Administration forms
must support the following:
- HTML 4.0: All forms are written to the HTML
4.0 specification. Your Web browser must support HTML 4.0
and framesets.
- Java(TM) 1.1 and JavaScript: Applets are written
to the Java 1.1 specification. Your Web browser must support a
Java Virtual Machine that is Java 1.1 compliant. The applets are
incompatible with Java Virtual Machines compliant with the Java 2.0
specification. Both JavaScript and Java must be enabled.
- 256 colors: The workstation on which the Web browser runs
must support at least 256 colors.
To access the Configuration and Administration forms:
- Ensure that the proxy server is running. For instructions on
starting the proxy server, refer to Starting and stopping the Caching Proxy.
- Direct an HTTP browser to request your proxy server's home page
(Frntpage.html) or the Configuration and Administration start page
(wte.html).
- Note:
- This page depends on your proxy server's actual mapping rules and can
vary from the default pages shown in parentheses.
http://your.server.name[:port][/directory][/page.html]
where
- your.server.name is the full path name
of your host (for example,
http://www.ibm.com/).
- [:port] If your proxy server listens for administrative
requests on a port other than 80, include the port number after the server
name:
http://your.server.name:port
- [/directory] The addition of a directory within the
URL depends on the mapping rules.
- [/page.html] The HTML page needs to be
specified only if it is not listed as a welcome page. For information
on welcome pages, refer to Define default welcome pages.
- Click Configuration and Administration forms to get to the
server configuration forms. You are prompted for the administrator user
name and password. Type an authorized user name and password.
The Caching Proxy configuration client window opens.
- Note:
- The contents of the navigation frame on the left can take several seconds to
load after the main page is displayed.
- The navigation frame on the left shows the five major categories of
configuration forms:
- Proxy Configuration
- Cache Configuration
- Server Configuration
- Server Activity Monitor
- Plug-in Configuration
Click the triangular pointer at the left of a heading to expand the list
of configuration forms in that category. Click a form to open
it. The form shows the current configuration values (if any) in the
input fields; if you have not changed the configuration since
installation, these are default values.
- On any form, enter configuration information for that particular
function. Each form provides instructions to assist you in deciding
what changes to make. For further information, click the help icon, the
question mark (?) at the top of each form. It provides the
following links:
- Field help--Descriptions of the fields in each screen
panel
- How do I...--Detailed steps in using
the form to do specific tasks
- Index--An index of the help information
- After filling in a form, click Submit to update the server
configuration with the changes you made. The Submit button
is located below the input fields on each form. If you do not want to
make the changes you indicated on the form, click Reset, and the
fields on the form return to their original values.
- If you click Submit and your input is accepted, the following
message is displayed in the upper frame:
The requested configuration changes have been completed successfully
If the input is not accepted, an error message is displayed in the upper
frame, indicating which settings are not acceptable.
- To restart the proxy server, click the server restart icon (|)
in the upper frame. When the proxy server receives the restart command,
it stops accepting requests from clients but completes any requests that are
already in process. After reloading the changed configuration file, the
proxy starts accepting client requests again.
- Note:
- Changing certain directives either by using the Configuration and
Administration forms or by editing the ibmproxy.conf file requires that
instead of a restart, you stop the server completely and then start it again
before the changes can take effect. Those directives are listed in Table 6.
After installing the Caching Proxy packages, you must create an
administrator identification and password for accessing the Configuration and
Administration forms. The default proxy server configuration
authenticates users that request the Configuration and Administration forms by
using the webadmin.passwd passwords file in either the
/opt/ibm/edge/cp/server_root/protect/ directory on UNIX(R) systems or the
\Program Files\IBM\edge\cp\etc\ directory on Windows(R) systems.
Package installation does not overwrite an existing webadmin.passwd
file.
Use the following commands to add an administrator entry to the
webadmin.passwd file:
- On UNIX systems:
# htadm -adduser /opt/ibm/edge/cp/server_root/protect/webadmin.passwd
When prompted, provide the htadm program with a user name,
password, and real name for the administrator.
- On Windows systems:
cd "\Program Files\IBM\edge\cp\server_root\protect\"
htadm -adduser webadmin.passwd"
When prompted, provide the htadm program with a user name,
password, and real name for the administrator.
For a detailed description of the htadm command, refer to htadm command.
The Caching Proxy Configuration Wizard enables you to quickly configure an
installed Caching Proxy. This program sets only the essential
directives that are required to modify the behavior of the Caching Proxy to
function as a surrogate. The proxy server can require additional
configuration.
To use the Caching Proxy Configuration Wizard:
- Start the Configuration Wizard.
On Windows systems: click Start -> Programs -> IBM
WebSphere -> Edge Server -> Caching Proxy -> Configuration
Wizard.
On UNIX systems: enter the command
/opt/ibm/edge/cp/wizard/wsescfgwiz.
- Select the network port on which the proxy server will listen for HTTP
requests.
- Type the name of the target content server.
- Enter the user ID and password for the proxy server administrator.
Notes:
- The Configuration Wizard sets the following directives:
AdminPort 8008
Proxy /* http://content server :port
- If the Configuration Wizard is used to configure the proxy server, then to
enable SSL, a mapping rule must be created to proxy requests received through
port 443. For more information, refer to Define mapping rules.
Examples:
Proxy /* http://content server :443
or
Proxy /* https://content server :443
It is recommended that you use the Configuration and Administration forms
to configure the Caching Proxy, but you can also configure your proxy server
by editing the configuration file directly.
- On UNIX systems, the ibmproxy.conf file is located in the /etc/
directory.
- On Windows systems, the ibmproxy.conf file is located in
C:\Program Files\IBM\edge\cp\etc\en_US\.
The configuration file is made up of statements called directives.
To change your configuration, edit the configuration file by modifying the
directives, and save your changes. You can use almost any text editor,
such as emacs and vi, to edit the configuration file.
- Note:
- Do not use the text file editor that is included in the Solaris Common
Desktop Environment (CDE). The Solaris editor sometimes modifies the
file's owning group and changes properties of the file link so that the
Configuration and Administration forms cannot write to the configuration
file.
Your changes to the configuration file take effect when you restart the
server, unless you changed one of the directives identified in Table 6. If you changed one of the directives in that list,
you must stop the server and start it again. For instructions, see Starting and stopping the Caching Proxy.
Appendix B, Configuration file directives describes each of the configuration file directives and
gives details about syntax.
The Caching Proxy is designed to run continuously as a background process
with minimal operator intervention. Typically, the proxy server starts
during the boot cycle of the machine and is stopped only when maintenance is
required. The proxy server may be manually started when
necessary. The proxy server can also be passed a restart instruction,
which effectively stops then starts the proxy server without disrupting active
client connections.
On UNIX systems, an ibmproxy initialization script and
associated symbolic links are placed in the appropriate /etc/ directories when
the Caching Proxy is installed. These scripts are then integrated into
the startup and shutdown routines of the operating system. You can
change the configuration settings for automatic restart by editing the
ibmproxy script and changing the ibmproxy command
options.
- Note:
- Solaris file descriptor limit
It is possible that the Caching Proxy initialization script can fail to set
the desired maximum number of file descriptors due to the Solaris systemwide
limit on file descriptors. If the systemwide maximum is less than the
setting in the Caching Proxy initialization script, then the systemwide limit
is used. You can change the file descriptor limit to avoid proxy
performance problems that can result from too low a value (less than
1024). Issue the ulimit command to view the number of
descriptors that are currently available. If the value is less than
1024, increase the file descriptor limit. To increase the file
descriptor limit to 1024, add the following line to the /etc/system
file:
set rlim_fd_cur=0x400
Disabling automatic startup and shutdown
To disable automatic startup and shutdown:
- On AIX(R) systems, remove the ibmproxy command from the
initialization file.
- On Linux systems, remove the symbolic links to
/etc/rc.d/init.d/ibmproxy in the run level
subdirectories.
On SuSE Linux, remove the following links to ibmproxy:
- /etc/rc.d/rc3.d/S20ibmproxy
- /etc/rc.d/rc3.d/K20ibmproxy
- /etc/rc.d/rc4.d/S20ibmproxy
- /etc/rc.d/rc4.d/K20ibmproxy
- /etc/rc.d/rc5.d/S20ibmproxy
- /etc/rc.d/rc5.d/K20ibmproxy
On Red Hat Linux, remove the following links to ibmproxy:
- /etc/rc.d/rc0.d/K54ibmproxy
- /etc/rc.d/rc1.d/K54ibmproxy
- /etc/rc.d/rc2.d/K54ibmproxy
- /etc/rc.d/rc6.d/K54ibmproxy
- /etc/rc.d/rc3.d/S88ibmproxy
- /etc/rc.d/rc5.d/S88ibmproxy
- On Solaris systems, remove the ibmproxy start command and its
two kill scripts as follows:
- Delete S88ibmproxy from the /etc/rc2.d directory.
- Delete K54ibmproxy from the /etc/rc0.d directory.
- Delete K54ibmproxy from the /etc/rc1.d directory.
Regardless of the startup method, the ibmproxy command is
eventually invoked, either directly from the command prompt or from within a
script. For a detailed description of the ibmproxy command,
refer to ibmproxy command. Examples of only the most commonly used arguments
follow.
- To start the proxy server by running the initialization script, enter the
following at a root prompt:
/etc/rc.d/init.d/ibmproxy start
- To start the proxy server as a background process without running the
initialization script, enter the following at a root prompt:
/usr/sbin/ibmproxy
- To start the proxy server as a foreground process without running the
initialization script, enter the following at a root prompt:
/usr/sbin/ibmproxy -nobg
- To start the proxy server using a preexisting SQUID configuration file,
squidConfig.file, enter the following at a root prompt:
squidConfig.file -r /etc/errors_icons.conf
where the errors_icons.conf file identifies which icons
to use for designated file types when browsing directories.
If the Caching Proxy is installed as a Windows service, it is started like
any other Windows service:
- Click Start -> Settings -> Control Panel.
- In the Control Panel window, double-click
Services. (On Windows 2000, double-click Administrative
Tools -> Services.)
- In the Services window, highlight Caching
Proxy.
- Click Start to initiate the Caching Proxy service.
If the Caching Proxy is installed as a service, it can be configured to
start up automatically when Windows starts. In that case, you do not
have to log on before the proxy can serve requests. To have your proxy
start automatically:
- Click Start -> Settings -> Control Panel.
- In the Control Panel window, double-click
Services. (On Windows 2000, double-click Administrative
Tools -> Services.)
- In the Services window, highlight Caching
Proxy.
- Click the Automatic radio button, then click Start
to initiate the Caching Proxy service automatically when Windows
starts.
Refreshing the PATH environment variable
If the Caching Proxy is marked as Started in the
Services window, but the proxy is not working, the machine might
not have been restarted after the proxy was installed. If the Caching
Proxy service is set to interact with the desktop, failure to restart can also
cause the following error message to appear in a pop-up box:
Message catalog error: the message catalog could not be loaded or
is invalid
The machine must be restarted so that the value of the PATH environment
variable is refreshed in the Windows registry. If the registry is not
refreshed, it is possible for the PATH variable to show the correct Caching
Proxy and GSK4 paths but to function incorrectly.
- Note:
- A potential conflict exists for Windows systems when both the Caching Proxy
and another application, such as a network file system, run as
services. The Caching Proxy sometimes cannot interpret a path
containing a remote drive owned by a file system application that also is
running as a service.
The problem can occur if the path for the file system service appears
before the path for the Caching Proxy service in the Windows PATH environment
variable. Altering the PATH variable to put file system services near
the end of the setting can solve this problem.
This problem does not affect remote drives controlled by applications that
do not run as Windows services. For example, the Caching proxy can
access shared drives on other Windows machines that are visible through a
local area network (LAN).
When the Caching Proxy is installed as a Windows application, the
installation procedure creates a Caching Proxy entry as a submenu
of the Start menu. To start the Caching Proxy as an
application, click Start -> Programs -> IBM WebSphere
-> Edge Server -> Caching Proxy.
This startup procedure runs the proxy server with the current configuration
settings. If you want to specify other settings at startup time, use
the command startup procedure (see the next section).
To start the server from any Windows or DOS command prompt, use the
ibmproxy command. If you have not shut down and restarted
Windows since you installed the server, enter the full path name for this
command, as follows, (by default):
c:\Program Files\IBM\edge\cp\bin\ibmproxy.exe
The ibmproxy command starts the server with the current
configuration settings. If you have not changed the server
configuration since installation, the current configuration is based on the
information you entered during installation and on the default options.
The ibmproxy command starts the server as an application, even
if you have installed the Caching Proxy to run as a service. To force
the server to run as an application, you can also specify the command option
-noservice. Other command options change the configuration
settings at run time.
Multiple instances of the proxy server can run concurrently, but each
instance must listen on a separate port. On AIX systems, only one
instance can be started with SRC. Unique configuration files must be
specified for all instances of the server because the configuration file
identifies a port number, and this number must be different for each server on
a particular machine. To start an additional instance of the server
(when at least one is already running), enter the following command:
where other_config_file is a unique configuration file.
When starting multiple instances of the server, record the process ID that
is displayed for each instance. These IDs are required to stop specific
instances of the server.
- Note:
- On Linux systems running multiple instances of the server, the command
/etc/rc.d/init.d/ibmproxy stop stops only the last
server that was started. Other instances must be stopped
separately. Refer to Manual shutdown on UNIX systems for related information.
To stop the server:
- You must be either the user who started the process or the superuser
root.
- You must use the same method by which the server was started. The
following table lists start methods and their associated stop methods.
Table 2. Start and stop methods for UNIX systems
| Start method
| Stop method
|
| From /etc/inittab (On AIX)
| Enter stopsrc -s ibmproxy
|
| From /etc/rc.d/init.d (On Linux)
| Enter /etc/rc.d/init.d/ibmproxy stop
|
| ibmproxy
|
- Find the ibmproxy process ID: On AIX, enter ps -aef
| grep "ibmproxy". On Linux, enter ps -aux | grep ibmproxy |
grep server_ID. On Solaris, enter ps -ef | grep
"ibmproxy"
- Stop the ibmproxy process: Enter kill
process_id
To stop all servers on this machine: Enter killall
ibmproxy
|
| ibmproxy -nobg
| Enter ctrl-c
|
| ibmproxy -r -other_config_file(On AIX)
| Enter stopsrc -s ibmproxy -p process_id
|
| ibmproxy -r -other_config_file(On Linux)
|
- Find the ibmproxy process ID: Enter ps aux | grep
ibmproxy | grep process_id
- Stop the ibmproxy process: Enter kill
process_id
|
To stop the server at a root prompt, enter:
- On AIX: stopsrc -s ibmproxy
- On Linux: /etc/rc.d/init.d/ibmproxy stop
- On Solaris: /etc/init.d/ibmproxy stop
You can experience the following limitations when using the shutdown
commands:
- AIX and Linux
On AIX and Linux systems, the commands to stop the Caching Proxy system
sometimes shut down only the Caching Proxy process. The AIX command
that results in this behavior is the stopsrc -s ibmproxy
command. The Linux command that results in this behavior is the
ibmproxy -stop command.
The PACD process, which is used by the LDAP server, might be left running
after shutting down the proxy server. The PACD process can be safely
shut down by using the kill command as follows:
kill -15 PACD_process_ID
- Solaris
Issuing the ibmproxy -stop command on a Solaris system does not
have the same effect as the command does on other operating systems.
Because of a limitation in Solaris code, the Server Termination plug-in step
is not executed when ibmproxy -stop is used on Solaris
platforms.
This limitation has implications for the proxy server software as well as
for customer-implemented plug-ins.
It is possible for the PACD process, which is used by the LDAP server, to
continue running after the proxy server is shut down. The PACD process
can be safely shut down by using the kill command as follows:
kill -15 PACD_process_ID
You can stop the Caching Proxy server in the same ways that you stop other
Windows programs.
If the proxy is installed as a service:
- Click Start -> Settings -> Control Panel.
- In the Control Panel window, double-click
Services. (On Windows 2000, double-click Administrative
Tools -> Services.
- In the Services window, highlight Caching
Proxy.
- Click Stop to stop the Caching Proxy service.
If the proxy is not installed as a service, do any of the following to stop
the Caching Proxy:
- Click the x icon in the top right corner.
- From the File menu, click Exit.
- Press Alt + F4.
After changing the server configuration (by using the Configuration and
Administration forms or by editing the ibmproxy.conf file), you must
restart the server before the changes take effect. In most cases, you
can restart the server without stopping it first. But some settings are
not refreshed by a simple restart. For more information, see Table 6.
To restart the server without stopping it first, click the
Restart button on any Configuration and Administration form, or
enter the following command:
ibmproxy -restart
This part explains how the Caching Proxy component interacts with the
operating system, computer hardware, and network. It also provides
procedures for configuring this interaction. These elements of proxy
server configuration are typically managed by the system administrator and
must be carefully coordinated with network resources, such as IP addresses and
host names, as well as with system resources, such as available memory and CPU
cycles.
This part contains the following topics:
Define the server
Establish process ownership
Manage connections
Tune the proxy server process
The Caching Proxy typically runs as a background process on a host computer
system that is configured to perform as a network server. This process
is associated with (bound to) one or all active Internet Protocol
(IP) addresses on the host computer system. It listens for various
Internet protocols, such as FTP and HTTP, on specified ports and performs
actions on these requests in accordance with its behavioral
configuration. (For more information, refer to Configuring Caching Proxy behavior.)
By default, the Caching Proxy assumes the name of its host computer
system. You can override this default behavior by deliberately
specifying a host name for the proxy server. In order to bind the
Caching Proxy to a specific IP address, the host name of the proxy server must
be changed to equal that IP address.
- Note:
- In the event that the proxy server attempts to bind to an IP address, and
that host name is not set to an available IP address, the bind will fail and
the proxy server will listen on all available IP addresses.
Regardless of which IP address a proxy server is bound to, only one process
can listen on a specific port at one time. In other words, each port
number is associated with the host computer system, not to the IP
address; therefore you cannot run two proxy servers on the same machine,
each bound to a different IP address but both listening for HTTP traffic on
port 80.
The host name of the proxy server does not affect how client traffic is
resolved. The proxy server does not compare its own host name with the
value of the host name argument in the header of the HTTP request. The
proxy server does not support name-based or IP-based virtual hosting.
However, mapping rules can be written to create a port-based virtual hosting
environment. The host name of the proxy server is occasionally
incorporated into dynamically generated local content pages, such as error
messages. It is also passed backed to the requested client as the value
of the Via argument in the HTTP header.
The proxy server can be configured to replace the host name of the
requesting client with the host name of the proxy server prior to passing the
request on to the destination server. Doing so forces the destination
server to maintain the communication channel through the proxy server, rather
than establishing a direct connection with the client.
Define the proxy server process by specifying the physical location of the
proxy server files on the host computer system, the name with which proxy
server refers to itself, and the ports on which it listens as values for the
ServerRoot, Hostname, and
Port directives. If the host has multiple IP
addresses, the proxy server can be bound to a specific address by setting the
value of the BindSpecific directive to on and setting
the value of the Hostname directive equal to the IP address.
An administration port provides a method of accessing the Configuration and
Administration forms and maintaining the server. To provide access to
the proxy server through an administration port, specify a value for the AdminPort directive. Requests received on the
administration port are not queued with requests received on the standard
port. Mapping rules can be written to allow access to the Configuration
and Administration forms through this port.
To override the default name of the server that is running, such as
IBM-PROXY or IBM_HTTP_SERVER, specify a value for HeaderServerName directive. This value
populates the HTTP response server field.
To improve proxy performance, the value of the PureProxy directive can be set to on. This
completely disables all caching functionality.
The following directives define the proxy server process:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration forms edit the values of the
associated directives:
- Server Configuration -> Basic Settings -> Host name
- Server Configuration -> Basic Settings -> Server
root
- Server Configuration -> Basic Settings -> Default port
number(s)
- Server Configuration -> Basic Settings -> Administrator
port number
- Server Configuration -> Basic Settings -> Bind
options
- Proxy Configuration -> Proxy Performance -> Run as pure
proxy
- Note:
- You cannot use the Configuration and Administration forms to edit the
HeaderServerName directive.
For more information, refer to Using the Configuration and Administration forms.
When a user other than the superuser root starts the Caching Proxy, that
user maintains ownership of all of the processes associated with the proxy
server. However, if the Caching Proxy is started by the superuser root,
a set user ID function within the proxy server reads the UserId and GroupId
directives in the ibmproxy.conf file and changes process ownership to
the specified user and group. This is done to limit file access and
protect the computer system. If you change the UserId or GroupId
directives, you must update the ownership and permissions for log directories
and other files, such as an access control list (ACL), that are used by the
proxy server.
- Note:
- On Linux systems, only processes and threads responsible for listening for
connections will have their ownership changed. Processes and threads
responsible for other activities within the workflow will still be owned by
root. All processes and threads receive process ID (PID)
numbers. The ps command lists all process IDs, regardless of
whether they are associated with a process or thread.
Establish the ownership of the proxy server process by specifying the user
identification, group identification, and location of the file in which the
process ID is recorded as values for the UserID, GroupID, and PidFile
directives.
To force the proxy server process to run as foreground process, set the
value of the NoBG directive to on.
The following directives establish proxy server process ownership:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration forms edit the values of the
associated directives:
- Server Configuration -> Basic Settings -> UserID
- Server Configuration -> Basic Settings -> GroupID
- Server Configuration -> Basic Settings -> Process ID file
location
- Note:
- You cannot use the Configuration and Administration forms to edit the NoBG
directive.
For more information, refer to Using the Configuration and Administration forms.
The Caching Proxy spawns a new thread to handle each client request.
If no threads are available, the proxy server holds requests until more
threads become available. As the number of active threads increases,
the proxy server consumes more memory. Specify the maximum number of
active threads as the value for the MaxActiveThreads directive.
The listen backlog is the number of pending requests for client connections
that the server logs before it refuses connections with new clients.
Base this setting on the number of requests that the server can process in a
few seconds. A server must respond to a client connection before it
times out. Specify the maximum number of connections that can be held
in the backlog as the value for the ListenBacklog directive.
The proxy server can maintain persistent client/server connections.
With a persistent connection, the server accepts multiple requests from the
client and sends responses over the same TCP/IP connection. Using
persistent connections reduces latency for clients and lowers the CPU load on
the proxy server, at the low cost of a small increase in server memory.
Overall throughput is increased when the server does not establish a separate
TCP/IP connection for each request and response, and the TCP/IP connection can
be used with greatest efficiency when the connection is persistent.
Server-side connection pooling applies the benefits of persistent
connections on the server side by allowing the reuse of existing connections
between a proxy server and the origin servers. Each reused connection
saves three TCP packets (two three-way handshake packets to set up the
connection, and one to close it). The benefits of server-side
connection pooling include:
- Less network congestion (by minimizing the opening and closing of
connections)
- Less CPU time used in routers, clients, and servers
- Less memory used on clients and servers
- On cache misses, quicker proxy response (by avoiding opening and closing
connections)
- Note:
- Connection pooling is recommended only in a controlled environment. It
can degrade performance where the origin servers are not HTTP 1.1
compliant. Note also that it is critical that the origin servers are
set up properly. The following is a simple example from the Apache
1.3.19 configuration file:
- #KeepAlive: Whether or not to allow persistent connections
(more than one request per #connection). Set to Off to
deactivate#
- KeepAlive On
- #MaxKeepAliveRequests: The maximum number of requests to allow
during a persistent connection. Set to 0 to allow an unlimited
amount. Leave this number high for maximum performance#
- Max KeepAliveRequests 0
- #KeepAliveTimeout: Number of seconds to wait for the next
request from the same client on the same connection#
- KeepAliveTimeout 240
These settings keep connections to the Web servers open as long as they
are being used and allow the proxy, rather than the origin server, to manage
the connections. Therefore, the connections are pooled only to the
extent needed.
When server-side connection pooling is enabled, HTTP connections to the
origin servers are pooled. SSL connections are also pooled in
configurations where the SSLEnable directive for the proxy is set to
on.
Configure how connection pooling is maintained by specifying the maximum
number of idle sockets to hold per server at any one time, how long the server
waits before terminating an idle persistent connection, and the time interval
at which the garbage collection thread checks for timed-out connections (the
default is two minutes).
Define the amount of time that various connections remain open as values
for the InputTimeout, OutputTimeout, PersistTimeout, ReadTimeout, and
ScriptTimeout directives.
The following directives manage connections with the proxy server
process:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration forms edit the values of the
associated directives:
- Server Configuration -> System Management -> Performance
-> Maximum number of active threads
- Server Configuration -> System Management -> Performance
-> Size of listen backlog
- Proxy Configuration -> Proxy Performance -> Allow
persistent connections
- Server Configuration -> System Management -> Performance
-> Maximum Requests
- Server Configuration -> System Management -> Performance
-> Persist timeout
- Server Configuration -> System Management -> Timeouts
-> Input timeout
- Server Configuration -> System Management -> Timeouts
-> Read timeout
- Server Configuration -> System Management -> Timeouts
-> Output timeout
- Server Configuration -> System Management -> Timeouts
-> Script timeout
- Server Configuration -> System Management -> Timeouts
-> Persist timeout
Notes:
- You cannot use the Configuration and Administration forms to edit the
ServerConnPool, MaxsocketPerServer, ServerConnTimeout, or ServerConnGCRun
directives.
- The PersistTimeout can be edited from either the Server Configuration
-> System Management -> Performance form or the Server
Configuration -> System Management -> Timeouts form.
For more information, refer to Using the Configuration and Administration forms.
You can noticeably improve the performance of the Caching Proxy by properly
setting up and tuning the system. The following are suggestions for
improving setup and tuning.
The following directives significantly affect the performance of the proxy
server process:
- PureProxy -- Disable a dedicated proxy. This feature improves system performance by
completely disabling caching.
- ProxyPersistence -- Allow persistent connections. This feature enables clients and servers to maintain
open connections. Persistent connections decrease the lag time for
requests for documents from the proxy server, but require increased network
bandwidth as well as a dedicated server thread for each connection. Do
not allow persistent connections if your setup limits the number of available
threads.
The following Configuration and Administration form fields edit the values
of the associated directives:
- Proxy Configuration -> Proxy Performance: Run as a pure
proxy
- Proxy Configuration -> Proxy Performance: Allow
persistent connections
Examine the services or daemons that are running on your system and remove
those that are not required to increase available memory and CPU
cycles. For example, if your system is running a Web server that serves
only a few Web pages, consider using the Caching Proxy as your only Web
server. Disable other Web servers as follows:
- On AIX: Examine /etc/inittab
- On Linux: Examine /etc/rc.d/rcx.d for your
system's default run level (typically 2)
- On Solaris: Examine /etc/rcx.d for your
system's default run level (typically 2).
- On Windows systems:
- Click Start -> Settings -> Control Panel ->
Services. (On Windows 2000, click Control Panel ->
Administrative Tools -> Services).
- Review services that are not required but are set to
Automatic.
- Change the startup type for those services from Automatic to
Manual.
Ensure that your system has sufficient paging space for proper
operation. The system needs twice as much paging space as physical
memory. If possible, spread the paging space across multiple physical
drives. For example, a Netfinity(R) 5000 server with 512 MB of
memory and five SCSI drives needs 1 GB of total paging space with
approximately 200 MB on each drive.
The Caching Proxy creates and destroys many files during its
operation. If your proxy server records accesses (using the access log,
proxy access log, or cache access log), direct the logs to their own file
system so that if the logs grow unexpectedly, they do not use space intended
for another function (such as the cache).
The Caching Proxy is sensitive to changes to TCP/IP configurations.
Lowering the TCP/IP values on any operating system might cause the proxy
server to perform in an unexpected manner. More specifically, if the
TCP/IP values are set too low, connections might be reset by clients that
connect to the proxy server or by origin servers to which the proxy
connect. This is especially true for clients that connect to the proxy
server through a low bandwidth connection (56700 bps or lower). If
TCP/IP parameters must be lowered, proceed with caution.
The TCP time wait interval specifies the length of time that a socket waits
for a FIN packet from the sender before forcibly closing. In high-load
environments, the proxy server may appear to stall if a large number of
sockets remain suspended in the TIME_WAIT state after their connections are
closed. Reducing the TCP time wait interval will reduce the number of
suspended sockets and, in high-load environments, may prevent the proxy server
from appearing to stall. It is recommended that this interval be set to
5 seconds.
To set the TCP time wait interval to 5 seconds:
- On Linux:
Issue the following commands:
echo "1024 61000" > /proc/sys/net/ipv4/ip_local_port_range
echo "5" > /proc/sys/net/ipv4/tcp_fin_timeout
- On Solaris 7 and 8:
Issue the following command:
ndd /dev/tcp -set tcp_time_wait_interval 5000
Edit the /etc/system file to read as follows::
set tcp:tcp_conn_hash_size=8129
- On Windows:
A registry entry must be created set a TCP time wait interval. Refer
to your Windows documentation for more information.
Several limits in the Linux kernel are low and can be modified. Some
can be changed through the /proc file system, and others require recompiling
the kernel.
Note: The /proc file system is virtual; that is, it does not
exist physically on the disk. Instead, it serves as an interface into
the Linux kernel. Because it does not exist, your input values are lost
on restart. Therefore, place changes that you want to make to the /proc
file system in the /etc/rc.d/rc.local file on RedHat or in the
/etc/rc.config file on SuSE. Changes are then always activated
at restart.
Some recommendations follow:
- The file descriptor maximum is 4096 by default. It can be changed
by adding the following to the rc.local file:
echo 32768 > /proc/sys/fs/file-max
- The inode maximum is 16384 by default. It can be changed by adding
the following to the rc.local file:
echo 65536 > /proc/sys/fs/inode-max
- The TCP and UDP port range is by default 1024 - 4999. This
can be changed to 32768 - 61000 by adding the following to the
rc.local file:
echo 32768 61000 > /proc/sys/net/ipv4/ip_local_port_range
- By default, the number of allowed tasks is 512. If too many tasks
are running, this affects the maximum number of threads for a process.
This limit can be increased to 2048 by modifying the value for NR_TASKS in the
YourKernelSource/include/linux/tasks.h file.
- In addition, change the value of MIN_TASKS_LEFT_FOR_ROOT to 24. You
must recompile your kernel for this change to take effect.
If you decide to rebuild your kernel, enable only those options that you
definitely need. If you do not need a specific daemon, do not run
it.
This part explains how the Caching Proxy component responds to client
requests and provides procedures for configuring this behavior. These
elements of proxy server configuration are typically managed by a Web
administrator and do not affect other processes on the host computer system or
other computer systems within the network.
This part contains the following topics:
Manage request processing
Manage delivery of local content
Manage FTP connections
Customize server processing
Configure header options
About the application programming interface
When the Caching Proxy receives a client request, it performs the action
specified in the method field on the object specified in the URL field, if the
requested method has been enabled. The proxy server resolves the URL
according to a set of mapping rules defined by the administrator. These
mapping rules might instruct the Caching Proxy to act as a Web server and
retrieve the object from the local file system or to act as a proxy server and
retrieve the object from an origin server.
This topic describes how to enable methods, define mapping rules, and configure a
surrogate proxy server.
Client requests to the server include a method field that indicates the
action that the server is to perform on the specified object.
Following is a list of methods that the proxy server supports and a
description of how it responds to a client request containing the method if
the method is enabled.
- Note:
- Some methods are the same for HTTP and for FTP requests. Enabling
these methods for HTTP also enables them for FTP.
- DELETE
- The proxy server deletes the object identified by the URL. DELETE
allows clients to erase files from your Caching Proxy. Use server
protection setups to define who can use DELETE and on which files. For
details, see Server protection setups.
- GET
- The proxy server returns whatever data is identified by the URL. If
the URL refers to an executable program, the proxy returns the output of the
program. This method can be handled over persistent connections.
- HEAD
- The proxy server returns only the HTTP document header identified by the
URL without the document body.
- OPTIONS
- The proxy server returns information about the communications options on
the request-response chain identified by the URL. This method allows a
client to determine the options and requirements associated with an object, or
the capabilities of a server, without having to act on or retrieve the
object.
- POST
- The request contains data and a URL. The proxy server accepts the
data enclosed in the request as a new subordinate of the resource identified
in the URL, which processes the data. The resource can be a
data-accepting program, a gateway to some other protocol, or a separate
program that accepts annotations.
The POST method is designed to handle the annotation of existing
resources. Examples include posting a message to a bulletin board,
newsgroup, mailing list, or similar group of resources; providing a block
of data, for example, from a form to a data-handling program; or
extending a database through an append operation. In the
Caching Proxy itself, the POST method is used to process the Configuration and
Administration forms.
This method can be handled over persistent connections.
- PUT
- The request contains data and a URL. The proxy server stores the
data in the resource identified in the URL. If the resource already
exists, PUT replaces it with the data contained in the request. If the
resource does not exist, PUT creates it and populates it with the data
contained in the request. This method can be handled over persistent
connections.
Enabling the PUT method allows files to be written to the Caching Proxy by
using HTTP and FTP. Because PUT allows clients to write to the Caching
Proxy, you need to use server-protection setups to define who can use PUT and
the files on which PUT can be used. (See Server protection setups.)
- TRACE
- The proxy server echoes the request message sent by the client.
This method allows the client to see what is being received at the other end
of the request chain and use that data for testing or diagnostics. The
content type of the proxy response is message/http.
The following directives enable HTTP/FTP methods:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration forms edit the values of the
associated directives:
- Server Configuration -> Request Processing -> HTTP
Methods -> GET
- Server Configuration -> Request Processing -> HTTP
Methods -> HEAD
- Server Configuration -> Request Processing -> HTTP
Methods -> POST
- Server Configuration -> Request Processing -> HTTP
Methods -> PUT
- Server Configuration -> Request Processing -> HTTP
Methods -> DELETE
- Server Configuration -> Request Processing -> HTTP
Methods -> OPTIONS
- Server Configuration -> Request Processing -> HTTP
Methods -> TRACE
- Note:
- If you disable the POST method, you cannot use the Configuration and
Administration forms to configure the Caching Proxy.
For more information, refer to Using the Configuration and Administration forms.
Mapping rules are configuration directives that cause client requests to
the Caching Proxy to be processed in some way, for example, passed to an
origin server (proxied), redirected, or rejected. Setting mapping rules
correctly is important to the proper functioning of your Caching Proxy.
Mapping rules affect the following:
- Basic proxy function
- Access to the browser-based Configuration and Administration forms
- Ability to cache servlet results and other dynamically generated content
Mapping rule directives use the following form:
rule template target [IP_address | host_name]:[port]
Only requests that match the given template and IP-port combination are
subject to that rule. A template can contain wildcards, for example,
https://**/*.asp.
The order in which the rules appear in the configuration file is
significant. Except for Map directives, as soon as the request is
matched to a template, it is processed and subsequent rules are not
evaluated. The Map directive replaces the URL in the request.
This new request continues to be compared to the remaining mapping
rules.
The following mapping rules apply to client requests that match the given
template:
- Map -- rewrite the request. The Map rule replaces a
request URL (template) with another URL string (target). After this
substitution, the request, containing the new string, continues to be compared
to the remaining mapping rules.
- Pass, Exec -- serve the request locally. The Pass
and Exec rules process the request at the proxy server. The Pass rule
maps a request URL (template) to a file that is served from the proxy server
(target); the Exec rule maps a request URL to a CGI program that runs on
the proxy server.
- Fail -- reject the request. The Fail rule rejects a
request (template) at the proxy server. Any request that matches the
template of a Fail rule is not processed further. Fail rules do not
have target arguments.
- Redirect -- forward the request. The Redirect rule
forwards a request (template) to another Web server (target). Because a
full URL, including the communication protocol, is the target of this rule, it
is possible to change the protocol during this redirection, for example, to
add SSL encryption to an HTTP request. A redirection does not check the
cache prior to satisfying the request.
- Proxy, ProxyWAS -- proxy the request. The Proxy and
ProxyWAS rules pass requests (templates) to another server (target).
Unlike a simple Redirect rule, the Proxy rules allow the proxy server to check
the cache to satisfy a request, to cache content from origin servers, and to
write HTTP headers that enable advanced functions. Use the ProxyWAS
rule instead of the Proxy rule when the origin server is a WebSphere
Application Server.
The following mapping rule applies to the origin server response:
- ReversePass -- intercept automatically redirected
requests. A ReversePass rule matches the response from the origin
server to the template as it passes through the proxy server on its way to the
client. The ReversePass directive is designed to detect a redirection
status code that would cause a client to directly contact the origin
server. The client is instructed to contact the server defined in the
target argument.
The following mapping rules apply to API applications:
- nameTrans -- accepts the request and runs an API
application, defined by the replacement file path, during the Name Translation
step of request processing.
- service -- accepts the request and runs an API
application, defined by the replacement file path, during the Service step of
request processing.
To configure a standard surrogate:
This allows all HTTP traffic on port 80 to be proxied to the origin
server. Traffic entering on the administration port does not match the
initial wildcard proxy rule, and so it is unaffected. The remaining
mapping rules are used to process the request.
The following directives define mapping rules:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration form edits the values of the
associated directives:
- Server Configuration -> Request Processing -> Request
Routing
- Note:
- The Configuration and Administration forms do not support the port number
argument.
For more information, refer to Using the Configuration and Administration forms.
This directive enables the junction rewriting routine within the Caching
Proxy to rewrite responses from origin servers to ensure that server relative
URLs get mapped to the appropriate origin server when junctions are
used. The junction rewriting plug-in must also be enabled.
Junctions are defined by the proxy mapping rules.
The following are examples of valid junctions that can be acted upon by the
junction rewriting routine:
- Proxy /shop/* http://shopserver.acme.com/*
- Proxy /auth/* http://authserver.acme.com/*
- Proxy /market/partners/*
http://b2bserver.acme.com/*
The following is an example of a valid junction that will not be acted upon
by the junction rewriting routine:
- Proxy /* http://defaultserver.acme.com/*
The following are examples of invalid junctions:
- Proxy /images/*.gif
http://imageserver.acme.com/images/*.gif
- Proxy /cgi-bin/*
http://cgiserver.acme.com/cgi/perl/*
These mapping rules have created junctions for shopserver, authserver, and
b2bserver. Consider that shopserver returns an HTML document with the
following URLs contained within appropriate HTML tags:
- /index.html (server relative reference)
- /images/shop.gif (server relative reference)
- buy/buy.jsp (directory relative reference)
- http://ebay.com (absolute reference)
The junction rewriting routine will rewrite the server relative references
using the proxy mapping rules as follows:
- /shop/index.html (changed)
- /shop/images/shop.gif (changed)
- buy/buy.jsp (unchanged)
- http://ebay.com (unchanged)
The junction rewriting routine affects the following tags:
Table 3. Tags affected by the junction rewriting routine
| Tag
| Attributes
|
| !--
| URL
|
| a
| href
|
| applet
| archive, codebase
|
| area
| href
|
| base
| href
|
| body
| background
|
| del
| cite
|
| embed
| pluginspage
|
| form
| action
|
| input
| src
|
| frame
| src, longdesc
|
| iframe
| src, longdesc
|
| ilayer
| src, background
|
| img
| src, usemap, lowsrc, longdesc, dynsrc
|
| layer
| src, background
|
| link
| href
|
| meta
| url
|
| object
| data, classid, codebase, codepage
|
| script
| src
|
| table
| background
|
| td
| background
|
| th
| background
|
| tr
| background
|
- Note:
- The junction rewriting routine will not affect tags generated by JavaScript
or by plug-ins within the browser.
The following directives are used to enable the junction rewriting routine
and plug-in.
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration form can be used to enable
the junction rewriting plug-in:
- Server Configuration -> Request Processing -> API Request
Processing
- Note:
- The Configuration and Administration forms do not support the JunctionRewrite
directive.
For more information, refer to Using the Configuration and Administration forms.
The Pass and Exec mapping rules are used to deliver local content to a
requesting client. By default, a Pass rule with a wildcard template is
placed as the last mapping rule. This rule directs all requests that do
not match previous templates to retrieve files from a target directory, which
is commonly referred to as the document root directory.
When a URL is received that does not contain a file name, the Caching Proxy
satisfies the request by searching the specified directory, if one is given,
or the document root directory, if no directory is specified, for a file that
matches the list of welcome pages specified in the configuration file.
If more than welcome page is defined, the proxy server searches for the pages
in the order in which they are defined. The first welcome page found is
served.
The server home page is the Web page that the server delivers by default
when it receives a request that contains only the server's URL without a
directory or file name. As previously explained, the default wildcard
mapping rule requires that the server home page is stored in the document root
directory and that the filename of the home page matches a defined welcome
page.
- Note:
- Some Web browsers use the term home page to refer to the first
page the browser loads when it is started. This document uses the term
only for the server home page.
This topic describes how to define the document root
directory and welcome pages.
The default document root directories are:
- On UNIX: /opt/ibm/edge/cp/server_root/pub/lang/
- On Windows: drive:\Program
Files\IBM\edge\cp\server_root\pub\lang\, or the directory you
speci