Manage request processing

The information here describes how to enable methods, define mapping rules, and configure a surrogate proxy server

When Caching Proxy receives a client request, it performs the action that is specified in the method field on the object that is specified in the URL field, if the requested method is enabled. The proxy server resolves the URL according to a set of mapping rules that are 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.

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 that contains the method, if 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.
DELETE
The proxy server deletes the object that is 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.
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 that is identified by the URL without the document body.
OPTIONS
The proxy server returns information about the communications options on the request-response chain that is identified by the URL. This method allows a client to determine the options and requirements that are 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 that is enclosed in the request as a new subordinate of the resource that is 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 that is identified in the URL. If the resource 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.

TRACE
The proxy server echoes the request message that is 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:

Configuration and Administration forms

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

  • Server Configuration –> Request Processing –> HTTP Methods –> GET
  • Server Configuration –> Request Processing –> HTTP Methods –> HEAD
  • Server Configuration –> Request Processing –> HTTP Methods –> POST
  • Server Configuration –> Request Processing –> HTTP Methods –> PUT
  • Server Configuration –> Request Processing –> HTTP Methods –> DELETE
  • Server Configuration –> Request Processing –> HTTP Methods –> OPTIONS
  • Server Configuration –> Request Processing –> HTTP Methods –> TRACE
  • Server Configuration –> Request Processing –> HTTP Methods –> CONNECT
Note: If you disable the POST method, you cannot use the Configuration and Administration forms to configure the Caching Proxy.

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 that are 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 enables you to collaboratively edit and manage files on remote web servers. Caching Proxy supports WebDAV methods, methods that are used by Microsoft Exchange Server, and user-defined (customized) methods.

These methods are hardcoded and are managed by the Enable and Disable directives. Administrators can also use the corresponding method-mask that is 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:

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:
  • Basic proxy function
  • Access to the browser-based Configuration and Administration forms
  • Ability to cache servlet results and other dynamically generated content
Mapping rule directives use the following form:
                                 rule
                
                                 template
                
                                 target
                [                  IP_address
                |                   host_name
               ]:[                  port
               ]

Only requests that match the 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:
  • Map, MapQueryrewrite the request. The Map and MapQuery rules replace a request URL (template) with another URL string (target). After this substitution, the request, containing the new string, continues to be compared to the remaining mapping rules.
  • RuleCaseSense — allows mapping requests from application URLs that are not case-sensitive. When tuned off, the RuleCaseSense directive allows the proxy to map requests against rules that are defined in the ibmproxy.conf file without case sensitivity.
  • Pass, Exec — serve the request locally. The Pass and Exec rules process the request at the proxy server. The Pass rule maps a request URL (template) to a file that is served from the proxy server (target); the Exec rule maps a request URL to a CGI program that runs on the proxy server.
  • Fail — reject the request. The Fail rule rejects a request (template) at the proxy server. Any request that matches the template of a Fail rule is not processed further. Fail rules do not have target arguments.
  • Redirect — forward the request. The Redirect rule forwards a request (template) to another web server (target). Because a full URL, including the communication protocol, is the target of this rule, it is possible to change the protocol during this redirection, for example, to add SSL encryption to an HTTP request. A redirection does not check the cache before satisfying the request.
  • Proxy, ProxyWAS — proxy the request. The Proxy and ProxyWAS rules pass requests (templates) to another server (target). Unlike a simple Redirect rule, the Proxy rules allow the proxy server to check the cache to satisfy a request, to cache content from origin servers, and to write HTTP headers that enable advanced functions. Use the ProxyWAS rule instead of the Proxy rule when the origin server is a WebSphere® Application Server.
The following mapping rule applies to the origin server response:
  • ReversePass — intercept automatically redirected requests. A ReversePass rule matches the response from the origin server to the template as it passes through the proxy server on its way to the client. The ReversePass directive is designed to detect a redirection status code that would cause a client to directly contact the origin server. The client is instructed to contact the server that is defined in the target argument.
The following mapping rules apply to API applications:
  • nameTrans — accepts the request and runs an API application, which is defined by the replacement file path, during the Name Translation step of request processing.
  • service — accepts the request and runs an API application, which is defined by the replacement file path, during the Service step of request processing.

Configure a surrogate server

To configure a standard surrogate:
  • Set the proxy server port to 80.
    Port 80
  • Add a Proxy rule, before all other rules, that proxy all requests that are received on port 80 to the origin server.
    Proxy /* http://our.content.server.com/* :80
  • Enable an administration port on a port other than 80.
    AdminPort 8080

This will allow 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.

Configuration and Administration forms

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

  • Server Configuration –> Request Processing –> Request Routing
Note: The Configuration and Administration forms do not support the port number argument.

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.

The junction rewriting routine affects the following tags:
Table 1. 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 that are generated by JavaScript or by plug-ins within the browser.

Define the junction without the JunctionPrefix option

The following are examples of valid junctions that can be acted upon by the junction rewriting routine:
  • Proxy /shop/* http://shopserver.acme.com/*
  • Proxy /auth/* http://authserver.acme.com/*
The following is an example of a valid junction that will not be acted upon by the junction rewriting routine:
  • Proxy /* http://defaultserver.acme.com/*
The following are examples of invalid junctions:
  • Proxy /images/*.gif http://imageserver.acme.com/images/*.gif
  • Proxy /cgi-bin/* http://cgiserver.acme.com/cgi/perl/*
These mapping rules create junctions for shopserver, authserver, and b2bserver. Consider that shopserver returns an HTML document with the following URLs contained within appropriate HTML tags:
  • /index.html (server relative reference)
  • /images/shop.gif (server relative reference)
  • buy/buy.jsp (directory relative reference)
  • http://ebay.com (absolute reference)
The junction rewriting routine rewrites the server relative references by using the proxy mapping rules as follows:
  • /shop/index.html (changed)
  • /shop/images/shop.gif (changed)
  • buy/buy.jsp (unchanged)
  • http://ebay.com (unchanged)

Define the junction with the JunctionPrefix option

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

Configuration and Administration forms

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

  • Server Configuration –> Request Processing –> API Request Processing
Note: The Configuration and Administration forms do not support the JunctionRewrite directive.

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 plug-in.

The following is a comparison of the JunctionRewrite plug-in and the cookie implementation.

  • JunctionRewrite plug-in
    • HTML page is rewritten.
    • Does not support rewrite of script languages and applets, unless using the transmogrifier plug-in.
    • Decreased performance.
    • No limitations on back-end server configurations. Client can cross-access back-end servers in a session.
  • Cookie implementation
    • HTML page is not rewritten. A cookie is sent to the client.
    • Client browser must enable cookie support.
    • Increased performance.
    • Some limitation on back-end server configurations. Can be used only when a client accesses on back-end server in a session.
    Note: There is a known limitation when using JunctionRewrite with the UseCookie option. It will incorrectly translate URLs for all requests even though the cookie applies only to one subdirectory of the host. The following are two ways to correctly handle the URLs that are under ROOT and do not need junction:
    • Place the proxy rules before the JunctionRewrite directive in the ibmproxy.conf file. (All proxy rules that are before the JunctionRewrite directive will not be rewritten.)
    • Explicitly map each URL, instead of using a wildcard (*). For example:
      Proxy /no-juntion.jpg  http://login-server/no-junction.jpg

Sample transmogrifier plugin to extend the JunctionRewrite function

Customizable sample code is provided, that rewrites and parses JavaScript™ (SCRIPT) and applet (APPLET) tag blocks in HTML files. Alone, the JunctionRewrite plug-in 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 in the samples/cp/ subdirectory, under the directory in which you downloaded the fix pack.
  • Makefile (Makefile for this sample plug-in)
  • junctionRewrite2.h (interface for customized parser handler
  • junctionRewrite2.c (implementation for above interface)
  • scriptHandler.c (sample JavaScript rewrite handler)
  • appletHandler.c (sample Applet block handler)
  • junctionRewrite2.def (Windows plug-in def file)
  • junctionRewrite2.exp (Linux and UNIX plug-in export file)

Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: March 23, 2018 0:18
File name: man_req_proc.html