Manage request processing

When 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 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.

Enable HTTP/FTP methods

Client requests to the server include a method field that indicates the action that the server is to perform on the specified object.

Following is a list of methods that the proxy server supports and a description of how it responds to a client request containing the method if the method is enabled.

Note:
Some methods are the same for HTTP and for FTP requests. Enabling these methods for HTTP also enables them for FTP.

CONNECT
The CONNECT method allows you to tunnel requests and responses through the proxy server. This applies to forward proxy configurations only.

For information on the format and available options for the Enable CONNECT method, see Configuring SSL tunneling.

DELETE
The proxy server deletes the object identified by the URL. DELETE allows clients to erase files from your Caching Proxy. Use server protection setups to define who can use DELETE and on which files. For details, see Server protection setups.
GET
The proxy server returns whatever data is identified by the URL. If the URL refers to an executable program, the proxy returns the output of the program. This method can be handled over persistent connections.
HEAD
The proxy server returns only the HTTP document header identified by the URL without the document body.
OPTIONS
The proxy server returns information about the communications options on the request-response chain identified by the URL. This method allows a client to determine the options and requirements associated with an object, or the capabilities of a server, without having to act on or retrieve the object.
POST
The request contains data and a URL. The proxy server accepts the data enclosed in the request as a new subordinate of the resource identified in the URL, which processes the data. The resource can be a data-accepting program, a gateway to some other protocol, or a separate program that accepts annotations.

The POST method is designed to handle the annotation of existing resources. Examples include posting a message to a bulletin board, newsgroup, mailing list, or similar group of resources; providing a block of data, for example, from a form to a data-handling program; or extending a database through an append operation. For Caching Proxy, the POST method is used to process the Configuration and Administration forms.

This method can be handled over persistent connections.

PUT
The request contains data and a URL. The proxy server stores the data in the resource identified in the URL. If the resource already exists, PUT replaces it with the data contained in the request. If the resource does not exist, PUT creates it and populates it with the data contained in the request. This method can be handled over persistent connections.

Enabling the PUT method allows files to be written to Caching Proxy by using HTTP and FTP. Because PUT allows clients to write to Caching Proxy, you need to use server-protection setups to define who can use PUT and the files on which PUT can be used. (See Server protection setups.)

TRACE
The proxy server echoes the request message sent by the client. This method allows the client to see what is being received at the other end of the request chain and use that data for testing or diagnostics. The content type of the proxy response is message/http.

Associated directives

The following directives enable HTTP/FTP methods:

For more information, refer to Manually editing the ibmproxy.conf file.

Configuration and Administration forms

The following Configuration and Administration forms edit the values of the associated directives:

Note:
If you disable the POST method, you cannot use the Configuration and Administration forms to configure the Caching Proxy.

For more information, refer to Using the Configuration and Administration forms.

Enable WebDAV methods, MS Exchange methods, and User-defined methods

This applies to reverse proxy configurations only.

In addition to support of standard HTTP methods, Caching Proxy supports forwarding other methods defined in RFCs or used by some applications. Caching Proxy also supports customer defined methods and allows them to be forwarded through the proxy server.

Web-based Distributed Authoring and Versioning (WebDAV) is a set of extensions to the HTTP protocol that allows you to collaboratively edit and manage files on remote Web servers. Caching Proxy supports WebDAV methods, methods used by Microsoft Exchange Server, and user-defined (customized) methods.

These methods are hard-coded and are managed by the Enable and Disable directives. Administrators can also use the corresponding method-mask defined in the PROTECT directive to authorize the use of these methods.

Supported WebDAV methods (RFC 2518): PROPFIND , PROPPATCH , MKCOL, COPY, MOVE, LOCK, UNLOCK, SEARCH

Supported MS Exchange methods: BMOVE, BCOPY, BDELETE, BPROPFIND, BPROPPATCH, POLL, NOTIFY, SUBSCRIBE, UNSUBSCRIBE, ACL, SUBSCRIPTIONS, X_MS_ENUMATTS

When the WebDAV or MS Exchange Server methods are enabled, Caching Proxy forwards the requests to the target servers only and does not rewrite any resource link in the request body.

Caching Proxy can also forward user-defined methods to the back-end server. Use the following syntax for the Enable directive in the ibmproxy.conf file to enable a customized method:

Enable   user-defined-method [WithBody | WithoutBody]

Setting a value of WithBody or WithoutBody indicates to the proxy if the user-defined method needs a request body.

The following example enables a user-defined method My_METHOD and indicates to the proxy that the method needs a request body:

Enable MY_METHOD WithBody

Associated directives

The following directives enable WebDAV methods, MS Exchange methods, and user-defined methods:

For more information, refer to Manually editing the ibmproxy.conf file.

Define mapping rules

Mapping rules are configuration directives that cause client requests to 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.

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:

Configure a surrogate server

To configure a standard surrogate:

This allows all HTTP traffic on port 80 to be proxied to the origin server. Traffic entering on the administration port does not match the initial wildcard proxy rule, and so it is unaffected. The remaining mapping rules are used to process the request.

Associated directives

The following directives define mapping rules:

For more information, refer to Manually editing the ibmproxy.conf file.

Configuration and Administration forms

The following Configuration and Administration form edits the values of the associated directives:

Note:
The Configuration and Administration forms do not support the port number argument.

For more information, refer to Using the Configuration and Administration forms.

Enable junction rewrite (optional)

This applies to reverse proxy configurations only.

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.

Define the junction 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:

Define the junction with the JunctionPrefix option (recommended method)

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:

Table 3. Tags affected by the junction rewriting routine
Tag Attributes
!-- URL
a href
applet archive, codebase
area href
base href
body background
del cite
embed pluginspage
form action
input src
frame src, longdesc
iframe src, longdesc
ilayer src, background
img src, usemap, lowsrc, longdesc, dynsrc
layer src, background
link href
meta url
object data, classid, codebase, codepage
script src
table background
td background
th background
tr background
Note:
The junction rewriting routine will not affect tags generated by JavaScript or by plug-ins within the browser.

Associated directives

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.

Configuration and Administration forms

The following Configuration and Administration form can be used to enable the junction rewriting plug-in:

Note:
The Configuration and Administration forms do not support the JunctionRewrite directive.

For more information, refer to Using the Configuration and Administration forms.

UseCookie as an alternative to JunctionRewrite

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:

  1. Change JunctionRewrite on with JunctionRewrite on UseCookie.
  2. Comment out the JunctionRewrite plugin.

The following is a comparison of the JunctionRewrite plugin and the cookie implementation.

Sample transmogrifier plugin to extend JunctionRewrite functionality

Customizable sample code is provided that rewrites and parses JavaScript™ (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™.

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.