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.
- 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
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.
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. Enable MY_METHOD WithBody
Associated directives
The following directives enable WebDAV methods, MS Exchange methods, and user-defined methods:
Define mapping rules
- Basic proxy function
- Access to the browser-based Configuration and Administration forms
- Ability to cache servlet results and other dynamically generated content
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
- Map, MapQuery — rewrite 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.
- 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.
- 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
- 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.
Associated directives
The following directives define mapping rules:
- Map — Change matching requests to a new request string, using the request path string to match the rule
- MapQuery — Change matching requests to a new request string, using the request path and query string to match the rule
- RuleCaseSense — Maps requests from application URLs that are not case sensitive
- Pass — Specify the template for accepting requests
- Exec — Run a CGI program for matching requests
- Redirect — Specify a template for requests sent to another server
- Proxy — Specify proxy protocols or reverse proxy
- ProxyWAS — Specify that requests are sent to WebSphere Application Server
- ReversePass — Intercept automatically redirected requests
Configuration and Administration forms
The following Configuration and Administration form edits the values of the associated directives:
- Server Configuration –> Request Processing –> Request Routing
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.
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 |
Define the junction without the JunctionPrefix option
- Proxy /shop/* http://shopserver.acme.com/*
- Proxy /auth/* http://authserver.acme.com/*
- Proxy /* http://defaultserver.acme.com/*
- Proxy /images/*.gif http://imageserver.acme.com/images/*.gif
- Proxy /cgi-bin/* http://cgiserver.acme.com/cgi/perl/*
- /index.html (server relative reference)
- /images/shop.gif (server relative reference)
- buy/buy.jsp (directory relative reference)
- http://ebay.com (absolute reference)
- /shop/index.html (changed)
- /shop/images/shop.gif (changed)
- buy/buy.jsp (unchanged)
- http://ebay.com (unchanged)
Define the junction with the JunctionPrefix option
Proxy url_patern1 url_pattern2 JunctionPrefix:url_prefix
Proxy /market/partners/*.html http://b2bserver.acme.com/*.html
junctionprefix:/market/partners
Associated directives
The following directives are used to enable the junction rewriting routine and plug-in.
- ServerInit — Customize the Server Initialization step
- Transmogrifier — Customize the Data Manipulation step
- JunctionRewrite — Enables URL rewriting
- JunctionRewriteSetCookiePath — Rewrite the path option in the Set-Cookie header, when used with JunctionRewrite plugin
- JunctionReplaceUrlPrefix — Replace URL instead of insert prefix when used with JunctionRewrite plugin
- JunctionSkipUrlPrefix — Skip rewriting URLs that already contain the prefix, when used with JunctionRewrite plugin
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
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.
- Change JunctionRewrite on with JunctionRewrite on UseCookie.
- 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.
- 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)