Caching Proxy API reference information

Variables

When writing API programs, you can use Caching Proxy variables that provide information about the remote client and server system.

Notes:

Variable definitions

Note:
Header variables that do not begin with HTTP_ or PROXY_ prefixes are ambiguous. To avoid ambiguity, always use the HTTP_ or PROXY_ prefix with variable names for headers.
ACCEPT_RANGES
Contains the value of the Accept-Ranges response header, which specifies whether the content server can respond to range requests. Use PROXY_ACCEPT_RANGES to extract the header value that is sent by the content server to the proxy. Use HTTP_ACCEPT_RANGES to set the header value that is sent from the proxy to the client.
Note:
ACCEPT_RANGES is ambiguous. To eliminate ambiguity, use HTTP_ACCEPT_RANGES and PROXY_ACCEPT_RANGES instead.
ALL_VARIABLES
Read-only. Contains all of the CGI variables. For example:
     ACCEPT_RANGES BYTES
     CLIENT_ADDR 9.67.84.3
AUTH_STRING
Read-only. If the server supports client authentication, this string contains the undecoded credentials to be used to authenticate the client.
AUTH_TYPE
Read-only. If the server supports client authentication and the script is protected, this variable contains the method used to authenticate the client. For example, Basic.
CACHE_HIT
Read-only. Identifies whether or not the proxy request was found in the cache. Values returned include the following:
CACHE_MISS
Write-only. Used to force a cache miss. Valid values are the following:
CACHE_TASK
Read-only. Identifies whether the cache was used. Values returned include the following:

This variable can be used in the PostAuthorization, PostExit, ProxyAdvisor, or Log steps.

CACHE_UPDATE
Read-only. Identifies whether or not the proxy request updated the cache. Values returned include the following:
CLIENT_ADDR or CLIENTADDR
Same as REMOTE_ADDR.
CLIENTMETHOD
Same as REQUEST_METHOD.
CLIENT_NAME or CLIENTNAME
Same as REMOTE_HOST.
CLIENT_PROTOCOL or CLIENTPROTOCOL
Contains the name and version of the protocol that the client is using to make the request. For example, HTTP/1.1.
CLIENT_RESPONSE_HEADERS
Read-only. Returns a buffer containing the headers that the server sends to the client.
CONNECTIONS
Read-only. Contains the number of connections being served, or the number of active requests. For example, 15.
CONTENT_CHARSET
Character set of the response for text/*, for example, US ASCII. Extracting this variable applies to the content-charset header from the client. Setting it affects the content-charset header in the request to the content server.
CONTENT_ENCODING
Specifies the encoding used in the document, for example, x-gzip. Extracting this variable applies to the content-encoding header from client. Setting it affects the content-encoding header in the request to the content server.
CONTENT_LENGTH
Extracting this variable applies to the header from the client's request. Setting it affects the value of the header in the request to the content server.

Note:
CONTENT_LENGTH is ambiguous. To eliminate ambiguity, use HTTP_CONTENT_LENGTH and PROXY_CONTENT_LENGTH.
CONTENT_TYPE
Extracting this variable applies to the header from the client's request. Setting it affects the value of the header in the request to the content server.

Note:
CONTENT_TYPE is ambiguous. To eliminate ambiguity, use HTTP_CONTENT_TYPE and PROXY_CONTENT_TYPE.
CONTENT_TYPE_PARAMETERS
Contains other MIME attributes, but not the character set. Extracting this variable applies to the header from the client request. Setting it affects the value of header in the request to the content server.
DOCUMENT_URL
Contains the Uniform Request Locator (URL). For example:
http://www.anynet.com/~userk/main.htm
DOCUMENT_URI
Same as DOCUMENT_URL.
DOCUMENT_ROOT
Read-only. Contains the document root path, as defined by pass rules.
ERRORINFO
Specifies the error code to determine the error page. For example, blocked.
EXPIRES
Defines when documents stored in a proxy's cache expire. Extracting this variable applies to the header from client request. Setting it affects the value of header in the request to the content server. For example:
Mon, 01 Mar 2002 19:41:17 GMT
GATEWAY_INTERFACE
Read-only. Contains the version of the API that the server is using. For example, ICSAPI/2.0.
GC_BIAS
Write-only. This floating-point value influences the garbage collection decision for the file being considered for garbage collection. The value entered is multiplied by the Caching Proxy's quality setting for that file type to determine ranking. Quality settings range from 0.0 to 0.1 and are defined by the AddType directives in the proxy configuration file (ibmproxy.conf).
GC_EVALUATION
Write-only. This floating-point value determines whether to remove (0.0) or keep (1.0) the file being considered for garbage collection. Values between 0.0 and 1.0 are ordered by rank, that is, a file with the GC_EVALUATION value 0.1 is more likely to be removed than a file with the GC_EVALUATION value 0.9.
GC_EXPIRES
Read-only. Identifies how many seconds remain until the file under consideration expires in the cache. This variable can be extracted only by a GC Advisor plug-in.
GC_FILENAME
Read-only. Identifies the file being considered for garbage collection. This variable can be extracted only by a GC Advisor plug-in.
GC_FILESIZE
Read-only. Identifies the size of the file being considered for garbage collection. This variable can be extracted only by a GC Advisor plug-in.
GC_LAST_ACCESS
Read-only. Identifies when the file was last accessed. This variable can be extracted only by a GC Advisor plug-in.
GC_LAST_CHECKED
Read-only. Identifies when the files were last checked. This variable can be extracted only by a GC Advisor plug-in.
GC_LOAD_DELAY
Read-only. Identifies how long it took to retrieve the file. This variable can be extracted only by a GC Advisor plug-in.
HTTP_COOKIE
When read, this variable contains the value of the Set-Cookie header set by the client. It can also be used to set a new cookie in the response stream (between the proxy and the client). Setting this variable causes the creation of a new Set-Cookie header in the document request stream, regardless of whether or not a duplicate header exists.
HTTP_HEADERS
Read-only. Used to extract all of the client request headers.
HTTP_REASON
Setting this variable affects the reason string in the HTTP response. Setting it also affects the reason string in the proxy's response to the client. Extracting this variable returns the reason string in the response from the content server to the proxy.
HTTP_RESPONSE
Setting this variable affects the response code in the HTTP response. Setting it also affects the status code in the proxy's response to the client. Extracting this variable returns the status code in the response from the content server to the proxy.
HTTP_STATUS
Contains the HTTP response code and reason string. For example, 200 OK.
HTTP_USER_AGENT
Contains the value of the User-Agent request header, which is the name of the client Web browser, for example, Netscape Navigator / V2.02. Setting this variable affects the header in the proxy's response to the client. Extracting it applies to the header from the client's request.
INIT_STRING
Read-only. The ServerInit directive defines this string. This variable can be read only during the Server Initialization step.
LAST_MODIFIED
Extracting this variable applies to the header from the client request. Setting it affects the value of the header in the request to the content server. For example:
Mon, 01 Mar 1998 19:41:17 GMT
LOCAL_VARIABLES
Read-only. All the user-defined variables.
MAXACTIVETHREADS
Read-only. The maximum number of active threads.
NOTMODIFIED_TO_OK
Forces a full response to the client. Valid in the PreExit and ProxyAdvisor steps.
ORIGINAL_HOST
Read-only. Returns the host name or destination IP address of a request.
ORIGINAL_URL
Read-only. Returns the original URL sent in the client request.
OVERRIDE_HTTP_NOTRANSFORM
Enables modification of data in the presence of a Cache-Control: no-transform header. Setting this variable affects the response header to the client.
OVERRIDE_PROXY_NOTRANSFORM
Enables modification of data in the presence of a Cache-Control: no-transform header. Setting this variable affects the request to the content server.
PASSWORD
For basic authentication, contains the decoded password. For example, password.
PATH
Contains the fully translated path.
PATH_INFO
Contains the additional path information as sent by the Web browser. For example, /foo.
PATH_TRANSLATED
Contains the decoded or translated version of the path information contained in PATH_INFO. For example:
d:\wwwhome\foo
/wwwhome/foo
PPATH
Contains the partially translated path. Use this in the Name Translation step.
PROXIED_CONTENT_LENGTH
Read-only. Returns the length of the response data actually transferred through the proxy server.
PROXY_ACCESS
Defines whether the request is a proxy request. For example, NO.
PROXY_CONTENT_TYPE
Contains the Content-Type header of the proxy request made through HTTPD_proxy(). When information is sent with the method of POST, this variable contains the type of data included. You can create your own content type in the proxy server configuration file and map it to a viewer. Extracting this variable applies to the header value from the content server response. Setting it affects the header for the request to the content server. For example:
application/x-www-form-urlencoded
PROXY_CONTENT_LENGTH
The Content-Length header of the proxy request made through HTTPD_proxy(). When information is sent with the method of POST, this variable contains the number of characters of data. Servers typically do not send an end-of-file flag when they forward the information using standard input. If needed, you can use the CONTENT_LENGTH value to determine the end of the input string. Extracting this variable applies to the header value from the content server response. Setting it affects the header for the request to the content server. For example:
7034
PROXY_COOKIE
When read, this variable contains the value of the Set-Cookie header set by the origin server. It also can be used to set a new cookie in the request stream. Setting this variable causes the creation of a new Set-Cookie header in the document request stream, regardless of whether or not a duplicate header exists.
PROXY_HEADERS
Read-only. Used to extract the Proxy headers.
PROXY_METHOD
Method for the request made through HTTPD_proxy(). Extracting this variable applies to the header value from the content server response. Setting it affects the header for the request to the content server.
QUERY_STRING
When information is sent by using a method of GET, this variable contains the information that follows a question mark (?) in a query. This information must be decoded by the CGI program. For example:
NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
RCA_OWNER
Read-only. Returns a numeric value, giving the node that owned the requested object. This variable can be used in the PostExit, ProxyAdvisor, or Log steps, and is meaningful only when the server is part of a cache array using remote cache access (RCA).
RCA_TIMEOUTS
Read-only. Returns a numeric value, containing the total (aggregate) number of timeouts on RCA requests to all peers. You can use this variable in any step.
REDIRECT_*
Read-only. Contains a redirection string for the error code that corresponds to the variable name (for example, REDIRECT_URL). A list of possible REDIRECT_ variables can be found in online documentation for the Apache Web server at http://httpd.apache.org/docs-2.0/custom-error.html.
REFERRER_URL
Read-only. Contains the last URL location of the browser. It allows the client to specify, for the server's benefit, the address (URL) of the resource from which the Request-URL was obtained. For example:
http://www.company.com/homepage
REMOTE_ADDR
Contains the IP address of the Web browser, if available. For example, 45.23.06.8.
REMOTE_HOST
Contains the host name of the Web browser, if available. For example, www.raleigh.ibm.com.
REMOTE_USER
If the server supports client authentication and the script is protected, this variable contains the user name passed for authentication. For example, joeuser.
REQHDR
Read-only. Contains a list of the headers sent by the client.
REQUEST_CONTENT_TYPE
Read-only. Returns the content type of the request body. For example:
application/x-www-form-urlencoded
REQUEST_CONTENT_LENGTH
Read-only. When information is sent with the method of POST, this variable contains the number of characters of data. Servers typically do not send an end-of-file flag when they forward the information using standard input. If needed, you can use the CONTENT_LENGTH value to determine the end of the input string. For example, 7034.
REQUEST_METHOD
Read-only. Contains the method (as specified with the METHOD attribute in an HTML form) used to send the request. For example, GET or POST.
REQUEST_PORT
Read-only. Returns the port number specified in the URL, or a default port based on the protocol.
RESPONSE_CONTENT_TYPE
Read-only. When information is sent with the method of POST, this variable contains the type of data included. You can create your own content type in the proxy server configuration file and map it to a viewer. For example, text/html.
RESPONSE_CONTENT_LENGTH
Read-only. When information is sent with the method of POST, this variable contains the number of characters of data. Servers typically do not send an end-of-file flag when they forward the information using standard input. If needed, you can use the CONTENT_LENGTH value to determine the end of the input string. For example, 7034.
RULE_FILE_PATH
Read-only. Contains the fully qualified file system path and file name of the configuration file.
SSL_SESSIONID
Read-only. Returns the SSL session ID if the current request is received on an SSL connection. Returns NULL if the current request is not received on an SSL connection.
SCRIPT_NAME
Contains the URL of the request.
SERVER_ADDR
Read-only. Contains the local IP address of the proxy server.
SERVER_NAME
Read-only. Contains the proxy server host name or IP address of the content server for this request. For example, www.ibm.com.
SERVER_PORT
Read-only. Contains the port number of the proxy server to which the client request was sent. For example, 80.
SERVER_PROTOCOL
Read-only. Contains the name and version of the protocol used to make the request. For example, HTTP/1.1.
SERVER_ROOT
Read-only. Contains the directory where the proxy server program is installed.
SERVER_SOFTWARE
Read-only. Contains the name and version of the proxy server.
STATUS
Contains the HTTP response code and reason string. For example, 200 OK.
TRACE
Determines how much information will be traced. Returned values include:
URI
Read/Write. Same as DOCUMENT_URL.
URI_PATH
Read-only. Returns the path portion only for a URL.
URL
Read/Write. Same as DOCUMENT_URL.
URL_MD4
Read-only. Returns the file name of the potential cache file for the current request.
USE_PROXY
Identifies the proxy with which to associate the current request. Specify the URL. For example, http://myproxy:8080.
USERID
Same as REMOTE_USER.
USERNAME
Same as REMOTE_USER.

Authentication and authorization

First, a short review of the terminology:

Authentication
The verification of the security tokens associated with this request in order to ascertain the identity of the requester.
Authorization
A process that uses security tokens to determine whether the requester has access to the resource.

Figure 3 depicts the proxy server's authentication and authorization process.

Figure 3. Proxy server authentication and authorization process
Authorization and authentication process diagram

As demonstrated in Figure 3, the initiation of the authorization process is the first step in the server's authorization and authentication process.

In the Caching Proxy, authentication is part of the authorization process; it occurs only when authorization is required.

Authentication and authorization process

The proxy server follows these steps when processing a request that requires authorization.

  1. First, the proxy server examines its configuration file to determine whether or not there is an authorization directive.
  2. The proxy server begins the authentication process by checking to see if the HTTP_authenticate header is present in the client request.
  3. The proxy server checks to see if there is an authentication directive present in the proxy configuration file.

If your Caching Proxy plug-in provides its own authorization process, it overrides the default server authorization and authentication. Therefore, if you have authorization directives in your configuration file, the plug-in functions associated with them must also handle any necessary authentication. The predefined HTTPD_authenticate() function is provided for you to use.

There are three ways to provide for authentication in your authorization plug-ins:

If your Caching Proxy plug-in does not provide its own authorization process, you can still provide customized authentication by using the following method:

When the Authorization step is executed, it performs the default server authorization, which, in turn, calls your authentication plug-in function.

Remember the following points:

Variant caching

Use variant caching to cache data that is a modified form of the original document (the URI). The Caching Proxy handles variants generated by the API. Variants are different versions of a base document.

In general, when origin servers send variants, they fail to identify them as such. The Caching Proxy supports only variants created by plug-ins (for example, code page conversion). If a plug-in creates a variant based on criteria that are not in the HTTP header, it must include a PreExit or PostAuthorization step function to create a pseudoheader so that the Caching Proxy can correctly identify the existing variant.

For example, use a Transmogrifier API program to modify the data that users request based on the value of the User-Agent header that the browser sends. In the close function, save the modified content to a file or specify a buffer length and pass the buffer as the data argument. Then use the variant caching functions httpd_variant_insert() and httpd_variant_lookup() to put the content in the cache.

API examples

To help you get started with your own Caching Proxy API functions, look at the sample programs provided in the samples directory of the Edge components installation CD-ROM. Additional information is available on the WebSphere® Application Server Web site, www.ibm.com/software/webservers/appserv/.