This edition applies to:
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.
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.
| 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 Linux(TM) and UNIX(R) command-shell prompt for a command that does not require root privileges. |
| # | Represents the Linux and UNIX command-shell prompt for a command that requires root privileges. |
| C:\ | Represents the Windows(R) 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(R) Application Server, Version 6.0:
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:
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:
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 Administration Guide includes new features, new supported platforms, and corrective updates for Version 6.0 as well as for post-V5.0 releases (5.0.1, 5.0.2, 5.1, and 5.1.1). The most significant of these new features (for V6.0 and post-V5.0) are listed here.
In addition to support for running Caching Proxy on Linux for Intel, the proxy now runs on Linux for S/390, zSeries, iSeries and pSeries.
In addition to AIX 5.1, Caching Proxy now supports AIX 5.2 and AIX 5.3.
In addition to Solaris 8, Caching Proxy now supports Solaris 9.
In addition to Windows 2000, Caching Proxy now supports Windows Server 2003.
In addition to support for AIX, Linux, Solaris, and Windows systems, Caching Proxy now supports HP-UX.
A new version of the 32-bit JDK is now supported: JDK 1.4.2.
A new version of the GSKit is provided and installed by default with Caching Proxy: GSKit 7.
There are enhancement and new directives related to junction rewriting. For more information, see:
Also provided is an alternative to using the JunctionRewrite plugin. For more information, see:
The following new directives are supported:
There are enhancements to the following existing directives:
For JunctionRewrite, sample code that can be customized is now provided which rewrites/parses JavaScript (SCRIPT) and applet (APPLET) tag blocks in HTML files. (On its own, the JunctionRewrite plugin cannot process the resource links in JavaScript or in parameter values of Java. For more information, see Sample transmogrifier plugin to extend JunctionRewrite functionality.
To enable anonymous binding, see Creating pac_ldap.cred.
For an SSL connection between a proxy and an LDAP server, put the key database password in the pac_keyring.pwd file. See Creating a new key database, password, and stash file.
In the configuration file (ibmproxy.conf), changes to default settings were made in order to provide greater security. For example, changes were made to disable HTTP CONNECTION and disable SSL tunneling. There are no new directives for this enhancement.
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:
Recommended browsers are Mozilla 1.4 (for Linux and UNIX systems) or Internet Explorer (for Windows systems). Refer to Concepts, Planning, and Installation for Edge Components for additional browser related information for viewing Configuration and Administration forms.
To access the Configuration and Administration forms:
http://your.server.name[:port][/directory][/page.html]where
The requested configuration changes have been completed successfullyIf the input is not accepted, an error message is displayed in the upper frame, indicating which settings are not acceptable.
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 Linux and UNIX systems or the \Program Files\IBM\edge\cp\etc\ directory on Windows 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:
# htadm -adduser /opt/ibm/edge/cp/server_root/protect/webadmin.passwdWhen prompted, provide the htadm program with a user name, password, and real name for the administrator.
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:
On Windows systems: click Start -> Programs -> IBM WebSphere -> Edge Components -> Caching Proxy -> Configuration Wizard.
On Linux and UNIX systems: enter the command /opt/ibm/edge/cp/cpwizard/cpwizard.sh
Port port Proxy /* http://content server :port
Examples:
Proxy /* http://content server :443
or
Proxy /* https://content server :443
Limitations: On Linux systems, keyboard shortcuts do not work for the Caching Proxy Configuration Wizard.
Caching Proxy can be configured manually, editing the ibmproxy configuration file, or via the Configuration and Administration forms.
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.
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 Linux and 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.
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 SuSE Linux, remove the following links to ibmproxy:
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.
startsrc -s ibmproxy
startsrc -s ibmproxy -e "LC_ALL=locale"
ibmproxy
/sbin/init.d/ibmproxy start
/usr/sbin/ibmproxy
/usr/sbin/ibmproxy -nobg
/etc/rc.d/init.d/ibmproxy start
/usr/sbin/ibmproxy
/usr/sbin/ibmproxy -nobg
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.
/etc/init.d/ibmproxy start
/usr/sbin/ibmproxy
/usr/sbin/ibmproxy -nobg
If the Caching Proxy is installed as a Windows service, it is started like any other Windows 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:
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 GSK7 paths but to function incorrectly.
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 Components -> 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:
ibmproxy -r other_config_fileibmproxy -noservice -r other_config_filewhere 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.
To stop the server:
| Start method | Stop method |
| From /etc/inittab (On AIX) | Enter stopsrc -s ibmproxy |
| From /sbin/init.d (On HP-UX) | Enter /sbin/init.d/ibmproxy stop |
| From /etc/rc.d/init.d (On Linux) | Enter /etc/rc.d/init.d/ibmproxy stop |
| ibmproxy |
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) |
|
To stop the server at a root prompt, enter:
You can experience the following limitations when using the shutdown commands:
On AIX, HP-UX, 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 HP-UX and 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
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:
If the proxy is not installed as a service, do any of the following to stop the Caching Proxy:
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 type the following: 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:
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.
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 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.
When the BindSpecific directive is enabled, Caching Proxy is bound to the port specified by the Port directive along with the IP address derived from the value of the Hostname directive. The port specified by the AdminPort directive is bound to all IP addresses available on the system.
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:
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.
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:
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:
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:
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:
The following Configuration and Administration form fields edit the values of the associated directives:
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:
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 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:
Issue the following command:
ndd /dev/tcp -set tcp_time_wait_interval 5000
Use the "sam" utility to set the kernel parameter max_thread_proc to at least 2048.
Issue the following commands:
echo "1024 61000" > /proc/sys/net/ipv4/ip_local_port_range echo "5" > /proc/sys/net/ipv4/tcp_fin_timeout
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
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:
echo 32768 > /proc/sys/fs/file-max
echo 65536 > /proc/sys/fs/inode-max
echo 32768 61000 > /proc/sys/net/ipv4/ip_local_port_range
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.
On AIX systems, Caching Proxy performance can be improved by using system scope threads and allowing multiple heaps to be used by threads. Performance is related to the operating system's multiprocessing ability and the thread scheduling of the underlying operating system. Performance improvement can be achieved by setting the following AIX thread tuning variables as follows:
export AIXTHREAD_SCOPE=S export SPINLOOPTIME=500 export YIELDLOOPTIME=100 export MALLOCMULTIHEAP=1
You can set these environment variables either before starting /usr/sbin/ibmproxy, or you can add them to /etc/rc.ibmproxy if using startsrc -s ibmproxy to start the proxy server. After adjusting these thread tuning variables, performance improvement will be more evident on SMP systems. However, in some cases, improvement may also be evident on uniprocessor systems.
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 delivery of local content
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.
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.
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.)
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:
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:
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:
The following mapping rule applies to the origin server response:
The following mapping rules apply to API applications:
To configure a standard surrogate:
Port 80
Proxy /* http://our.content.server.com/* :80
AdminPort 8080
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:
For more information, refer to Using the Configuration and Administration forms.
The JunctionRewrite 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.
When using the proxy mapping rules to define the junction, you can use the Proxy directive with or without the JunctionPrefix option.
The following are examples of valid junctions that can be acted upon by the junction rewriting routine:
The following is an example of a valid junction that will not be acted upon by the junction rewriting routine:
The following are examples of invalid junctions:
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:
The junction rewriting routine will rewrite the server relative references using the proxy mapping rules as follows:
When using the JunctionPrefix option with the Proxy directive, instead of inferring the JunctionPrefix from the first URL pattern in the Proxy rule, you can declare the junction prefix in the Proxy rule using the following format:
Proxy url_patern1 url_pattern2 JunctionPrefix:url_prefix
When using JunctionPrefix there is no limitation on the format of the first URL pattern. In order to support junction rewriting when not using the JunctionPrefix option, the proxy URL must have the following format: Proxy /market/* http://b2bserver/*. However, when using JunctionPrefix, the following Proxy rule is valid for junction rewriting:
Proxy /market/partners/*.html http://b2bserver.acme.com/*.html
junctionprefix:/market/partners
The junction rewriting routine affects the following tags:
| 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 |
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:
For more information, refer to Using the Configuration and Administration forms.
You can use cookies to store back-end server information as follows: A cookie is sent to the client browser. When the browser sends requests for the resources in the HTML page, it attaches a cookie so that Caching Proxy forwards the requests to the correct back-end server.
To use cookies as an alternative to JunctionRewrite, make the following modifications to the ibmproxy.conf file:
The following is a comparison of the JunctionRewrite plugin and the cookie implementation.
Proxy /no-juntion.jpg http://login-server/no-junction.jpg
Customizable sample code is provided that rewrites and parses JavaScript(TM) (SCRIPT) and applet (APPLET) tag blocks in HTML files. Alone, the JunctionRewrite plugin cannot process the resource links in JavaScript or in parameter values of Java(TM).
After installing Caching Proxy, you can compile the same code and configure it to run with JunctionRewrite.
The following sample files are located in the ...samples/cp/ subdirectory, under the directory in which you downloaded the fix pack.
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.
This topic describes how to define the document root directory and welcome pages.
The default document root directories are:
The following directive defines the document root directory:
For more information, refer to Manually editing the ibmproxy.conf file.
To change the document root directory in the Configuration and Administration forms, use the following procedure:
After restarting, the server begins to use the new document root directory.
For more information, refer to Using the Configuration and Administration forms.
The server looks for the home page in the document root directory, but the specific file it returns is defined by the list of welcome pages.
About welcome pages
When the server receives a URL request that does not specify a file name, it tries to satisfy the request according to a list of welcome pages set in the server's configuration file. This list defines files to use as default home pages. The server determines your home page by matching the list of welcome pages to the files in the document root directory. The first match it finds is the file returned as your home page. If no match is found, the server displays a listing of the document root directory.
To have a particular file used as your server's home page and returned when a request does not specify either a directory or file name, you must put the file in the document root directory and also make sure that its name matches one of the file names listed in the list of welcome pages.
The default configuration file defines these file names, in this order, to be used as welcome pages:
The server returns the first file it finds that matches a file name in the list. Until you create a welcome.html or index.html file and place that file in the document root directory, the server uses Frntpage.html as your home page.
For example, if you are using the default configuration and your document root directory does not contain a file named welcome.html, but does contain files named index.html and FrntPage.html, the index.html file is used as your home page.
If no home page is found, the contents of the document root directory are displayed as a directory.
The following directive defines the welcome pages:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration form defines the welcome pages:
For more information, refer to Using the Configuration and Administration forms.
The Caching Proxy proxies requests for FTP URLs to the appropriate FTP server, but it cannot be used to proxy requests from an FTP client. It can support only those FTP requests received from an HTTP client (using the ftp:// protocol scheme).
Only the GET, PUT, and DELETE methods are supported for requests for FTP files. Only the GET method is supported for requests for FTP directory listings. By default, PUT and DELETE are disabled in the Caching Proxy. For more information, refer to Enable HTTP/FTP methods.
This topic describes how to protect FTP files and manage FTP server login, directory paths, and chaining.
If you have enabled the PUT method for FTP file uploading or the DELETE method for FTP file deletion, you need to define FTP proxy protection for at least PUT and DELETE requests, to prevent unauthorized file updating at your FTP server.
To protect the proxying of FTP requests, in the Configuration and Administration forms, select Server Configuration -> Document Protection. To create a protection setup for FTP file requests, include ftp:// at the beginning of the request template. For example, to protect files in a directory named exams, use the template ftp://exams/*.
For more information on creating protection setups, see Server protection setups.
If no user ID and password is specified in the request URL, the Caching Proxy attempts to log into the requested FTP server anonymously (using the user ID ANONYMOUS). Many FTP servers require an e-mail address as the password for anonymous FTP. If the FTP server asks for a password for the anonymous login, the Caching Proxy sends the e-mail address specified by the WebmasterEmail directive in the configuration file.
To set the Webmaster e-mail address in the Configuration and Administration forms, select Server Configuration -> System Management-> SNMP MIB. The e-mail address can also be set by using the WebmasterEmail directive; for details, see the reference section: WebMasterEMail -- Set an e-mail address to receive select server reports.
If the FTP server in the request URL requires a specific user ID and password to log in, users can enter the user ID and password in the request URL, for example:
ftp://userid:password@ftpserverhost/
If you do not want to specify the password for the FTP user ID in the request URL, users can enter only the user ID in the URL: ftp://userid@ftpserverhost. The Caching Proxy first attempts to log into the FTP server with the specified user ID and no password. If the login is unsuccessful without a password, then the browser prompts for the password associated with the specified user ID.
For logins other than anonymous, at least the user ID must be specified in the URL. If the user ID is not specified, then anonymous login is attempted and the client is not prompted for the user ID.
You must specify to the Caching Proxy whether you want the path names in FTP URLs to be interpreted as relative to the user's working directory or relative to the root directory. For example, if a user who is logged into an FTP server has a default working directory called /export/home/user1 and wants to retrieve a file called test1.exe from a subdirectory called test, the proxy uses the following URLs to retrieve the file from the FTP server, depending on how FTP URLs are interpreted:
If relative FTP URL paths are set, users can still specify an absolute path name by using the convention of escaping the initial slash character (/) with %2F to indicate the root directory. For example, if user1, whose working directory is /export/home/user1, wants to access a file in user2's working directory, /export/home/user2, the request ftp://user1:user1pw@FTPhost/%2Fexport/home/user2/file is interpreted correctly as a URL relative to the root directory / (that is, as an absolute path name), even if relative FTP URL path names have been chosen.
To specify how FTP URLs are to be interpreted, in the Configuration and Administration forms, select Proxy Configuration -> Proxy Performance. In the lower portion of the form, under FTP URL paths should be:, select absolute paths to specify the server's root directory or relative paths to specify the user's working directory as the start of the path.
This setting can also be changed in the proxy configuration file; for more information, see FTPUrlPath -- Specify how FTP URLs are interpreted.
If you are chaining multiple Web proxy servers together, you can specify that requests containing FTP URLs are to be sent to a chained Web proxy server rather than directly to the FTP server. To specify a chained proxy server for FTP requests, in the Configuration and Administration forms, select Proxy Configuration -> Proxy Chaining and Non-Proxy Domains. The http:// protocol scheme is used to specify the URL of the chained proxy, even when chaining requests for an ftp:// protocol scheme.
To configure FTP chaining by using the proxy configuration file, see the reference section on ftp_proxy -- Specify another proxy server for FTP requests.
This topic describes how to use server-side includes to insert information into CGI programs and HTML documents that are delivered to a client. Customizing the server's error messages and resource mapping are also discussed.
Server-side includes allow you to add information to CGI programs and HTML documents that the server sends to the client when acting as an origin server (that is, not to proxied or cached objects). The current date, the size of a file, the date of last change to a file are examples of the kind of information that can be sent to the client. This section describes the command format for server-side includes and explains how to make server-side include commands work in your CGI programs and HTML documents. You can also use server-side includes to customize error pages.
Before using server-side includes on your server, consider performance, security, and risk issues:
To enable server-side includes, in the Configuration and Administration forms, select Server Configuration -> Basic Settings. Use this form to specify which of the following types of server-side includes are acceptable:
Use this form also to specify whether to do server-side include processing for text or HTML documents in addition to other file types.
In addition, ensure that the file extension that you use for the include is recognized. In the Configuration and Administration forms, select Server Configuration -> MIME Types and Encoding, and use the MIME Types form. Note that the shtml and htmls extensions are recognized by default.
To configure your server for server-side includes by editing the directives in the proxy configuration file, see the reference sections for the following directives:
Include commands must be included in the HTML document or CGI program as comments. The commands have the following format:
<!--#directive tag=value ... --> or <!--#directive tag="value" ... -->
The quotation marks around values are optional, but they are required in order to embed spaces.
This section explains the directives that are accepted by the server for server-side includes. (Do not confuse these directives with the directives for the proxy configuration file, which are documented in Appendix B. Configuration file directives.)
config--control file processing
Use this directive to control certain aspects of file processing. Valid tags are cmntmsg, errmsg, sizefmt, and timefmt.
Example:
<!--#config cmntmsg="[This is a comment]" --> <!-- #echo var=" " extra text -->
Result: <!--[This is a comment] extra text -->
Default: [the following was extra in the directive]
Example:
<!-- #config errmsg="[An error occurred]" -->
Default: "[An error occurred while processing this directive]"
Example 1:
<!--#config sizefmt=bytes --> <!--#fsize file=foo.html -->
Result: 1024
Example 2:
<!--#config sizefmt=abbrev --> <!--#fsize file=foo.html -->
Result: 1K
Default: "abbrev"
Example:
<!--#config timefmt="%D %T" --> <!--#flastmod file=foo.html -->
Result: "10/18/95 12:05:33"
Default: "%a, %d %b %Y %T %Z"
The following strftime() formats are valid with the timefmt tag:
| Specifier | Meaning |
|---|---|
| %% | Replace with % |
| %a | Replace with the abbreviated weekday name |
| %A | Replace with the full weekday name |
| %b | Replace with the abbreviated month name |
| %B | Replace with the full month name |
| %c | Replace with the date and time |
| %C | Replace with the century number (year divided by 100 and truncated) |
| %d | Replace with the day of the month (01-31) |
| %D | Insert the date as %m/%d/%y |
| %e | Insert the month of the year as a decimal number (01-12) (Under C POSIX only, it is a 2-character, right-justified, blank-filled field) |
| %E[cCxyY] | If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %EC is mapped to %C) |
| %Ec | Replace with the alternative date and time representation |
| %EC | Replace with the name of the base year (period) in the alternative representation |
| %Ex | Replace with the alternative date representation |
| %EX | Replace with the alternative time representation |
| %Ey | Replace with the offset from %EC (year only) in the alternative representation |
| %EY | Replace with the full alternative year representation |
| %h | Replace with the abbreviated month name (the same as %b) |
| %H | Replace with hour (23-hour clock) as a decimal number (00-23) |
| %I | Replace with hour (12-hour clock) as a decimal number (00-12) |
| %j | Replace with the day of the year (001-366) |
| %m | Replace with the month (01-12) |
| %M | Replace with minute (00-59) |
| %n | Replace with a new line |
| %O[deHlmMSUwWy] | If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %Od is mapped to %d) |
| %Od | Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading zeroes if there is any alternative symbol for zero, otherwise with leading spaces |
| %Oe | Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading spaces |
| %OH | Replace with the hour (24-hour clock), using the alternative numeric symbols |
| %OI | Replace with the hour (12-hour clock), using the alternative numeric symbols |
| %Om | Replace with the month, using the alternative numeric symbols |
| %OM | Replace with the minutes, using the alternative numeric symbols |
| %OS | Replace with the seconds, using the alternative numeric symbols |
| %OU | Replace with the week number of the year (Sunday as the first day of the week, rules corresponding to %U), using the alternative numeric symbols |
| %Ow | Replace with the weekday (Sunday=0), using the alternative numeric symbols |
| %OW | Replace with the week number of the year (Monday as the first day of the week), using the alternative numeric symbols |
| %Oy | Replace with the year (offset from %C) in the alternative representation and using the alternative numeric symbols |
| %p | Replace with the local equivalent of AM or PM |
| %r | Replace with the string equivalent to %I:%M:%S %p |
| %R | Replace with time in 24-hour notation (%H:%M) |
| %S | Replace with seconds (00-61) |
| %t | Replace with a tab |
| %T | Replace with a string equivalent to %H:%M:%S |
| %u | Replace with the weekday as a decimal number (1-7), with 1 representing Monday |
| %U | Replace with the week number of the year (00-53), where Sunday is the first day of the week |
| %V | Replace with the week number of the year (01-53), where Monday is the first day of the week |
| %w | Replace with the weekday (0-6), where Sunday is 0 |
| %W | Replace with the week number of the year (00-53), where Monday is the first day of the week |
| %x | Replace with the appropriate date representation |
| %X | Replace with the appropriate time representation |
| %y | Replace with the 2-digit year number within the century |
| %Y | Replace with the full 4-digit year number |
| %Z | Replace with the name of the time zone or no characters if the time zone is unknown |
The operating system configuration determines the full and abbreviated month names and years.
echo--display variable values
Use this directive to display the value of environment variables specified with the var tag. If a variable is not found, a (None) is displayed. Also, echo can display a value set by the set or global directives. The following environment variables can be displayed:
Example:
<!--#echo var=SSI_DIR -->
exec--specify CGI programs
Use this directive to include the output of a CGI program. The exec directive discards any HTTP headers that the CGI outputs except for the following:
cgi--specify CGI program URL
Use this directive to specify the URL of a CGI program.
In this example, program is the CGI program to be executed, and path_info and query_string represent one or more parameters passed to the program as environment variables:
<!--#exec cgi="/cgi-bin/program/path_info?query_string" -->
This example shows the use of variables:
<!--#exec cgi="&path;&cgiprog;&pathinfo;&querystring;" -->
flastmod--display date and time document was last changed
Use this directive to display the last date and time the document was changed. The formatting of this variable is defined by the config timefmt directive. The file and virtual tags are valid with this directive, and their meanings are defined as follows.
Directive formats:
<!--#flastmod file="/path/file" --> <!--#flastmod virtual="/path/file" -->
<!--#flastmod file="/path/file" -->
<!--#flastmod virtual="/path/file" -->
Example:
<!--#flastmod file="foo.html" -->
Result: 12May96
fsize--display file size
Use this directive to display the size of the specified file. The formatting of this variable is defined by the config sizefmt directive. The file and virtual tags are valid with this directive, and their meanings are the same as defined previously for the flastmod directive.
Example:
<!--#fsize file="/path/file" --> <!--#fsize virtual="/path/file" -->
Result: 1K
global--defines global variables
Use this directive to define global variables that can be echoed later by this file or by any included files.
Example:
<!--#global var=VariableName value="SomeValue" -->
For example, to reference a parent document across the virtual boundary, you need to set a global variable DOCUMENT_URI. You also need to reference the global variable in the child document. This example shows the HTML coding you need to insert in the parent document:
<!--#global var="PARENT_URI" value=&DOCUMENT_URI; -->
This example shows the HTML coding you need to insert in the child document:
<!--#flastmod virtual=&PARENT_URI; -->
include--includes a document in output
Use this directive to include the text from a document in the output. The file and virtual tags are valid with this directive, and their meanings are the same as defined above for the flastmod directive.
set--set variables to be echoed
Use this directive to set a variable that can be echoed later, but only by this file.
Example:
<!--#set var="Variable 2" value="AnotherValue" -->
While defining a directive, you can echo a string in the middle of value. For example:
<!--#include file="&filename;" -->
Variables: A server-side set directive is generally followed by an echo directive, so that it looks for the set variable, echoes where the variable is found, and proceeds with the function. It can contain multiple references to variables. Server-side sets also allow you to echo a variable already set. If a set variable is not found, nothing is displayed.
When a server-side set encounters a variable reference inside a server-side include directive, it attempts to resolve it on the server side. In the second line of the following example, the server-side variable &index; is used with the string var to construct the variable name var1. The variable &var1; is then assigned a value by escaping the & in ê so that it is not recognized as a variable. Instead, it is used as a string to create the value frêd, or fred with a circumflex over the e. The variable ê is a client-side variable.
<!--#set var="index" value="1" --> <!--#set var="var&index;" value="fr\êd" --> <!--#echo var="var1" -->
Characters that can be escaped (called escaped variables) are preceded with a backslash (\) and include the following:
| Character | Meaning |
|---|---|
| \a | Alert (bell) |
| \b | Backspace |
| \f | Form feed (new page) |
| \n | New line |
| \r | Carriage return |
| \t | Horizontal tab |
| \v | Vertical tab |
| \' | Single quotation mark |
| \" | Double quotation mark |
| \? | Question mark |
| \\ | Backslash |
| \- | Hyphen |
| \. | Period |
| \& | Ampersand |
You can customize the error messages that the Caching Proxy returns, and you can define specific messages for particular error conditions. In the Configuration and Administration forms, select Server Configuration -> Error Message Customization. Use this form to select an error condition and specify a particular HTML file to use for that condition.
To customize error messages by editing directives in the proxy configuration file, see the reference section for the directive ErrorPage -- Specify a customized message for a particular error condition.
WebSphere Application Server, Version 6.0 introduces streaming media support in the form of the RTSP Redirector. RTSP enables the Caching Proxy to act as a first point of contact with media players and to redirect their requests to an appropriate proxy server or to a content server that provides the requested media content.
RTSP, the Real Time Streaming Protocol, is defined in RFC 2326. It is an Internet standard protocol for controlling data streams. Although it does not include technology for delivering streams, it is flexible enough that it can be used to control data streams that are unrelated to video or audio playback.
The RTSP redirection feature allows Caching Proxy to redirect requests for any streaming media sessions controlled by RTSP. These include the following types of media:
Any player that can be configured to contact a proxy server on its RTSP port (typically 554) can use this framework in the Caching Proxy to have its requests handled by the RTSP redirector.
The RTSP redirector does not cache or directly proxy media presentations. The RTSP redirector must be used in conjunction with a third-party streaming media server to provide either or both of those functions. The Caching Proxy with RTSP redirector must have network access to one or more RTSP proxy servers.
This feature is subject to the following limitation:
Currently, only RealNetworks technologies are supported. These include the RealProxy proxy server, the RealServer origin server, and the RealPlayer media player.
Previously, the RTSP Redirector was subject to the limitation that all requests to the same origin server for any URL were redirected the same way. Redirection based on file names or other portions of the requested URL was not possible. This limitation no longer applies. The RTSP Redirector now uses the complete URL from received requests along with the threshold value (rtsp_proxy_threshold) set in the Caching Proxy configuration file to determine whether to redirect the client request to the origin server or to a proxy server. Requests to the same origin server are now handled individually.
The following configuration file directives are used to control RTSP redirection. The settings for these directives are not refreshed by a server restart. The server must be completely stopped and then started again before changes to these directives take effect.
When requesting documents, Web clients send headers that provide additional information about the browser or the request. Headers are automatically generated when a request is sent.
The Caching Proxy allows several options for customizing header information to keep it hidden from the destination server. Although substituting a more generic header for the actual header has the advantage of increasing client anonymity, it has the disadvantage of disabling header-based page customization that is written into some Web pages.
Headers typically use this form:
User-Agent: Mozilla 2.02/OS2 Client-IP: 45.37.192.3 Referer: http://www.bigcompany.com/WebTrafficExpress/main.html
This header includes the following fields:
Most headers can be blocked by the appropriate proxy configuration settings. However, some header fields are required by origin servers, so blocking them can cause Web pages to be displayed incorrectly (For example, in certain cases blocking the "host" header field can cause users to see the wrong Web page). For further information on header fields, refer to the HTTP Version 1.1 specification.
To change header options by editing the proxy configuration file, see the reference sections for the following directives:
For more information, refer to Manually editing the ibmproxy.conf file.
You can use two Configuration and Administration forms to specify header options:
Check this box if you want the requesting client's IP address to be forwarded to the destination (content) server. If you do not check this box, the destination server receives the IP address of the proxy server. Leaving this box unchecked increases the clients' anonymity while surfing the Web.
Type the string to send in the header to the destination server to replace the type of browser and operating system that a client is using. For example: specifying Caching Proxy 4.0 replaces Mozilla 2.02/OS2 in the following header:
Content-Type:MIME User-Agent: Mozilla 2.02/OS2 Referer: http://www.ics.raleigh.ibm.com/WebTrafficExpress/main.html Pragma:no-cache
Type the e-mail address that the destination server reads when it parses the "From:" header. You might want to specify the e-mail address of the proxy administrator because the administrator is the person who needs to receive reports of any problems.
For more information, refer to Using the Configuration and Administration forms.
The application programming interface (API) is fully detailed in the Programming Guide for Edge Components. API directives within the configuration file enable plug-in routines that are called during specific steps within the request processing workflow. These plug-in routines can replace or run in addition to built-in routines.
Following are the API directives:
For more information, refer to Manually editing the ibmproxy.conf file.
The following Configuration and Administration form edits the values of the associated directives:
For more information, refer to Using the Configuration and Administration forms.
This section discusses the proxy cache and how to configure it. The cache can be set up to store files in memory (memory cache) or on one or more storage devices (disk cache). A cache refresh agent can be configured to preload frequently requested files into the cache, and various URL filters can be applied to caching. This section also discusses cache sharing by using remote cache access or the Internet caching protocol (ICP) plug-in, removing obsolete files with cache garbage collection, and caching dynamically generated files.
This part contains the following topics:
Caching is a feature in which the proxy server saves local copies of the files that clients request so that it can serve them quickly from the cache when they are requested again by the same or other clients.
The Caching Proxy is HTTP 1.1 compliant and generally follows the HTTP 1.1 protocol for caching and determining the freshness of documents.
This chapter discusses some features of the proxy server cache. For those features that can be configured, details about how to set the appropriate values are included in subsequent chapters.
The proxy server can store the cache on a physical storage device or in system memory. The type of cache storage that is better for your system depends on the capabilities of your hardware and on whether it is more important to have fast cache response or to have a larger number of items stored in the cache. Response time for a memory cache typically is faster than for a disk cache, but the size of a memory cache is limited by the amount of RAM in the proxy server machine. The size of a disk cache is limited by the size of the storage device, which typically is much larger than the amount of RAM.
For disk caches, the Caching Proxy uses raw disk caching, which means that the proxy server writes directly to the cache device without using the operating system's read and write protocols. The storage device for a disk cache must be prepared by using the htcformat command. Details about htcformat are included in the section Configuring basic caching.
In either a memory or disk cache, the Caching Proxy also uses system memory space to hold an index of the cache, which reduces the processing time to find cached files.
The Caching Proxy's cache directory structure and its lookup methods are different from those of other proxy servers. The Caching Proxy maintains an index in memory with information about the files in the cache. Using RAM for lookup instead of a disk or other medium results in faster file lookup and retrieval.
The index includes URLs, cache locations, and expiry information for cached objects. For this reason, the amount of memory necessary to hold the index is proportional to the number of objects in the cache.
When a request is received from a client, the proxy checks the cache index in memory for that URL.
When the proxy is configured to cache requests, it can cache FTP file requests as well as HTTP file requests. However, because FTP files do not contain the same type of header information as HTTP files, expiration dates for cached FTP files are calculated differently than for other cached files.
When a request is made to the FTP server to retrieve a file, the proxy first sends to the FTP server a LIST request for the file to obtain FTP directory information about the file. If the FTP server responds to the LIST request with a positive completion reply and the directory information for the file, the proxy creates an HTTP Last-Modified header with the date parsed from the FTP directory information. The caching function of the proxy then uses this Last-Modified header, together with the value set in the CacheLastModifiedFactor directive in the configuration file, to determine the length of time that the FTP file remains in the cache before expiring.
For more information on how the Last-Modified header and the CacheLastModifiedFactor directive are used to determine the length of time a file remains in the cache, see Maintaining cache content.
FTP files that are retrieved for a specific user ID rather than by anonymous login are considered to be private files and are not cached.
In addition to caching Web content, the proxy server performs domain name server (DNS) caching. For example, when a client requests a URL from www.myWebsite.com, the proxy asks its DNS server to resolve the host name www.myWebsite.com to an IP address. The IP address is then cached to improve response time for subsequent requests to that host name. DNS caching is automatic and cannot be reconfigured.
Some files and documents are never cached. These include the following:
It is possible to further restrict the items cached by setting caching filters. For example, you might not want the proxy server to cache files that are served locally from the proxy. Refer to Controlling what is cached for details.
Managing a cache involves many factors. As a server administrator, you can specify the following:
In addition, adjustments can be made to cache configuration in order to improve the overall performance of the Caching Proxy. For details about performance tuning, see Tuning the proxy server cache.
If you used the default settings in the Edge components Product Setup Program to install the Caching Proxy, caching is enabled and the cache is stored in memory. You might want to adjust the following basic cache settings to customize the cache for the needs of your system.
If you did not use the setup program, configure these settings to enable caching.
The basic steps necessary to configure caching are the following:
After configuring basic cache settings, you might want to add or change settings for the following features.
Instructions about changing each of these settings are given or referred to in this chapter.
To enable caching, set the Caching directive to on, or check the Enable proxy caching box on the Cache Configuration -> Cache Settings configuration form. If you do not specify a cache device, the cache will be stored in memory. To create a disk cache, follow the steps in 2. Configure cache storage.
The tasks for configuring cache storage depend on whether you use a memory cache or a disk cache.
To use a memory cache, customize the Cache Memory setting so that it includes enough memory to hold the contents of a cache. See Set cache memory for recommended cache memory sizes.
To use a disk cache, you must do the following:
The cache requires a specially formatted device. Devoting an entire device or disk partition to the cache is recommended. The minimum size for a cache is 16392 KB.
To format the cache device:
htcformat raw_device_path [-blocksize block_size]
[-blocks number_of_blocks]The -blocksize and -blocks arguments
are optional. The default block size is 8192 bytes. If the number of blocks
is not specified, the disk partition will be filled with as many blocks as
it can contain.
When specifying the device path, be sure to specify the raw device path.
raw /dev/raw/raw1 dev/sdb1
See the reference material for your file system for additional information about accessing raw devices.
If the operating system attempts to write to the cache device, cached data can be lost. To avoid this, you can use the Windows Disk Manager utility to prepare the disk before using the htcformat command. To prepare the disk, use the disk utility to delete the device or partition you want to use, then recreate it without formatting it. This causes the system to consider the device unavailable for system storage.
Set the value in the CacheMemory directive (or in the Cache Memory field of the Cache Settings configuration form), according to the following principles. The amount of memory set in this value is used for cache infrastructure support, including the cache index, and, if memory caching is configured, to store the contents of the cache.
For optimum performance of disk caches, a minimum cache memory value of 64 MB is recommended for cache infrastructure support, including the cache index. As the cache size increases, the cache index increases, and more cache memory is required to store the index. A cache memory value of 64 MB is large enough to provide cache infracture support and store a cache index for a disk cache of up to approximately 6.4 GB. For larger disk caches, the cache memory should be 1% of the cache size.
For memory caches, the cache memory value is the amount of memory set aside for the cache infrastructure support and the cache itself. A minimum cache memory value of 64 MB is recommended.
If too much physical memory is allocated for a memory cache, undesirable operations such as "out of memory" errors or proxy server failures can possibly occur. The value limitations for cache memory are due to the limitations of a 32-bit application. Because the Caching Proxy is a 32-bit application, it can use a maximum of 2 GB of memory.
The Caching Proxy allocates the memory defined by the CacheMemory directive and uses it as the cache to store objects. Additional memory must be allocated, whether it is a memory cache or a raw disk cache, for data structures for the cache, network I/O and connection buffers, session buffers, and memory for the main process and for all the threads. Furthermore, it is possible that requests from some clients might need to allocate a larger memory pool block than the default. Therefore, if the CacheMemory directive is set close to the 2-GB mark, it is possible that the Caching Proxy might not have enough memory to operate, especially under high request loads.
It is recommended that the value of the CacheMemory directive be less than or equal to 1600 MB. Setting the value higher than 1600 MB interferes with the memory that the Caching Proxy needs for its normal operation, and causes adverse side effects. These side effects typically include but are not limited to increased CPU usage (possibly up to 100% usage), out-of-memory errors, and sluggish performance. If an overall larger cache size is required, use cache devices or implement a shared cache configuration with RCA or ICP.
You can import and export cache contents to or from a dump file. This is useful when cache memory gets lost during restart, or when deploying the same cache for multiple proxies.
Filters can restrict what is cached by matching the form of the URL request. See Controlling what is cached for details about setting filters.
Optionally, you can configure the proxy server to cache results of query requests. By default, URLs that contain a question mark (?) are not cached. Refer to Caching query responses for details.
Another option is to cache results of servlet or JSP execution from an IBM WebSphere Application Server. Refer to Caching dynamically generated content for details.
Refer to Maintaining cache content for information about configuring when files in the cache expire and how obsolete files are removed.
The cache can be configured to automatically refresh the most popular files on a daily basis, before they are requested. Refer to Configuring the cache agent for automatic refreshing and preloading for information.
Under certain circumstances, using a shared cache increases the likelihood that a requested file is found in the cache. Refer to Using a shared cache for information.
Maintaining concise and accurate logs is important for managing the Caching Proxy. Monitoring the Caching Proxy contains information about configuring and using proxy server logs.
The caching proxy offers several filtering methods to control which files, documents, and other objects are cached. These include the following features:
The proxy server can be configured to compare requests to a URL template in order to determine whether a file is cached. This feature is configured by setting templates for requests whose files are always cached, and separate templates for requests whose files must never be cached. Multiple templates can be used.
A similar system is used to enable query response caching. Refer to Caching query responses for information.
To set URL caching filters by editing the ibmproxy.conf file, refer to CacheOnly -- Cache only the files with URLs that match a template andNoCaching -- Specify that files with URLs that match a template are not cached.
To set URL caching filters in the Configuration and Administration forms, use the Cache Configuration -> Cache Behavior: Cache filtering by URL field. Use this section to specify URLs whose files are always cached, or to specify URLs whose files are never cached. To specify two lists, one of files to always cache and one of files to never cache, create one list and then click Submit before creating the other list.
The responses returned from queries (URL requests that contain a question mark) can be cached by using caching filters. This feature can be useful in reverse proxy (surrogate) scenarios if many clients make the same query request.
Query caching can be configured by editing the CacheQueries directive in the ibmproxy.conf configuration file. The CacheQueries directive has the following options:
Additional information about these options is available in CacheQueries -- Specify cache responses to URLs containing a question mark (?).
To configure query response caching in the Configuration and Administration forms, use the Cache Configuration -> Cache Behavior: Cache Query Response filtering by URL field. To specify two lists, create one list and then click Submit before creating the other list.
In addition to configuring the query caching setting, ensure that the following settings are configured properly to enable query responses to be cached. Refer to Configuring cache freshness for information about setting these options by using the Configuration and Administration forms.
Because it is typically inefficient to cache files that are served from the proxy server, files originating in the server's local domain are not cached by default. To cache objects that originate in the server's local domain, check the Cache local domain files box on the Cache Configuration -> Cache Behavior Configuration and Administration form. Alternatively, set the CacheLocalDomain directive in the proxy configuration file to on.
Items can be cached based only on a specified (significant) part of the incoming URL, instead of the full URL. This is useful in transaction-model Web serving or for dynamic caching, because the same response is often returned for varying incoming requests when significant parts of the incoming requests' URLs are identical.
You cannot use the Configuration and Administration forms to specify caching based on partial URLs. Instead, use the SignificantUrlTerminator directive in the proxy configuration file to specify a terminating code for URL requests. This specification causes the Caching Proxy to evaluate only characters before the terminating code when it processes the request and determines whether the requested file is cached. When more than one terminator code is defined, the Caching Proxy compares incoming URLs against the terminator codes in the order in which they are defined in the ibmproxy.conf file. See SignificantURLTerminator -- Specify a terminating code for URL requests for more information.
To set caching filters by directly editing the proxy configuration file, see the reference sections for the following directives:
See Overview of proxy server caching for information on documents that cannot be cached.
Because caching involves making and saving a copy of the served file, some routine maintenance is required for the cache to function properly. Cached files must be checked for freshness and invalidated when they are no longer consistent with the files on the origin server. This file expiration process is explained in File expiration. Also, invalidated or unused files must be removed from the cache to make room for new files. This cache-purging process is described in Garbage collection.
Keeping cached objects consistent with the original object on the content server is known as maintaining cache freshness. For each document or other object that it caches, the Caching Proxy computes a time at which the object expires.
For HTTP pages, the header of the document, generated by the content server, contains the expiration information.
Because the FTP protocol does not include equivalent expiration information, the Caching Proxy generates its own Last-Modified: header for FTP files, based on the FTP directory information for each file, and uses this information to compute expiry times. If the proxy server cannot obtain directory information for the file from the FTP server, the default value that matches the FTP URL is used. In addition, because there is no standard date format for FTP servers, the Caching Proxy might be unable to understand the date and time sent by some FTP servers. In that case, the proxy server's default expiry time value is used. This procedure allows the proxy to manage the caching of HTTP pages and FTP files in a similar manner.
Expiration can be specified by a content server in one of several ways (in order of preference):
After the expiry time is computed as just described, the Caching Proxy checks to see whether there is a Minimum Hold value that applies for this URL. If there is, and the time it specifies is longer than the computed expiry time, then the time specified by the Minimum Hold value is used as the object's expiry time. This is true even if the Caching Proxy computes an expiry time of 0 minutes for a document. Therefore, to avoid serving stale content, be cautious about using the Minimum Hold setting. (To set the Minimum Hold value, use the CacheMinHold directive or the Cache Configuration -> Cache Expiry Settings: URL Expiration setting. Refer to Configuring cache freshness for additional information.)
The final expiry time value is checked against the time specified in the Time Margin setting. If the expiry time is greater than the Time Margin value, the document is cached; otherwise, it is not added to the cache. (To set the Time Margin value use the CacheTimeMargin directive or see the instructions in Configuring cache freshness.)
If the document is found in the cache, but it has expired, the Caching Proxy issues a special request known as an if-modified-since request to the content server. This request causes the content server to send the document only if it has been modified since it was last received by the proxy. If the document has not been modified, the content server sends a message indicating that, and does not resend the page. In that case, the proxy serves the cached document. For FTP files, the proxy server simulates this if-modified-since process. If it determines that the file has not been changed at the FTP server, it serves the file from the cache. Otherwise, it gets the newer version from the FTP server.
Because the FTP protocol does not define dates and times as strictly as the HTTP protocol does, several factors can cause the Last-Modified header generated by the proxy for FTP files to be slightly different from the actual file date. These factors include the following:
When an FTP file expires from the cache, the proxy simulates the HTTP if-modified-since revalidation process for the FTP file. It does this by reissuing the FTP LIST command for the requested file, parsing the file date from the response returned by the FTP server, and comparing this date with the date that the proxy server generated for the Last-Modified header when the file was initially retrieved. If the file date has not changed, then the proxy server marks the cached FTP file as revalidated, sets a new expiration time for the file, and serves the file from the cache rather than retrieving it again from the FTP server. If the two file dates do not match, then the proxy retrieves the file from the FTP server again and caches the new copy with the new file date.
It is not always possible to obtain the directory information for the file from the FTP server. If the proxy is unable to determine the file date for the FTP file, it does not generate a Last-Modified header for the file. Instead, it uses the value specified for the CacheDefaultExpiry directive that matches the URL to determine the length of time to keep the file in the cache. When this time period expires, the proxy always retrieves the file from the FTP server again. If specific FTP files in your cache seem to be using the CacheDefaultExpiry directive very often and are frequently being retrieved (generating a high volume of network traffic), consider specifying a more granular CacheDefaultExpiry value for those specific files. Doing this holds them in the cache for a longer period of time.
To specify cache expiration settings in the Configuration and Administration forms, use the Cache Configuration -> Cache Expiry Settings -> Time Limit for Cached Files form. For more details on setting cached file expiration dates, see File expiration.
To specify the expiration times for cached files, in the Configuration and Administration forms, select Cache Configuration -> Cache Expiry Settings. The following forms are useful.
Use this form to set the minimum length of time that files are held in the cache, based on their URLs. You can specify different caching behavior for different URL request templates.
To set URL-based file expiration by editing the proxy configuration file, see the reference sections in Appendix B. Configuration file directives for the following directives:
Use the Cache Expiration Settings form to specify the default expiration settings for used or unused files. You can set different values for HTTP, FTP, and Gopher files, and you can set different values for used or unused files.
This form also contains additional file-expiration options:
To set default expiration settings by editing the proxy configuration file, see the reference pages for the following directives:
Use the Last Modified Factor form to set the value that the proxy uses to calculate an expiration date for cached files with no expiration dates in their headers. You can set different values for files matching different request templates. The first matching template is used to calculate the expiration date.
To set the Last Modified factor by directly editing the proxy configuration file, see CacheLastModifiedFactor -- Specify the value for determining expiration dates.
Use the Time Limit for Cached Files configuration form to set the maximum time that a file can remain in the cache. Time limits are set based on request templates, and you can specify that files are discarded or revalidated when the time limit expires. These settings can be used to maintain files whose expiration dates are invalid or files with extremely long expiration times.
To set the maximum expiration time limit for cached files by editing the proxy configuration file, see the following:
As part of the effort to keep popular URLs cached and minimize usage of system resources, the Caching Proxy performs the cleanup process known as garbage collection, in which old or unused files are removed from the cache to make room for more-current files.
The garbage collection process examines the files in the cache directory and attempts to eliminate expired files to reduce the size of the cache and make room for new files. Garbage collection is done automatically, but some settings can be configured to tailor the process to your needs.
To configure garbage collection, in the Configuration and Administration forms, select Cache Configuration -> Garbage Collection Settings. Use this form to set the high water mark and low water mark, which determine when garbage collection is started and stopped. When the amount of space used in the cache reaches or exceeds the percentage set for the high water mark, garbage collection begins. Garbage collection continues until the percentage of used space in the cache is equal to or less than the value set for the low water mark.
You can choose between two garbage-collection algorithms. The responsetime algorithm optimizes the time required to respond to users by preferentially removing large files from the cache. The bandwidth algorithm optimizes the use of network bandwidth by preferentially removing smaller files from the cache. Choose either, or a blend of the two.
To configure garbage collection by editing the proxy configuration file, see the reference sections for the following directives:
Most caching proxy servers cache a file only after a user requests it. The Caching Proxy has a cache agent that provides automatic cache preloading. You can specify that the cache agent automatically retrieves specified URLs, the most popular URLs, or both, and places them in the cache before they are requested.
In some cases, you need to set the host name of the proxy server and identify the cache access log before the cache is preloaded. To configure the cache agent, in the Configuration and Administration forms, select Cache Configuration and use the Cache Preload and Cache Refresh forms. Note that files representing query results (that is, files whose URLs include the question mark character (?) are cached only if query caching is enabled).
Automatic cache refreshing and preloading provides the following advantages:
Disadvantages include the following:
For optimal efficiency, set the cache agent to run when server activity is low and before the server becomes busy with client requests. Then the files are ready in the cache to provide fast service the first time a user requests them. By default, the cache agent is started every night at 3 a.m. local time.
On Linux and UNIX platforms, specify the host name of the proxy server whose cache is being preloaded or refreshed. On Windows platforms, specify the host name only if the proxy server being refreshed is not on the local machine (Note that refreshing a remote server's cache based on its most frequently accessed files is not possible because the local cache agent does not have access to a remote server's cache access log.)
To set the host name of the proxy server, in the Configuration and Administration forms, select Cache Configuration -> Cache Refresh: Identify cache destination server.
To preload the cache with the content stored at specific URLs, in the Configuration and Administration forms, use Cache Configuration -> Cache Preload. In this form, you can specify URLs for the cache agent to load. The proxy retrieves those pages when the cache agent starts, regardless of whether they were in the cache previously (These URLs are specified in the proxy configuration file by the LoadURL directive). This form can also be used to define URLs whose content is never cached. Access to a cache access log is not required for this type of cache preloading.
Use the Cache Preload form to configure the following options:
To preload the most frequently accessed pages automatically, use the Cache Configuration -> Cache Refresh form. This function requires a Cache Access Log for the proxy server. (The log's location and name can be changed; refer to Monitoring the Caching Proxy for information.) The most popular URLs are determined automatically from the Cache Access Log. The administrator can also specify the number of popular pages to preload in the cache. (This number is specified in the proxy configuration file by the LoadTopCached directive.)
Use the Cache Refresh form to configure the following options:
Delving is an optional part of the automatic cache refresh feature. Most Web pages have links to other pages with related information, and users often follow the path linking from one page to another and from one site to another. Delving is a way to cache these logical information paths. In delving, the cache agent follows a specified level of hypertext (HTML) links on the pages it is loading, and also caches all of those linked pages. The linked pages can reside on the same host as the source page or on other hosts. An illustration is shown in Figure 1.
To control the delving process, the administrator specifies to the cache agent a maximum number of URLs that it can load (the default setting is 2000), a maximum length of time it can run (the default setting is two hours), and a maximum number of threads it can use (the default setting is four). The administrator can also configure additional controls. By default, delving is enabled for two levels of hierarchy and is not allowed across hosts. Additionally, a delay is inserted between requests. To change these settings, see Related proxy configuration file directives.
The cache agent loads and then refreshes the cache in this order:
Note that the cache agent does not check whether the maximum number of pages has been reached until it starts delving across links. If the value for the maximum number of pages (called MaxURLs in the proxy configuration file) is lower than the number of pages retrieved in steps 1 and 2, no linked pages are retrieved.
The following examples show how the cache agent handles cache refresh priorities and delving, relative to the maximum number of URLs that are specified (assume that delving is configured for all of these examples).
| Configuration file setting | Result |
|---|---|
LoadURL http://www.getthis.com/main.html LoadURL http://www.getmetoo.com/welcome.htm LoadTopCached 30 MaxURLs 50 |
If the Cache Access Log has more than 30 unique URLs, the cache agent retrieves main.html, welcome.htm, and the top 30 requested URLs based on the cache access log. Because it has not reached the MaxURLs value, it retrieves and loads up to 18 linked URLs from pages already cached. |
LoadURL http://ww.joesmith.edu/favorites.html LoadURL http://www.janesmith.edu/dislikes.html LoadTopCached 30 MaxURLs 25 |
If the cache access log has more than 30 unique URLs, the cache agent retrieves favorites.html, dislikes.html, and the top 30 requested URLs from the cache access log. No other files are retrieved because the value in MaxURLs has been exceeded. |
LoadURL http://www.hello.com/hi.htm LoadURL http://www.ballyhoo.com/index.html LoadTopCached 20 MaxURLs 25 |
If the cache access log has more than 20 unique URLs, the cache agent retrieves hi.htm, index.html, the top 20 requested URLs from the cache access log, and up to 3 linked URLs from the earlier pages. No other files are retrieved because the value in MaxURLs has been reached. |
The cache agent can also be configured by directly editing the appropriate directives in the proxy configuration file. For proxy configuration file directives relating to the cache agent, see the following reference pages in Appendix B. Configuration file directives:
If automatic cache refreshing is enabled, the cache agent automatically runs a refresh operation at the specified time. However, you also can run the cache agent at any time from a command line.
The executable file is as follows:
Where server_root is the drive and directory where you installed the Caching Proxy (for example, C:\Program Files\IBM\edge\cp).
On Linux and UNIX platforms, you can automatically run the cache agent at various times by using the cron daemon. Jobs controlled by cron are specified by adding a line to the system crontab file. An example entry of the command file on Linux and UNIX is:
45 16 * * * /usr/sbin/cacheagt
This command example starts the cache agent every day at 4:45 p.m. local time. You can use multiple entries to run the cache agent more than once, if desired. For more information, see your operating system's documentation about the cron daemon.
When using a cron daemon to run the cache agent, remember to turn off the automatic refresh option, either by using the Cache Configuration -> Cache Refresh configuration form or by editing the proxy configuration file. Otherwise, the cache agent runs more than once each day.
It is common for a point of presence on the Web to have more traffic than a single server can handle. One solution is to simply add more servers. However, when multiple caching proxy servers are used, the contents of one cache often overlap with the contents of the other caches. In addition to unnecessary redundancy in storage, maximum bandwidth savings are not achieved because a cached file is re-fetched from the origin server when a request for it comes to a proxy server that does not have that file in its own cache. Although duplicate caching can be minimized by using a hierarchical chain of proxy servers, this scenario still results in additional traffic through a given server, and each additional link in the chain adds latency.
Cache sharing solves these problems by allowing each cache to share its contents with the other caches. Bandwidth savings result because of the following facts:
Two methods are provided for using multiple caches as if they are one logical cache:
RCA and ICP can be used together.
In planning for RCA, consider the following recommendations:
Remote cache access is not appropriate if any of these conditions is violated or if different organizations manage different servers that are members of the array.
To configure remote cache access, in the Configuration and Administration forms, select Cache Configuration -> Remote Cache Access. The fields in this form define a named array that shares one logical cache. Enter the required information for each member of the array.
To configure remote cache access by editing the proxy configuration file, see the reference sections in Appendix B. Configuration file directives for the following directives:
The Internet Caching Protocol plug-in enables a Caching Proxy to query ICP-compliant caches in search of HTML pages and other cacheable resources. When the proxy server receives an HTTP request, it searches its own cache for the resource. If the resource is not found in the local cache and the ICP plug-in is enabled, the proxy server encapsulates the URL request in an ICP query packet and then delivers this packet to all identified ICP peer caches. If a peer cache responds that it has the resource, the proxy server retrieves the resource from that peer's cache. If two or more peers respond positively, the first response is processed. If no peers respond with hits, the original server continues to process the request according to its workflow. For example, the proxy server can invoke another plug-in, continue to the Remote Caching Access routine (if RCA is enabled), or retrieve the requested resource itself.
The ICP plug-in is activated and configured by editing the proxy configuration file, ibmproxy.conf. A ServerInit directive, a PreExit directive, or both must be added to the API directives section of the configuration file in order to use the ICP plug-in. Which directives are used depends on the role that the Caching Proxy has in the ICP system:
To create these directives, either manually edit the ibmproxy.conf file, or if the proxy server is already running, connect to the Configuration and Administration form Server Configuration-> Request Processing -> API Request Processing.
Note that prototype directives (in the form of comments) have been added to the API section of the ibmproxy.conf file. These API directives are in a purposeful order. When adding API directives to enable new features and plug-in modules, order the directives as shown in the prototype section of the configuration file. Alternatively, uncomment and edit, if necessary, API directives to include support for each desired function or plug-in.
Both the ServerInit and the PreExit directives have two arguments: (1) the fully qualified path of the shared library and (2) the function call. These arguments are delimited by a colon (:). The first argument is system specific and depends on where the plug-in components are installed. The second argument is hard-coded into the shared library and must be typed exactly as shown.
Each directive must appear on a single line in the proxy configuration file.
ServerInit path_of_shared_library:icpServerLinux and UNIX example:
ServerInit /opt/ibm/edge/cp/internet/lib/plugins/icp/libicp_plugin.so:icpServer
Windows example:
ServerInit C:\Program Files\IBM\edge\cp\Bin\plugins\icp\icpplugin.dll:icpServer
PreExit path_of_shared_library:icpClientLinux and UNIX example:
PreExit /opt/ibm/edge/cp/internet/lib/plugins/icp/libicp_plugin.so:icpClient
Windows example:
PreExit C:\Program Files\IBM\edge\cp\Bin\plugins\icp\icpplugin.dll:icpClient
To configure settings of the plug-in, add or modify the ICP* directives that are provided in the proxy configuration file. For additional information, refer to the descriptions of the following directives.
The dynamic caching function enables the Caching Proxy to cache dynamically generated content in the form of responses from JavaServer Pages (JSP) and servlets generated by a IBM WebSphere Application Server. A Caching Proxy adapter module is used at the application server to modify the responses so that they can be cached at the proxy server in addition to being cached in the application server's dynamic cache. With this feature, dynamically generated content can be cached on the edge of the network, freeing the content host from making repeated requests to the application server when more than one client requests the same content.
It is sometimes necessary to enable query caching in order for the dynamic caching feature to work, for example, if your servlets use URLs in the form of queries. The proxy server considers any URL that contains a question mark (?) to be a query.
The caching of dynamically generated content offers the following benefits:
The application server exports only fully composed public pages for proxy caching. Private pages are not cached by the proxy. For example, a dynamically generated page from a public site that lists the current weather forecast can be exported by the IBM WebSphere Application Server and cached by the Caching Proxy. However, a dynamically generated page that lists the contents of a user's shopping cart cannot be cached by the proxy server. Also, in order for a dynamically generated page to be cached, all subcomponents of that page also must be cacheable.
Cached dynamic files do not expire in the same way that regular files do; they can be invalidated by the application server that generated them.
Entries in the dynamic cache are invalidated in the following circumstances:
Invalidation of dynamic cache entries is done by generating an Invalidate message for the specific instance of the Caching Proxy dynamic caching plug-in. The Caching Proxy receives Invalidate messages as posts to the /WES_External_Adapter resource locator. The Caching Proxy then clears the invalid entries from its cache.
Dynamic caching requires the following configuration steps.
Follow the instructions in the IBM WebSphere Application Server documentation for configuring your application server to use its local dynamic cache (also called the dynamic fragment cache). The dynamic fragment cache interacts with the external cache at the Application Server Caching Proxy.
The IBM WebSphere Application Server communicates with the Caching Proxy by using a software module called the External Cache Adapter, which is installed with the Application Server.
To enable the proxy server to cache dynamically generated content (results from servlets and JSPs), you must make two changes in the proxy configuration file, ibmproxy.conf. The first change enables the dynamic caching plug-in module, and the second change configures it to recognize the sources of cacheable dynamic content.
An API directive for the Service step is used to enable the dynamic caching plug-in. To create this directive, either manually edit the ibmproxy.conf file, or if the proxy server is already running, use the Configuration and Administration forms to select Server Configuration -> Request Processing -> API Request Processing. The content of the directive is shown in examples that appear later in this section.
A prototype Service directive for enabling dynamic caching exists as a comment in the API section of the ibmproxy.conf file. It has the heading JSP Plug-in. Note that the prototype API directives are in a purposeful order. When adding API directives to enable new features and plug-in modules, order the directives as shown in the prototype section of the configuration file. Optionally, you can remove the comment characters from the prototype API directives and edit them as necessary to include support for each desired function or plug-in.
Set the Service directive as shown in the following examples. (Note that each directive must appear on a single line in the proxy configuration file; these examples sometimes contain line breaks for readability.)
Service /WES_External_Adapter /opt/ibm/edge/cp/lib/plugins/ dynacache/libdyna_plugin.o:exec_dynacmd
Service /WES_External_Adapter /opt/ibm/edge/cp/lib/plugins/ dynacache/libdyna_plugin.so:exec_dynacmd
Service /WES_External_Adapter /usr/lib/libdyna_plugin.so:exec_dynacmd
Service /WES_External_Adapter C:\Program Files\IBM\edge\cp\bin\plugins\ dynacache\dyna_plugin.dll:exec_dynacmd
If the Caching Proxy software is installed in a directory other than the default, substitute your installation path for the path in these examples.
Each Caching Proxy must also be configured to recognize the source of the dynamically generated files. Add an ExternalCacheManager directive to the ibmproxy.conf file for each application server that caches dynamically generated content at this proxy server. This directive specifies a WebSphere Application Server that caches results at the proxy, and sets a maximum expiration time for content from that server. More details appear in ExternalCacheManager -- Configure the Caching Proxy for dynamic caching from IBM WebSphere Application Server.
The server ID used in the ExternalCacheManager directive must match the group ID used in the external cache group stanza of the application server's dynacache.xml file.
For the previous example, add the following entry to each proxy's ibmproxy.conf file.
ExternalCacheManager IBM-edge-cp-XYZ-1 20 seconds
The Caching Proxy caches only contents from a IBM WebSphere Application Server whose group ID matches an ExternalCacheManager entry in the ibmproxy.conf file.
When caching is enabled, the speed of cache storage devices is critical to Caching Proxy performance. This section gives suggestions on choosing a type of cache storage and configuring your cache storage devices for best performance.
The Caching Proxy can use two different types of cache storage media:
A memory cache provides the fastest file retrieval, but the size of a memory cache is limited by the amount of available memory on the proxy server machine. A disk cache, made up of one or more raw disk partitions, is slower than a memory cache but allows larger cache sizes in most cases.
The device partitions used for disk caching need to be dedicated to the cache; that is, do not use these physical disks to contain any other file systems, and do not use them for any purpose other than storing the proxy cache. Additionally, do not use data compression on any disk used for the proxy cache because it reduces performance.
Each cache storage device (whether a disk or a file) incurs memory overhead on the proxy server. In general, using an entire physical disk as a single cache device yields the best performance. Using RAID or other mechanisms to combine multiple physical disks into a single logical disk can be counterproductive. If you want to use multiple disks, specify them as multiple cache devices by using the Cache Settings configuration form or by editing the CacheDev directive in the proxy configuration file. This method allows the proxy server to control the parallelism of reading and writing to multiple disks, and does not rely on the performance of the operating system or a disk subsystem.
Cache garbage collection for the proxy server discards expired files from the cache, freeing space to cache files for new requests. Garbage collection is triggered automatically when the amount of used space in the cache reaches an administrator-specified limit called the high water mark and continues until the amount of used space reaches a low water mark.
Because the garbage collection routine uses minimal CPU resources and does not affect the availability of unexpired cached material, configuring garbage collection to run at specific times is not necessary.
To improve the performance of garbage collection, you can set the high water mark and low water mark. You can also configure the type of algorithm used for garbage collection. See Garbage collection for more information on modifying garbage collection.
The following are additional suggestions for optimizing cache performance on each platform.
Create a single logical volume on a disk, preferably using all the physical partitions (PPs) available. For example, given a 9-GB disk, create a 9-GB logical volume called cpcache1. Format it and specify it as a proxy cache device using its raw logical volume, /dev/rcpcache1.
On your cache device, create a single partition (or slice) that uses the entire size of the disk. For example, on a 9-GB disk, create a 9-GB partition called c1t3d0s0. Format it and specify it as a proxy cache device using its raw device, /dev/rdsk/c1t3d0s0.
Create a single partition, using the entire size of the disk. For example, on a 9-GB disk, create a 9-GB partition called i:. Format it and specify it as a proxy cache device using its raw device, \\.\i:.
Information on configuring the proxy server's cache and on formatting and specifying cache devices is included in Configuring proxy server caching.
This part provides information about basic security, using SSL with the Caching Proxy, enabling cryptographic hardware, and using the IBM Tivoli(R) Access Manager (formerly Tivoli Policy Director) plug-in and the PAC-LDAP authorization module.
This part contains the following topics:
Enabling the support of cryptographic hardware
Using the Tivoli Access Manager plug-in
Using the PAC-LDAP authorization module
Any server accessible from the Internet is at risk for attracting unwanted attention to the system on which it runs. Unauthorized people might try to guess passwords, update files, execute files, or read confidential data. Part of the attraction of the World Wide Web is its openness. However, the Web is open to both positive use and abuse.
The following sections describe how to control who has access to the files on your Caching Proxy server.
The Caching Proxy supports Secure Sockets Layer (SSL) connections, in which secure transmissions involving encryption and decryption are established between the client browser and the destination server (either a content server or a surrogate server).
When the Caching Proxy is configured as a surrogate, it can establish secure connections with clients, with content servers, or both. To enable SSL connections, in the Configuration and Administration forms, select Proxy Configuration -> SSL Settings. On this form select the Enable SSL check box and specify a key ring database and a key ring database password file.
You can take several basic precautions to protect your system:
Packet filtering allows you to define where data can come from and where it can go. You can configure your system to reject certain source-destination combinations.
A firewall separates an internal network from a publicly accessible network, such as the Internet. The firewall can be a group of computers or a single computer that acts as a gateway in both directions, regulating and tracking the traffic passing through it. IBM Firewall is an example of firewall software.
Examples:
Proxy /* http://content server :443
or
Proxy /* https://content server :443
This chapter describes how to protect the data and files on your server by using protection setups. Protection setups are triggered based on the request that the server receives, specifically on the particular directory, file, or type of file that the request addresses. Within a protection setup, subdirectives control how access is granted or denied based on the characteristics of the directories or files being protected.
To define a protection setup and how it is applied, in the Configuration and Administration forms, select Server Configuration -> Document Protection. Use this form for the following steps:
Protection rules are applied in the order in which they are listed in the table on the configuration form. In general, rules are listed from specific to generic.
Use the drop-down menu and buttons to specify the placement of a protection rule.
Protection is activated based on request templates, which are compared to the content of requests that clients send to your proxy server.
A request is the part of a full URL that follows your server host name. For example, if your server is named fine.feathers.com and a browser user enters the URL http://fine.feathers.com/waterfowl/schedule.html, your server receives the request /waterfowl/schedule.html. Request templates specify directory or file names, or both, that are subject to protection. For example, some requests that activate protection based on the request template just described (/waterfowl/schedule.html) include /waterfowl/* and /*schedule.html.
Type the request template in the URL request template field.
A protection setup tells the Caching Proxy what to do with a request that matches a request template. You can use a named protection setup or define a new setup in the Document Protection form.
To use a named setup, click the Named protection radio button and type the name in the field provided. To define a new setup, click the In-line radio button and follow the instructions provided (see Step 6).
Different rules can be applied to requests from different server addresses. For example, you might want to apply a different protection setup to requests for log files when those requests are received from IP addresses assigned to your company.
If you want to include the address of the requester in the rule, type it in the Server IP address or host name field.
If you have used a named protection setup, no further input is required. If you have selected an in-line protection setup or specified a named setup that does not exist, the system opens additional forms.
If you did not specify an existing named protection setup, an additional form opens, on which you can specify which users can access the documents or directories matching the request template, and which actions those users are allowed.
To set protection by directly editing the Caching Proxy's configuration file, you must first understand the following issues:
Request-routing directives, like Map, Exec, Pass, and Proxy, are used to control which requests your server accepts and how it redirects requests to actual file locations. Request-routing directives use the same type of request templates as protection directives. Because the directions associated with the first matching template for each request are executed, protection directives must be listed before routing directives in the configuration file, in order for protection to work correctly. For more information, see Protect -- Activate a protection setup for requests that match a template.
The Protect directive can be used to specify an in-line protection setup or can refer to an existing, named setup. The syntax for the two types of statements is slightly different. For information, see Protect -- Activate a protection setup for requests that match a template.
A protection setup is a series of statements that use the protection subdirectives. Syntax and reference information about writing protection setups is contained in Appendix B. Configuration file directives; see the following reference sections:
The default proxy configuration file includes a protection setup that requires an administrator ID and password in order to access files in the /admin-bin/ directory. This setting restricts access to the Configuration and Administration forms.
Secure Sockets Layer (SSL) is a system that automatically encrypts information before sending it over the Internet and decrypts it at the other end before it is used. This protects sensitive information like credit card numbers while it is transmitted over the Internet.
The Caching Proxy uses SSL to secure surrogate servers and to provide secure remote administration, as described in the following sections. SSL can also be used to protect connections to back-end servers (for example, content or application servers) as well as to protect communications between the proxy server and its clients.
SSL protection is initiated when a secure connection request is sent from one machine to another--for example, when a browser sends a request to a surrogate proxy server. The request syntax https:// instead of http:// tells the browser to send the request on port 443, which is where the server listens for secure connection requests (instead of port 80 for routine requests). To establish a secure session between the browser and the server, the two machines perform an exchange called an SSL handshake to agree on a cipher specification and to select a key that is used to encrypt and decrypt information. Keys are automatically generated, and they expire when the session expires. A typical scenario (assuming SSL Version 3) is the following:
The client initiates an SSL session with the Caching Proxy by sending a Client Hello message that describes the client's encryption capabilities.
The server sends its certificate to the client and chooses the ciphersuite to use for data encryption.
The client sends cipher key information that is used to create symmetric encryption keys for the encrypted data. This key material is known as the premaster secret and it is encrypted with the server's public key (obtained from the server's certificate; see Key and certificate management). Both the server and the client can derive the read and write symmetric encryption keys from the pre-master secret.
The server sends a final confirmation and a Message Authentication Code (MAC) for the entire handshake protocol.
The client sends a message to validate the server finish message.
If the client validates the server finish message, then encrypted data flow begins.
Using a Caching Proxy as an end point for secure connections can reduce the load on your content or application servers. When a Caching Proxy maintains a secure connection, it performs encryption, decryption, and key creation, which are all CPU-intensive operations. The Caching Proxy also allows you to configure SSL session timeouts to maximize the use of each key.
Limitations of SSL
The following limitations apply to SSL in WebSphere Application Server's Caching Proxy:
Remote administration of your Caching Proxy can be achieved by using the security features provided by Secure Sockets Layer (SSL) and password authentication. This significantly reduces the probability of access to the proxy server by unauthorized persons.
To apply SSL during remote administration of your server, use an https:// request instead of an http:// request to open the Configuration and Administration forms. For example:
https://your.server.name/yourFrontPage.html
As noted previously, before configuring SSL you must set up a key database and obtain or create a certificate. Certificates are used to authenticate server identities. Use the IBM Key Management utility (sometimes called iKeyman) to set up your certification files. This utility is part of the GSKit software, which is included with Application Server. GSKit also includes a Java-based graphical interface for opening certificate files.
The following are the basic steps to set up your SSL keys and certificates.
Your public key must be associated with a digitally signed certificate from a certificate authority (CA) that is designated as a trusted root CA on your server. You can buy a signed certificate by submitting a certificate request to a certificate authority (CA) provider. The Caching Proxy supports the following external CAs:
By default, the following are designated as trusted CAs:
This section provides a quick reference for using the IBM Key Manager utility (iKeyman). Use the key manager to create your SSL key database file, public-private key pair, and certificate request. After you receive the CA-signed certificate, use the key manager to place the certificate in the key database where you created the original certificate request.
More detailed documentation on the IBM Key Manager and GSKit is packaged with the GSKit software.
Set up your system to run the key manager
Before starting the IKeyman GUI, do the following:
ibmjcefw.jar ibmpkcs11.jar
ibmjceprovider.jar ibmpkcs.jar
local_policy.jar US_export_policy.jar
Update the JAVA_HOME/jre/lib/security/java.security file to add both IBM CMS and IBM JCE providers after the Sun provider. For example:
security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.spi.IBMCMSProvider security.provider.3=com.ibm.crypto.provider.IBMJCE
A sample java.security file can be found in GSKit_Installation_path/classes/gsk_java.security.
security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.spi.IBMCMSProvider security.provider.3=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.4=com.ibm.crypto.provider.IBMJCE
security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.crypto.pkcs11.provider.IBMPKCS11
Starting the key manager
Start the key manager graphical user interface as follows:
Note that if you create a new key database file during this session, the file is stored in the directory from which you started the key manager.
A key database is a file that the server uses to store one or more key pairs and certificates. You can use one key database for all your key pairs and certificates, or create multiple databases. The key management utility is used to create new key databases and specify their passwords and stash files.
To create a key database and stash file:
The password that you specify when you create a new key database protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key.
Use the following guidelines when specifying the password:
It is a good practice to change the key database password frequently. However, if you specify an expiration date for the password, keep a record of when to change it. If the password expires before you change it, a message is written to the error log and the server starts, but it cannot make secure network connections.
Follow these steps to change the key database password:
For an SSL connection between a proxy and an LDAP server, put the key database password in the pac_keyring.pwd file. (Note that the pac_keyring.pwd file is not the stash file generated by IKeyMan.)
Creating a new key pair and certificate request
The key database stores key pairs and certificate requests. To create a public-private key pair and certificate request, follow these steps:
A new certificate request has been successfully created in the file keyfile_database_name.
Creating a self-signed certificate
Use the key management utility to create a self-signed server certificate to enable SSL sessions between clients and your proxy server while waiting for a certificate to be issued. You also can use self-signed certificates for testing purposes.
Follow this procedure to create a self-signed certificate:
Exporting keys
Use this procedure to export keys to another key database:
Importing keys
To import keys from another key database:
Listing certificate authorities
To display a list of trusted certificate authorities (CAs) in a key database:
Use this procedure to receive a certificate that is electronically mailed to you from a certificate authority (CA) that is designated as a trusted CA by default (see the list in Certificate authorities). If the CA that issues your CA-signed certificate is not a trusted CA in the key database, you must first store the CA's certificate and designate the CA as a trusted CA. Then you can receive your CA-signed certificate into the database. You cannot receive a CA-signed certificate from a CA that is not a trusted CA (see Storing a CA certificate).
To receive a CA-signed certificate into a key database:
Only certificates signed by trusted CAs are accepted for establishing secure connections. To add a CA to the list of trusted authorities, you must obtain and store its certificate as trusted. Follow this procedure to store a certificate from a new CA, prior to receiving it into the database:
Displaying the default key in a key database
Display the default key entry as follows:
The encryption algorithms and hashes used for SSL versions 2 and 3 are listed in the following tables.
Key Pair Generation: RSA 512-1024 private key sizes
SSL Version 2
| US version | Export version |
| RC4 US | RC4 Export |
| RC2 US | RC2 Export |
| DES 56-bit | not applicable |
| Triple DES US | not applicable |
| RC4 Export | not applicable |
| RC2 Export | not applicable |
SSL Version 3
| US version | Export version |
| Triple DES SHA US | DES SHA Export |
| DES SHA Export | RC2 MD5 Export |
| RC2 MD5 Export | RC4 MD5 Export |
| RC4 SHA US | NULL SHA |
| RC4 MD5 US | NULL MD5 |
| RC4 MD5 Export | NULL NULL |
| RC4 SHA 56-bit | not applicable |
| DES CBC SHA | not applicable |
| NULL SHA | not applicable |
| NULL MD5 | not applicable |
| NULL NULL | not applicable |
These SSL specifications can also be configured by directly editing the proxy configuration file. For details, see the reference sections in Appendix B. Configuration file directives for the following directives:
128-bit encryption for the Caching Proxy
Only a 128-bit encryption version of the Caching Proxy is being delivered. The 56-bit version is no longer available. If you are updating a previous version, you can install the Caching Proxy directly to your currently installed 128-bit or 56-bit version. If you were previously using a 56-bit (export) browser, you must upgrade to a 128-bit browser in order to take advantage of the 128-bit encryption in the proxy.
After an upgrade from a 56-bit version of the Caching Proxy to the 128-bit version, if the key size used to encrypt certificates is set to 1024, then no configuration change is necessary. However, if the key size is set to 512, in order to take advantage of the proxy's 128-bit encryption, you must create new certificates with a key size of 1024. Create new keys by using the IBM Key Manager utility (iKeyman).
See Key and certificate management for a detailed discussion of the IBM Key Manager utility.
Note that this version of the product does not support encryption on SuSE Linux.
Follow this procedure to enable the SSL handshake routine to be offloaded to a cryptographic hardware card:
A Caching Proxy plug-in is provided with Tivoli Access Manager (formerly Tivoli Policy Director) that enables the Caching Proxy to use Access Manager for authentication and authorization. This plug-in makes it possible for an enterprise that uses Access Manager for Web access control to add Edge technology without having to duplicate work by setting up separate authorization schemes for the proxy server.
For additional information about Tivoli Access Manager, view the product Web site at http://www.ibm.com/software/tivoli/products/. For information about software and hardware requirements and about installing the Access Manager plug-in, refer to the documentation provided with Tivoli Access Manager.
A setup script for the Caching Proxy is provided with the Access Manager plug-in.
Before running the script, do the following:
The set up script is named wslconfig.sh and it is provided in the /opt/pdweb-lite/bin/ directory. Enter the Access Manager administrator ID and the LDAP administrator name when prompted.
The configuration script automatically performs the following steps:
ServerInit /opt/pdweb-lite/lib/wesauth.so:WTESeal_Init /opt/pdweb-lite/etc/ibmwesas.conf
PreExit /opt/pdweb-lite/lib/wesauth.so:WTESeal_PreExit
Authorization * /opt/pdweb-lite/lib/wesauth.so:WTESeal_Authorize
ServerTerm /opt/pdweb-lite/lib/wesauth.so:WTESeal_Term
Creates a Protect statement and Protection setup that forwards all requests to the Access Manager authentication process, as follows:
Protection PROXY-PROT {
ServerId WebSEAL-Lite
Mask All@(*)
AuthType Basic
}
Protect * PROXY-PROT
After configuring the proxy server and the Access Manager plug-in, use the command wslstartwte instead of ibmproxy start to start the proxy server. The wslstartwte command automatically loads environment variables that the Access Manager plug-in requires in order to initialize. If you do not use wslstartwte when starting the proxy server, error messages are displayed about the Access Manager plug-in. The corresponding stop command, ibmproxy stop, is still valid when the plug-in is used.
The PAC-LDAP authorization module enables the Caching Proxy to access a Lightweight Directory Access Protocol (LDAP) server when performing authorization or authentication routines. The module consists of two component sets: a pair of shared libraries that add LDAP functionality to the Caching Proxy API and a Policy Authentication Control (PAC) daemon. A ServerInit directive within the ibmproxy.conf file instructs the shared library to initialize one or more PAC daemons when the caching proxy starts up. The shared libraries read a paccp.conf file to determine the number and characteristics of the PAC daemons. During initialization, the daemon reads the pac.conf file for configuration directives and the pacpolicy.conf for policy information. Then, either an Authentication directive within the ibmproxy.conf file instructs the proxy server to call the shared library whenever authentication is required, or an Authorization directive usurps the caching proxy workflow during standard HTTP request processing.
The process of authentication determines if a supplied set of credentials - user name and password - are valid. This process includes verifying that a user is in the registry and that the supplied password matches the password stored in the registry. These are the actions performed by using the PAC-LDAP module during the authentication step.
When the PAC-LDAP authorization module is enabled for authentication, it becomes the default repository from which user IDs, passwords, and groups are retrieved. As an HTTP request passes through the caching proxy workflow, each Protect directive compares the requested URL to its request template. If a match occurs, the Protect directive invokes a protection schema, which includes the server ID, the type of authentication to use, masking rules to apply to the requesting client, and the locations of the passwords and groups files. If the passwords file is not defined, then the user ID and password are retrieved via the PAC-LDAP authorization module. Type 0, 1, 2, and 3 policies define authentication schemes. If authentication passes, the request is served; otherwise, the caching proxy returns a 401 error to the client.
The process of authorization determines if a user has the necessary permission to access a protected resource. When the PAC-LDAP module is used, this includes applying authorization rules residing in the pacpolicy.conf file for the HTTP request.
When the PAC-LDAP authorization module is enabled for authorization, authorization rules within the pacpolicy.conf file are applied to the HTTP request. As the HTTP request passes through the caching proxy workflow, each Protect directive compares the requested URL to its request template. If a match occurs, the Protect directive invokes a protection schema. In this case, the protection schema is the authorization routine usurped by the PAC-LDAP authorization module. The Authorization directive compares the requested URL to its request template, and, if a match occurs, the PAC-LDAP authorization module is invoked. Type 4 policies defined within the pacpolicy.conf file further refine the authentication required for various URL requests.
LDAP provides interactive access to X.500 directories with a minimal consumption of system resources. The IANA has assigned TCP port 389 and UDP port 389 to LDAP. For more information, refer to RFC 1777, which defines LDAP.
All components of the PAC-LDAP authorization module are automatically installed when the Caching Proxy system of WebSphere Application Server, Version 6.0 is installed. On Linux and UNIX systems, a Caching Proxy library (./lib/) directory, a PAC-LDAP authorization module library (./lib/plugins/pac/) directory, a binary (./bin/) directory, and a configuration (./etc/) directory are created within the /opt/ibm/edge/cp/ directory. Symbolic links are then created from the /usr/lib/, /usr/sbin/, and /etc directories to these product-specific ones.
Directory structure
| Linux and UNIX directory | Windows directory | Content |
|---|---|---|
| /opt/ibm/edge/cp/ | \Program Files\IBM\edge\cp\ | Caching Proxy base directory (cp_root) |
| cp_root/sbin/ | \Program Files\IBM\edge\cp\Bin\ | Caching Proxy binaries and scripts |
| /usr/sbin/ | Symbolic links to cp_root/sbin/ | |
| cp_root/etc/ | \Program Files\IBM\edge\cp\etc\ | Caching Proxy configuration files |
| /etc/ | Symbolic links to cp_root/etc/ | |
| cp_root/lib/ | \Program Files\IBM\edge\cp\lib\ plugins\ | Caching Proxy libraries |
| cp_root/lib/ plugins/pac/ | \Program Files\IBM\edge\ cp\lib\plugins\pac\ | PAC-LDAP authorization module libraries |
| /usr/lib/ | Symbolic links to cp_root/lib/ and cp_root/lib/ plugins/pac/ | |
| cp_root/server_root/pac/data/ | \Program Files\IBM\ edge\cp\server_root\pac\data\ | PAC-LDAP authorization module data storage |
| cp_root/server_root/ pac/creds/ | \Program Files\IBM\ edge\cp\server_root\pac\creds\ | PAC-LDAP authorization module credentials |
LDAP Plug-in files
| Linux and UNIX file name | Windows file name | Description |
|---|---|---|
| libpacwte.so | pacwte.dll | shared library |
| libpacman.so | pacman.dll | shared library |
| pacd_restart.sh | pacd_restart.bat | PAC daemon restart script |
| paccp.conf, pac.conf, pacpolicy.conf | paccp.conf, pac.conf, pacpolicy.conf | configuration and policy files |
To enable secure sockets layer (SSL) connections between the PACD daemon and the LDAP server, you should install the GSKit package that is required by the LDAP client package. GSKit 7 is required and provided by default on the Caching Proxy machine, but it may not be the version that is required by the LDAP client on the machine. It is possible to use different GSKit versions on the same machine for different processes.
Place the GSKit key file to $pacd_creds_dir/pac_keyring.kdb and the password to $pacd_creds_dir/pac_keyring.pwd.
On Linux systems, the LD_PRELOAD environment variable must be configured as follows in order to enable SSL connections between the PACD daemon and the LDAP server. Set the variable to the following value:
LD_PRELOAD=/usr/lib/libstdc++-libc6.1-1.so.2
The GSKit requirement referenced previously in this section also applies to Linux systems.
Three directives, ServerInit, Authorization or Authentication, and ServerTerm must be added to the API directives section of the ibmproxy.conf file to initialize the PAC-LDAP authorization module. To create these directives, either manually edit the ibmproxy.conf file, or if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (Click Server Configuration -> Request Processing-> API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether or not the examples given in this section contain line breaks for clarity.
Note that prototype directives (in the form of comments) are given in the API section of the ibmproxy.conf file. These API directives are in a purposeful order. When adding API directives to enable new features and plug-in modules, order the directives as shown in the prototype section of the configuration file. Alternatively, uncomment and edit, if necessary, API directives to include support for each desired function or plug-in.
The ServerInit directive has three arguments: (1) the fully qualified path of the shared library, (2) the function call, and (3) the fully qualified path of the paccp.conf file. The first and second arguments are delimited by a colon (:). The second and third arguments are delimited by a space. The first and third arguments are system specific and depend on where the plug-in components are installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. When creating a ServerInit directive using the API Request Processing form, both the second and third arguments must be entered in the Function Name field. The third argument is displayed in the IP Template column.
The Authorization directive has three arguments: (1) a request template, (2) the fully qualified path of the shared library, and (3) the function name. HTTP requests are compared to the request template to determine whether the application function is called. The request template can include a protocol, domain, and host; can be preceded by a slash (/); and can use an asterisk (*) as a wildcard. For example, /front_page.html , http://www.ics.raleigh.ibm.com , /pub*, /*, and * are all valid. The function name is the name given to your application function within the program. It is hard coded and must be typed exactly as shown. The first two arguments are delimited by a space. The last two arguments are delimited by a colon (:).
The Authentication directive has two arguments: (1) the fully qualified path of the shared library and (2) the function name. These arguments are delimited by a colon (:). The first argument is system specific and depends on where the shared library is installed. The URL template for the first argument must start at the document root (/) when using Caching Proxy as a reverse proxy. The second argument is hard-coded into the shared library and must be typed exactly as shown.
The ServerTerm directive has two arguments: (1) the fully qualified path of the shared library and (2) the function name. These arguments are delimited by a colon (:). The first argument is system specific and depends on where the shared library is installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. This directive terminates the PAC daemon when the proxy server shuts down. If the owner of the daemon is different from the owner of the proxy server, the proxy server might be unable to stop the daemon, in which case an administrator must manually stop the daemon.
ServerInit path_of_shared_library:pacwte_auth_init path_of_conf_policy_file
Linux and UNIX example:
ServerInit /usr/lib/libpacwte.so:pacwte_auth_init /etc/pac.conf
Windows example:
ServerInit C:\Progra ~1\IBM\edge\cp\lib\plugins\ pac\pacwte.dll:pacwte_auth_init C:\Progra ~1\IBM\edge\cp
Authorization request-template path_of_shared_library:pacwte_auth_policyLinux and UNIX example:
Authorization http://* /usr/lib/libpacwte.so:pacwte_auth_policy
Windows example:
Authorization http://* C:\Program Files\IBM\edge\cp\lib\plugins\ pac\pacwte.dll:pacwte_auth_policy
Authentication BASIC path_of_shared_library:pacwte_auth_policyLinux and UNIX example:
Authentication BASIC /usr/lib/plugins/pac/libpacwte.so:pacwte_auth_policy
Windows example:
Authentication BASIC C:\Program Files\IBM\edge\cp\lib\plugins\ pac\pacwte.dll:pacwte_auth_policy
ServerTerm path_of_shared_library:pacwte_shutdownLinux and UNIX example:
ServerTerm /usr/lib/libpacwte.so:pacwte_shutdown
Windows example:
ServerTerm BASIC C:\Program Files\IBM\edge\cp\lib\plugins\ pac\bin\pacwte.dll:pacwte_shutdown
The PAC-LDAP authorization module configuration and policy files must be manually edited with a text editor. A directive name is separated from its first argument by a colon (:). Multiple arguments are delimited by commas (,). Remarks are included in the configuration and policy file to assist in editing it. Key policy directives are shown below.
The paccp.conf file is read by the shared libraries during the initialization of the Caching Proxy and contains the definitions ([PAC_MAN_SERVER] stanza) of each PAC daemon that will start. Each PAC daemon must have its own [PAC_MAN_SERVER] stanza.
[PAC_MAN_SERVER]
hostname: # name of PAC daemon
port: # port pacd is listening on
[PACWTE_PLUGIN]
hostname_check:[true|false] # enables DNS lookup. Must have
# DNS lookup turned on for ibmproxy to work.
The pac.conf file specifies the LDAP server with which the PAC daemon attempts to connect.
[PAC_MAN_SERVER]
hostname: # name of PAC daemon
port: # port pacd is listening on
conn_type:ssl # comment out if you do not use SSL
authentication_sequence: [primary|secondary|none]
authorization_sequence: [primary|secondary|none]
[LDAP_SERVER]
hostname: # LDAP Server hostname
port:389 # Port LDAP is listening on
ssl_port:636 # SSL port used by the LDAP server
admin_dn: # User with permission to access the LDAP server
# specify admin_dn:NULL to enable anonymous binding
search_base: # Portion of LDAP tree to search for policy info
# If not required, specify search_base:NULL
search_key: # ID field to search
[CACHE]
cred_cache_enabled [TRUE|FALSE] # turn credentials cache on
cred_cache_min_size:100 # minimum number of credentials to cache in pacd
cred_cache_max_size:64000 # maximum number of credentials to cache in pacd
cred_cache_expiration:86400 # when a credential expires
policy_cache_enabled:[TRUE|FALSE] # turns policy cache on/off
policy_cache_min_size:100 # min. number of policy related items to cache
policy_cache_max_size:64000 # max. number of policy related items to cache
policy_cache_expiration:86400 # when a policy related item expires
Every LDAP policy uses the following template within the configuration and policy file. Each policy must begin with the uppercase keyword POLICY in brackets.
[POLICY]
default_policy:[grant|deny] # describes the default policy for users
# that are not described in the POLICY section
pac_client_hotname: # the instances of Caching Proxy that are allowed
# to use a policy list
id: # the id for the LDAP entry or ip/hostname
# (wildcard supported, such as *.ibm.com)
grant:[true|false] # true means to grant access, false means
# to deny access
type:[0|1|2|3|4] # 0 LDAP entry that is a group,
# 1 LDAP entry that is not a group,
# 2 IP address
# 3 hostname
# 4 URL
propagate:[true|false] # true means that the access rights (grant
# or deny) will be propagated to all
# descendants or members
stop_entry:[entry|NULL] # Propagation of the access right stops
# at this entry. If the id is a group,
# stop_entry must be set to NULL.
# stop_entry may be applied to an IP
# address or hostname. Each stop_entry
# must be on its own line
exception_entry:[entry|NULL] # Assignment of the access right skips
# these entries, but continues through their
# subtrees. This may be a list of entries.
# exception_entry may be applied to a group,
# IP address, or hostname. Each
# exception_entry must be on its own line.
Exception_type:
Exception:
The wildcard (*) is supported only for the last position of an IP address or the first position of a host name in the id and stop_entry directives. Wildcards are not supported in the exception_entry. Wildcards are not supported for any LDAP entries in any fields.
Multiple policies are supported, and the value false always takes priority if policies conflict. In other words, a single denial in any policy blocks access. The order in which the policies are listed in the configuration and policy file is irrelevant and does not establish a priority.
For a set of policy examples, refer to the pacpolicy.conf file in the configuration files directory.
Create a plain text file named pac_ldap.cred in /cp_root/server_root/pac/creds. This file contains the password corresponding to the user name in the admin_dn directive, which is in the pac.conf file.
The PAC daemon encrypts the password the first time that it reads the file.
To create the file pac_ldap.cred on Linux and UNIX platforms, issue the following commands:
cd cp_root/server_root/pac/creds echo "password" > pac_ldap.cred chown nobody pac_ldap.cred chgrp nobody pac_ldap.cred (on SuSE Linux, use chgrp nogroup pac_ldap.cred.)
To create the file on a Windows platform, type the password in a text file and store the file in the server_root\pac\creds\ directory.
The LDAP authorization daemon runs as the pacd process. You can restart the LDAP authorization daemon without interrupting Caching Proxy by using scripts that are provided. Run the pacd script as follows:
/usr/sbin/pacd_restart.sh pacd_user_idC:\Program Files\IBM\edge\cp\Bin\pacd_restart.bat CP_install_root
kill -15 pacd_process_IDOn HP-UX: The PAC-LDAP plug-in and pacd may not load all their dependent shared libraries at runtime. Before using them, ensure that the system variables are set as follows
SHLIB_PATH=/usr/lib:/usr/IBMldap/lib PATH=/usr/IBMldap/bin:$PATH PATH=/usr/IBMldap/bin/usr/IBMldap/
is the default installation path for the LDAP client on HP-UX. Please adjust PATH and SHLIB_PATH accordingly if the LDAP client is installed in a different location. Without setting these variables, the following errors may occur:
"Serverinit Error: server did not load functions from DLL module /opt/ibm/edge/cp/lib/plugins/pac/libpacwte.sl"
"/usr/lib/dld.sl: Can't find path for shared library: libibmldap.sl /usr/lib/dld.sl: No such file or directory Abort"
On AIX: When starting pacd with IBM Tivoli Directory Server 5.2, the PAC-LDAP module may be unable to load resulting in the following error:
exec(): 0509-036 Cannot load program /usr/sbin/pacd because of the following errors:
0509-022 Cannot load module /usr/lib/libpacman.a.
0509-150 Dependent module libldap.a could not be loaded.
0509-022 Cannot load module libldap.a.To work around this problem, create the following symbolic: ln -s /usr/lib/libibmldap.a /usr/lib/libldap.a
This part provides instructions for monitoring the Caching Proxy using logs and the Server Activity Monitor.
This part contains the following topics:
Using the Server Activity Monitor
To customize logging, you can use the Configuration and Administration forms or edit directives in the proxy configuration file. You can set the following options:
The Caching Proxy can create three types of access logs, in addition to an event log and an error log:
The Caching Proxy creates new log files each day at midnight. If the proxy is not running at midnight, new logs are created the first time it is started that day. You can specify the directory and file name prefix for each log file; each log file that is created also contains a date suffix in the form .Mmmddyyyy (for example, .Apr142000).
Because logs can use a large amount of space, consider storing your log files on a storage device that is separate from the operating system and cache, to prevent errors. In addition, configure log maintenance routines, as specified in Maintaining and archiving logs.
To specify the basic configuration of the proxy server logs, in the Configuration and Administration forms, select Server Configuration -> Logging -> Log Files. Specify the path and file name for each log file that you want to use. The current file name for each log is displayed in the corresponding text box; if you have not specified a path, the default path is displayed.
Information that is logged into the proxy logs is not automatically written to the system log, but you can configure the Caching Proxy to write to the system log in addition to or instead of to its own logs. On the Log Files form, select the Log information to Syslog check box. Note that the system log must be created before this option is chosen.
To specify that proxy server log information is written only to the system log, you must edit the proxy configuration file; see the reference section for LogToSyslog -- Specify whether to send access information to the system log (Linux and UNIX only).
Related configuration file directives
To set up logs by using the proxy configuration file, see the reference sections in Appendix B. Configuration file directives for the following directives:
Access logs record the activity of the host machine, the proxy, and the cache. For each access request that your proxy receives, an entry in the appropriate access log includes the following information:
Access errors are logged in the server's error log.
There are several reasons to restrict what is logged:
The log files of a busy server can become large enough to fill the server's disk space. By default, all access requests are logged, which means that log entries are made not only for an HTML page but for each image that the page contains. Including only meaningful access requests can significantly reduce the number of entries in the log. For example, you might want to configure your access logs so that they include log entries for HTML page access requests, but not for requests for GIF images.
For example, if you are interested in who is accessing your server from outside your company, you can filter out access requests that originate from IP addresses within your company. If you are interested in finding out the size of the audience for a particular Web site, you can create an access log that shows only the access requests for that URL.
Information that is excluded from access logs is not recorded in any access report and is not available for future use. Therefore, if you are unsure about how much access information you need to track, apply exclusion filters conservatively until you gain experience in monitoring your server.
Access log entries can be filtered based on any of the following attributes:
To specify your filters, in the Configuration and Administration forms, select Server Configuration -> Logging -> Access Log Exclusions. Specify only those exclusions that you want. You do not need to use all the categories.
Click Submit.
Related configuration file directives
To set access log filters by using the proxy configuration file, see the reference sections in Appendix B. Configuration file directives for the following directives:
All logs are enabled in the Caching Proxy default configuration. They are stored in the logs/ subdirectory of the installation directory. The default paths are the following:
Each log file name is a combination of the base name and a date suffix in the form .Mmmddyyyy, for example, proxy.Feb292000.
Logs are stored in the common file format by default. A combined log format is also available and can be set by adding the following line to the proxy configuration file (ibmproxy.conf).
LogFileFormat combined
The combined log format is similar to the common format but has added fields that show the referrer, the user agent, and cookie information. Local time format is the default time format.
By default, all access requests are recorded in the appropriate access log, and no access information is recorded in the system log. Error log information is written to the error log only, and event log information is written to the event log only.
In the default configuration, logs are not archived or deleted.
The Caching Proxy uses a plug-in to manage logs. For further information, see the reference page in Appendix B. Configuration file directives for the configuration file directive Midnight -- Specify the API plugin used to archive logs.
You can specify how to archive and remove daily logs. The basic options are:
By default, the current and previous days' logs are never deleted by any maintenance agent. All of the current day's logs and the previous day's cache access log are never compressed by any maintenance agent.
To configure log maintenance, in the Configuration and Administration forms, select Server Configuration -> Logging -> Log Archiving. In this form, use the drop-down box to specify the maintenance method.
Related configuration file directives
To configure log archiving using the proxy configuration file, see the reference pages in Appendix B. Configuration file directives for the following directives:
The following example shows how you can customize logging to meet your needs. Suppose you have just purchased and installed the Caching Proxy. You want to set up your server to log access and error information with the following requirements:
To configure the Caching Proxy to keep logs according to these criteria, in the Configuration and Administration forms, select Server Configuration -> Logging.
Following these directions produces the following lines in the proxy configuration file:
LogArchive purge PurgeAge 30 PurgeSize 25 AccessLogExcludeURL *.gif NoLog 130.128.*.* AccessLogExcludeReturnCode 300
The Caching Proxy's Server Activity Monitor displays server and network performance statistics, server and network status, and access log entries. The monitor can be used remotely and does not need to be on the same machine that is running the proxy server. The Server Activity Monitor is enabled by default and requires no configuration.
There are two ways to open the Server Activity Monitor:
http://your.server.name/Usage/Initial
Unlike other forms in the configuration client, the forms in this category do not set configurations for the server, but display data about server usage. These forms provide considerably more information than can be displayed in a single console window.
The following sections show the type of information that the Server Activity Monitor provides, and suggest how to use the information to tune performance.
Several Server Activity Monitor pages are available:
Each of the pages has a Refresh button, which can be used to update the information.
Activity Statistics
Table 4 shows an example of the Activity Statistics page.
| Activity Statistics | |
|---|---|
| Connections | 1 Active, 431 maximum |
| Response time | Not available |
| Throughput | 0 connections/second |
| Requests processed today | 0 |
| Total requests processed | 114 |
| Request errors | 3 |
These server activity statistics can be used to monitor the server traffic in terms of number of access requests, response time, throughput, requests processed today, total requests processed, and errors. The following configuration changes affect the statistics on the Activity page.
Network Statistics
Table 5 shows an example of the Network Statistics page.
| Network Statistics | |
|---|---|
| Outgoing data: | 1K bytes/second |
| Incoming data: | 1K bytes/second |
| Bandwidth saved: | 3 K bytes (0K bytes/second) |
| Bandwidth saved today: | 0 K bytes (0 K bytes/second) |
The Network Statistics form provides information about the network the proxy is running on, including the data speeds for bytes sent and received.
Access Statistics
The Access Statistics page displays the 20 most recent entries in the access logs. This page displays recent entries in the Proxy Access log (in black type) and the cache access log (in blue type). You can customize what is displayed by customizing what is logged. For more information on the access log statistics, see Access log filters.
Proxy Access Statistics
The Proxy Access Statistics form provides information on the proxy activity, such as which URLs were requested and whether they were served from the cache. Following the URLs are the return codes given to the clients and the file size in bytes. The following settings can improve the proxy access statistics:
Cache Statistics
If caching is enabled, the Cache Statistics page shows recent cache access information. It provides information on the cache and index, including the following:
Many cache configuration options change the cache statistics results (see Configuring proxy server caching).
Cache Refresh Summary
If the cache agent is configured to preload files in the cache, the Cache Refresh Summary page shows information on the most recent run of the cache agent. The cache agent must have run at least once to display any information. To change the way the cache refresh agent works, consider the following:
This topic provides a reference for proxy server commands.
Use the cgiparse command to parse the QUERY_STRING environment variable for CGI scripts. If the QUERY_STRING environment variable is not set, the command reads CONTENT_LENGTH characters from its standard input. All returned output is written to its standard output.
cgiparse -Flag [Modifier]
Flags, their one-character equivalents (-k -f -v -r -i -s -p -c -q -P) and their function, include:
eval 'cgiparse -init'
This sets the QUERY_STRING environment variable, regardless of whether the GET or POST method was used.
cgiparse can be called multiple times in the same script when the GET method is used, but it must only be called once if the POST method is used. With the POST method, after standard input is read, the next cgiparse finds standard input empty and waits indefinitely.
The following examples ignore the fact that, in reality, QUERY_STRING is already set by the server. In the following examples, $ is the Bourne shell prompt.
$ QUERY_STRING="is+2%2B2+really+four%3F" $ export QUERY_STRING $ cgiparse -keywords is 2+2 really four? $
$ export QUERY_STRING="name1=Value1&name2=Value2%3f+That%27s+right%21"; $ cgiparse -form FORM_name1='Value1'; FORM_name2='Value2? That'\'s right!' $ eval `cgiparse -form` $ set | grep FORM FORM_name1="Value1" FORM_name2="Value2? That's right!" $
$ QUERY_STRING="name1=value1&name2=Second+value%3F+That'\'s%27s $ cgiparse -value name1 value1 $ cgiparse -value name2 Second value? That's right! $
Use the cgiutils command in no-parse header programs to produce a full HTTP 1.0 response.
cgiutils -Flag [Modifier]
If Modifier contains blanks, enclose it in quotation marks ("").
cgiutils -ct text/html
If you omit the type/subtype, the MIME content type is set to the default text/plain. This example sets the MIME content type to text/plain.
cgiutils -ct
cgiutils -ce x-compress
cgiutils -cl en_UK
cgiutils -expires 2 days 12 hours
The cgiutils command adds the time you specify to the current Greenwich Mean Time to determine the expiration date. The expiration date is put in the Expires: header in the HTTP format.
cgiutils -expires "1 year 3 months 2 weeks 4 days 12 hours 30 mins"
cgiutils -status 200 -reason "Virtual doc follows" -expires now
This might produce headers similar to these:
HTTP/1.0 200 Virtual doc follows MIME-Version: 1.0 Server: IBM-ICS Date: Tue, 05 Jan 1996 03:43:46 GMT Expires: Tue, 05 Jan 1996 03:43:46 GM
The cgiutils command automatically produces the Server: header because it is available in the CGI environment. The Date: field is also automatically generated unless the -nodate flag is specified.
This includes a blank line after the output to mark the end of the MIME header section. If you want to follow this with some more headers yourself, use the -noel (NO-Empty-Line) flag as shown in the next example.
cgiutils -noel -expires "2 days" -nodate
HTTP/1.0 200 Virtual doc follows MIME-Version: 1.0 Server: IBM-ICS Expires: Tue, 07 Jan 1996 03:43:46 GMT
Use the htadm command to control your server password files. Your server uses password files to control access to your files. You can add a user name to a password file, delete a user from a password file, verify a user's password, and create an empty password file. You can also change a password for a user by first deleting the user's password and then creating a new one.
htadm -Flag [Modifier]
Use only alphabetic and numeric characters for the user name; do not use special characters.
The command fails if there is already a user of the same name in the password file.
Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.
Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.
htadm -adduser /opt/ibm/edge/cp/server_root/protect/heroes.pwd clark superman "Clark Kent"
htadm -adduser "C:\Program Files\IBM\edge\cp\server_root\protect\ heroes.pwd" clark superman "Clark Kent"
htadm -deluser /opt/ibm/edge/cp/server_root/protect/
heroes.pwd clark superman "Clark Kent"htadm -deluser "C:\Program Files\IBM\edge\cp\server_root\protect\
heroes.pwd" clark superman "Clark Kent"Use the htcformat command to prepare a raw device or file to hold the proxy cache. This format command must be used before the device is specified for use with the proxy cache.
The device path must specify the raw device. See your file system documentation for details on how to access raw devices. Examples are available in Configuring proxy server caching.
The minimum size for a Caching Proxy cache is 16392 KB, which is 2049 blocks.
htcformat device [-blocksize <block size>] [-blocks number of blocks] htcformat -file filepath [-blocksize block size] -blocks number of blocks
The caching system additionally segregates cache files or devices into containers for indexing and garbage collection. The size of containers is set to a certain number of blocks; container size cannot be configured. In order for garbage collection to run, a minimum of two containers is required; the minimum cache size is 16392 KB.
The htcformat command rejects a format request that yields a cache device with fewer than two containers.
The following example formats a disk partition called c0t0d0s0 on Solaris.
htcformat /dev/rdsk/c0t0d0s0
The following example formats a disk partition called lv02 on AIX.
htcformat /dev/rlv02
The following example formats a disk partition called d: on Windows.
htcformat \\.\d:
The following example formats a file named filecache to be about 1 GB large.
htcformat -file /opt/ibm/edge/cp/filecache -blocks 131072
Use the ibmproxy command to start the server.
You can set all these flags (except -r) using the directives in the server configuration file.
It is common practice to create a file named README containing instructions or notices to be read by anyone new to the directory. By default, the ibmproxy command embeds any README file in the hypertext version of a directory. The README file instructions can also be set with the DirReadme configuration directive.
ibmproxy [-Flag [-Flag [-Flag..]]]
Because the http daemon must read the configuration file the server is currently using in order to access the PidFile, you must specify the same configuration file when restarting. If you used the -r flag and a specific configuration file when you started the server, then you must specify this flag and the same file with -restart.
Signal handling options also exist on Linux and UNIX platforms only. On Linux and UNIX platforms, the following options are available.
ibmproxy -p 8080 -r /usr/etc/ibmproxy.conf
startsrc -s ibmproxy
If the default configuration file does not exist, the ibmproxy command exports the /Public directory tree. This tree can contain soft links to other directory trees.
This topic describes the directives contained in the ibmproxy.conf configuration file.
Use this information as a reference if you configure the server by editing the ibmproxy.conf file. If you use the Configuration and Administration forms, you do not need to refer to this chapter.
Directives are listed alphabetically.
Some directives are not refreshed when the server is restarted. If the following directives are changed while the server is running, you must manually stop and then manually start the server again. (See Starting and stopping the Caching Proxy.)
| Directive group | Directives |
| CGI | DisinheritEnv, InheritEnv |
| Caching | Caching |
| Logging | AccessLog, CacheAccessLog, ErrorLog, ProxyAccessLog, ServerRoot |
| Network Access | BindSpecific, Hostname, ListenBacklog, Port |
| Performance | MaxActiveThreads |
| RTSP | All RTSP directives |
| SSL | All SSL directives |
| Linux and UNIX Process Control | GroupId, UserId |
| Miscellaneous | TransparentProxy |
This appendix provides the following information about each directive:
DirectiveName valueThese are the original values coded in the default configuration file. Change only the parts of the configuration file that you want to be different from the defaults. A directive that has no default value initially coded appears in the file preceded by a comment marker (#). If you want to specify a value for the directive, remove the comment marker and add the value to the line in the configuration file.
The following list includes values that are accepted in the configuration file:
All entries are converted to seconds and added together.
When editing the configuration file, remember the following requirements:
The Caching Proxy directives follow.
Use this directive to serve files to the client even if the MIME type of the file does not match an ACCEPT: header sent by the client. If this directive is set to OFF, files whose MIME types differ from the types that the client can accept are not displayed. An error page is displayed instead.
AcceptAnything {off | on}
AcceptAnything off
AcceptAnything on
Use this directive to specify the directory and file where you want the server to log access statistics. By default, the server writes an entry to this log each time a client sends the server a request for data stored on the local server. Typically, these entries include only requests from the configuration client or accesses when the Caching Proxy machine is used as an origin server. This log does not contain proxy or cache access information.
Use the NoLog directive to specify clients whose requests you do not to be logged. For a description of the NoLog directive, refer to NoLog -- Suppress log entries for specific hosts or domains that match a template.
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
It is a good idea to remove old log files because they can use a significant amount of space on your hard drive.
AccessLog /directory_path/logfile_name
AccessLog /logs/accesslog
Use this directive to prevent the logging of requests made by a specific method for access to files or directories. For example, you might not want to log DELETE requests for files or directories.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple methods on the same directive if you separate them by one or more spaces.
AccessLogExcludeMethod method [...]
AccessLogExcludeMethod GET AccessLogExcludeMethod PUT AccessLogExcludeMethod POST AccessLogExcludeMethod DELETE AccessLogExcludeMethod GET PUT
None. The server includes in the access log the files and directories requested by all types of methods.
Use this directive to specify that you do not want record in the Proxy access log requests for access to directories or files of a specified MIME type. (Examples of MIME types are text/html, image/gif, and image/jpeg.) For example, you might not want to log access requests for GIF images.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple MIME types on the same directive if you separate them by one or more spaces.
AccessLogExcludeMimeType MIME_type [...]
AccessLogExcludeMimeType image/gif AccessLogExcludeMimeType text/html AccessLogExcludeMimeType image/gif text/html
None. The access log includes requests to the server for files and directories of all MIME types.
Use this directive to specify that you do not want to log access requests that fall within a specified range of error code numbers. These error code numbers are proxy server status codes. You cannot specify individual codes. Specifying 300 indicates that you want to exclude access requests with redirection return codes (301, 302, 303, and 304).
You can have multiple occurrences of this directive in your configuration file. You can also put multiple return codes on the same directive if you separate them by one or more spaces.
AccessLogExcludeReturnCode range
AccessLogExcludeReturnCode 300
None. The access log includes all requests to the server, regardless of the code.
Use this directive to specify that you do not want to log requests for access to specific files or directories that match a specified URL template. For example, you might not want to log access requests for GIF files, or you might not want to log access requests to a particular file or directory on your server.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple entries for the same directive if you separate them by one or more spaces.
AccessLogExcludeURL file_or_type [...]
AccessLogExcludeURL *.gif AccessLogExcludeURL /Freebies/* AccessLogExcludeURL *.gif /Freebies/*
None. The server logs requests for access to all files and directories.
Use this directive to specify that you do not want to log access requests made by specific user agents (for example, Internet Explorer 5.0).
You can have multiple occurrences of this directive in your configuration file. You can also put multiple entries for the same directive if you separate them by one or more spaces.
AccessLogExcludeUserAgent user_agent [...]
AccessLogExcludeUserAgent *Mozilla/2.0 AccessLogExcludeUserAgent *MSIE 5*
By default, the ibmproxy.conf file contains the following definitions for the AccessLogExcludeUserAgent directive:
AccessLogExcludeUserAgent IBM_Network_Dispatcher_HTTP_Advisor AccessLogExcludeUserAgent IBM_Network_Dispatcher_WTE_Advisor
The user agents listed above are those defined for certain Load Balancer advisors that typically sit in front of the Caching Proxy server. To improve performance by minimizing the number of writes to the log, these user agents are not logged. By default, the server logs access requests made by all other user agents.
Use this directive to specify an icon to use for aligning the headings on directory listings that are returned when the server acts as a proxy for FTP requests. The icons appear beside the associated files to help users differentiate the files.
The icon can either be a blank icon or another icon that you specify to appear on the headings of your directory listings. For proper alignment, the icon you use must be the same size as the other icons you are using on your directory listings.
AddBlankIcon icon_URL alternative_text
Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server.
AddBlankIcon logo.gif logo
The default does not specify alternative text because the icon is blank.
Use this directive to specify an icon for representing a directory on a directory listing.
AddDirIcon icon_URL alternatIve_text
Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddDirIcon direct.gif DIR
Use this directive to bind files with a particular suffix to a MIME encoding type. This directive is seldom used.
AddEncoding .extension encoding
AddEncoding .qp quoted_printable
AddEncoding .Z x-compress
Use this directive to specify icons for representing files with a specific MIME content type or encoding type. The server uses the icons on directory listings, including FTP directory listings.
AddIcon icon_URL alternative_text MIME_type_template
Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddIcon video_file.m.pm.gif MOV video/*
Numerous defaults are set for the AddIcon directive in the ibmproxy.conf configuration file.
Use this directive to specify an icon for representing a parent directory on directory listings.
AddParentIcon icon_URL alternative_text
Specifies the last part of the URL for the icon. The server adds this value to the /icons/ directory to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddParentIcon parent.gif UP
AddParentIcon dir-up.gif UP
Use this directive to bind files with a particular suffix to a MIME type and subtype. You can have multiple occurrences of this directive in your configuration file. The server provides defaults for the most-commonly used suffixes.
AddType .extension type/subtype encoding [quality[ character_set]]
Any other value of encoding receives the same treatment as binary and is passed in MIME headers as a content encoding MIME header. The specification 7bit and 8bit is not sent in MIME headers.
AddType .ps application/postscript 8bit 1.0 AddType *.* application/binary binary 0.3
AddType .bin application/octet-stream binary 0.8
Numerous default settings for the AddType directive are contained in the configuration file (ibmproxy.conf).
Use this directive to specify an icon for representing files with an unknown file type on a directory listing.
AddUnknownIcon icon_URL alternative_text
Specifies the last part of the URL for the icon. The server adds this value to /icons/ to form the complete URL request. If the request is for a local file, the server translates the request through the mapping directives. For the icon to be retrieved, the mapping directives must allow the request to be passed.
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddUnknownIcon saywhat.gif unknown
Use this directive to specify a port that administrators can use to access server status pages or configuration forms. Requests to this port are not queued with all other incoming requests on the standard port or ports that are defined with the Port directive. However, requests on the AdminPort go through the same normal access-control and request-mapping rules as, for example, Pass, Exec, Protect.
AdminPort port_number
AdminPort 2001
None
Use this directive to specify whether files returned by the origin server and marked noncacheable are to be cached anyway. Noncacheable files that are cached according to this directive are marked as must revalidate. Each time the file is requested, the proxy server sends an If-Modified-Since request to the origin server to revalidate the response before the response is served from the cache. Currently, the only noncacheable files affected by this directive are responses from the origin server that contain a cache-control: no-cache header. This directive can be specified multiple times.
AggressiveCaching url_pattern
AggressiveCaching http://www.hosta.com/* AggressiveCaching http://www.hostb.com/*
For backwards compatibility, the previous syntax for this directive (AggressiveCaching {on | off}) is now treated as follows:
None
For requests that contain a directory name but not a file name, the AlwaysWelcome directive controls whether the server looks in the directory for a welcome file to return. By default, AlwaysWelcome is set to a value of on. This means the server always looks in the requested directory for a file matching a name specified on a Welcome directive. If a match is found, the file is returned to the requester. If the server finds more than one match between files in a directory and file names on Welcome directives, the order of the Welcome directives determines which file is returned. The server uses the Welcome directive closest to the top of the configuration file.
AlwaysWelcome on | off
AlwaysWelcome on
Use this directive to specify URLs for which the Caching Proxy appends the carriage return and line-feed characters to the end of the body of a POST request. This directive can be specified multiple times.
appendCRLFtoPost url_pattern
appendCRLFtoPost http://www.hosta.com/
None
Use this directive to specify the remote cache array to be shared by the servers.
ArrayName array_name
None
Use this directive to specify a customized application function you want the server to call during the Authentication step of the server request process. This code is executed according to the authentication scheme. Only BASIC authentication is supported.
Authentication type /path/file:function_name
Authentication BASIC /ics/api/bin/icsextpgm.so:basic_authentication
None
Use this directive to specify a customized application function that the server calls during the Authorization step of the server request process. This code verifies that the requested object can be served to the client.
Authorization request_template /path/file:function_name
Authorization /index.html /api/bin/icsextpgm.so:auth_url
None
Use this directive to turn cache refreshing on or off. If refreshing is turned on, the cache content is refreshed automatically. If refreshing is turned off, the cache agent is not invoked and all of its settings are ignored. If you are starting the cache agent by another method, for example, by using a cron job on Linux and UNIX systems, set this directive to off.
AutoCacheRefresh {on | off}
AutoCacheRefresh On
Use this directive on a multihomed system to specify whether the server listens on a single network address. If you set the value to On, the server binds to the IP address specified in the Hostname directive, instead of binding to all local IP addresses.
If this directive is not specified, the server binds to the default Hostname.
If you change this directive, you must manually stop and then start the server again. The server does not make the change if you only restart it. (See Starting and stopping the Caching Proxy.)
BindSpecific {on | off} [OutgoingSrcIp ip_addr | host_name]
BindSpecific Off
This directive specifies the size (in bytes) of blocks in the medium of the caching device. By default, the value is 8192. Because it is the only size supported, do not change the value. For more information, see the reference section for htcformat command.
BlockSize size
By default, there is no setting for BlockSize in the configuration file. (The default value is 8192.)
Use this directive to specify the path and file name where you want the server to store a log of accesses to the proxy cache. This directive is valid only if the server is running as a proxy. See CacheRefreshTime -- Specify when to start the cache agent for more information.
To enable logging of requests to the proxy cache, the Caching directive must be set to ON, and values must be set for the CacheMemory and the CacheAccessLog directives. Optionally, one or more cache devices can be defined by using the CacheDev directive.
The value of CacheAccessLog can be either an absolute path or a path relative to ServerRoot. (One example is shown of each.)
CacheAccessLog path/file
CacheAccessLog /absolute/path/logfile CacheAccessLog /logs/logfile
Use this directive to specify the cache algorithm that the server uses during garbage collection.
CacheAlgorithm {bandwidth | responsetime | blend}
CacheAlgorithm bandwidth
Use this directive to specify whether the generated cache file names are based on the incoming URL of the request.
If this directive is set to on, the cache file names are generated based on the incoming URL. If this directive is set to off, the incoming URL is first passed through all applicable name translation plugins, MAP rules, and PROXY rules, and the generated cache file name is based on the resulting URL.
CacheByIncomingUrl {on | off}
CacheByIncomingURL off
Use this directive to specify how long you want the server to keep cached files. When garbage collection runs, the server deletes cached files that have exceeded this time, regardless of the files' expiration date. Any time a file is requested that has been in the cache longer than the specified time, the server will revalidate the file to ensure it is valid before serving it.
CacheClean time_specification
CacheClean 2 weeks
CacheClean 1 month
Use this directive to set a default expiration time for files for which the server did not provide either an Expires or a Last-Modified header. Specify a URL template and the expiration time for files with URLs that match the template. Multiple occurrences of this directive can be included in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.
CacheDefaultExpiry URL_template expiration_time
CacheDefaultExpiry ftp:* 1 day CacheDefaultExpiry gopher:* 2 days CacheDefaultExpiry http:* 0 days
Use this directive to specify a cache storage device. Either a file or a raw disk partition can be specified. On AIX platforms, a raw logical volume can be specified. (If a memory cache is not used, raw disk caching yields the best performance.)
Note that cache devices must be prepared before they are specified. To prepare a cache device, format it by using the htcformat command. For more information, see htcformat command.
Multiple cache devices can be specified. Each device is associated with the same CacheMemory and BlockSize values. However, each cache device incurs a memory overhead in the proxy server machine of about 8 MB. Fewer large devices are more efficient than more smaller devices. For best efficiency, use an entire disk as one large partition with nothing else on the disk. More information about cache storage is included in Optimizing disk cache performance.
CacheDev {raw_disk_partition | file}
AIX: CacheDev /dev/rlv02
HP-UX: CacheDev /dev/rdsk/c1t15d0
Linux: CacheDev /opt/IBMWTE/filecache1
Solaris: CacheDev /dev/rdsk/clt3d0s0
Windows: CacheDev \\.\E:
None
Use this directive to specify whether the server returns cached files that have expired. Set the value to Off if you want the server to be able to return expired files. Use the default value of On if you want the proxy to check with the origin server for a more recent version when a client requests an expired file. Generally, administrators do not want the server to return expired files except possibly when they are demonstrating the server and do not particularly care about the content being returned.
CacheExpiryCheck {on | off}
CacheExpiryCheck On
Use this directive to specify the maximum size of files to be cached. Files larger than this size are not cached. The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter whether the specification includes a space between the number and the unit of measurement (B, K, M, G).
CacheFileSizeLimit maximum {B | K | M | G}
CacheFileSizeLimit 4000 K
Use this directive to specify the value to use for calculating expiration dates for specific URLs or for all the URLs that match a template.
HTTP servers frequently give the last-modified time for a file but not an expiration date. Similarly, FTP files can have a last-modified time stamp, but not an expiration date. The Caching Proxy calculates an expiration date for these files based on the last-modified time. It uses the last-modified time to determine the length of time since the file was modified and multiplies that by the value on a CacheLastModifiedFactor directive. The result of this calculation is the lifetime of the file, or the length of time before the file becomes stale.
You can also specify off or -1 to turn the directive off and not calculate an expiration date. The proxy server reads the CacheLastModifiedFactor directives in the order they appear in the configuration file. It uses the first directive that it can apply to the cached file.
CacheLastModifiedFactor url factor
CacheLastModifiedFactor *://hosta/* off CacheLastModifiedFactor ftp://hostb/* 0.30 CacheLastModifiedFactor ftp://* 0.25 CacheLastModifiedFactor http://* 0.10 CacheLastModifiedFactor * 0.50
CacheLastModifiedFactor http://*/ 0.10 CacheLastModifiedFactor http://*.htm* 0.20 CacheLastModifiedFactor http://*.gif 1.00 CacheLastModifiedFactor http://*.jpg 1.00 CacheLastModifiedFactor http://*.jpeg 1.00 CacheLastModifiedFactor http://*.png 1.00 CacheLastModifiedFactor http://*.tar 1.00 CacheLastModifiedFactor http://*.zip 1.00 CacheLastModifiedFactor http:* 0.15 CacheLastModifiedFactor ftp:* 0.50 CacheLastModifiedFactor * 0.10
The default of 0.14 causes files modified a week ago to expire in one day.
Use this directive to specify whether to cache URLs from hosts in the same domain as the proxy. Local sites on an intranet usually do not need to be cached because the internal bandwidth is sufficient to load URLs quickly. Not caching local sites saves cache space for URLs that take longer to retrieve.
CacheLocalDomain {on | off}
CacheLocalDomain on
If the backend server has the capability of returning language variants to customers for the same URL, use this directive to support caching different languages for the same URL. The directive allows Caching Proxy to verify the language preference in the requests with the language of the cached response.
When CacheMatchLanguage is enabled, before Caching Proxy loads the cached content, it compares the language preference in your request's Accept-Language header with the language of the cached content. Caching Proxy also compares the preference distance. If a preference distance is less than a specified limit, it returns the cached copy; otherwise, the proxy forwards the request to the backend server to get a fresh copy in your requested language.
CacheMatchLanguage {on | off} lang-prefer-distance-limit special-id-for-all-lang
The following is a configuration example of the directive, cache object, and the request.
CacheMatchLanguage On 0.2
If the cache object is simplified Chinese (zh_cn) and the request is:
GET / HTTP/1.1 ... Accept-Language: en_US;q=1.0, zh_cn;q=0.7, ja;q=0.3 ....
For this request, the customer requests a page in English (with code and quality en_US/1.0), then simplified Chinese (with code and quality zh_cn/0.7), and then Japanese (its code and quality is ja/0.3). The cached object is in simplified Chinese. The preference distance between best expected quality and matched language quality is 1.0 - 0.7 = 0.3. Because the limit is set to 0.2 by the CacheMatchLanguage directive, and 0.3 is greater than the limit, the proxy asks the server for a new copy of that URL instead of returning the cached object.
If the server does not specify a language or does not specify special-id-for-all-lang in the Content-Language header when returning a response, when the next request comes in, the proxy does not match language preference and returns the cached copy.
CacheMatchLanguage off
Use this directive to define the maximum length of time files can stay in the cache. The lifetime of a cached file defines the length of time it can be served from the cache without checking the origin for updates. In some cases, the computed lifetime for a cached file can be longer than you want to keep the file. The lifetime of the file, either specified by the origin or computed by the Caching Proxy, cannot exceed the limit specified by the CacheMaxExpiry directive.
Multiple occurrences of this directive are allowed in the configuration file. Include a separate directive for each template.
CacheMaxExpiry URL lifetime
CacheMaxExpiry ftp:* 1 month CacheMaxExpiry http://www.santaclaus.np/* 2 days 12 hours
CacheMaxExpiry 1 month
Use this directive to specify the amount of memory to associate with the cache. For optimum performance of disk caches, a minimum cache memory value of 64 MB is recommended for cache infracture support, including the cache index. As the cache size increases, the cache index increases, and more cache memory is required to store the index. A cache memory value of 64 MB is large enough to provide cache infrastructure support and store a cache index for a disk cache of up to approximately 6.4 GB. For larger disk caches, the cache memory should be 1% of the cache size.
If memory caching is used, set this directive to include both the cache and the amount of memory needed for the cache index.
The maximum recommended value for this directive is 1600 MB. This limit is determined by the fact that the Caching Proxy, as a 32-bit application, can use a maximum of 2 GB of memory. If the amount of memory required for the cache plus the amount of memory used for routine processing approaches or exceeds 2 GB, the Caching Proxy does not operate normally.
The amount can be specified in one of the following units: bytes (B), kilobytes (K), megabytes (M), and gigabytes (G).
CacheMemory amount {B | K | M | G}
CacheMemory 64 M
Use this directive to specify URLs for files whose expiration is to be overridden. Some sites set files to expire before the end of their lifetime, requiring the server to request the file more frequently. The CacheMinHold directive causes the expired file to be held in the cache for the specified amount of time before it is requested again. This directive can be specified multiple times.
CacheMinHold http://www.cachebusters.com/* 1 hour
None
Use this directive to specify whether the proxy server retrieves files from remote servers. The default value (Off) enables the server to retrieve files from remote servers. The value On sets the server to run in stand-alone cache mode. This means that the server can return only files already stored in its cache. Typically, when running the server in this mode, you also set the CacheExpiryCheck directive to Off.
Running the server in stand-alone cache mode can be useful if you are using the server for demonstrations. If you know that all the files you want to use for a demonstration are stored in the cache, then you do not need a network connection.
CacheNoConnect {on | off}
CacheNoConnect Off
Use this directive to specify that only files with URLs that match a specified template are to be cached. You can use multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. If no value is set for this directive, any URLs that do not match a NoCaching directive can be cached. If neither the CacheOnly nor the NoCaching directive is included in the configuration file, any URL can be cached.
CacheOnly url_pattern
CacheOnly http://realstuff/*
None
Use this directive to specify the URLs for which responses to query requests are cached. If the value PUBLIC url_pattern is used, responses to GET requests that contain a question mark in the URL are cached if the origin server includes the cache-control: public header and the response is otherwise cacheable. If the value ALWAYS url_pattern is specified, responses to GET requests that contain a question mark in the URL are cached if the responses are otherwise cacheable.
This directive can be specified multiple times.
CacheQueries {ALWAYS | PUBLIC} url_pattern
CacheQueries ALWAYS http://www.hosta.com/* CacheQueries PUBLIC http://www.hostb.com/*
None
Use this directive to specify when to check with the origin server to determine whether a cached file is changed.
Although the CacheClean directive appears to be similar to this directive, there is a difference. CacheRefreshInterval specifies only that the proxy revalidates a file before using it, whereas the CacheClean directive causes the file to be removed from the cache after a specified period of time.
CacheRefreshInterval URL_pattern time_period
CacheRefreshInterval time_periodCacheRefreshInterval *.gif 8 hours CacheRefreshInterval 1 week
CacheRefreshInterval 2 weeks
Use this directive to specify when to start the cache agent. You can start the cache agent at a specific time.
CacheRefreshTime HH:MM
CacheRefreshTime 03:00
The CacheTimeMargin directive specifies the minimum lifetime of a file that is required in order for it to be cached.
The Caching Proxy computes an expiration time for each file. If it is unlikely that another request for the file will be received before the file expires, the Caching Proxy considers the lifetime of the file to be too short for the file to be cached. By default, the Caching Proxy does not cache files whose lifetime is less than 10 minutes. If your cache is not close to its maximum capacity, leave this directive at its initial value. If your cache is filled close to capacity, consider increasing the value for the minimum lifetime.
CacheTimeMargin minimum_lifetime
CacheTimeMargin 10 minutes
Use this directive to set the maximum length of time for the server to keep unused cached files with URLs that match a specified template. The server deletes unused files with URLs matching the template after they are cached for the specified time, regardless of their expiration date. You can include multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.
CacheUnused url_template time_length
CacheUnused ftp:* 3 weeks CacheUnused gopher:* 3 days 12 hours CacheUnused * 4 weeks
CacheUnused ftp:* 3 days CacheUnused gopher:* 12 hours CacheUnused http:* 2 days
Use this directive to enable the caching of files. With caching turned on, the proxy server stores the files it retrieves from other servers in a local cache. The proxy server then responds to subsequent requests for the same files without needing to retrieve them from other servers.
Caching {on | off}
Caching On
Use this directive to specify whether the Caching Proxy is part of a Content Distribution Framework.
CdfAware {yes | no}
CdfAware no
Use this directive to designate the name of the file that stores filename to URL mapping data so that it is persistent over multiple instances of ibmproxy in a Content Distribution Framework. The Caching Proxy maintains a mapping table that associates a requested URL with its file name on the Web server. This file provides persistent storage of this table across restarts. Use this directive only if the CdfAware directive is set to yes.
CdfRestartFile path/filename
None
Use this directive to specify the age after which logs are compressed. When the logs are older than the value set for CompressAge, they are compressed. If CompressAge is set to 0, no logs are ever compressed. The logs for the current and previous days are never compressed.
CompressAge number_of_days
CompressAge 1
Use this directive to build a command that identifies the compression utility used to compact the logs and that passes parameters to that utility. Include the path for the archived logs.
The compression utility must be installed in a directory listed in the path for that machine.
CompressCommand command
CompressCommand tar -cf /logarchs/log%%DATE%%.tar %%LOGFILES%% ;
gzip /logarchs/log%%DATE%%.tar
CompressCommand tar -cf /logarchs/log%%DATE%%.tar %%LOGFILES%% ;
compress /logarchs/log%%DATE%%.tar
CompressCommand zip -q /logarchs/log%%DATE%%.zip %%LOGFILES%%
CompressCommand pkzip -q d:\logarchs\log%%DATE%%.tar %%LOGFILES%%
None
Use this directive to specify when to delete a log after it has been compressed. When a log is older than the number of days set for the value of CompressDeleteAge, it is deleted. If CompressDeleteAge is set to 0, or if its value is less than the value set for the CompressAge directive, a log is not deleted.
CompressDeleteAge number_of_days
CompressDeleteAge 7
Use this directive to specify the name and location of an additional configuration file. Directives found in the specified configuration file are processed after the current configuration file.
None
Use this directive to defines the number of connection threads to be used for connection management.
ConnThreads number
ConnThreads 5
Use this directive to specify how much of a requested file must be transferred for the Caching Proxy to complete the creation of the cache file, even though the client connection is terminated. Valid values for this variable are integers in the range of 0 - 100.
For example, if ContinueCaching 75 is specified, the Caching Proxy continues transferring the file from the content server and generates the cache file if 75% or more of the file is already transferred before the Caching Proxy detects that the client connection is terminated.
ContinueCaching percentage
ContinueCaching 75
Use this directive to supply the proxy with the necessary information to filter URLs for content including rating service information. You can specify this directive multiple times.
DefinePicsRule "filter_name" {
DefinePicsRule "RSAC Example" {
Use this directive to associate a default protection setup with requests that match a template.
DefProt request_template setup_name [FOR server_IP_address | host_name]
Protection is not actually activated for requests matching the template unless the request also matches a template on a subsequent Protect directive. See Protect -- Activate a protection setup for requests that match a template for an explanation of how the Protect directive is used with DefProt.
You can specify an IP address (for example, FOR 240.146.167.72) or you can specify a host name (for example, FOR hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address on which the requests come in or the host name in the URL.
A wildcard character cannot be specified for a server's IP address.
DefProt /secret/* /server/protect/setup1.acc
DefProt /secret/* SECRET-PROT
DefProt {
AuthType Basic
ServerID restricted
PasswdFile /docs/etc/WWW/restrict.password
GroupFile /docs/etc/WWW/restrict.group
GetMask authors
PutMask authors
}DefProt /secret/* CustomerA-PROT 0.67.106.79 DefProt /secret/* CustomerB-PROT 0.83.100.45
DefProt /secret/* CustomerA-PROT hostA.bcd.com DefProt /secret/* CustomerB-PROT hostB.bcd.com
None
Use this directive to specify whether the cache agent waits between sending requests to destination servers. Specifying a delay between requests reduces the load on the proxy machine and your network link, as well as on the destination servers. Specifying no delay lets the cache agent run at maximum speed. For slow Internet connections, consider specifying no delay period in order to achieve maximum use of your network.
DelayPeriod {on | off}
DelayPeriod On
Use this directive to specify whether the cache agent follows hypertext links across hosts. If a cached URL contains links to other servers, the server can ignore the link or follow it. If the directive DelveInto is set to never, this directive is not applied.
DelveAcrossHosts {on | off}
DelveAcrossHosts Off
Use this directive to specify the number of link levels to follow when searching for pages to load into the cache. If the directive DelveInto is set to never, this directive is not applied.
DelveDepth number_of_levels
DelveDepth 2
Use this directive to specify whether the cache agent loads pages linked from cached URLs.
DelveInto {always | never | admin | topn}
DelveInto always
Use this directive to apply a background image to directory listings generated by the proxy server. Directory listings are generated when the proxy server is used to browse FTP sites.
Specify an absolute path for the background image. If the image is located on another server, the background image must be specified as a full URL. If no background image is specified, a plain white background is used.
DirBackgroundImage /path/file
DirBackgroundImage /images/corplogo.png DirBackgroundimage http://www.somehost.com/graphics/embossed.gif
None
Use this directive to specify whether directory listings include the exact byte count for files smaller than 1 KB. A value of Off means the directory listing shows a size of 1 KB for all files that are 1 KB or smaller.
DirShowBytes {on | off}
DirShowBytes Off
Use this directive to specify whether directory listings distinguish between uppercase and lowercase letters when sorting file names.
A value of On means that uppercase letters are placed before lowercase letters in the list of files.
DirShowCase {on | off}
DirShowCase On
Use this directive to specify whether directory listings include the date each file was last modified.
DirShowDate {on | off}
DirShowDate On
Use this directive to specify whether directory listings include descriptions for HTML files. The descriptions are taken from the files' HTML <title> tags.
Descriptions for FTP directory listings show the MIME types for files if they can be determined.
DirShowDescription {on | off}
DirShowDescription On
Use this directive to specify whether directory listings include any hidden files in the directory. The server considers any file that has a name beginning with a period (.) to be a hidden file.
DirShowHidden {on | off}
DirShowHidden On
Use this directive to specify whether the server includes icons in directory listings. Icons can be used to provide a graphic representation of the content type of the files in the listing. The icons themselves are defined by the AddBlankIcon, AddDirIcon, AddIcon, AddParentIcon, and AddUnknownIcon directives.
DirShowIcons {on | off}
DirShowIcons On
Use this directive to set the maximum number of characters to show in the description field on directory listings.
DirShowMaxDescrLength number_of_characters
DirShowMaxDescrLength 25
Use this directive to set the maximum number of characters that are used for file names on directory listings.
DirShowMaxDescrLength number_of_characters
DirShowMaxLength 25
Use this directive to set the minimum number of characters that are always reserved for file names on directory listings. File names in the directory can exceed this number. However, file names cannot be longer than the number specified on the DirShowMaxLength directive.
DirShowMinLength number_of_characters
DirShowMinLength 15
Use this directive to specify whether directory listings include the size of each file.
DirShowSize {on | off}
DirShowSize On
Use this directive to specify which HTTP methods the server does not accept. For each method that the server is to reject, enter a separate Disable directive.
In the default configuration file, the GET, HEAD, OPTIONS, POST, and TRACE methods are enabled and all other supported HTTP methods are disabled. To disable a method that is currently enabled, delete it from the Enable directive and add it to the Disable directive.
Disable method
Disable PUT Disable DELETE Disable CONNECT
Use this directive to specify which environment variables you do not want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).
By default, all environment variables are inherited by CGI programs. Use this directive to exclude individual environment variables from being inherited.
DisInheritEnv environment_variable
DisInheritEnv PATH DisInheritEnv LANG
In this example, all environment variables except PATH and LANG are inherited by CGI programs.
None
Use this directive to specify whether the server looks up the host names of requesting clients.
DNS-Lookup {on | off}
The value you use affects the following things about how your server works:
DNS-Lookup Off
Use this directive to specify which HTTP methods the server accepts.
You can enable as many of the HTTP methods as you need. For each method the server is to accept, enter a separate Enable directive.
Enable method
If no Service directive exists for a particular URL, you can use the Enable directive to perform customized programming for any HTTP method. The program you specify on this directive overrides the standard processing for that method.
Enable method /path/fileDLL:function_name
Enable GET Enable HEAD Enable POST Enable TRACE Enable OPTIONS
Use this directive to enable the TCP NODELAY socket option.
The EnableTcpNodelay directive improves performance when small IP packets, such as an SSL handshake or a short HTTP response, are transmitted between Caching Proxy and the client. By default, the TCP NODELAY option is enabled for all sockets.
EnableTcpNodelay {All | HTTP | HTTPS | None}
EnableTcpNodelay All
Use this directive to specify a customized application function that you want the server to call during the Error step. This code is executed to provide customized error routines when an error is encountered.
Error request_template /path/file:function_name
Error /index.html /ics/api/bin/icsext05.so:error_rtns
None
Use this directive to specify the path and file name where you want the server to log internal errors.
If it is running, the server starts a new log file each day at midnight. Otherwise, the server starts a new log file the first time it is started on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm represents the first three letters of the month; dd represents the day of the month; and yyyy represents the year.
ErrorLog /path/logs_directory/file_name
Use this directive to specify the name of a file that is sent to the requesting client when the server encounters a particular error condition. The configuration file ibmproxy.conf provides ErrorPage directives that associate the error keywords with error message files.
To customize error messages, you can modify the ErrorPage directives to associate the error keywords with different files, or you can modify the provided error message files. For example, you can change a message to include more information about the cause of the problem and suggest possible solutions to fix it. For internal networks, you might provide a contact person for your users to call.
ErrorPage directives can be placed anywhere in the configuration file. When the error occurs, the file is processed according to the mapping rules defined in your configuration file. Therefore, the file you want to send must be in a location that can be reached through the mapping rules as defined by the Fail, Map, NameTrans, Pass, Redirect, and Service directives. At a minimum, you need a Pass directive that allows the server to pass the error message file.
ErrorPage keyword /path/filename.html
ErrorPage scriptstart /HTML/errorpages/scriptstart.htmls
In this example, when a scriptstart condition is encountered, the server sends the scriptstart.htmls file found in the /HTML/errorpages/ directory to the client.
The following HTML text is an example what the file might contain:
<HTML> <HEAD> <TITLE>Message for SCRIPTSTART condition</TITLE> </HEAD> <BODY> The CGI program could not be started. <P> <A HREF="mailto:admin@websvr.com">Notify the administrator</A> of this problem. </BODY> </HTML>
If the directive that matches the above path in the server's configuration file is PASS /* /wwwhome/*, then the full path for this message file is /wwwhome/HTML/errorpages/scriptstart.htmls.
Each error condition is identified by a keyword. To decide which error messages you want to customize, first review the error message files provided with the Caching Proxy, which you can find in /HTML/errorpages. The error page includes the error number, the default message, an explanation of the cause, and an appropriate recovery action.
Then, do one of the following to change an error message:
All error keywords and default error message files are listed in the file ibmproxy.conf in the ErrorPage directive section. The error message files include the error message number, keyword, default message, explanation, and user response (action).
Numerous defaults are included in the file ibmproxy.conf
If you do not modify an ErrorPage directive for an error condition, the server's default error page for that condition is sent.
Use this directive to specify the event log path and file name. The event log captures informational messages about the cache itself.
If it is running, the server starts a new log file each day at midnight . Otherwise, the server starts a new log file the first time it is started on any day. When creating the file, the server uses the file name you specify and appends a date suffix. The date suffix is in the format Mmmddyyyy, where Mmm represents the first three letters of the month; dd represents the day of the month; and yyyy represents the year.
EventLog /path/logs_directory/file_name
Use this directive to specify a template for requests to accept and respond to by running a CGI program. After a request matches a template on an Exec directive, the request is not compared to request templates on any subsequent directives.
Exec request_template program_path [Server_IP_address | host_name]
You must use an asterisk (*) as a wildcard in both the request_template and program_path. The part of the request that matches the request_template wildcard must begin with the name of the file that contains the CGI program.
The request can also contain additional data that is passed to the CGI program in the PATH_INFO environment variable. The additional data follows the first slash character (/) that comes after the CGI program file name on the request. The data is passed according to CGI specifications.
The Exec directive is recursive and applies to all subdirectories. You do not need a separate Exec directive for each directory under cgi-bin and admin-bin.
You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Wildcard characters cannot be used to specify server IP addresses.
In the following example, if the server receives a request of /idd/depts/plan/c92, it runs the CGI program in /depts/bin/plan.exe with c92 passed to the program as input.
The following example uses the optional IP address parameter. If your server receives requests that begin with /cgi-bin/, it serves the request from a different directory based on the IP address of the network connection on which the request comes in. For requests coming in on 130.146.167.72, the server uses the /CGI-BIN/customerA directory. For requests coming in on any connection with an address of 0.83.100.45, the server uses the /CGI-BIN/customerB directory.
Exec /cgi-bin/* /CGI-BIN/customerA/* 130.129.167.72 Exec /cgi-bin/* /CGI-BIN/customerB/* 0.83.100.45
The following example uses the optional host name parameter. If your server receives requests that begin with /cgi-bin, it serves the request from a different directory based on the host name in the URL. For requests coming in for hostA.bcd.com, the server uses the /CGI-BIN/customerA directory. For requests coming in for hostB.bcd.com, the server uses the /CGI-BIN/customerB directory.
Exec /cgi-bin/* /CGI-BIN/customerA/* hostA.bcd.com Exec /cgi-bin/* /CGI-BIN/customerB/* hostB.bcd.com
Exec /cgi-bin/* /opt/ibm/edge/cp/server_root/cgi-bin/* Exec /admin-bin/* /opt/ibm/edge/cp/server_root/admin-bin/*
Exec server_root/cgi-bin/* Exec server_root/admin-bin/* Exec server_root/DOCS/admin-bin/*
Use this directive to export the cache contents to a dump file. This is useful when memory cache gets lost during restart, or when deploying the same cache for multiple proxies.
ExportCacheImageTo export_file_name
None
Use this directive to configure the Caching Proxy to recognize a IBM WebSphere Application Server (that is configured with a Caching Proxy adapter module) from which it can cache dynamically created resources. The Caching Proxy saves copies of JSP results that also are stored in the application server's dynamic cache. The Caching Proxy caches only contents from a IBM WebSphere Application Server whose group ID matches an ExternalCacheManager entry.
Note that it is also necessary to add a Service directive to the Caching Proxy configuration file to enable this feature. Additional configuration steps also are necessary at the application server. Refer to Caching dynamically generated content for complete information.
ExternalCacheManager External_Cache_Manager_ID Maximum_Expiry_Time
The following entry defines an external cache manager (a IBM WebSphere Application Server) that is within the www.xyz.com domain and whose resources expire in 20 seconds or earlier.
ExternalCacheManager IBM-CP-XYZ-1 20 seconds
None
Use this directive to specify a template for requests that the server is not to process. After a request matches a template on a Fail directive, the request is not compared to request templates on any subsequent directives.
Fail request_template [Server_IP_address | host_name]
You can use an asterisk as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.
You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
A wildcard character cannot be specified for a server's IP address.
In the following example, the server rejects any requests beginning with /usr/local/private/.
Fail /usr/local/private/*
The following examples use the optional IP address parameter. The server rejects any requests beginning with /customerB/ if the request comes in on a network connection with the IP address 240.146.167.72. The server rejects any requests beginning with /customerA/ if the request comes in on a network connection with the IP address 0.83.100.45.
Fail /customerB/* 240.146.167.72 Fail /customerA/* 0.83.100.45
The following examples use the optional host name parameter. The server rejects any requests beginning with /customerB/ if the request comes in for hostA.bcd.com. The server rejects any requests beginning with /customerA/ if the request comes in for hostB.bcd.com.
Fail /customerB/* hostA.bcd.com Fail /customerA/* hostB.bcd.com
None
Use this directive to instruct the proxy to use the SOCKS configuration file to determine the type of connection to make.
flexibleSocks {on | off}
flexibleSocks on
Use this directive to enable FTP servers to generate a welcome or descriptive message for a directory. This message can optionally be displayed as part of the FTP listings. The FTPDirInfo directive allows you to control where the message is displayed.
FTPDirInfo {top | bottom | off}
FTPDirInfo top
If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for FTP requests. You must specify a full URL, including the trailing slash character (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.
ftp_proxy full_URL [domain_name_or_template]
ftp_proxy http:// outer.proxy.server/
None
Use this directive to specify whether the path information in FTP URLs is interpreted as relative to the logged-in user's working directory or to the root directory.
FTPUrlPath {relative | absolute}
If the FTPUrlPath directive is set to absolute, then the logged-in user's FTP working directory must be included in the FTP URL path. If FTPUrlPath Relative is specified, then the logged-in user's FTP working directory must be omitted from the FTP URL path. For example, to access the file test1.html, contained in the working directory /export/home/user1 for a logged-in user, the following URL paths are required, depending on the setting of the FTPUrlPath directive:
None
Use this directive to specify whether garbage collection is used. If caching is enabled, the server uses the garbage collection process to delete files that must no longer be cached. Files are deleted based on their expiration date and other proxy directive values. Generally, if caching is enabled, garbage collecting is used. If garbage collection is not used, the proxy cache is used inefficiently.
Gc {on | off}
Gc On
Use this directive to specify a customized application you want the server to use for garbage collection.
GCAdvisor /path/file:function_name
GCAdvisor /api/bin/customadvise.so:gcadv
Use this directive to specify the percentage of the total cache capacity that must be filled to trigger garbage collection. This percentage is called the high-water mark. The high-water mark is specified as a percentage of the total cache capacity. Garbage collection continues until the low-water mark has been reached--see GcLowWater -- Specify when garbage collection ends for information about setting this. The percentage for the high-water mark can be set between 50 and 95.
GcHighWater percentage
GcHighWater 90
Use this directive to specify the percentage of the total cache capacity that triggers the end of garbage collection. This percentage is known as the low-water mark. The low-water mark is specified as a percentage of the total cache capacity. It must be set to a value lower than the value set for the high-water mark; see GcHighWater -- Specify when garbage collection begins for information about setting the high-water mark.
GcLowWater percentage
GcLowWater 60
If the proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for Gopher requests. You must specify a full URL including the trailing slash (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.
gopher_proxy full_URL[domain_name_or_template]
gopher_proxy http://outer.proxy.server/
None
Use this directive to specify the group name or number to which the server changes before accessing files.
If you change this directive, you must manually stop and then start your server again in order for the change to take effect. The change does not take effect if you only restart the server. (See Starting and stopping the Caching Proxy.)
GroupId { group_name | group_number}
AIX: GroupId nobody
HP-UX: GroupId other
Linux:
Solaris: GroupId nobody
Use this directive to specify the name of the proxy server returned in the HTTP header
HeaderServerName name
None
Use this directive to specify the domain name or an IP address returned to clients from file requests. If you specify a domain name, a domain name server must be able to resolve the name into an IP address. If you specify an IP address, the domain name server is not needed or accessed.
Hostname {name | IP address}
By default, this directive is not specified in the initial configuration file. If you do not specify this directive in the configuration file, the value defaults to the host name defined in your domain name server.
If the proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server contacts for HTTP requests. You must specify a full URL, including the trailing slash (/). For information on using an optional domain name or template, refer tono_proxy -- Specify templates for connecting directly to domains.
http_proxy full_URL[domain_name_or_template]
http://outer.proxy.server/
None
Use this directive to specify whether the Caching Proxy retrieves the insecure home page for the URL and attempts to find labels in it. If labels are found, they are applied to the secure request. For example, if you request https://www.ibm.com/, the Caching Proxy retrieves http://www.ibm.com/, searches it for labels, and uses any labels it finds to filter https://www.ibm.com/.
If HTTPSCheckRoot is set to off, the Caching Proxy does not retrieve the insecure home page and search it for labels.
HTTPSCheckRoot {on | off}
HTTPSCheckRoot on
Use this subdirective to specify an IP address that is used for sending and receiving ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.
ICP_Address IP_address
By default, this directive is not specified in the initial configuration file. If you do not specify this directive in the configuration file, the value defaults to accepting and sending ICP queries on any interface.
Use this subdirective to specify the number of threads spawned to listen for ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.
ICP_MaxThreads number_of_threads
ICP_MaxThreads 5
If the proxy server is part of an ICP cluster, use this subdirective to specify the ICP peers. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.
When a new peer is added to the ICP cluster, ICP peer information must be added to the configuration file of all existing peers. Use one line for each peer. Note that the current host can also be included in the peer list. When ICP initializes, it ignores the current host's entry. This makes it possible to have a single configuration file that can be copied to other peer machines without editing it to remove the current host.
ICP_Peer hostname http_port icp_port
The following line adds the host abc.xcompany.com, whose proxy port is 80 and ICP port 3128, as a peer.
ICP_Peer abc.xcompany.com 80 3128
None
Use this subdirective to specify the port number on which the ICP server listens for ICP queries. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.
ICP_Port port_number
ICP_Port 3128
Use this subdirective to specify the maximum time that the Caching Proxy waits for responses to ICP queries. The time is specified in milliseconds. It must be enclosed within the <MODULEBEGIN> ICP and <MODULEEND> directives.
ICP_Timeout timeout_in_milliseconds
ICP_Timeout 2000
Use this directive to specify URLs that are not to be loaded by the cache agent. This directive is useful when the cache agent is loading pages linked from cached URLs. You can use multiple occurrences of the IgnoreURL directive to specify different URLs or URL masks. The value for this directive can contain asterisks (*) as wildcards, to apply a mask.
IgnoreURL URL
IgnoreURL http://www.yahoo.com/ IgnoreURL http://*.ibm.com/*
IgnoreURL */cgi-bin/*
Use this directive to specify whether you want server-side include processing to be performed for files served from the file system, CGI programs, or both. Server-side include processing is done on files with a content type of ext/x-ssi-html. Optionally, you can specify that server-side include processing is also done for files with a content type of text/html. For more information about content types, see AddType -- Specify the data type of files with particular suffixes.
You can use server-side include processing to dynamically insert information into the file being returned. Such information can include the date, the size of a file, the last change date of a file, CGI or server-side include environment variables, or text files. Server-side include processing is performed only on files originated locally. The Caching Proxy does not perform server-side include processing on proxied or cached objects.
Server-side include processing causes the server to search your files for special commands each time they are served. This can affect the server's performance and slow down response time to clients.
imbeds {on | off | files | cgi | noexec} {SSIOnly | html}
The server checks the content type of each file it retrieves and the output of each CGI program it processes.
Server-side include processing is normally done only for files having a content type of text/x-ssi/html. However, you can specify that files with a content type of text/html are processed for server-side includes.
Each suffix must have an AddType directive defined with the correct content type. If you use suffixes other than .htm or .html, make sure an AddType directive is defined with a content type of text/x-ssi/html.
imbeds on SSIOnly
Use this directive to import the cache contents from a dump file. This is useful when memory cache gets lost during restart, or when deploying the same cache for multiple proxies.
ImportCacheImageFrom import_file_name
None
Use this directive to specify which environment variables you want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).
If you do not include an InheritEnv directive, all environment variables are inherited by CGI programs. If you include any InheritEnv directive, only those environment variables specified on InheritEnv directives are inherited along with the CGI-specific environment variables. The directive allows you to optionally initialize the value of the variables that are inherited.
InheritEnv environment_variable
InheritEnv PATH InheritEnv LANG=ENUS
In this example, only the PATH and LANG environment variables are inherited by CGI programs, and the LANG environment variable is initialized with the value of ENUS.
None. By default, all environment variables are inherited by CGI programs.
Use this directive to set the time allowed for a client to send a request after making a connection to the server. A client first connects to the server and then sends a request. If the client does not send a request within the amount of time specified with this directive, the server closes the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).
InputTimeout time
InputTimeout 3 mins 30 secs
InputTimeout 2 minutes
This directive will override the default action of the JunctionRewrite plugin, allowing the proxy to correct certain URL links in the html page. It is used in conjunction with the JunctionRewrite directive.
The JunctionReplaceUrlPrefix directive will direct the JunctionRewrite plugin to replace the URL from url_pattern_1 to url_pattern_2, instead of inserting a prefix at the beginning of the URL.
JunctionReplaceUrlPrefix url_pattern_1 url_pattern_2
JunctionReplaceUrlPrefix /server1.internaldomain.com/* /server1/*
In this example, assume the URL is /server1.internaldomain.com/notes.nsf and assume the prefix is /server1. Instead of inserting the prefix to rewrite the URL to /server1/server1.internaldomain.com/notes.nsf, the JunctionRewrite plugin will change the URL to /server1/notes.nsf.
None
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 plugin must also be enabled if you set JunctionRewrite on without the UseCookie option. Junctions are defined by the proxy mapping rules.
See UseCookie as an alternative to JunctionRewrite and Sample transmogrifier plugin to extend JunctionRewrite functionality for additional information about JunctionRewrite.
JunctionRewrite {on | on UseCookie | off}
JunctionRewrite off
The directive will allow the proxy to rewrite the path option in the Set-Cookie header when the cookie name is matched. If the response needs junction, and a junction prefix is defined, the prefix will be inserted before each path. It can be used with the JunctionRewrite plugin, or it can be used with the RewriteSetCookieDomain directive.
JunctionRewriteSetCookiePath cookie-name1 cookie-name2...
None
This directive will override the default action of the JunctionRewrite plugin, skipping the URL rewrite if the URL-pattern already matches. It works with the JunctionRewrite plugin providing a way to correct some of the URL links in the html page. Normally, the directive is used to skip the URLs that already include a prefix.
JunctionSkipUrlPrefix url_pattern
JunctionSkipUrlPrefix /server1/*
In this example, assume the URL is /server1/notes.nsf and assume the junction prefix is /server1/. Instead of rewriting the URL to /server1/server1/notes.nsf, the JunctionRewrite plugin will skip rewriting the URL, and the URL remains unchanged as /server1/notes.nsf.
None
Use this directive to specify the treatment of expired files during garbage collection for the proxy cache. Valid values are on and off. When this directive is set to on, expired files are eligible for deletion and are the first files considered for deletion during garbage collection. If the cache is full, expired files are deleted first. When this directive is set to off, expired files are deleted during garbage collection even if the proxy cache is not full.
KeepExpired {on | off}
KeepExpired off
Use this directive to specify the file path to the key ring database that the server uses for SSL requests. Key ring files are generated via the iKeyman key manager utility.
KeyRing filename
Windows: KeyRing c:\Program Files\IBM\edge\cp\\key.kdb
Linux and UNIX: KeyRing /etc/key.kdb
None
Use this directive to to specify the file path to the key ring database's password file. The password file is generated via the iKeyman key manager utility when a key ring database file is built.
KeyRingStash file_path
Windows: KeyRingStash c:\Program Files\IBM\edge\cp\key.sth
Linux and UNIX: KeyRingStash /etc/key.sth
None
Use this directive to control the maximum body size in PUT or POST requests. The LimitRequest directives are used to protect the proxy from attack.
The value can be specified in kilobytes (K), megabytes (M), or gigabytes (G).
LimitRequestBody max_body_size {K | M | G}
LimitRequestBody 10 M
Use this directive to specify the maximum number of headers that can be sent in client requests. The LimitRequest directives are used to protect the proxy from attack.
LimitRequestFields number_headers
LimitRequestFields 32
Use this directive to specify the maximum length of the request line and the maximum length of each header in a request. The LimitRequest directives are used to protect the proxy from attack.
The value can be specified in bytes (B) or kilobytes (K).
LimitRequestFieldSize max_hdr_length {B | K}
LimitRequestFieldSize 4096 B
Use this directive to specify the number of listen backlog client connections that the server carries before it sends connection refused messages to clients. This number depends on the number of requests that your server can process in a few seconds. Do not set it to a value higher than the number the server can process before the clients time out and abort the connection.
ListenBacklog number_of_requests
ListenBacklog 128
Use this directive to specify whether inline images are retrieved by the cache agent. If LoadInlineImages is set to on, images that are imbedded in a page that is being cached are also cached. If it is set to off, imbedded images are not cached.
LoadInlineImages {on | off}
LoadInlineImages on
Use this directive to instruct the cache agent to access the previous night's cache access log and load the most-requested URLs.
The Caching directive must be set to On, and a value must be set for the CacheAccessLog directive when a value is set for the LoadTopCached directive.
LoadTopCached number_of_pages
LoadTopCached 100
Use this directive to specify URLs to be loaded into the cache by the cache agent. Multiple LoadURL directives can be included in the configuration file, but wildcards cannot be used.
LoadURL url
LoadURL http://www.ibm.com/
None
Use this directive to specify a customized application function that the server calls during the Log step. This code provides logging and other processing that is performed after the connection is closed.
Log request_template /path/file:function_name
Log /index.html /api/bin/icsextpgm.so:log_url
None
Use this directive to specify the behavior of the archiving routine. This directive affects all logs with global settings. It specifies that logs are compressed or purged, or that nothing is done with them.
If you specify Compress, use the CompressAge and CompressDeleteAge directives to specify when the logs are compressed or deleted. Use the CompressCommand directive to specify which command and its parameters to use.
If you specify Purge, use the PurgeAge and PurgeSize directives to specify when the logs are purged.
LogArchive {Compress | Purge | none}
LogArchive Purge
Use this directive to specify the file format of the access log files.
LogFileFormat {common | combined}
By default, logs are displayed in the NCSA Common Log Format. Specify combined to display logs in NCSA Combined Log Format instead. The combined format adds fields for Referring URL, User Agent, and Cookie (if present in the request).
LogFileFormat common
Windows systems only. When running the proxy via the command line, use this directive to output to the access log. To optimize server performance, by default this directive is set to off (disabled).
LogToGUI {on | off}
LogToGUI off
Linux and UNIX systems only. Use this directive to specify whether the server logs access requests and errors to the system log in addition to the access and error log files.
LogToSyslog {on | off}
The system log file must be present on your server before you specify that error log information is written to it. You can choose whether to log access information, error information, or both.
To send only error information to the system log, add the following line to your /etc/syslog.conf file:
user.err syslog_output_file_for_error_information
To send only access information to the system log, add the following line to your /etc/syslog.conf file:
user.info syslog_info_file_for_access_information
To send both error and access information to the system log, add both of the lines to your /etc/syslog.conf file:
Specify syslog_output_file and syslog_info_file in the following formats:
After you create the system log file, you can restart it with the following command:
kill -HUP 'cat /etc/syslog.pid'
LogToSyslog Off
Use this directive to specify a template for requests that you want to change to a new request string. After the server changes the request, it takes the new request string and compares it to the request templates on subsequent directives.
Map request_template new_request [server_IP_address | host_name]
You can use an asterisk (*)as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.
You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
A wildcard character cannot be specified for a server's IP address.
Map /stuff/* /good/stuff/*
Map /stuff/* /customerA/good/stuff/* 240.146.167.72 Map /stuff/* /customerB/good/stuff/* 0.83.104.45
Map /stuff/* /customerA/good/stuff/* hostA.bcd.com Map /stuff/* /customerB/good/stuff/* hostB.bcd.com
None
Use this directive to set the maximum number of threads that are active at one time. If the maximum is reached, the server holds new requests until another request finishes and threads become available. Generally, the more power a machine has, the higher the value that is set for this directive. If a machine starts to spend too much time on overhead tasks, such as swapping memory, try reducing this value.
MaxActiveThreads number_of_threads
MaxActiveThreads 100
Use this directive to set the size of the buffer for dynamic data generated by the server. Dynamic data is output from CGI programs, server-side includes, and API programs.
The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter whether there is a space between the number and the value (B, K, M, G).
MaxContentLengthBuffer size
MaxContentLengthBuffer 100 K
Use this directive to specify the maximum size for each log file. Each log file cannot exceed the size defined by this directive. Once a log file reaches the maximum defined size, the current log file will be closed, and a new log file will be created with the same name, appended by the next incremental integer value.
The maximum size can be specified in one of the following units: bytes (B), kilobytes (K), megabytes (M), and gigabytes (G).
MaxLogFileSize maximum {B | K | M | G}
MaxLogfileSize 128 M
Use this directive to specify the maximum number of requests the server receives on a persistent connection. When determining this number, consider the number of images used in your pages. Each image requires a separate request.
MaxPersistRequest number
MaxPersistRequest 5
Use this directive to specify the maximum depth for the cache agent's queue of outstanding page retrieval requests. If you have a large system with a large amount of memory, you can define a larger queue of page retrieval requests without consuming all the available memory.
The queue of URLs to cache is determined at the beginning of each run of the cache agent. If you instruct the cache agent to follow the hypertext links to other URLs, these other URLs are not counted in the cache queue depth. After the value specified in the MaxURLs directive is reached, the cache agent stops, even if there are more URLs in the queue.
MaxQueueDepth maximum_depth
MaxQueueDepth 250
Use this directive to specify the maximum amount of time for the the cache agent to retrieve URLs during a particular run. A value of 0 means the cache agent runs until completion.
MaxRuntime {0 | maximum_time}
MaxRuntime 2 hours 10 minutes
MaxRuntime 2 hours
Use this directive to set the maximum number of open sockets to maintain to any one origin server. Use this directive only if the ServerConnPool directive is set to on.
MaxSocketPerServer num
MaxSocketPerServer 10
MaxSocketPerServer 5
Use this directive to specify the maximum number of URLs the cache agent retrieves during a particular run. A value of 0 means there is no limit. When the automatic mode of the cache agent is used, the LoadURL and LoadTopCached directives take precedence over MaxURLs.
MaxURLs maximum_number
MaxURLs 2000
Use this directive to specify members of the arrays that are shared by the servers using remote cache access.
Member name {
subdirective
subdirective
.
.
}
The following subdirectives are included:
Member bittersweet.chocolate.ibm.com {
RCAAddr 127.0.0.1
RCAPort 6294
CacheSize 25G
Timeout 500 milliseconds
BindSpecific On
ReuseAddr Off
}
None
Use this directive to specify the application plugin that runs at midnight to archive the logs. This directive is initialized during installation. If you do not include this directive in the configuration file, archiving is not performed.
Midnight /path/file:function_name
Use this directive to specify a customized application function the server calls during the Name Translation step. This code supplies the mechanism for translating the virtual path in the request to the physical path on the server, mapping URLs to specific objects.
NameTrans request_template /path/file:function_name [Server_IP_address | host_name]
A wildcard character cannot be specified for a server's IP address.
NameTrans /index.html /api/bin/icsextpgm.so:trans_url
None
On Linux and UNIX platforms, use this directive to prevent the Caching Proxy server process from automatically running in the background. The directive, which is set to off by default, has the format:
NoBG [on | off]
NoBG on
NoBG off
Use this directive to specify that the server does not cache files with URLs matching the specified template. You can include multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol.
If neither the CacheOnly or the NoCaching directive is set, any URL is a candidate for caching.
NoCaching URL_pattern
NoCaching http://joke/*
None
Use this directive to specify that access requests made from specific hosts or domains that match a specified template are not logged. For example, you might not want to log access requests from local hosts.
You can include multiple occurrences of this directive in your configuration file. You can also put multiple templates on the same directive if you separate them by one or more spaces. You can use host names or IP number addresses on the templates.
NoLog {host_name | IP_address} [...]
NoLog 128.0.* *.edu localhost.*
None
If you are using the directive http_proxy, ftp_proxy, or gopher_proxy for proxy chaining, you can use this directive to specify the domains that the server connects to directly instead of going through a proxy.
Specify the value as a string of domain names or domain name templates. Separate each entry in the string with a comma (,). Do not use any spaces in the string.
Templates on this directive are entered differently than on other directives. Most importantly, you cannot use the wildcard character (*). You can specify a template by including only the last part of a domain name. The server connects directly to any domains that end with a string matching the templates you specify. This directive applies only to proxy chaining and is equivalent to a direct @/= line in the SOCKS configuration file.
no_proxy domain_name_or_template[,...]
no_proxy www.someco.com,.raleigh.ibm.com,.some.host.org:8080
In this example, the server does not go through a proxy for the following requests:
None
Use this directive to specify client URL headers to block. Any HTTP header sent by a client can be blocked, including required headers. Use extreme care when blocking headers. Common headers include:
See the HTTP protocol specification for details of these and other headers. You can specify this directive multiple times.
NoProxyHeader header
NoProxyHeader Referer:
None
Use this directive to specify the number of threads the cache agent uses to retrieve pages in the queue. Base the number of threads on the speed of your internal network and your connection to the Internet. The allowable range is 1 through 100.
NumClients number
NumClients 4
Use this directive to specify a customized application function that the server calls during the Object Type step. This code locates the requested object in the file system and specifies its MIME type.
ObjectType request_template /path/file:function_name
ObjectType /index.html /api/bin/icsextpgm.so:obj_type
None
Use this directive to set the maximum time allowed for the server to send output to a client. The time limit applies to requests for local files and requests for which the server is acting as a proxy. The time limit does not apply for requests that start a local CGI program.
If the server does not send the complete response within the time limit specified on this directive, the server drops the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).
OutputTimeout time
OutputTimeout 30 minutes
Use this directive to specify the directory containing the proxy autoconfiguration files generated by using the remote config PAC file form.
PacFilePath directory_path
Use this directive to specify a template for requests that you want to accept and respond to with a file from your server. After a request matches a template on a Pass directive, the request is not compared to request templates on any subsequent directives.
Pass request_template [file_path [server_IP_address | host_name]]
You can use an asterisk (*) as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.
This parameter is optional. If you do not specify a path, the request itself is used as the path.
You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
A wildcard character cannot be specified for a server's IP address.
Pass /gooddoc/*
Pass /parts/* /customerA/catalog/* 240.146.167.72 Pass /parts/* /customerB/catalog/* 0.83.100.45
Pass /Admin/* /usr/lpp/internet/server_root/Admin/* Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /errorpages/* /usr/lpp/internet/server_root/pub/errorpages/* Pass /* /usr/lpp/internet/server_root/pub/*
Pass /Admin/* /opt/ibm/edge/cp/server_root/Admin/* Pass /Docs/* /opt/ibm/edge/cp/server_root/Docs/* Pass /errorpages/* /opt/ibm/edge/cp/server_root/pub/errorpages/* Pass /* /opt/ibm/edge/cp/server_root/pub/*
Pass /Admin/* /usr/lpp/internet/server_root/Admin/* Pass /Docs/* /usr/lpp/internet/server_root/Docs/* Pass /errorpages/* /usr/lpp/internet/server_root/pub/errporpages/* Pass /* /usr/lpp/internet/server_root/pub/*
Pass /Admin/* /opt/ibm/edge/cp/server_root/Admin/* Pass /Docs/* /opt/ibm/edge/cp/server_root/Docs/* Pass /errorpages/* /opt/ibm/edge/cp/server_root/pub/errorpages/* Pass /* /opt/ibm/edge/cp/server_root/pub/*
Pass /icons/* C:\Program Files\IBM\edge\cp\icons\* Pass /Admin/* C:\Program Files\IBM\edge\cp\Admin\* Pass /Docs/* C:\Program Files\IBM\edge\cp\Docs\* Pass /erropages/* C:\Program Files\IBM\edge\cp\pub\errorpages\* Pass /* C:\Program Files\IBM\edge\cp\pub\*
Use this directive to specify the length of time that the server waits between client requests before canceling a persistent connection. The time can be specified in any valid time increment, but it is usually specified in seconds or minutes.
The server uses a different timeout directive, the InputTimeout, to determine how long to wait for the client to send the first request after the connection is established. For more information about the input timeout, see InputTimeout -- Specify the input timeout.
After the server sends its first response, it uses the value set for the PersistTimeout directive to determine how long to wait for each subsequent request before canceling the persistent connection.
PersistTimeout time
PersistTimeout 4 seconds
Use this directive to specify a customized application function that the server calls to retrieve PICS labels for a specified URL. The function can either dynamically create a PICS label for the requested file or search for a PICS label in an alternative file or database.
PICSDBLookup /path/file:function_name
PICSDBLookup /api/bin/icsext05.so:get_pics
None
Linux and UNIX only. Use this directive to specify the location of the file that contains the process ID of Caching Proxy. When the server process starts, it records its process ID (PID) in a file. If multiple instances of the server are running on a single system, each instance must have its own PidFile directive.
PidFile path_to_pid_file_info
PidFile /usr/pidinfo
The directives listed below have been added to the Caching Proxy ibmproxy.conf file to enable new features and plugins. Configuration and Administration forms are not available for editing most of these directives. A standard text editor, such as vi or emacs, must be used to manually edit them. Further information on each of these new directives appears in this chapter, in alphabetical order.
In the ibmproxy.conf file, directives used to configure Caching Proxy plugin modules must be entered in the following format:
<MODULEBEGIN> plugin name subdirective1 subdirective2 <MODULEEND>
Each plugin program parses the ibmproxy.conf file and reads only its own block of subdirectives. The Caching Proxy parser disregards everything between <MODULEBEGIN> and <MODULEEND>.
Caching Proxy plugin modules and some new features require that API directives be added to the ibmproxy.conf file. Because the proxy server interacts with the plugin modules in the order in which they are listed, take care when ordering the directives within the proxy configuration file. Prototype directives (in the form of comments) have been added to the API section of the ibmproxy.conf file. These API directives are in a purposeful order. When adding API directives to enable new features and plugin modules, order the directives as shown in the prototype section of the configuration file. Alternatively, uncomment and edit, if necessary, API directives to include support for each desired function or plugin. Add user-generated plugin modules after those supplied with the product.
Use this directive to specify the number of the port on which the server listens for requests. The standard port number for HTTP is 80. Other port numbers lower than 1024 are reserved for other TCP/IP applications and must not be used. Common ports used for proxy Web servers are 8080 and 8008.
When a port other than 80 is used, clients are required to include a specific port number on requests to the server. The port number is preceded by a colon (:) and placed after the host name on the URL. For example, from the browser, the URL http://www.turfco.com:8008/ requests the default welcome page from a host named www.turfco.com that is listening on port 8008.
You can use the -p option on the ibmproxy command to override this setting when starting the server.
Port number
If you change this directive, you must manually stop and then start your server again for the change to take effect. The server does not recognize the change if you only restart it. (See Starting and stopping the Caching Proxy.)
Port 80
Use this directive to specify a customized application function that the server calls during the PostAuth step. This code is executed regardless of the return codes from previous steps or other PostAuth handlers. It allows you to clean up any resources allocated to process the request.
PostAuth /path/file:function_name
AuthExit /ics/api/bin/icsext05.so:post_exit
None
Use this directive to specify a customized application function that the server calls during the PostExit step. This code is executed regardless of the return codes from previous steps or other PostExit handlers. It allows you to clean up any resources allocated to process the request.
PostExit /path/file:function_name
PostExit /ics/api/bin/icsext05.so:post_exit
None
Use this directive to specify a customized application function that the server calls during the PreExit step. This code is executed after a client request is read but before any other processing occurs. You can call the GoServe module during this step.
PreExit /path/file:function_name
PreExit /ics/api/bin/icsext05.so:pre_exit
None
Use this directive to activate protection setup rules for requests that match a template.
A protection setup is defined with protection subdirectives. The format of the Protect directive depends on whether you want to point to a label or file containing the protection subdirectives or to include the protection subdirectives inline as part of the Protect directive.
This parameter can take the following forms:
Protect request_template [setup_file | label[
[FOR Server_IP_address | host_name]
Protect request_template [FOR Server_IP_address | hhost_name] subdirective value subdirective value . . . }
The following parameters are used:
This parameter is optional. If it is omitted, the protection setup is defined by the most recent DefProt directive that contains a matching template.
Example:
Protect http://x.x.x.x PROT-ADMIN
Within a Web browser:
Example:
Protect http://hostname.example.com PROT-ADMIN
Within a Web browser:
You can specify an IP address (for example, FOR 240.146.167.72), or you can specify a host name (for example, FOR hostA.bcd.com ).
Wildcard characters cannot be used to specify server IP addresses.
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
These examples use IP addresses. If the server receives requests that begin with /secret/ or /topsecret/, it activates a different protection setup for the request, based on the IP address of the network connection that request comes in on.
Protection BUS-PROT {
UserID busybody
GroupID webgroup
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/restrict.pwd
GroupFile /docs/WWW/restrict.grp
GetMask authors
PutMask authors
}
DefProt /secret/* /server/protect/setup1.acc
Protect /secret/scoop/*
Protect /secret/business/* BUS-PROT
Protect /topsecret/* {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/restrict.pwd
GroupFile /docs/WWW/restrict.grp
GetMask topbrass
PutMask topbrass
}
Pass /secret/scoop/* /WWW/restricted/*
Pass /secret/business/* /WWW/confidential/*
Pass /topsecret/* /WWW/topsecret/*
Protect /secret/* CustomerA-PROT FOR 0.67.106.79
Protect /secret/* CustomerB-PROT FOR 0.83.100.45
Protect /topsecret/* 0.67.106.79 {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-A.pwd
GroupFile /docs/WWW/customer-A.grp
GetMask A-brass
PutMask A-brass
}
Protect /topsecret/* 0.83.100.45 {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-B.pwd
GroupFile /docs/WWW/customer-B.grp
GetMask B-brass
PutMask B-brass
}Protect http://host1/* proxy-prot
Protect /secret/* CustomerA-PROT FOR hostA.bcd.com
Protect /secret/* CustomerB-PROT FOR hostB.bcd.com
Protect /topsecret/* hostA.bcd.com {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-A.pwd
GroupFile /docs/WWW/customer-A.grp
GetMask A-brass
PutMask A-brass
}
Protect /topsecret/* hostB.bcd.com {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-B.pwd
GroupFile /docs/WWW/customer-B.grp
GetMask B-brass
PutMask B-brass
}By default, protection is provided for the Configuration and Administration forms by a Protect directive with a request template of /admin-bin/*.
Use this directive to define a protection setup within the configuration file. You give the protection setup a name and define the type of protection by using protection subdirectives.
Protection label_name {
subdirective value
subdirective value
.
.
.
}
See Protection subdirectives -- Specify how a set of resources is protected for descriptions of the protection subdirectives.
Protection NAME-ME {
AuthType Basic
ServerID restricted
PasswdFile /WWW/password.pwd
GroupFile /WWW/group.grp
GetMask groupname
PutMask groupname
}
Protect /admin-bin/* {
ServerId Private_Authorization
AuthType Basic
GetMask All@(*)
PutMask All@(*)
PostMask All@(*)
Mask All@(*)
PasswdFile /opt/ibm/edge/cp/server_root/protect/webadmin.passwd
}
The following are descriptions of the protection subdirectives that can be used in a protection setup. The subdirectives are in alphabetical order.
The protection setups can be either in separate files or included in the configuration file as part of DefProt, Protect, or Protection directives.
Use this Protection subdirective when limiting access based on user names and passwords. Specify the type of authentication to use when the client sends a password to the server. With basic authentication (AuthType Basic), passwords are sent to the server as plain text. They are encoded, but not encrypted.
AuthType Basic
Use this Protection subdirective to specify user names, groups, and address templates authorized to make DELETE requests to a protected directory.
DeleteMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Use this Protection subdirective to specify user names, groups, and address templates authorized to make GET requests to a protected directory.
GetMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
GetMask All@(*)
Use this Protection subdirective to specify the path and file name of the server group file that the protection setup uses. The groups defined within the server group file can then be used by the following:
GroupFile /docs/etc/WWW/restrict.group
Use this subdirective to specify user names, groups, and address templates authorized to make HTTP requests that are not covered by other mask subdirectives.
Mask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
MASK WEBADM,webadm
Use this Protection subdirective when limiting access based on user names and passwords. Specify the path and name of the password file that this protection setup is to use.
Because some browsers cache User IDs and passwords by security realm (ServerID) within a host, follow these guidelines when specifying ServerID and password files:
PasswdFile /docs/etc/WWW/restrict.password
PasswdFile "c:\test this\admin.pwd"
For a secure server, use this Protection subdirective to specify users, groups, and address templates authorized to make POST requests to a protected directory.
PostMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Use this Protection subdirective to specify users, groups, and address templates authorized to make PUT requests to a protected directory.
PutMask authors,(niceguy,goodie)@45.96.3.1,128.0.*.*
Use this Protection subdirective when limiting access based on user names and passwords. Specify a name that you want to associate with the password file being used. The name does not need to be a real machine name.
The name is used as an identifier to the requester. Because different protection setups can use different password files, associating a name with the protection setup can help the client decide which password to send. Most clients display this name when prompting for a user name and password.
Because some browsers cache user IDs and passwords by security realm (ServerID) within a host, follow these guidelines when specifying ServerID and password files:
ServerID restricted
Use this directive to indicate which protocols the Caching Proxy is to process and map a request to a server. Valid protocols are http, ftp, and gopher.
The UseSession parameter option for the Proxy directive helps maintain a persistent channel on the server side if the requests from clients are forwarded to the same server and from the same client-side TCP channel. UseSession overrides the directive ServerConnPool, which allows requests from different clients to share a persistent connection to the back-end server.
The JunctionPrefix parameter option for the Proxy directive is used in conjunction with the junction rewriting plugin. For more information, refer to Enable junction rewrite (optional) and Define the junction with the JunctionPrefix option (recommended method).
Proxy request_template target_server_path [[ip]:port] [UseSession] [JunctionPrefix:url_prefix]
This directive passes the request to a remote server. For example, the following directive causes all requests to be forwarded to the designated URL:
Proxy /* http://proxy.server.name/*
For a secure reverse proxy server, use the following directive:
Proxy /* https://proxy.server.name/*
If you want your proxy server to be less restrictive, uncomment the following directives from your configuration file. (However, these directives may introduce a security problem when proxy is configured as a reverse proxy.)
Proxy http:* Proxy ftp:* Proxy gopher:*
The following is an example of the UseSession option for the Proxy directive:
Proxy /abc/* http://server1/default/abc/* :80 UseSession
When the incoming client request comes from port 80, and if the URL on the client request matches the pattern /abc/*, then the URL is mapped to http://server1/default/abc/* .
The following is the format for the JunctionPrefix option for the Proxy directive:
Proxy url_patern1 url_pattern2 JunctionPrefix:url_prefix
For more information on use of the JunctionPrefix parameter option, refer to Enable junction rewrite (optional) and Define the junction with the JunctionPrefix option (recommended method).
None.
Use this directive to specify the path and name for the file where you want the server to log access statistics for proxy requests. By default, the server writes an entry to this log each time it acts as a proxy for a client request. You can use the NoLog directive if you do not want to log requests from certain clients.
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on any day. When creating the file, the server uses the file name you specify and appends a date suffix or extension. The date suffix or extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
It is a good idea to remove old log files, because they can consume a significant amount of space on your hard drive.
ProxyAccessLog path/file
Use this directive to specify a customized application you want the server to call during the Proxy Advisor step. This code will service the request.
ProxyAdvisor /path/file:function_name
ProxyAdvisor /api/bin/customadvise.so:proxyadv
None
Use the ProxyForwardLabels directive to specify PICS filtering at the proxy server and at the client, or at two proxies in a proxy hierarchy.
If ProxyForwardLabels is set to on, the the proxy server generates PICS-Label: HTTP headers for all PICS labels found, including labels from the origin server, label bureaus, the Caching Proxy's label cache, and label-supplier plugins.
If ProxyForwardLabels is set to Off, PICS-Label: HTTP headers are not generated.
ProxyForwardLabels {On | Off}
ProxyForwardLabels Off
Use this directive to generate a From: header. This is typically used to give an e-mail address of the proxy administrator.
ProxyFrom e-mail_address
The setting ProxyFrom webmaster@proxy.ibm.com results in the following header change:
| Original header | Modified Header |
|---|---|
| Location: http://www.ibm.com/ | Location: http://www.ibm.com/ |
| Last Modified: Tue 5 Nov 1997 10:05:39 GMT | Last Modified: Tue 5 Nov 1997 10:05:39 GMT |
| Pragma: no-cache | From: webmaster@proxy.ibm.com |
| Pragma: no-cache |
None
Use this directive to specify how the server reacts when users click Reload on the browser. If the ProxyIgnoreNoCache directive is set to on, during periods of high load, the server does not request the page from the destination server and supplies the cached copy of the file if it is available. The server essentially disregards the Pragma: no-cache header sent from the browser.
ProxyIgnoreNoCache {on | off}
ProxyIgnoreNoCache off
Use this directive to specify whether a persistent connection is maintained with the client. A persistent connection reduces waiting time for users and reduces the CPU load on the proxy server, but it requires more resources. More threads, and therefore more memory on the proxy server, are required for a persistent connection.
Persistent connections must not be used on a multilevel proxy server setup if any of the proxies is not HTTP 1.1 compliant.
ProxyPersistence {on | off}
ProxyPersistence on
Use this directive to specify whether the proxy forwards the IP address of the client to the destination server.
ProxySendClientAddress {Client_IP: | OFF}
The directive ProxySendClientAddress Client-IP: results in the following header change:
| Original header | Modified Header |
|---|---|
| Location: http://www.ibm.com/ | Location: http://www.ibm.com |
| Last Modified: Tue 5 Nov 1997 10:05:39 GMT | Last Modified: Tue 5 Nov 1997 10:05:39 GMT |
| Pragma: no-cache | Client-IP: 0.67.199.5 |
| Pragma: no-cache |
None
Use this directive to specify a User Agent string that replaces the string that the client sends. This allows greater anonymity while visiting Web sites. However, some sites have customized pages based on the User Agent string. Using the ProxyUserAgent directive prevents these custom pages from being displayed.
ProxyUserAgent product_name/version
The directive ProxyUserAgent Caching Proxy/6.0 results in the following header change:
| Original header | Modified header |
|---|---|
| Location: http://www.ibm.com/ | Location: http://www.ibm.com |
| Last Modified: Tue 5 Nov 1997 10:05:39 GMT | Last Modified: Tue 5 Nov 1997 10:05:39 GMT |
| User Agent: Mozilla/ 2.02 OS2 | User Agent: Caching Proxy/6.0 |
| Pragma: no-cache | Pragma: no-cache |
None
Use this directive to control the format of the HTTP header. There are four possible values for this directive. If ProxyVia is set to Full, the Caching Proxy adds a Via header into the request or reply; if a Via header is already in the stream, the Caching Proxy adds host information at the end. If set to Set, the Caching Proxy sets the Via header to host information; if a Via header is already in the stream, the Caching Proxy removes it. If set to Pass, the Caching Proxy forwards any header information as is. If set to Block, the Caching Proxy does not forward any Via header.
ProxyVia {Full | Set | Pass | Block}
ProxyVia Pass
ProxyVia Full
The ProxyWAS mapping directive works identically to the Proxy directive, but also indicates to the Caching Proxy that matching requests are directed to a WebSphere Application Server. For examples on using this directive, see Proxy -- Specify proxy protocols or reverse proxy.
ProxyWAS request_template target_server_path [UseSession]
[JunctionPrefix:url_prefix]
None
Use this directive to specify whether the server is acting as a proxy server or as a proxy and content server. It is recommended that you use the Caching Proxy as a proxy only.
PureProxy {on | off}
PureProxy on
Use this directive to specify the age of a log, in days, before it is purged. If PurgeAge is set to 0, the log is never deleted.
PurgeAge number
PurgeAge 7
Use this directive to specify how large, in megabytes, the log files can grow before the log archive is purged. If the PurgeSize directive is set to 0, there is no size limit and no files are deleted.
The setting for PurgeSize refers to all the logs of a log type. For instance, if you are logging errors (that is, if an ErrorLog entry has been made in the configuration file) and PurgeSize is defined as 10 MB, the Caching Proxy calculates the sizes of all the error logs, adds them together, then deletes logs until the total size is less than 10 MB.
PurgeSize number_of_MB
PurgeSize 0
Use this directive to specify the name and location of the Remote Cache Access configuration file.
RCAConfigFile /etc/file_name
RCAConfigFile /etc/user2rca.conf
RCAConfigFile /etc/rca.conf
Use this directive to specify the number of threads working on an RCA port.
RCAThreads number_of_threads
RCAThreads 50
MaxActiveThreads x [(ArraySize -1) / (2 x ArraySize -1)]
Use this directive to specify the time limit allowed without network activity before a connection is canceled.
ReadTimeout time
ReadTimeout 5 minutes
Use this directive to specify a template for requests that you want to accept and send to another server. After a request matches a template on a Redirect directive, the request is not compared to templates on any other directives in the configuration file.
Redirect request_template URL [server_IP_address | host_name]
You can use an asterisk (*) as a wildcard in the template. The tilde character (~) just after a slash (/) must be explicitly matched; a wildcard cannot be used to match it.
URL must contain a protocol specification and the name of the server to which the request is sent. It can also contain a path or file name. If request_template uses a wildcard, the path or file name on URL can also use a wildcard. The part of the original request that matches the wildcard on request_template is inserted in place of the wildcard on URL.
You can specify an IP address (for example, 240.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
A wildcard character cannot be specified for a server's IP address.
Redirect /chief/stuff/* http://www.other.org/wahoo/*
Redirect /stuff/* http://www.chief.org/wahoo/* 240.146.167.72 Redirect /stuff/* http://www.dawg.com/pound/* 0.83.100.45
Redirect /stuff/* http://www.chief.org/wahoo/* hostA.bcd.com Redirect /stuff/* http://www.dawg.com/pound/* hostB.bcd.com
None
The ReversePass mapping directive examines the server response stream to detect requests that are rewritten as a result of automatic redirection. Typically, when a server returns an HTTP code in the 3xx class (for example, 301, moved permanently, or 303, see other), the server sends a message with the reply that instructs the requesting client to direct future requests to the correct URL and IP address. In the case of a reverse proxy setup, a redirection message from the origin server can cause client browsers to bypass the proxy server for subsequent requests. To avoid having clients directly contact the origin server, use the ReversePass directive to intercept requests that are made specifically to the origin server.
Unlike other mapping directives, which process the request stream, ReversePass matches its template to the response stream. The response stream is the reply that the proxy server obtains from the origin server and sends to the client.
ReversePass rewritten_URL proxy_URL [host:port]
The host:port option allows the proxy to apply a different ReversePass rule based on the backend server hostname and port.
ReversePass http://backend.company.com:9080/* http://edge.company.com/*The port 9080 is the default port for Application Service at the Edge. This type of request might be generated if the origin application server returned a 3xx code to the client.
ReversePass http://edge.company.com:9080/* http://edge.company.com/*
None
Use this directive to specify the domain pattern that needs to be rewritten. The directive will transform the domain from domain_pattern1 to domain_pattern2.
RewriteSetCookieDomain domain_pattern1 domain_pattern2
RewriteSetCookieDomain .internal.com .external.com
None
This directive enables or disables RTSP redirection. Options are on or off.
RTSPEnable {on | off}
RTSPEnable on
None
This directive is used to specify RTSP proxy servers to receive redirected requests. Different servers can be specified for different types of streams. The format of this directive is:
rtsp_proxy_server server dns address[:port] default rank [list of mime types]
rtsp_proxy_server rproxy.mycompany.com:554 1 rtsp_proxy_server fw1.mycompany.com:554 2 rtsp_proxy_server fw1.mycompany.com:555 3 rtsp_proxy_server fw2.mycompany.com:557 4
None
This directive specifies how many requests are received before an RTSP request is redirected to a proxy server rather than to the origin server. RealNetworks proxies cache streams on the first request, and caching initially incurs at double the bandwidth of receiving a stream. Specifying a threshold greater than one prevents requests made only once from being cached. The format of this directive is:
rtsp_proxy_threshold number_of_hits
rtsp_proxy_threshold 5
None
This directive specifies the number of unique URLs that are kept in memory for redirection. The proxy refers to this list to determine whether a given URL has been encountered before. Larger list sizes improve the proxy server's ability to send a subsequent request to the same proxy server that received the previous request, but each list entry consumes approximately 16 bytes of memory.
rtsp_url_list_size size_of_list
rtsp_url_list_size 8192
None
Use this directive to set the time allowed for a CGI program started by the server to finish. When the time expires, the server ends the program. On Linux and UNIX platforms, this is done with the KILL signal.
Enter the time value using any combination of hours, minutes (or mins), and seconds (or secs).
ScriptTimeout timeout
ScriptTimeout 5 minutes
Use this directive to specify that requests sent from the Caching Proxy to a downstream server are to use the HTTP Version 1.0 protocol. (A downstream server is another proxy server in a chain of proxies or an origin server that processes the request.)
If this directive is used, the Caching Proxy identifies HTTP 1.0 as the protocol in the request line. Only HTTP 1.0-specific functionality and certain HTTP 1.1 functions, such as cache-control headers, which are supported by most HTTP 1.0 servers, are sent to the downstream server. Use this directive if you have a downstream server that does not handle HTTP 1.1 requests correctly.
If the SendHTTP10Outbound directive is not specified, the Caching Proxy identifies HTTP 1.1 as the protocol in the request line. HTTP 1.1 functionality, such as persistent connections, can also be used in the request.
SendHTTP10Outbound url_pattern
This directive can be specified multiple times, for example:
SendHTTP10Outbound http://www.hosta.com/* SendHTTP10Outbound http://www.hostb.com/*
For backward compatibility, the previous syntax of SendHTTP10Outbound is handled as follows:
None
When functioning as a reverse proxy, the Caching Proxy receives HTTP requests from a client and sends the requests to the origin server. By default, the Caching Proxy writes the origin server's host name in the HOST header of the request that it sends to the origin server. If the SendRevProxyName directive is set to yes, the Caching Proxy writes its own host name in the HOST header instead. This directive can be used to enable special configuration for back-end servers because it allows the request to the origin server to always appear to come from the proxy server, even in the case where the request is redirected from one back-end server to another.
This directive differs from the ReversePass mapping directive as follows: the ReversePass directive intercepts requests with a specified syntax and substitutes different request content that you specify. The SendRevProxyName directive can be set only to substitute the Caching Proxy host name for the origin server host name. This directive is not useful in configuring Application Service at the Edge.
SendRevProxyName {yes | no}
This directive sets the interval at which the garbage collection thread check for server connections that have timed out (set with the ServerConnTimeout directive). Use this directive only if the ServerConnPool directive is set to on.
ServerConnGCRun time_interval
ServerConnGCRun 2 minutes
ServerConnGCRun 2 minutes
This directive allows the proxy to pool together its outgoing connections to origin servers. Setting this directive to on enhances performance and takes better advantage of origin servers that allow persistent connections. You can also specify how long to maintain an unused connection via the ServerConnTimeout directive.
ServerConnPool {on | off}
ServerConnPool off
Use this directive to limit the time allowed without network activity before cancelling the connection. Use this directive only if the ServerConnPool directive is set to on.
ServerConnTimeout time-spec
ServerConnTimeout 30 seconds
ServerConnTimeout 10 seconds
Use this directive to specify a customized application function that the server calls during its initialization routines. This code is executed before any client requests are read and whenever the server is restarted.
If you are using the GoServe modules in the PreExit or Service steps, you need to call the gosclone module here.
ServerInit /path/file:function_name [initialization_string]
ServerInit /ics/api/bin/icsext05.so:svr_init
None
Use this directive to specify the directory where the server program is installed (the current working directory of the server). Logging directives use this current working directory as the default root when relative path names are used.
On Windows systems, the directory is identified during installation.
ServerRoot directory_path
Use this directive to specify a customized application function that the server calls during the Server Termination step. This code is executed when an orderly shutdown occurs and whenever the server is restarted. It allows you to release resources allocated by a PreExit application function.
ServerTerm /path/file:function_name
ServerTerm /ics/api/bin/icsext05.so:shut_down
None
Use this directive to specify a customized application function that the server calls during the Service step. This code services the client request. For example, it sends the file or runs the CGI program.
There is no default for this directive. If the request matches a Service rule (that is, if an application function specified on a Service directive is executed), but the function returns HTTP_NOACTION, the server generates an error and the request fails.
Service request_template/path/file:function_name [server_IP_address | host_name]
A wildcard character cannot be specified for a server's IP address.
Service /index.html /ics/api/bin/icsext05.so:serve_req Service /cgi-bin/hexcalc* /ics/api/calculator:HEXcalc*
None
Use this directive to specify a terminating code for URL requests. Using the terminating code in a request causes the Caching Proxy to evaluate only characters before the terminating code when processing the request and when evaluating whether the result is already cached. When more than one terminator code is defined, the Caching Proxy compares incoming URLs against the terminator codes in the order in which they are defined in the ibmproxy.conf file.
SignificantURLTerminator terminating_string
SignificantURLTerminator &.
In this example, the two requests that follow are treated as identical.
http://www.exampleURL.com/tx.asp?id=0200&.;x=004;y=001 http://www.exampleURL.com/tx.asp?id=0200&.;x=127;y=034
None
Use this directive to set the SMTP server used by the internal sendmail routine within the Caching Proxy for Windows. The following two directives must also be set for this routine: WebMasterEMail -- Set an e-mail address to receive select server reports and WebMasterSocksServer (Windows only)-- set a socks server for the sendmail routine.
SMTPServer IP address or hostname of SMTP server
SMTPServer mybox.com
None
Use this directive to enable or disable SNMP support.
SNMP {on | off}
SNMP off
Use this directive to define the password between the Web server Distributed Protocol Interface (DPI) subagent and the SNMP agent. The SNMP community name authorizes a user to view the performance variables monitored by SNMP for a specified community of servers. The system administrator defines which variables from which servers can be viewed when a password is entered. If you change the SNMP community name, be sure to also change the community name specified in the file /etc/snmpd.conf.
SNMPCommunity name
SNMPCommunity public
Use this directive to cache content on a secure request when a reverse proxy is used. This directive configures caching for all connections to the proxy server, both client connections and connections with a back-end content server.
SSLCaching {on | off}
SSLCaching off
Use this directive to specify key labels that allow the proxy to determine which certificate to send to the client when the Caching Proxy is acting as a single reverse proxy for multiple domains that offer their own SSL certificates and to instruct the proxy server to either retrieve or not retrieve a client-side PKI certificate for client authentication..
SSLCertificate serverIP/hostname CertificateLabel
[NoClientAuth | ClientAuthRequired]
SSLCertificate www.abc.com ABCCert SSLCertificate 204.146.167.72 intABCCert SSLCertificate www.xyz.com XYZCert SSLCertificate www.xyz.com XYZCert ClientAuthRequired
None
Use this directive to tell the proxy server that there is a cryptographic card installed and to specify the card.
SSLCryptoCard {rainbowcs | nciphernfast} {on | off}
SSLCryptoCard rainbowcs on
None
Use this directive to specify that the Caching Proxy listens on port 443 for secure requests.
SSLEnable {on | off}
SSLEnable off
Use this directive to specify the port to address for HTTP requests that the Caching Proxy upgrades to HTTPS requests by implementing SSL. Specify a port other than the main HTTP port 80 or the main SSL port 443.
SSLForwardPort port number
SSLForwardPort 8888
None
Use this directive to disable listener threads for standard HTTP requests (typically ports 80 and 8080) when SSL (typically port 443) is enabled.
SSLOnly {on | off}
SSLOnly off
Use this directive to allow SSL tunneling to any port on the destination host. Setting this directive on allows SSL tunneling to any port on the destination server. Setting this directive off allows SSL tunneling only to ports given in Proxy rules. If there are no Proxy rules for SSL tunneling, and the SSLTunneling directive is set to off, then SSL tunneling is not allowed. If the SSLTunneling directive is set to on, you must also enable the method CONNECT, using the directive Enable.
When using Caching Proxy as a reverse proxy, disabling this directive (default) protects against SSL tunneling vulnerability attacks.
SSLTunneling {on | off}
SSLTunneling off
Use this directive to specify the version of SSL to use: V2, V3, or all versions. Set this directive to V2 if you are using servers that cannot support SSL Version 3.
SSLVersion {SSLV2 | SSLV3 | all}
SSLVersion SSLV3
Use this directive to specify in seconds how long an SSL version 2 session waits with no activity before the session expires.
SSLV2Timeout seconds
where seconds represents a value between 0 and 100.
SSLV2Timeout 100
Use this directive to specify in seconds how long an SSL version 3 session waits with no activity before it expires.
SSLV3Timeout seconds
where seconds represents a value between 1 and 86400 seconds (which is 1 day in seconds).
SSLV3Timeout 100
Use this directive to specify whether you want the server to distinguish between uppercase and lowercase letters when file suffixes are compared to the suffix patterns on the AddClient, AddCharSet, AddType, AddEncoding, and AddLanguage directives. By default, the server does not distinguish between cases.
SuffixCaseSense {on | Off}
SuffixCaseSense Off
Use this directive to enable the TLS version 1 protocol in SSL connections. After this directive is turned on, the SSL connection checks the TLS protocol first, then the SSLv3 protocol, and the SSLv2 protocol last.
TLSV1Enable {on | off}
TLSV1Enable on
None
Use this directive to specify a customized application function that the server calls during the Data Manipulation step. This code provides three application functions:
You can have multiple Transmogrifiers active for each instance of the server.
Transmogrifier /path/file:function_name:function_name:function_name
Transmogrifier /ics/bin/icsext05.so:open_data:write_data:close_data
None
Use this directive to send a message to the client informing it that the data:
transmogrifiedwaning {yes|no}
Yes
Linux and AIX only. Use this directive to specify whether the server can run as a transparent proxy server.
TransparentProxy {On | Off}
Port 80
TransparentProxy Off
ibmproxy -unloadOn Linux systems, this command removes the redirection Firewall rules, and on AIX systems, it unloads the Transparent Proxy Kernel Extension. If you do not issue this command after stopping the server, your machine will accept requests that are not destined for it.
Use this directive to specify which proxy server the cache agent updates. This is required when the cache agent needs to update a proxy server other than the local proxy server on which the cache agent is running. Optionally, you can specify the port.
Although the cache agent can update the cache on another server, it cannot retrieve the cache access log from that machine. Therefore, if the UpdateProxy directive specifies a host other than the local host, the LoadTopCached directive is ignored.
UpdateProxy fully_qualified_host_name_of_proxy_server
UpdateProxy proxy15.ibm.com:1080
None
Use this directive to specify the user name or number to which the server changes before accessing files.
If you change this directive, you must manually stop your server and then start it again for the change to take effect. The server does not recognize the change if you only restart it. (See Starting and stopping the Caching Proxy.)
UserId {ID_name | number}
AIX, Linux, Solaris: UserId nobody
HP-UX: UserId www
This directive lists the available cipher specification for SSL Version 2.
V2CipherSpecs specification
Acceptable values are any combination of the following. None can be used twice.
None (SSL is disabled by default.)
This directive lists available cipher specifications for SSL Version 3.
V3CipherSpecs specification
Acceptable values include the following:
None (SSL is disabled by default.)
Use this directive to set an e-mail address at which to receive select Caching Proxy reports, such as a notice 30 days prior to the expiration of an SSL certificate. On Linux and UNIX systems, a sendmail process must be running. For Windows systems, the sendmail process is built into the Caching Proxy, so no external mail server is required; however, two additional directives must be set: WebMasterSocksServer (Windows only)-- set a socks server for the sendmail routine and SMTPServer (Windows only)-- set an SMTP server for the sendmail routine.
WebMasterEMail webmastermailaddress
WebMasterEmail webmaster@computer.com
WebMasterEmail webmaster
Use this directive to set the socks server used by the internal sendmail routine within the Caching Proxy for Windows. The following two directives must also be set for this routine: WebMasterEMail -- Set an e-mail address to receive select server reports and SMTPServer (Windows only)-- set an SMTP server for the sendmail routine.
WebMasterSocksServer IP address or hostname of socks server
WebMasterSocksServer socks.mybox.com
None
Use this directive to specify the name of a welcome file that the server looks for to respond to requests that do not contain a specific file name. You can build a list of welcome files by putting multiple occurrences of this directive in the configuration file.
For requests that do not contain a file name or a directory name, the server always looks in the file root directory for a file that matches a name specified on a Welcome directive. If a match is found, the file is returned to the requester.
For requests that contain a directory name but not a file name, the AlwaysWelcome directive controls whether the server looks in the directory for a welcome file to return. By default, AlwaysWelcome is set to a value of On. This means the server always looks in the requested directory for a file matching a name specified on a Welcome directive. If a match is found, the file is returned to the requester.
If the server finds more than one match between files in a directory and file names on Welcome directives, the order of the Welcome directives determines which file is returned. The server uses the Welcome directive closest to the beginning of the configuration file.
Welcome file_name [server_IP_address | host_name]
You can specify an IP address (for example, 240.146.167.72), or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests, regardless of the IP address on which the requests come in or the host name in the URLs.
A wildcard character cannot be specified for a server's IP address.
Welcome letsgo.html Welcome Welcome.html
Welcome CustomerA.html 0.67.106.79 Welcome CustomerB.html 0.83.100.45
Welcome CustomerA.html hostA.bcd.com Welcome CustomerB.html hostB.bcd.com
These defaults are in the order used by the default configuration:
Welcome Welcome.html Welcome welcome.html Welcome index.html Welcome Frntpage.html