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:
- User-defined variable names cannot have a prefix of SERVER_. The Caching Proxy
API function reserves any variable starting with SERVER_ for the server and,
therefore, these variables are read-only. In addition, the prefixes HTTP_
and PROXY_ also are reserved for HTTP headers.
- All request headers sent by the client (such as Set-Cookie) are prefixed
by HTTP_, and their values can be extracted. To access variables that are
request headers, prefix the variable name with HTTP_. You can also create
new variables using the httpd_setvar() predefined function. For details about
these headers, see Return codes from predefined functions and macros.
- Two variable prefixes, HTTP_ and PROXY_, are used to denote whether a
variable applies to headers for the request or for the response. The HTTP_
prefix refers to variables that flow between the client and the Caching Proxy. The
PROXY_ prefix refers to variables that flow between the Caching Proxy and the origin
server (or the next server in a proxy chain). These variables are valid only
during the request processing steps.
- Extracting an HTTP_* variable gives you the value of a header that was
in the client's request to the proxy server.
- Setting an HTTP_* variable sets the response header that is sent from
the proxy server to the client.
- Extracting a PROXY_* variable gives you the value for a header returned
from the content server to the proxy server.
- Setting a PROXY_* variable sets the request header that is sent from the
proxy server to the content server (or to the next server in a proxy chain).
Figure 2 demonstrates the use of these prefixes as the Caching Proxy
handles a client request.
- Some variables are read-only. Read-only variables represent values that
you can extract from a request or a response and use in the httpd_getvar()
predefined function. A return code of HTTPD_READ_ONLY results if you try to
change read-only variables by using the httpd_setvar() function.
- Variables not identified as read-only can be read and set in the httpd_getvar()
or httpd_setvar() predefined functions. These variables represent values that
you can extract from a request or response; or values that you can set or
create when processing a request or response.
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:
- 0 - The request was not found in the cache.
- 1 - The request was found in the cache.
- CACHE_MISS
- Write-only. Used to force a cache miss. Valid values are the following:
- 0 - Do not force a cache miss.
- 1 - Force a cache miss.
- CACHE_TASK
- Read-only. Identifies whether the cache was used. Values returned include
the following:
- 0 - The request did not access or update the cache.
- 1 - The request was served from cache.
- 2 - The requested object was in the cache but needed to be revalidated.
- 3 - The requested object was not in the cache and possibly has been added.
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:
- 0 - The cache was not updated.
- 1 - The cache was updated.
- 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:
- OFF - No tracing.
- V - Verbose mode.
- VV - Very Verbose mode.
- MTV - Much Too Verbose mode.
- 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.
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.
- First, the proxy server examines its configuration file to determine
whether or not there is an authorization directive.
- If an authorization directive is present in the configuration file, the
server calls the authorization function defined in the directive and begins
authentication with step 2.
- If there is no authorization directive, the server performs a default
authorization and then proceeds directly to the authentication procedures
in step 3.
- The proxy server begins the authentication process by checking
to see if the HTTP_authenticate header is present in the client request.
- If the header is present, the server continues the authentication process
(see step 3).
- If the header is not present, authentication must be performed by another
method.
- The proxy server checks to see if there is an authentication directive
present in the proxy configuration file.
- If an authentication directive is present in the configuration file, the
server calls the authentication function defined in the directive.
- If there is no directive, the server performs a default authentication.
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:
- Write your own separate authorization and authentication plug-ins. In
your proxy configuration file, use both the Authorization and the Authentication
directives to specify these functions. Be sure to include the HTTPD_authenticate()
function call in your authorization plug-in function.
When the Authorization
step is executed, it performs your authorization plug-in function, which,
in turn, calls your authentication plug-in function.
- Write your own authorization plug-in function, but have it call the default
server authentication. In your proxy configuration file, use the Authorization
directive to specify your function. In this case, you do not need the Authentication
directive. Be sure to call the HTTPD_authenticate() function in your authorization
plug-in function.
When the Authorization step is executed, it performs
your authorization plug-in function, which, in turn, calls the default server
authentication.
- Write your own authorization plug-in function and include all required
authentication processing in it. Do not use the HTTPD_authenticate() function
in your authorization plug-in. In your proxy configuration file, use the Authorization
directive to specify your authorization plug-in. In this case, you do not
need the Authentication directive.
When the Authorization step is executed,
it performs your authorization plug-in function and any authentication it
includes.
If your Caching Proxy plug-in does not provide its own authorization process, you
can still provide customized authentication by using the following method:
- Write your own authentication plug-in function. In your proxy configuration
file, use the Authentication directives to specify your function. In this
case, you do not need the Authorization directive.
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:
- If you do not have any Authorization directives in your configuration
file, or if their specified plug-in functions decline to handle the request
by returning HTTP_NOACTION, the server's default authorization occurs.
- If you have Authorization
directives in your configuration file and their plug-in functions include
HTTPD_authenticate(), the server calls any authentication functions specified
in the Authentication directives. If you have not defined any Authentication
directives, or if their specified plug-in functions decline to handle the
request by returning HTTP_NOACTION, the server's default authentication occurs.
- If you have Authorization directives in your configuration file but their
plug-in functions do not include HTTPD_authenticate(), no authentication functions
are called by the server. You must write your own authentication processing
as part of your authorization plug-in functions or make your own calls to
other authentication modules.
- The Caching Proxy automatically generates a challenge (prompting the browser to
return a user ID and password) if your authorization function returns the
codes 401 or 407. However, you must still configure
a protection setup in the Caching Proxy so that this action occurs correctly.
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/.